Convert RST to Wiki

Why Convert RST to Wiki?

Converting reStructuredText (RST) documents to MediaWiki format enables you to publish documentation on Wikipedia-style wiki platforms. MediaWiki powers Wikipedia, Wikimedia Commons, and thousands of corporate and community wikis worldwide.

Wiki markup is designed for collaborative editing, making it ideal for team documentation where multiple contributors need to update content. The syntax is intentionally simple, allowing non-technical users to participate in documentation efforts without learning complex markup languages.

The conversion is particularly valuable when migrating technical documentation from Sphinx-based systems to internal corporate wikis. Many organizations use MediaWiki or similar platforms for knowledge management, and converting RST content allows seamless integration with existing wiki infrastructure.

MediaWiki's powerful template system, categories, and namespaces provide organizational capabilities that complement the technical depth of RST documentation. Converting to wiki format opens up these features while preserving the essential content structure.

Key Benefits of Converting RST to Wiki:

• Wikipedia Compatibility: Use the same format as the world's largest encyclopedia
• Collaborative Editing: Enable team contributions with built-in version control
• Easy Learning Curve: Wiki syntax is accessible to non-developers
• Template System: Reuse content with MediaWiki templates
• Categories: Organize content with wiki categorization
• Internal Links: Create interconnected documentation
• Wide Platform Support: Works with MediaWiki, DokuWiki, and others

Practical Examples

Example 1: Documentation Page

Input RST file (guide.rst):

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

Prerequisites
-------------

Before installing, ensure you have:

* Python 3.8 or higher
* pip package manager
* Git (optional)

.. note::
   Administrator privileges may be required.

Output Wiki file (guide.wiki):

= Installation Guide =

== Prerequisites ==

Before installing, ensure you have:

* Python 3.8 or higher
* pip package manager
* Git (optional)

{{Note|Administrator privileges may be required.}}

Example 2: Code and Tables

Input RST file (api.rst):

API Methods
===========

.. code-block:: python

   def get_user(user_id):
       return database.fetch(user_id)

+-----------+--------+----------------+
| Method    | Type   | Description    |
+===========+========+================+
| get_user  | GET    | Fetch user     |
+-----------+--------+----------------+
| set_user  | POST   | Create user    |
+-----------+--------+----------------+

Output Wiki file (api.wiki):

= API Methods =

<syntaxhighlight lang="python">
def get_user(user_id):
    return database.fetch(user_id)
</syntaxhighlight>

{| class="wikitable"
|-
! Method !! Type !! Description
|-
| get_user || GET || Fetch user
|-
| set_user || POST || Create user
|}

Example 3: Links and References

Input RST file (resources.rst):

Resources
=========

External Links
--------------

* `Python Documentation <https://docs.python.org>`_
* `GitHub Repository <https://github.com/example>`_

See Also
--------

See the :ref:`installation` section for setup instructions.

See the :doc:`configuration` document for options.

Output Wiki file (resources.wiki):

= Resources =

== External Links ==

* [https://docs.python.org Python Documentation]
* [https://github.com/example GitHub Repository]

== See Also ==

See the [[Installation]] section for setup instructions.

See the [[Configuration]] document for options.

Frequently Asked Questions (FAQ)

Q: What is MediaWiki markup?

A: MediaWiki markup (also called wikitext) is the formatting language used by Wikipedia and MediaWiki-powered wikis. It uses simple syntax like '''bold''', ''italic'', and = for headers to format content in a way that's easy for anyone to learn and edit.

Q: Will RST directives convert to wiki templates?

A: Common directives like note, warning, and code-block convert to MediaWiki equivalents (templates and syntaxhighlight tags). However, Sphinx-specific directives like autodoc don't have wiki equivalents and may need manual handling.

Q: How do RST tables convert to wiki tables?

A: RST tables convert to MediaWiki table syntax using {| and |}. Simple tables convert well, but complex grid tables with merged cells may need adjustment. The wikitable class is typically applied for consistent styling.

Q: Can I use the output on Wikipedia?

A: Yes, the converted markup is compatible with Wikipedia. However, Wikipedia has specific content guidelines, citation requirements, and notability standards. Technical documentation may be better suited for Wikibooks or project-specific wikis.

Q: What about cross-references in RST?

A: RST cross-references (:ref:, :doc:) convert to MediaWiki internal links using [[Page Name]] syntax. You may need to adjust page names to match your wiki's naming conventions after conversion.

Q: Does wiki markup support code highlighting?

A: Yes! MediaWiki supports syntax highlighting through the <syntaxhighlight> tag (or <source> in older versions). The SyntaxHighlight extension supports most programming languages, similar to RST's code-block directive.

Q: Can I use this with DokuWiki?

A: DokuWiki uses a slightly different syntax from MediaWiki. While similar, you may need to adjust header syntax (====== vs =) and some formatting. Pandoc can also output DokuWiki format directly if needed.

Q: How do I convert wiki back to RST?

A: Use Pandoc to convert MediaWiki to RST: `pandoc -f mediawiki -t rst input.wiki -o output.rst`. This is useful for pulling wiki content into Sphinx documentation projects or for offline editing with RST tools.