PHPackages professional-wiki/native-markdown - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Parsing & Serialization](/categories/parsing) 4. / 5. professional-wiki/native-markdown ActiveMediawiki-extension[Parsing & Serialization](/categories/parsing) professional-wiki/native-markdown ================================= MediaWiki extension that makes Markdown a native content model with first-class wiki integration 1.2.0(1mo ago)1153[4 issues](https://github.com/ProfessionalWiki/NativeMarkdown/issues)GPL-2.0-or-laterPHPPHP >=8.1CI failing Since Jul 7Pushed 1w ago2 watchersCompare [ Source](https://github.com/ProfessionalWiki/NativeMarkdown)[ Packagist](https://packagist.org/packages/professional-wiki/native-markdown)[ Docs](https://professional.wiki/en/extension/native-markdown)[ RSS](/packages/professional-wiki-native-markdown/feed)WikiDiscussions master Synced 1w ago READMEChangelog (4)Dependencies (21)Versions (7)Used By (0) Native Markdown =============== [](#native-markdown) [![GitHub Workflow Status](https://camo.githubusercontent.com/ae54679735b7e31ed7fe7abb35f87e8e8d4bfb64a63337d685ec3809df911110/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f50726f66657373696f6e616c57696b692f4e61746976654d61726b646f776e2f63692e796d6c3f6272616e63683d6d6173746572)](https://github.com/ProfessionalWiki/NativeMarkdown/actions?query=workflow%3ACI)[![codecov](https://camo.githubusercontent.com/ec1c30e54d47c9284cdcbd9355fdd757db59b26cb59efd8da9c1c0dea1e34e06/68747470733a2f2f636f6465636f762e696f2f67682f50726f66657373696f6e616c57696b692f4e61746976654d61726b646f776e2f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/ProfessionalWiki/NativeMarkdown)[![Type Coverage](https://camo.githubusercontent.com/f20b7bc0a672ab85a0ab8edf88369e03525df4159104c9e11fa9bcd2e8b5673e/68747470733a2f2f73686570686572642e6465762f6769746875622f50726f66657373696f6e616c57696b692f4e61746976654d61726b646f776e2f636f7665726167652e737667)](https://shepherd.dev/github/ProfessionalWiki/NativeMarkdown)[![Psalm level](https://camo.githubusercontent.com/b5815ff78737cd7fbafd78904ef3b689e97c934f7e7c38ad3fad7dd38e8571e3/68747470733a2f2f73686570686572642e6465762f6769746875622f50726f66657373696f6e616c57696b692f4e61746976654d61726b646f776e2f6c6576656c2e737667)](psalm.xml)[![Latest Stable Version](https://camo.githubusercontent.com/20f89dcc6588969e0950eb319a7049183f4bb40104a62a6e8785d223a604f2d6/68747470733a2f2f706f7365722e707567782e6f72672f70726f66657373696f6e616c2d77696b692f6e61746976652d6d61726b646f776e2f762f737461626c65)](https://packagist.org/packages/professional-wiki/native-markdown)[![Download count](https://camo.githubusercontent.com/c2127d8205c52653658303929738eadbe25b2e2e28681658883e847d90984927/68747470733a2f2f706f7365722e707567782e6f72672f70726f66657373696f6e616c2d77696b692f6e61746976652d6d61726b646f776e2f646f776e6c6f616473)](https://packagist.org/packages/professional-wiki/native-markdown)[![License](https://camo.githubusercontent.com/30a7b7a604864879453ed4fd5635c14ae8d0fb24e76d5d816a9b648d63befd7e/68747470733a2f2f706f7365722e707567782e6f72672f70726f66657373696f6e616c2d77696b692f6e61746976652d6d61726b646f776e2f6c6963656e7365)](LICENSE) [MediaWiki](https://www.mediawiki.org) extension that makes Markdown a **native content model**: whole pages are stored and edited as Markdown and rendered with real wiki integration (internal links, categories, search, templates, and more), coexisting with wikitext pages on the same wiki. Because pages are stored as plain Markdown, they are directly consumable and writable by LLMs and agents: `action=raw` returns clean Markdown; no wikitext conversion needed. See [For AI agents and LLMs](#for-ai-agents-and-llms). [![Editing a Markdown page: clean Markdown source, then the rendered page with a table of contents, wiki links, and a category](docs/screenshots/native-markdown-demo.gif)](docs/screenshots/native-markdown-demo.gif) - [Introduction to the extension](https://professional.wiki/en/extension/native-markdown#Overview) - [Usage documentation](https://professional.wiki/en/extension/native-markdown#Usage) - [Installation](#installation) - [Configuration](#configuration) - [Templates and parser functions](#templates-and-parser-functions) - [For AI agents and LLMs](#for-ai-agents-and-llms) - [Comparison with other Markdown extensions](#comparison-with-other-markdown-extensions) - [Development](#development) - [Release notes](#release-notes) Get professional support for this extension via [Professional Wiki](https://professional.wiki), its creators and maintainers. We provide [MediaWiki Development](https://professional.wiki/en/mediawiki-development), [MediaWiki Hosting](https://pro.wiki), and [MediaWiki Consulting](https://professional.wiki/en/mediawiki-consulting-services) services. Installation ------------ [](#installation) Platform requirements: - [PHP](https://www.php.net) 8.1 or later - [MediaWiki](https://www.mediawiki.org) 1.43 or later Installation uses [Composer](https://getcomposer.org) with [MediaWiki's built-in support for Composer](https://professional.wiki/en/articles/installing-mediawiki-extensions-with-composer). On the command line, go to your wiki's root directory. Then run these two commands: ``` COMPOSER=composer.local.json composer require --no-update professional-wiki/native-markdown:~1.0 ``` ``` composer update professional-wiki/native-markdown --no-dev -o ``` Then enable the extension by adding the following to the bottom of your wiki's [LocalSettings.php](https://www.mediawiki.org/wiki/Manual:LocalSettings.php) file: ``` wfLoadExtension( 'NativeMarkdown' ); ``` For Markdown syntax highlighting in the editor, also install the [CodeEditor extension](https://www.mediawiki.org/wiki/Extension:CodeEditor): [![The wiki edit form with Markdown syntax highlighting](docs/screenshots/editor-markdown-highlighting.png)](docs/screenshots/editor-markdown-highlighting.png) For syntax highlighting of fenced code blocks in the rendered page, install the [SyntaxHighlight extension](https://www.mediawiki.org/wiki/Extension:SyntaxHighlight) (bundled with MediaWiki). When it is installed, a fenced block whose info string names a language is highlighted server-side with Pygments, exactly like a wikitext `` block; without it, code blocks render as plain preformatted text. ``` ```python def greet(name): print(f"Hello {name}") ``` ``` Configuration ------------- [](#configuration) New pages use the Markdown content model where the wiki's configuration says so. Defaults apply to page creation only; existing pages never change model implicitly. Individual pages can be switched between wikitext and Markdown (in both directions) via `Special:ChangeContentModel`. SettingDefaultEffect`$wgNativeMarkdownNamespaces``[]`Namespace IDs in which new pages default to Markdown, e.g. `[ NS_HELP ]``$wgNativeMarkdownEverywhere``true`New pages everywhere default to Markdown, the "Markdown wiki" mode (see exclusions below); set to `false` to keep wikitext as the default`$wgNativeMarkdownSuffixDetection``false`New pages whose title ends in `.md` default to Markdown, except in the Template and MediaWiki namespaces`$wgNativeMarkdownAllowExternalImages``false`Embed external `![alt](url)` images; when off they render as plain links`$wgNativeMarkdownWikitextExpansion``true`Run `{{...}}` on Markdown pages through the MediaWiki parser: templates, parser functions, magic words, and Lua modules. Set to `false` to leave `{{...}}` as literal text (see [Templates and parser functions](#templates-and-parser-functions))`$wgNativeMarkdownEverywhere` covers the whole prose wiki but deliberately leaves some pages as wikitext: the discussion (Talk), Template, and MediaWiki namespaces, namespaces whose content model is explicitly configured elsewhere, and titles ending in `.css`, `.js` or `.json`. `$wgNativeMarkdownSuffixDetection` reads the `.md` suffix as a deliberate per-page choice, so it also applies inside Talk namespaces. The [configuration documentation](https://professional.wiki/en/extension/native-markdown#Configuration) covers the exact semantics of both. ### Converting existing pages [](#converting-existing-pages) Those defaults apply at page creation only, so enabling suffix detection or adding a namespace never touches pages that already exist. The `NativeMarkdown:ConvertToMarkdownModel` maintenance script is the retroactive counterpart: it switches existing wikitext pages to the Markdown model using the very same rules, selecting pages via `--md-suffix` and/or `--namespace ` (combinable, at least one being required). It changes the content model, not the page text — the stored wikitext is then reinterpreted as Markdown and may render differently — so always start with `--dry-run`. Redirects are skipped, `--batch-size` controls how many pages each batch processes, and each conversion is an ordinary revision, reversible per page with `Special:ChangeContentModel`. The [configuration documentation](https://professional.wiki/en/extension/native-markdown#Configuration) covers the exact selector semantics. ``` php maintenance/run.php NativeMarkdown:ConvertToMarkdownModel --md-suffix --dry-run php maintenance/run.php NativeMarkdown:ConvertToMarkdownModel --namespace 3000 php maintenance/run.php NativeMarkdown:ConvertToMarkdownModel --md-suffix --namespace 10 ``` Templates and parser functions ------------------------------ [](#templates-and-parser-functions) Markdown pages can use MediaWiki's `{{...}}` syntax. Because expansion delegates to the wikitext parser, this covers the whole double-brace surface: templates (a wiki's shared infoboxes, citations and navboxes), parser functions (`{{#if:}}`, `{{#switch:}}`, and so on), magic words and variables (`{{PAGENAME}}`, `{{CURRENTYEAR}}`), and, where [Scribunto](https://www.mediawiki.org/wiki/Extension:Scribunto) is installed, Lua modules via `{{#invoke:}}`. Set `$wgNativeMarkdownWikitextExpansion = false` to turn this off and leave `{{...}}` as literal text. ``` {{Infobox person | name = Ada Lovelace | born = 1815 }} Ada Lovelace was an English **mathematician**, regarded as the first computer programmer. ``` Because it is the real parser, the same trust and resource model as wikitext applies: template dependencies are tracked, recursion and size limits apply, output is sanitized exactly as wikitext is, and enabling `{{...}}` grants a Markdown page the same capabilities a wikitext page has. Notably out of scope in this version: `` tags and transcluding Markdown pages with `{{:Page}}`. The [template documentation](https://professional.wiki/en/extension/native-markdown#templates) covers the placement rules (block versus inline calls, escaping) and the full scope notes. For AI agents and LLMs ---------------------- [](#for-ai-agents-and-llms) Markdown is the native read/write format of today's language models, and Native Markdown stores pages as exactly that: plain Markdown, no wikitext wrapper. That makes a Markdown page directly consumable and directly writable by an agent, with no lossy conversion step in either direction: - **Read the source** with `action=raw`: ``` GET /index.php?title=Release_Notes.md&action=raw ``` returns the raw Markdown, front matter and all, exactly the bytes an author typed. - **Read via the REST API**, which also reports the model: ``` GET /rest.php/v1/page/Release_Notes.md → { "content_model": "markdown", "source": "# Release Notes\n...", ... } ``` - **Read the rendered HTML** with `action=parse` (`?action=parse&page=Release_Notes.md&prop=text`), for when an agent wants the resolved links and table of contents rather than the source. - **Write** through the ordinary editing APIs (`action=edit`, the REST update endpoint) or, more conveniently, through the [MediaWiki MCP Server](https://github.com/ProfessionalWiki/MediaWiki-MCP-Server): an agent hands over Markdown and it is stored verbatim, rendered with full wiki integration on read. Because the round trip is lossless, an agent can fetch a page as Markdown, edit it, and write it back without the content drifting through a wikitext translation. Links work the way a model already writes them: a plain `[label](Page Name)` link whose target names a page resolves to an internal wiki link, spaces and all. The [usage documentation](https://professional.wiki/en/extension/native-markdown#Usage) covers link resolution and search indexing in detail. Comparison with other Markdown extensions ----------------------------------------- [](#comparison-with-other-markdown-extensions) Native Markdown exists because no maintained extension makes Markdown a native content model: - **[Extension:WikiMarkdown](https://www.mediawiki.org/wiki/Extension:WikiMarkdown)** embeds Markdown blocks inside wikitext pages via a tag, plus a shallow `.md`content handler with no working `[[wiki links]]`, categories, or table of contents inside the Markdown. - **[Extension:Markdown](https://www.mediawiki.org/wiki/Extension:Markdown)** is archived, and [MarkdownExtraParser](https://www.mediawiki.org/wiki/Extension:MarkdownExtraParser) has been unmaintained for over a decade. See the [full comparison](https://professional.wiki/en/extension/native-markdown#Comparison-with-other-Markdown-extensions) on our website for more detail. Related but different: our [ExternalContent extension](https://github.com/ProfessionalWiki/ExternalContent) embeds Markdown *files from external sources* (like GitHub) into wikitext pages, while Native Markdown is for the wiki's own pages being Markdown. They compose nicely. Development ----------- [](#development) The Application layer (the whole Markdown pipeline) has no MediaWiki dependencies, so the unit suite runs standalone in the extension directory with no MediaWiki install: ``` composer install composer test ``` Style checks and static analysis, also standalone: `composer cs`, `composer phpstan`, `composer psalm`. The full suite including integration tests runs inside a MediaWiki install, from the MediaWiki root: ``` php tests/phpunit/phpunit.php extensions/NativeMarkdown/tests/phpunit/ ``` Release notes ------------- [](#release-notes) ### Version 1.2.0 - 2026-07-17 [](#version-120---2026-07-17) - A `ConvertToMarkdownModel` maintenance script converts existing wikitext pages to the Markdown content model, selecting them by `.md` suffix and/or namespace, the same way the activation settings select new pages. It changes the content model rather than the page text, skips redirects, and supports `--dry-run` - Fenced code blocks whose info string names a language are now syntax highlighted, the same way a wikitext `` block is. This needs the [SyntaxHighlight extension](https://www.mediawiki.org/wiki/Extension:SyntaxHighlight) (bundled with MediaWiki) to be installed; without it, code blocks keep rendering as plain preformatted text - Code blocks no longer get a background pill behind each of their lines, which happened because skins style the `code` element for inline use and CommonMark nests it inside `pre` - A `thumb` file embed alone on its line now renders as a standalone framed thumbnail rather than being wrapped in a paragraph, which produced invalid HTML5 and a stray empty paragraph - A `thumb` embed of a missing file now renders the framed box with its caption and an upload link, the way wikitext does, instead of a bare upload link that silently dropped the caption - Thumbnail embeds now load the same media module MediaWiki loads for wikitext thumbnails, so their magnify affordance works ### Version 1.1.0 - 2026-07-09 [](#version-110---2026-07-09) - Standard Markdown `[label](target)` links now resolve to wiki pages, the same as `[[target]]`: a target that names a page (rather than a URL) becomes an internal link, with red/blue styling and link-table registration. Multi-word targets work directly, e.g. `[the guide](Help:Getting Started)`. Real URLs stay external links. ### Version 1.0.1 - 2026-07-07 [](#version-101---2026-07-07) - Redirect pages now render and register the content after the `#REDIRECT [[Target]]` line, so redirect categories (and any other trailing links or prose) work the same as on wikitext redirects ### Version 1.0.0 - 2026-07-07 [](#version-100---2026-07-07) Initial release for MediaWiki 1.43+ with these features: - Markdown content model (`markdown`) rendering CommonMark + GitHub Flavored Markdown with footnotes - Wikitext link syntax inside Markdown: internal links, section links, categories, file embeds, interwiki - MediaWiki integration: table of contents, red/blue links, link tables, WhatLinksHere, WantedPages/Files - Clean full-text search: rendered prose is indexed, not raw markup; front matter excluded - YAML front matter parsed, hidden from output and stored as page metadata - Per-page model switching via `Special:ChangeContentModel`, namespace/suffix/wiki-wide activation modes - MediaWiki `{{...}}` expansion (on by default): templates, parser functions, magic words and Lua run through the real parser with dependency tracking; opt out with `$wgNativeMarkdownWikitextExpansion = false` - XSS-safe by construction: raw HTML escaped, unsafe links blocked, external images off by default - `action=raw` / REST return the stored Markdown byte for byte, built for AI agents and git round-trips - CodeEditor syntax highlighting on Markdown pages Initial release announcement: ### Health Score 43 — FairBetter than 89% of packages Maintenance88 Actively maintained with recent releases Popularity18 Limited adoption so far Community11 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 90.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~3 days Total 4 Last Release 36d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/451bd4039d530fed8f9c3da91bfa519233a397d2182cdfdcad700f6cfea19b7f?d=identicon)[Jeroen De Dauw](/maintainers/Jeroen%20De%20Dauw) --- Top Contributors [![JeroenDeDauw](https://avatars.githubusercontent.com/u/146040?v=4)](https://github.com/JeroenDeDauw "JeroenDeDauw (40 commits)")[![translatewiki](https://avatars.githubusercontent.com/u/24829418?v=4)](https://github.com/translatewiki "translatewiki (3 commits)")[![kghbln](https://avatars.githubusercontent.com/u/1104078?v=4)](https://github.com/kghbln "kghbln (1 commits)") --- Tags markdownmarkdown-editormediawikimediawiki-extensionmediawikimarkdowncommonmarkwikicontent modelGitHub Flavored Markdown ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Psalm Type Coverage Yes ### Embed Badge ![Health badge](/badges/professional-wiki-native-markdown/health.svg) ``` [![Health](https://phpackages.com/badges/professional-wiki-native-markdown/health.svg)](https://phpackages.com/packages/professional-wiki-native-markdown) ``` ### Alternatives [helsingborg-stad/municipio A bootstrap theme for creating municipality sites. 4028.6k10](/packages/helsingborg-stad-municipio)[tempest/framework The PHP framework that gets out of your way. 2.3k37.6k21](/packages/tempest-framework)[statamic/cms The Statamic CMS Core Package 4.9k3.8M1.2k](/packages/statamic-cms)[october/rain October Rain Library 1601.7M103](/packages/october-rain)[jason-munro/cypht Lightweight Open Source webmail written in PHP and JavaScript 1.7k160.6k](/packages/jason-munro-cypht)[contao/core-bundle Contao Open Source CMS 1301.7M3.1k](/packages/contao-core-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)