How to Migrate from WordPress to MediaWiki: A Complete Guide

Moving a content site from WordPress to MediaWiki is a deliberate migration, not a one-click switch — but it is very doable with the right sequence. WordPress is a blogging/CMS platform; MediaWiki is a collaborative knowledge platform. If your need is hundreds of editors, granular page history, or structured data via templates and forms, the move makes sense. If you run a blog with a handful of authors and strong SEO dependencies, weigh it twice — the benefits come from collaboration, not from hosting. This guide covers the complete, verified path: export, conversion, import, media, URLs and users.

Before you start

1. Back up everything — MySQL dump, wp-content/, and the exported XML
2. Inventory the content — decide what maps: posts → articles, pages → mainspace pages, categories/tags → MediaWiki categories, comments → either drop them or import them into talk pages (manual job; usually not worth it)
3. Audit extensions and shortcodes — list every WordPress plugin that changes content (gallery, embeds, custom shortcodes). Each one needs a MediaWiki counterpart or a content fix; this audit decides the real effort
4. Set up a test wiki — a fresh MediaWiki instance (Docker or a scratch virtual host) with the extensions you plan to use: ParserFunctions, VisualEditor, ReplaceText (for post-import link fixes), optionally Page Forms and a structured-data backend
5. Plan URLs — old permalinks (/2022/09/post-title/) will 404 unless you map them; a redirect map or matching URL structure in MediaWiki is part of the job

Step 1 — Export from WordPress

WordPress ships a built-in exporter: Tools → Export → All content, which produces a WXR XML file containing posts, pages, categories, tags and comments. For large sites the web UI can time out — use WP-CLI instead:

wp export --dir=./exports --post_type=any --skip_comments

Step 2 — Convert HTML to wikitext

MediaWiki cannot read WXR directly. The conversion step turns each post's HTML body into wikitext. Writing a full converter by hand is error-prone; use a mature converter for the bulk work:

• pandoc — the reliable workhorse: pandoc -f html -t mediawiki article.html -o article.wiki. It handles headings, lists, tables, links and bold/italic reliably
• For the long tail (shortcodes, embeds, gallery markup), a small script pass after pandoc fixes what the converter cannot — typical cases: gallery blocks to <gallery>, embedded iframes to plain links, custom shortcodes deleted or rewritten

Decide per-page mapping (posts vs pages) here, and preserve the original publication dates — they matter for both archives and SEO. Build the import file from the converted pages.

Step 3 — Import into MediaWiki

MediaWiki imports XML dumps; there is no WXR importer. Two options:

• Build a MediaWiki XML dump from your converted pages — a page element per article with title, timestamp and wikitext — then run the import script:

php maintenance/importDump.php mediawiki-import.xml --username=ImportBot

• Special:Import — the in-browser importer, fine for a few dozen pages, not for thousands

The XML dump format is documented on mediawiki.org (mediawiki root element, page/revision/text hierarchy); a small generator script produces it from your conversion output. Import into the test wiki first, always.

Step 4 — Media assets

Copy the uploads into MediaWiki's image directory, then register them — copying alone is not enough, MediaWiki must create the file records and thumbnails:

rsync -av /var/www/wordpress/wp-content/uploads/ /var/www/mediawiki/images/
php maintenance/importImages.php /var/www/mediawiki/images --search-recursively

importImages.php walks the directory, creates the file pages with metadata and preserves timestamps when the files carry them. Check $wgFileExtensions / $wgTrustedMediaFormats if your site hosts file types outside the defaults (SVG, PDF, audio), so uploads are not rejected after the import.

Step 5 — Fix links, URLs and navigation

• Internal links — old perma-URLs embedded in content are fixed in bulk with the ReplaceText extension; alternatively keep a redirect map at the web-server level (nginx/Apache rewrite) from old permalinks to the new page titles
• Categories — map WordPress categories/tags to MediaWiki categories: add [[Category:Name]] to imported pages (a script or bot pass), then build the category taxonomy rather than recreating the WordPress menu
• Navigation — MediaWiki navigation lives in MediaWiki:Sidebar; recreate the essentials there instead of a theme's menu

Step 6 — Users and permissions

WordPress password hashes (phpass) are not compatible with MediaWiki's password storage, so do not try to copy user tables. Practical options:

• Recreate accounts — import users via a script (usernames + emails) and let them reset passwords
• Single sign-on — if the organization already has LDAP/AD or SAML, use the LDAP or OIDC/SAML extensions so the wiki authenticates against the existing identity provider
• Assign groups via Special:UserGroupRights to mirror your old roles

Step 7 — Go-live checks

• Sample audit — open a random sample of pages; check headings, links, images and tables render correctly
• Search — configure a proper search backend (CirrusSearch with Elasticsearch/OpenSearch, or at minimum enable the built-in search) before pointing users at it
• Redirects — verify old URLs: either 301 to new titles or serve a custom 404 with a search box
• Cleanup — decommission the WordPress install only after the redirect map and the sample audit pass

Configuration notes

Two configuration names people get wrong after migration: uploads are controlled by $wgEnableFileUploads (the old $wgEnableUploads name is deprecated), and structured forms are enabled by installing the Page Forms extension (wfLoadExtension( 'PageForms' )), not by a global variable.

Common pitfalls

• Importing into the live database — importDump.php writes to whatever wiki it runs on; always import into the staging instance first
• Shortcode drift — undetected WordPress shortcodes leave raw text like [gallery ids=12,13] on pages; run a sweep for bracket patterns before go-live
• Unicode/encoding — ensure the WXR and intermediate files are UTF-8; check the XML declares encoding='UTF-8'
• Trailing 404s from rewrites — WordPress ships .htaccess rules that make no sense on MediaWiki; do not carry them over

The migration is a sequence of four mechanical steps — export, convert, import, rewire — with content auditing as the real work. Wikitext conversion quality, shortcode mapping and the URL redirect map decide how much manual cleanup remains. Budget for it, stage on a test wiki, and the result is a knowledge platform that grows with its editors.