Migration Guide

Documentation frameworks share more than they differ. They all read Markdown, they all map a file path to a URL, they all have a navigation structure, and they all end up as static files. That overlap is what makes migration a tractable problem rather than a rewrite: the prose almost always survives, and what has to be replaced is the small set of things specific to the tool you are leaving.

The two things that break in a migration are URLs and links. A framework change is usually also a change of URL scheme, and if the old URLs stop resolving, every external link ever published becomes a dead reference. Everything else is work; that is an incident.

What moves and what does not

The content moves almost unchanged: the prose, the code blocks, and the tables need no editing. Three categories need attention.

Frontmatter is the first. Each tool reads a slightly different set of keys, and the ones a tool does not recognise are ignored rather than rejected, so a stale key is usually harmless while a missing key is usually not.

Call-outs are the second. Every tool has an admonition syntax and no two of them agree on the punctuation. The shapes are similar enough to convert mechanically once you know the target syntax.

Navigation is the third, and the only one that is genuinely design work: the source tool may have derived the sidebar from the file tree while the destination wants an explicit list, or the other way round.

Converting frontmatter and call-outs

The frontmatter keys that matter in practice, and what they become:

MeaningMkDocsVitePressDocusaurusStarlight
Page titletitletitletitletitle
Summarydescriptiondescriptiondescriptiondescription
Position in the sidebarorder in the nav configorder in the sidebar configsidebar_positionorder in the sidebar frontmatter settings
Draftdraft: truedraft: truedraft: truedraft: true
Stable identifierfile pathfile pathidfile path

The call-out syntaxes, which are the part people search for when they are halfway through a migration:

ToolCall-out syntax
MkDocs!!! note followed by indented content
VitePress::: note followed by indented content
Docusaurus:::note followed by indented content
Starlight:::note, or a GitHub-flavored > [!NOTE] blockquote

Note how close the first three are: two colons and a word, with the content indented beneath. A conversion is a regular expression over three lines; the interesting case is a nested code block inside a call-out, where the indentation must be preserved exactly.

Preserving URLs

Two approaches exist.

The first is to keep the URL structure identical. The default URL shapes differ between the tools, so this is a decision rather than a freebie:

ToolDefault URL for docs/installation.md
MkDocs/installation/ (a directory-style URL)
VitePress/installation.html (the extension is kept)
Docusaurus/docs/installation (extensionless)
Astro Starlight/installation/ (a directory-style URL)

MkDocs can be switched to flat .html paths, and VitePress to extensionless links when the hosting platform supports it, so a move between those two is usually a no-op for external links as long as the file tree is preserved. Moving to Docusaurus or Starlight changes the prefix, because Docusaurus mounts its documentation under a route prefix and Starlight builds its own route tree. That is where a redirect map becomes necessary.

The second approach is to accept new URLs and publish redirects. Every static host has a way to do this: a redirect rules file that the platform reads, or an entry in the deployment manifest. The redirect map is the deliverable that matters, and it should be generated from the old build output rather than written by hand — take the list of built pages from the old site and the list from the new one and pair them by content. Generate that map, put it in version control, and test it: a migration script that leaves it in a working directory is a migration that will be broken by the next person.

A staged migration

The reliable sequence looks like this.

Move the content first, with the old site still live. Copy the Markdown files into the new structure, convert the frontmatter and the call-outs, and do not touch the prose. Build the new site and put it on a staging host under a path that nobody links to.

Compare the two side by side, page by page. A script that walks the old build and the new build and diffs the visible text of each page catches most migration mistakes in minutes: a page that was dropped, a call-out that lost its content, a table that lost a column, a code block that came out as a paragraph. Only after the two match does the destination become the production site, and only then do the redirects go live.

Check the things that are easy to forget. Search: the new build’s index has to cover every page, and a page that was reachable before but is not reachable now is a silent loss. Navigation: pages orphaned from the old sidebar are still reachable by URL and are now invisible, and a link checker that only follows navigation will not find them. Images and downloads are the most commonly missed, because they are referenced by a path rather than by a page.

The migrations that need more than a script

Two moves are qualitatively harder than the rest.

Moving to Docusaurus from anything else means taking on its model, where content lives in a plugin-owned directory, the sidebar is an explicit JavaScript structure, and documents are MDX. A document containing a stray brace or an HTML tag that Markdown does not allow will fail to build, which is a good thing: it turns an invisible rendering difference into a compile error.

Moving away from Docusaurus is harder still, because of versioning. Its versioned snapshots are a directory tree with a specific layout and generated version identifiers; there is no automatic conversion, and the version switcher is a component you will have to rebuild in the destination tool.

Moving to MkDocs or to Starlight from a JavaScript framework is usually the easiest, because both are Markdown-first and neither expects the content to contain components. The work is in the frontmatter and the call-outs, and in any inline component, which has to become a code sample, a screenshot, or a link.

What to take away

Migration is a mechanical problem with one genuinely manual part, and the manual part is the redirect map. Move the content, convert the syntax, build both sites, diff them against each other, and only then switch over. What makes the difference between a smooth migration and an incident is whether you noticed the URLs before the links broke.

More courses

Recommended courses

Found an issue with this content?

Tell us what could be improved.