Convert MediaWiki to MD

Why Convert MediaWiki to MD?

Converting MediaWiki markup to MD (.md) files is essential for migrating wiki content into the modern developer ecosystem. The .md file extension is the universal standard recognized by GitHub, GitLab, Bitbucket, VS Code, and virtually every development tool and platform. When you convert your MediaWiki content to .md files, you gain immediate compatibility with the entire software development toolchain.

MediaWiki markup was designed for server-rendered wiki environments where features like templates, transclusion, and categories are processed by the MediaWiki engine. The .md format, in contrast, is designed to be rendered by thousands of different tools and platforms. Converting from MediaWiki to .md transforms wiki-specific syntax into the widely portable Markdown format that works everywhere from code repositories to static site generators.

The conversion process maps MediaWiki constructs to Markdown equivalents: headings (== to ##), text formatting (''' to **, '' to *), links ([[target|text]] to [text](target)), lists, and tables. Wiki-specific features like templates are converted to their closest Markdown representations, such as blockquotes for admonition templates or tables for infobox templates. Categories can be preserved as YAML front matter tags.

The .md extension is particularly important because it triggers automatic rendering on platforms like GitHub, where README.md files are displayed on repository home pages. Documentation sites built with MkDocs, Docusaurus, or VuePress expect .md files. Note-taking apps like Obsidian use .md files as their native storage format. By converting to .md, your wiki content becomes immediately usable across this entire ecosystem.

Key Benefits of Converting MediaWiki to MD:

• .md Recognition: Auto-rendered on GitHub, GitLab, and code platforms
• Developer Ecosystem: Compatible with the entire modern development toolchain
• Static Sites: Direct use with Hugo, Jekyll, MkDocs, Docusaurus
• Version Control: Clean git diffs with simple, predictable Markdown syntax
• IDE Support: Preview and editing in VS Code, IntelliJ, and other editors
• Note-Taking: Compatible with Obsidian, Notion, Bear, and similar tools
• Portability: .md files work everywhere Markdown is supported

Practical Examples

Example 1: Wiki Page to README.md

Input MediaWiki file (project.wiki):

== MyProject ==

{{ProjectBadge|status=active}}

'''MyProject''' is an open-source tool for data processing.

=== Features ===
* Fast parallel processing
* Support for [[CSV]], [[JSON]], and [[XML]]
* Built-in [[Data Validation|validation]]

=== Quick Start ===
 git clone https://github.com/user/myproject
 cd myproject
 pip install -r requirements.txt

[[Category:Tools]]
[[Category:Python]]

Output MD file (README.md):

## MyProject

**MyProject** is an open-source tool for data processing.

### Features
- Fast parallel processing
- Support for [CSV](CSV), [JSON](JSON), and [XML](XML)
- Built-in [validation](Data_Validation)

### Quick Start
```bash
git clone https://github.com/user/myproject
cd myproject
pip install -r requirements.txt
```

Example 2: Wiki Documentation to .md File

Input MediaWiki file (api.wiki):

== API Reference ==

=== Authentication ===
All requests require an API key passed via the
Authorization header.

{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/users || GET || List all users
|-
| /api/users/{{id}} || GET || Get user by ID
|-
| /api/users || POST || Create new user
|}

{{Warning|Rate limit: 100 requests per minute.}}

Output MD file (api.md):

## API Reference

### Authentication
All requests require an API key passed via the
`Authorization` header.

| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/users | GET | List all users |
| /api/users/{id} | GET | Get user by ID |
| /api/users | POST | Create new user |

> **Warning:** Rate limit: 100 requests per minute.

Example 3: Wiki Content with Mixed Formatting

Input MediaWiki file (guide.wiki):

== Troubleshooting Guide ==

If you encounter errors, follow these steps:

# Check the [[Log Files|log files]] for errors
# Verify your {{Config|configuration}}
# Restart the service:
#: systemctl restart myapp

=== Common Errors ===
; Error 404
: The requested resource was not found.
; Error 500
: Internal server error. Check [[Server Logs]].

Output MD file (guide.md):

## Troubleshooting Guide

If you encounter errors, follow these steps:

1. Check the [log files](Log_Files) for errors
2. Verify your configuration
3. Restart the service:
   `systemctl restart myapp`

### Common Errors
**Error 404**
: The requested resource was not found.

**Error 500**
: Internal server error. Check [Server Logs](Server_Logs).

Frequently Asked Questions (FAQ)

Q: What is the difference between MD and Markdown?

A: MD and Markdown refer to the same format. ".md" is the standard file extension for Markdown files. Other extensions like .markdown and .mdown also exist but .md is by far the most common and universally recognized. GitHub, GitLab, VS Code, and most tools auto-detect and render .md files.

Q: Will my wiki page structure be preserved in the .md file?

A: Yes, the document structure is preserved. MediaWiki headings (== to ======) are converted to Markdown headings (## to ######). Lists, paragraphs, and content hierarchy are maintained. The .md file will reflect the same logical organization as the original wiki page.

Q: How are MediaWiki templates converted to MD?

A: Templates are converted based on their type. Warning/note templates become blockquotes (> **Warning:**...), infobox templates may become tables or structured text, and simple templates are expanded to their text content. Complex templates with no Markdown equivalent are simplified to preserve their visible content.

Q: Can I use the .md file with GitHub Pages?

A: Yes! GitHub Pages uses Jekyll to render .md files into web pages. The converted .md file can be placed directly in a GitHub Pages repository and will be rendered as a web page. You can add YAML front matter for title, layout, and other page metadata.

Q: What happens to MediaWiki categories in the .md output?

A: Categories from [[Category:Name]] tags can be preserved as YAML front matter tags at the top of the .md file or as HTML comments. Since Markdown has no native category system, this approach keeps the metadata available for static site generators that support tags or categories via front matter.

Q: How are wiki code blocks handled?

A: MediaWiki <code> tags become inline code (backticks) in MD, and <source> or <syntaxhighlight> blocks become fenced code blocks with language identifiers (```python, ```javascript, etc.). Indented text blocks (starting with spaces in wiki markup) are also converted to code blocks where appropriate.

Q: Is the converted .md file compatible with Obsidian?

A: Yes, the .md output works perfectly with Obsidian and other personal knowledge management tools. Internal links may use standard Markdown link syntax rather than Obsidian's [[wikilink]] format, but both are supported in Obsidian's settings. You can enable wikilink compatibility in Obsidian if preferred.

Q: How large of a MediaWiki file can I convert?

A: You can upload MediaWiki files of any reasonable size for conversion. The converter processes the markup efficiently, handling long articles, extensive tables, and deeply nested content. For very large wiki dumps, convert individual pages rather than trying to process multiple pages in a single file.