Migrating wikis is rarely fun. Source wiki has its quirks; target wiki has its own. Pages have history, links, attachments, formatting that may not translate cleanly.
This page covers the patterns for surviving wiki migrations.
MediaWiki → Confluence; Confluence → Notion; Markdown-in-git → SaaS wiki.
The hardest. Different content models, different feature sets.
On-premises Confluence to Confluence Cloud; self-hosted MediaWiki to a managed service.
Less hard; same platform but different deployment.
The reverse — usually data exodus from a vendor.
Often time-pressured (vendor changes terms; price increase; outage). Plan for it.
Merging multiple wikis into one. Multiple sources; one target.
Often involves deduplication, conflict resolution, link rewriting.
Wiki-specific markup that doesn't have an equivalent in the target. Tables, callouts, embedded macros.
Source wiki has a custom macro that displays a calendar. Target wiki doesn't. Page now broken.
YouTube videos, Twitter embeds, etc. Embedding methods vary; may break.
Some wikis have explicit hierarchy (Confluence); some don't. Mapping isn't always clean.
Inline references to attached files. URL structure changes; references break.
Source has fine-grained permissions; target's model is different. Hard to translate exactly.
Edit history may not migrate at all. Or migrates as a single "imported" entry.
For most platforms, accepting some history loss is realistic.
What's in the source?
Most migrations have surprises. Discovery surfaces them.
Migrate a small subset (10-50 pages). See what breaks.
Iterate on the migration tool until the pilot is acceptable.
Run the migration at scale. Probably overnight or weekend. Monitor for errors.
Spot-check pages. Use analytics to verify high-traffic pages.
Old wiki URLs likely don't match new ones. Either:
Without this, links throughout the new wiki break.
For a period, both old and new wikis available. Users transition. Old wiki marked read-only; eventually decommissioned.
Old wiki goes away. Final backup; archive; remove.
Many platforms ship migration tools: Confluence has importers; MediaWiki has dump tools.
Check what's available for the source-target combination.
Converts between document formats. For markdown, MediaWiki, AsciiDoc, etc., pandoc handles much of the format translation.
For complex migrations, custom code reads source; writes target. Time investment but flexibility.
Some companies specialize in wiki migrations. Worth it for large complex migrations; overkill for small.
Migrate clean content; don't carry forward dead pages, broken links, deprecated content.
Pre-migration audit: delete what's not worth migrating.
Source format → target format mappings. Where the source has X, what's the equivalent target?
Spot the gaps where there's no equivalent.
Before migrating production content, test pages with known features:
See what works.
Keep page slugs the same. External bookmarks survive.
If URLs must change, redirects are essential.
Users need to know:
Sometimes pages are bad enough that rewriting is better than migrating. The "garbage in, garbage out" problem — bad source content stays bad in the target.
For high-traffic pages: consider rewriting during migration.
For typical wiki migrations:
Plan for the timeline. Migrations always take longer than estimated.