Convert MediaWiki to Markdown

Why Convert MediaWiki to Markdown?

Converting MediaWiki markup to Markdown is one of the most common wiki migration tasks, driven by the growing adoption of Markdown as the universal lightweight markup language for developers and technical writers. Organizations migrating from MediaWiki-based wikis to GitHub-based documentation, static site generators, or modern knowledge management tools need to convert their existing wiki content to Markdown format.

MediaWiki and Markdown share the same fundamental goal of providing human-readable formatted text, but they approach it differently. MediaWiki uses wiki-specific syntax like == headings ==, '''bold''', [[links]], and complex template systems, while Markdown uses ## headings, **bold**, [links](url), and focuses on simplicity. The conversion maps MediaWiki constructs to their closest Markdown equivalents, preserving content structure and formatting while adapting to Markdown conventions.

The conversion handles the key syntax differences: MediaWiki headings (== H2 ==) become Markdown headings (## H2), bold markers (''' to **), italic markers ('' to *), links ([[target|text]] to [text](target)), lists (* and # to - and 1.), and tables (wiki table markup to pipe tables). Templates and categories, which are MediaWiki-specific features, are either converted to equivalent Markdown constructs or noted as comments.

Markdown's broad ecosystem makes it the ideal target for wiki content migration. Content converted to Markdown can be used directly on GitHub, rendered by static site generators like Hugo and Jekyll, imported into tools like Obsidian and Notion, or processed by documentation platforms like MkDocs and Docusaurus. This versatility makes MediaWiki-to-Markdown conversion a critical step in modernizing documentation workflows.

Key Benefits of Converting MediaWiki to Markdown:

• GitHub Integration: Markdown is the native format for GitHub READMEs, wikis, and documentation
• Broad Tool Support: Hundreds of editors, renderers, and platforms support Markdown natively
• Simpler Syntax: Markdown is easier to learn and write than MediaWiki markup
• Static Site Generators: Direct compatibility with Hugo, Jekyll, Gatsby, and more
• Version Control Friendly: Clean diffs in git due to simple, predictable syntax
• Modern Documentation: Powers MkDocs, Docusaurus, and other doc platforms
• Knowledge Management: Works natively in Obsidian, Notion, and similar tools

Practical Examples

Example 1: Wiki Article to Markdown Documentation

Input MediaWiki file (article.wiki):

== Getting Started ==

'''Welcome''' to the project documentation.

=== Installation ===
# Clone the [[Git|repository]]
# Run npm install
# Configure the {{Config|settings}} file

See the [[API Reference]] for details.

[[Category:Documentation]]
[[Category:Setup]]

Output Markdown file (article.markdown):

## Getting Started

**Welcome** to the project documentation.

### Installation
1. Clone the [repository](Git)
2. Run `npm install`
3. Configure the settings file

See the [API Reference](API_Reference) for details.

<!-- Categories: Documentation, Setup -->

Example 2: Wiki Table to Markdown Table

Input MediaWiki file (comparison.wiki):

== Feature Comparison ==

{| class="wikitable sortable"
! Feature !! Free Plan !! Pro Plan
|-
| Storage || 5 GB || 100 GB
|-
| Users || 3 || Unlimited
|-
| Support || Email || '''Priority'''
|}

''Last updated: January 2026''

Output Markdown file (comparison.markdown):

## Feature Comparison

| Feature | Free Plan | Pro Plan |
|---------|-----------|----------|
| Storage | 5 GB | 100 GB |
| Users | 3 | Unlimited |
| Support | Email | **Priority** |

*Last updated: January 2026*

Example 3: Wiki Content with Links and Formatting

Input MediaWiki file (guide.wiki):

== Quick Reference Guide ==

This guide covers the '''essential commands'''.

=== Basic Commands ===
* git clone - Clone a [[repository]]
* git commit - Save changes
* git push - Upload to [[Remote repository|remote]]

{{Note|Always pull before pushing.}}

=== External Resources ===
* [https://git-scm.com/ Official Git site]
* [https://github.com GitHub]

Output Markdown file (guide.markdown):

## Quick Reference Guide

This guide covers the **essential commands**.

### Basic Commands
- `git clone` - Clone a [repository](repository)
- `git commit` - Save changes
- `git push` - Upload to [remote](Remote_repository)

> **Note:** Always pull before pushing.

### External Resources
- [Official Git site](https://git-scm.com/)
- [GitHub](https://github.com)

Frequently Asked Questions (FAQ)

Q: What is MediaWiki markup?

A: MediaWiki markup is the formatting language used by Wikipedia and MediaWiki-powered wikis since 2002. It provides syntax for headings (== ==), bold ('''text'''), italic (''text''), links ([[page]]), templates, tables, and more. It is specifically designed for collaborative web-based content creation.

Q: How are MediaWiki templates handled in the conversion?

A: MediaWiki templates are wiki-specific features that have no direct Markdown equivalent. Simple templates like notes and warnings are converted to blockquotes or admonitions. Complex templates (infoboxes, navigation boxes) are simplified to their text content or converted to Markdown tables where possible. Template parameters are preserved as readable text.

Q: Which Markdown flavor does the output use?

A: The output uses GitHub Flavored Markdown (GFM), which is the most widely supported Markdown dialect. It includes support for tables, task lists, strikethrough, and fenced code blocks. The output is also compatible with CommonMark and works well with most Markdown renderers.

Q: Are MediaWiki categories preserved?

A: Categories are preserved as HTML comments or YAML front matter at the top of the Markdown file, depending on the conversion settings. Since Markdown has no native category system, this approach keeps the metadata accessible without affecting the rendered output.

Q: Can I use the converted Markdown on GitHub?

A: Absolutely! The Markdown output is fully compatible with GitHub. You can use it for README files, wiki pages, documentation, issues, and pull request descriptions. GitHub will render the headings, links, tables, code blocks, and formatting correctly.

Q: How are internal wiki links converted?

A: Internal links like [[Page Name]] become [Page Name](Page_Name) in Markdown. Links with display text like [[Target|Display]] become [Display](Target). You may need to update the link targets to match your new documentation structure after conversion.

Q: What about wiki tables with merged cells or complex formatting?

A: Standard Markdown tables do not support merged cells (colspan/rowspan). Complex wiki tables are simplified to standard pipe tables. Where cell merging was used, the content is placed in individual cells. For very complex tables, HTML table markup may be used in the Markdown output to preserve the structure.

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

A: You can convert individual wiki pages by exporting them as .wiki files and uploading them here. For full site migration, export pages one at a time or use the MediaWiki Special:Export feature to get individual page content, then convert each file. Internal links may need updating to reflect the new file-based structure.