Migrating a Wiki Is a Translation Problem, Not a Copy-Paste

When I moved a body of documentation out of one wiki and into a plain-markdown notes system, I assumed it would be an export-then-import chore. It wasn’t. The export is trivial; the translation is the whole job. A page isn’t just text — it’s text plus structure: code blocks with languages, callout panels, internal links, expandable sections, tables. Dump that as raw markup and you get a technically-migrated, practically-unusable mess. Treat it as a translation between two systems’ idioms and you get docs that actually belong in their new home.

First, know which direction you’re going

The very first thing to get straight, because it determines all your tooling: are you pulling content in or pushing it out? “Migrate the wiki” is ambiguous, and the two directions use completely different tools. Ingress (source wiki → your notes) is a read-and-convert job. Egress (your notes → some published wiki or site) is a publish job with entirely different plumbing. People conflate them constantly and then wonder why the tool they grabbed does the opposite of what they need. Name the direction first; pick the tool second.

Translate the structure, don’t dump the markup

Here’s where most migrations go wrong. A source page expresses meaning through its own constructs — an “info panel,” a fenced code block tagged with a language, an internal link, a collapsible section. The target system has equivalents for almost all of them. The quality of the migration is entirely about whether those constructs get translated into the target’s idioms or dumped as raw, broken markup:

• A source’s info/warning/note panels should become the target’s native callouts, not a wall of leftover HTML.
• Code blocks should keep their language tag, so syntax highlighting survives.
• Internal page links should become the target’s link form — in a wiki-link system, real links you can navigate, not dead URLs to the old system.
• Collapsible/expand sections should map to the target’s equivalent, not flatten into an undifferentiated blob.

The difference between a migration that’s usable and one that’s technically-complete- but-dead is whether the structure came across, not whether the text did.

If you’re driving the conversion with an LLM or an agent — which is a great fit for this — the single biggest lever on quality is naming these mappings explicitly in the instructions. “Convert this page” gets you a dump; “map panels to callouts, keep code languages, turn internal links into wiki-links, expand sections become collapsible blocks” gets you a real translation. The model can do the work; it just needs to know the target’s idioms, which it won’t infer from a vague ask.

Keep the provenance

A migrated page that’s lost track of where it came from is a future mystery. So every converted note should carry a link back to its source — a source: field or a small footer. It costs nothing at conversion time and it answers the question that always comes up later: “is this current, and where do I check?” Migration is also the perfect moment to add the target’s conventions — its frontmatter, its tags, its folder placement — so the imported content arrives already looking native instead of like an obvious transplant.

Migration is the moment to review for secrets

This one is non-negotiable and easy to skip in the rush to move volume: internal wiki pages are full of things that shouldn’t necessarily travel — credentials pasted into a runbook, tokens, customer data, the occasional password in a “temporary” note someone never cleaned up. A bulk migration will faithfully carry all of it into the new system, and if the new system is more visible (or you later publish from it), you’ve just widened the exposure.

So a migration needs a review gate: before content lands — and especially before any of it gets published — scan for secrets and sensitive data and strip or quarantine it. When I drive a bulk migration with an agent, I have it flag likely-sensitive pages for me to review rather than silently importing everything. It’s the same discipline as keeping secrets out of git: the moment content changes homes is exactly when a leak sneaks in, because nobody’s reading 400 pages line by line.

Bias toward updating, not duplicating

The last trap is volume for its own sake. A migration that mechanically creates a new note per source page, with no thought to what already exists, just rebuilds the source’s sprawl in a new system — and often duplicates notes you already wrote. Before converting, it’s worth a planning pass: how does the source’s structure map onto the target’s, which pages should merge, which should split, and is there already a note covering this that should be updated instead of duplicated? Migrating is a chance to improve the organization, not just relocate the mess.

Done well, a doc migration is a translation and a cleanup, not a bulk copy: name the direction, translate the structure into the target’s idioms, preserve provenance, gate on secrets, and consolidate as you go. The export button is the easy 10%; the other 90% is making the content actually belong where it landed. It’s documentation as infrastructure applied to a move — the docs are only worth migrating if they’re usable when they arrive. If you’re staring down a wiki migration and want to compare approaches, I’m easy to reach.