Convert MediaWiki to RST

Why Convert MediaWiki to RST?

Converting MediaWiki markup to reStructuredText is essential when migrating documentation from a wiki platform to a Sphinx-based documentation system. Many organizations start with wiki-based documentation for its ease of collaborative editing, but eventually need the more powerful features that Sphinx and RST provide, including automated API documentation, cross-referencing, and multi-format output to HTML, PDF, and EPUB.

MediaWiki and RST share a similar philosophy as lightweight markup languages, but they serve different audiences and purposes. MediaWiki excels at collaborative web-based editing with features like templates, categories, and transclusion, while RST is designed for structured technical documentation with directives, roles, and tight integration with the Python ecosystem. Converting from MediaWiki to RST allows you to preserve your content while gaining access to Sphinx's powerful documentation toolchain.

The conversion maps MediaWiki syntax elements to their RST equivalents: wiki headings with equals signs become RST underlined headings, bold and italic markup translates to RST asterisk-based formatting, wiki links become RST hyperlinks or cross-references, and wiki tables are converted to RST grid or simple table format. Template calls and categories require special handling, as RST uses directives and metadata for similar functionality.

This conversion is particularly valuable for Python projects that have documentation scattered across internal wikis and need to consolidate it into a professional Sphinx documentation site hosted on Read the Docs. It enables teams to leverage version control for documentation, automate builds, and produce consistently formatted output across multiple formats from a single RST source.

Key Benefits of Converting MediaWiki to RST:

• Sphinx Integration: Build professional documentation sites with Sphinx
• Multi-Format Output: Generate HTML, PDF, EPUB, and man pages from RST
• Cross-Referencing: Powerful cross-document linking and indexing
• Version Control: Track documentation changes in Git alongside code
• Read the Docs: Host documentation for free with automatic builds
• Python Standard: The standard documentation format for Python projects
• Extensible: Custom directives and roles for specialized content

Practical Examples

Example 1: Wiki Article to RST Documentation

Input MediaWiki file (article.wiki):

== Installation Guide ==

'''MyProject''' requires Python 3.8 or later.

=== Prerequisites ===
* Python 3.8+
* pip package manager
* Git (optional)

=== Quick Start ===
Install via pip:

 pip install myproject

See [[Configuration]] for setup details.

Output RST file (article.rst):

Installation Guide
==================

**MyProject** requires Python 3.8 or later.

Prerequisites
-------------
- Python 3.8+
- pip package manager
- Git (optional)

Quick Start
-----------
Install via pip:

.. code-block:: bash

   pip install myproject

See :doc:`configuration` for setup details.

Example 2: Wiki Reference Page to RST

Input MediaWiki file (api-ref.wiki):

== API Reference ==

=== authenticate() ===
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| username || string || User login name
|-
| password || string || User password
|-
| timeout || int || Connection timeout in seconds
|}

Returns: ''Authentication token as string''

Output RST file (api-ref.rst):

API Reference
=============

authenticate()
--------------

.. list-table::
   :header-rows: 1

   * - Parameter
     - Type
     - Description
   * - username
     - string
     - User login name
   * - password
     - string
     - User password
   * - timeout
     - int
     - Connection timeout in seconds

Returns: *Authentication token as string*

Example 3: Wiki Content with Images and Links

Input MediaWiki file (overview.wiki):

== Project Overview ==

[[File:architecture.png|thumb|System architecture]]

The project consists of three main components:

# '''Frontend''' — React-based web interface
# '''Backend''' — Django REST API
# '''Database''' — PostgreSQL with Redis cache

For more details, see [https://example.com docs]
and the [[Developer Guide]].

Output RST file (overview.rst):

Project Overview
================

.. figure:: architecture.png
   :alt: System architecture

   System architecture

The project consists of three main components:

#. **Frontend** --- React-based web interface
#. **Backend** --- Django REST API
#. **Database** --- PostgreSQL with Redis cache

For more details, see `docs <https://example.com>`_
and the :doc:`developer-guide`.

Frequently Asked Questions (FAQ)

Q: What is reStructuredText (RST)?

A: reStructuredText (RST) is a markup language developed as part of the Python Docutils project. It uses underlined headings, asterisks for emphasis, backticks for inline code, and a powerful directive system for images, code blocks, admonitions, and more. RST is the standard documentation format for Python projects and is used by Sphinx to generate professional documentation sites.

Q: How are MediaWiki headings converted to RST?

A: MediaWiki headings use equals signs (== Heading ==), while RST uses underline characters. The converter maps MediaWiki heading levels to RST underline characters: level 1 uses = underlines, level 2 uses - underlines, level 3 uses ~ underlines, and so on. The heading text itself is preserved, with the underline matching the length of the heading text.

Q: Will wiki tables be converted properly?

A: Yes, MediaWiki tables are converted to RST table format. Simple tables use RST's simple table syntax, while more complex tables are converted to grid tables or list-table directives. The converter preserves table headers, cell content, and basic alignment. However, advanced wiki table styling (colors, column spans) may require manual adjustment in the RST output.

Q: How are MediaWiki templates handled?

A: MediaWiki templates do not have a direct equivalent in RST. The converter handles templates by either expanding their content inline or converting them to RST directives where appropriate. Infobox templates may become RST field lists or admonitions. Complex templates with logic may need manual review and conversion to appropriate RST constructs.

Q: Can I use the RST output with Sphinx?

A: Yes! The converted RST files are fully compatible with Sphinx. You can add them to your Sphinx documentation project, include them in your table of contents tree (toctree), and build HTML, PDF, or EPUB output. You may need to adjust cross-references and add Sphinx-specific directives for optimal integration with your documentation structure.

Q: How are wiki links converted to RST?

A: Internal wiki links ([[Page Name]]) are converted to RST cross-references using the :doc: role or inline hyperlinks. External links ([https://example.com text]) become RST inline hyperlinks (`text <https://example.com>`_). Category links are converted to RST metadata or labels depending on the Sphinx configuration.

Q: Is RST better than Markdown for documentation?

A: RST offers more powerful features than Markdown for technical documentation, including native directives, roles, cross-referencing, and table of contents generation. Sphinx with RST is the industry standard for Python documentation and supports multi-format output. However, Markdown is simpler to learn and more widely used outside the Python ecosystem. The choice depends on your project's needs.

Q: Can I convert an entire MediaWiki site to RST?

A: Yes, you can convert individual MediaWiki pages to RST files one at a time. For a complete wiki migration, export each page as MediaWiki markup, convert them to RST, then organize the resulting files into a Sphinx project structure with proper toctree directives. Internal links between pages will need to be updated to use RST cross-reference syntax.