Native Markdown

Markdown as a content model

The content model determines the format in which MediaWiki stores and renders a page. Native Markdown adds Markdown as a content model, so a Markdown page is not wikitext with Markdown embedded inside of it. The whole page is Markdown, stored exactly as you typed it, and rendered as a real wiki page. Markdown pages and wikitext pages coexist on the same wiki, and you choose the model per page.

Wiki links, categories, and the table of contents

Wikitext link syntax works inside Markdown, with the semantics you know. [[Page]] gives you a blue or red link depending on whether the page exists, and the link is tracked in Special:WhatLinksHere and Special:WantedPages. [[Category:X]] assigns a category. [[File:Diagram.png|300px|alt=Text|Caption]] embeds an image. Section links, same-page anchors, and interwiki links all behave like their wikitext counterparts. The table of contents is the real MediaWiki table of contents, built from your Markdown headings.

Anything inside [[...]] that is not a valid title renders as literal text.

A few behaviors differ from wikitext links:

• Inside GFM table cells, | separates columns before links are parsed, so write [[Page\|label]] with a backslash escape: | [[Page\|label]] |.
• Height-only image sizes (x100px) are ignored; only the width of 100px or 100x200px is used.
• [[Media:X]] links land on the file description page rather than the raw file.
• Relative subpage links ([[/sub]]) are not resolved; the text is treated as a literal page title.
• [[Special:...]] links render but are not recorded in Special:WhatLinksHere, as in wikitext.

Markdown flavor

The Markdown flavor is CommonMark plus GitHub Flavored Markdown: tables, strikethrough, task lists, and autolinks, with footnotes on top. Tables are automatically styled as wikitables. YAML front matter is parsed, hidden from the rendered page, and stored as page metadata. Raw HTML is always escaped, so page content cannot inject scripts or other active HTML into your wiki.

For readers coming from wikitext:

MediaWiki already renders the page title as the top-level heading, so starting a page with a # Heading is optional. When present, it becomes the first entry of the table of contents.

Templates and parser functions

You can include your wikitext templates, such as infoboxes, directly in Markdown pages with the usual {{...}} syntax. Expansion runs through MediaWiki's own parser, so template dependencies are tracked (editing a template re-renders the pages that use it), and the output is sanitized exactly as wikitext is.

Parser functions and magic words work inside the braces too, whether built into MediaWiki, like {{PAGENAME}}, or added by extensions, like {{#if:}}. A call on its own line renders as block output, so an infobox is not wrapped in a paragraph, and headings inside templates stay out of the table of contents.

The page source stays clean Markdown regardless: action=raw returns the literal {{...}} you typed rather than the expanded output, so the round trip for AI agents and git stays lossless.

A few less common things are not supported yet: <ref> and <references/> in the Markdown body (footnotes cover citations instead), transcluding another Markdown page with {{:Page}}, and subst:.

To disable transclusion and parser functions on Markdown pages, set $wgNativeMarkdownWikitextExpansion = false.

Editing

Editing happens in the standard edit form. With the CodeEditor extension installed you get Markdown syntax highlighting, and Show preview renders through the full pipeline. Diffs, history, undo, and rollback work as they do for wikitext pages, comparing and reverting the stored Markdown line by line. Edit conflicts are merged three-way at the Markdown source level, and genuinely conflicting edits surface the normal conflict screen.

Built for AI agents

Markdown is the format that AI assistants like Claude and ChatGPT read and write best. Because Native Markdown stores pages as plain Markdown, an agent can read and edit them directly.

Fetching a page with action=raw returns the Markdown source exactly as it was saved, front matter and all. The REST API (/rest.php/v1/page/{title}) reports content_model: markdown alongside the source, so an agent knows what kind of page it is working with. When an agent wants resolved links and the table of contents instead of the source, action=parse returns the rendered HTML. Writing works through the ordinary editing APIs, or more conveniently through the MediaWiki MCP Server, the tool that lets AI assistants read and edit your wiki. The round trip is lossless: an agent can fetch a page, edit it, and write it back without the content drifting through a wikitext translation. The same property makes Markdown pages a good fit for round-trips with git repositories.

Search

Full-text search indexes the rendered prose of a Markdown page rather than the raw markup, so keyword lookups match what a reader sees. Search snippets are clean text instead of # and ** noise, and front matter stays out of the index. The index updates through the job queue when a page is edited, so pages saved before Native Markdown was installed or upgraded keep their previously indexed text until their next edit or a search index rebuild.

Current limitations

The first release focuses on making the content model itself solid. A couple of MediaWiki editing features are not there yet: there is no VisualEditor support, and no section editing.

If your editors rely on VisualEditor, wikitext remains the right model for those pages, and both models coexist on the same wiki, so you choose per page. On the roadmap: mapping front matter to structured data such as Semantic MediaWiki properties, live preview and WYSIWYG editing, and import tooling for Obsidian vaults and git repositories.

Markdown is on by default. Once the extension is installed, new pages default to the Markdown content model across the whole wiki, with deliberate exceptions where wikitext is load-bearing: the discussion (Talk) namespaces, the Template and MediaWiki namespaces, and any namespace with an explicitly configured content model, for example Scribunto modules or JSON pages. The default affects page creation only. Existing pages never change model, and individual pages can be switched between wikitext and Markdown, in both directions, via Special:ChangeContentModel.

To keep wikitext as the default, set $wgNativeMarkdownEverywhere = false; in LocalSettings.php. To offer Markdown only in specific namespaces, use $wgNativeMarkdownNamespaces. With $wgNativeMarkdownSuffixDetection, a title ending in .md is read as a deliberate per-page choice: such new pages default to Markdown everywhere except the Template and MediaWiki namespaces, so both models can mix by naming convention. See the configuration reference for the full list of settings.