Convert MediaWiki to Markdown

What is MediaWiki markup?

MediaWiki markup — also called wiki syntax or wikitext — is the markup language that powers Wikipedia and every other site running the MediaWiki software. It was created in 2002 alongside Wikipedia's second platform rewrite, evolving from earlier wiki markup dialects (UseModWiki, MoinMoin). For over twenty years, it has been the dominant format for collaborative encyclopedic content on the web.

MediaWiki's reach extends well beyond Wikipedia. Fandom (formerly Wikia) hosts hundreds of thousands of community wikis in MediaWiki markup. Internal corporate wikis running on MediaWiki still exist at scale. Most open-source project documentation that started pre-2015 — Linux distributions, game modding communities, programming language reference sites — lives in MediaWiki format. The syntax survived because it was approachable for non-technical contributors and because Wikipedia's gravity pulled the format forward.

Where MediaWiki markup is most visible today: article migrations. Teams want to pull a Wikipedia article or a fandom wiki into a static documentation site, a Jekyll blog, an Obsidian vault, or a Hugo-powered knowledge base. MediaWiki's ==Heading== / '''bold''' / [[link]] syntax needs translating to Markdown's ## / ** / []() equivalents before the content fits into modern publishing pipelines.

Why migrate to Markdown?

The migration case for wiki content usually falls into three buckets. First, wiki archival: a fandom wiki is shutting down, a subject-matter community wants to mirror their content somewhere durable, and the export format is MediaWiki markup. Markdown has better tooling for backup, version control, and cold-storage reading than MediaWiki does.

Second, content repurposing: a Wikipedia article or wiki page has reference value — definitions, tables of facts, historical timelines — that belongs in a project's documentation. Pulling the useful sections into a Markdown-first docs site (Docusaurus, GitBook, VitePress, Hugo) means the content becomes searchable alongside the rest of the project docs and editable via standard git workflow.

Third, platform migration: a team moves from MediaWiki to a modern wiki platform — Outline, BookStack, DokuWiki (which has its own markup but accepts Markdown), Notion, or a Markdown-native SSG. The content has to come with them in a format the destination understands.

The loss is real. MediaWiki templates ({{infobox}}, {{cite web}}, hundreds of project-specific templates) are where a lot of Wikipedia's structural power lives. Plain Markdown cannot reproduce infobox layouts, citation linkbacks, or category taxonomies. If those matter for your use case, you need either a richer target format (an MDX-based site with custom components) or an acceptance that those structures will be simplified during migration.

Manual approach

Hand-converting MediaWiki markup is straightforward for prose, frustrating for structured content:

• ==Heading== → ## Heading, ===Subheading=== → ### Subheading
• '''bold''' → **bold**
• ''italic'' → *italic*
• [[Target]] → [Target](Target)
• [[Target|Display Text]] → [Display Text](Target)
• [url Display Text] (external link) → [Display Text](url)
• <code>x</code> → `x`
• <ref>text</ref> → a footnote reference. The pattern in Markdown is [^1] inline + [^1]: text at end of document. Numbering is sequential as refs appear.
• * bullet → - bullet at line start
• # numbered → 1. numbered — MediaWiki's # prefix means "numbered list", which collides with MD's # for headings. The rule is: # at line start followed by space is a list; # followed by more text (no space) is part of content.

The hard parts of manual conversion: templates (you have to look each one up on the wiki and decide what to replace it with), tables ({| class="wikitable" ... |} syntax is its own dialect), category tags ([[Category:Foo]] at the bottom of wiki pages has no MD equivalent — you drop them or move to frontmatter), and nested lists (indentation rules differ).

A Wikipedia article of 5–10 sections, mostly prose with a few references and internal links, takes 45–90 minutes to hand-convert. Most of that time is on references and templates.

Automated approach (our tool)

Our converter handles the common MediaWiki → Markdown patterns. Paste your wiki markup, get clean Markdown. Coverage:

• Headings: ==H==, ===H===, ====H==== become ##, ###, ####
• Inline formatting: '''bold''' becomes **bold**; ''italic'' becomes *italic*. Order matters — we apply the three-quote pattern first to avoid greedy consumption of italics inside bold.
• Internal links: [[Paris]] becomes [Paris](Paris); [[Paris|City of Light]] becomes [City of Light](Paris)
• External links: [https://example.com Example] becomes [Example](https://example.com)
• Inline code: <code>x</code> becomes `x`
• References: <ref>source text</ref> become sequentially-numbered footnote markers [^1], [^2], etc. in the body, with the source text accumulated into a footnote block appended to the end of the document: [^1]: source text
• Templates: {{template-name}} becomes an HTML comment <!-- template: template-name --> preserving the name for later reference
• Lists: line-leading * becomes - ; line-leading # (followed by space) becomes 1.

Not covered: wikitables ({| ... |} syntax), infoboxes (just templates, but complex ones), category tags ([[Category:X]] — these pass through as regular internal links), namespace-prefixed links ([[File:image.jpg]], [[User:Alice]] — these pass through as regular links, which may not be what you want).

For prose with typical wiki formatting and moderate reference density, our engine produces clean GFM. For content dominated by templates and tables, the output requires significant post-processing.

Common gotchas

Internal links may need URL normalization. [[Paris]] becomes [Paris](Paris) — the URL is literally Paris. If your target destination uses different URL conventions (e.g. Hugo slugs are lowercase with hyphens: paris), you need a post-conversion pass to normalize link URLs. A simple sed or JavaScript rewrite on the output handles it.

Category and file links fall through as content links. [[Category:Physics]] becomes [Category:Physics](Category:Physics), which is not what you want. MediaWiki treats category and file links as metadata; Markdown doesn't have an equivalent concept. Filter these out of your source before conversion (search-and-replace [[Category:...]] with empty string) or strip them from the output.

Template placeholders show in the output. {{infobox country}} becomes <!-- template: infobox country -->. This is intentional — we preserve the template name so you can manually reconstruct its function. But rendered output will show nothing in place of the infobox. If your migration target is an MDX-capable site, you can build custom components with the same names and wire them up. If your target is plain Markdown, you need to either reconstruct the data manually (often a table with key-value pairs) or accept the loss.

References collect at the end, not inline. Our footnote output follows the CommonMark GFM footnote syntax: marker at the citation point, definition at the end of the document. If your MediaWiki source had references interspersed or grouped by section, the output flattens them all to the bottom. Most Markdown renderers handle this correctly, but if you want a specific reference layout you'll need manual editing.

Bold vs italic ordering can clash on edge cases. MediaWiki uses quotes for emphasis: two quotes for italic, three for bold, five for both. Our engine processes ''' before '' to avoid greedy matching. If your source has five-quote emphasis ('''''both'''''), you may get unexpected output — it often comes through as italic-in-bold, which is usually fine but not always. Hand-check any five-quote sections.

# at line start has two meanings. In MediaWiki, # item is a numbered list item. In Markdown, # is a heading. Our engine distinguishes by context (list requires a space after #) but context detection is local, not perfect. If your source has headings that look like # Intro (not valid wiki syntax but not uncommon in copy-paste content), the engine may misclassify.

Magic words and variables pass through. MediaWiki has {{CURRENTYEAR}}, {{SITENAME}}, {{PAGENAME}}, and dozens of others — dynamic values filled at render time. These become template-comment placeholders in our output. Resolve them to literal values in your source before conversion if you want the rendered result to show the value (e.g. replace {{CURRENTYEAR}} with the actual year).

When to use Pandoc instead

Pandoc's MediaWiki reader is mature and handles the harder structural content our tool skips. Tables, category handling (with --reader-opts), and most template patterns go through cleanly. The invocation: pandoc input.wiki -f mediawiki -t gfm -o output.md.

Pandoc also has a -f mediawiki+raw_html mode if your source embeds HTML (common in Wikipedia articles). And for bulk article migration, you can script Pandoc to iterate over a directory of wiki-format exports and produce a parallel directory of GFM output.

Our tool covers the casual case: one page at a time, paste-and-copy, no local install. For any migration project that involves more than a dozen articles or relies heavily on tables and templates, Pandoc is worth the setup.

Migration workflow

A practical workflow for a wiki content migration:

1. Export your source. MediaWiki offers bulk export via Special:Export or dump files. Fandom's wikis can be exported the same way. Save the wiki-format content to local files.
2. Survey the complexity. Count template usage (grep -c '{{' *.wiki), table usage (grep -c '{|' *.wiki), category tags (grep -c '\[\[Category' *.wiki). High counts suggest Pandoc; low counts suggest our tool is enough.
3. Decide on template handling. For each template you use frequently (say, appearing in more than 10 articles), decide: ignore it, replace with literal content, or build a custom component in your target. Write a search-and-replace pass for each.
4. Strip category and file-link pollution. Before conversion, remove [[Category:...]] and reformat [[File:...]] if your target doesn't use the same image-link convention.
5. Convert via our tool or Pandoc. For each page, paste the source in and review the output. Pay attention to internal links (URL normalization may be needed), references (should be consolidated at the end), and any remaining template comments.
6. Normalize internal links. Run a post-conversion pass to convert wiki-style URLs ([[Page Name]] → page-name.md) to the slug scheme your destination uses. Hugo wants lowercase-hyphenated; Obsidian wants wiki-link format with [[]]; Jekyll wants /posts/slug.html.
7. Add frontmatter. Your target probably wants YAML frontmatter with title, date, tags, and layout. Wiki sources often don't have this — generate from filename and category tags where possible.
8. Build a redirect map. If you're preserving URLs, map old wiki URL structure to new Markdown paths. This is a server / CDN concern, not a file-content concern, but do it during migration so users with bookmarks don't 404.
9. Review rendered output in the target. Check references render, links work, headers nest correctly, tables (if any) display.

A medium wiki migration (50–100 articles, moderate template usage, tables in a quarter of pages) takes one to three days of work spread across scripting, conversion, and review. Our tool is one component of the pipeline — it handles the per-page text transformation while your scripts handle source prep and destination-specific decoration.