Skip to content

Add a maintenance script to convert existing pages to the markdown content model #40

Description

@kghbln

Situation

$wgNativeMarkdownSuffixDetection (like the other activation settings) applies at page creation only: the ContentHandlerDefaultModelFor hook fills in a default model just for pages that do not exist yet, and existing pages keep their stored model. Enabling suffix detection or adding a namespace to $wgNativeMarkdownNamespaces on a wiki that already has matching pages therefore leaves those pages on wikitext, with no way to migrate them in bulk.

Use case (from MediaWiki-l, July 2026): wikis where AI agents participate keep agent instructions in pages like Project:AGENTS.md or User:SomeUser/CLAUDE.md, created via the API or MCP tooling before the setting was enabled. The stored text of those pages is already Markdown; only the content model is wrong, so they render as wikitext.

What exists today: MediaWiki core ships changeContentModel.php, which converts one page per invocation:

php maintenance/run.php changeContentModel --title 'User:SomeUser/CLAUDE.md' --model markdown

That is a workable stopgap for a handful of pages, but it does not scale to a sweep and applies none of the extension's namespace policy.

Requested feature

A maintenance script with two selectors that mirror the two activation settings and can be combined (at least one required):

# all .md-suffixed pages — the retroactive counterpart to $wgNativeMarkdownSuffixDetection
php maintenance/run.php NativeMarkdown:convertToMarkdownModel --md-suffix

# every page in one namespace — the retroactive counterpart to $wgNativeMarkdownNamespaces
php maintenance/run.php NativeMarkdown:convertToMarkdownModel --namespace 3000

# only .md-suffixed pages within one namespace
php maintenance/run.php NativeMarkdown:convertToMarkdownModel --md-suffix --namespace 3000

Selection rules:

  1. Only pages whose current content model is wikitext are candidates; pages with any other model are never touched.
  2. --md-suffix applies the same namespace rules as live suffix detection, ideally by reusing MarkdownDefaultPolicy so script and hook cannot drift: Template and MediaWiki namespaces are skipped, Talk namespaces are included (the suffix rule deliberately covers them).
  3. --namespace mirrors the $wgNativeMarkdownNamespaces semantics: explicitly naming a namespace is a deliberate per-namespace choice, so it works for any namespace.

The conversion itself works the way core's script does: a new revision with unchanged text and an edit summary, attributed to a maintenance user. Useful options: --dry-run to list the affected pages without changing anything, plus batching/throttling for large wikis.

One caveat the script and its documentation should state clearly: it changes the content model, it does not convert syntax. A page whose stored text is real wikitext will render differently after conversion. That risk is small for .md-titled pages and real in namespace mode, so running --dry-run first should be the documented workflow.

Actual wikitext-to-Markdown syntax conversion, e.g. for migrating a whole existing wiki after enabling $wgNativeMarkdownEverywhere, is a different and much larger feature and intentionally out of scope here.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions