Get started
Migrating an existing docs site
What carries over unchanged from a docs.json-based site, what to check, and how to cut over without downtime.
What carries over unchanged from a docs.json-based site, what to check, and how to cut over without downtime.
Papervine reads the same docs.json + MDX format used by other documentation platforms. For
most repositories, migrating means connecting the repo and changing a DNS record — the
content itself doesn’t change.
Connect the repository as a new site. You get a complete, working copy at a Papervine address while your current site keeps serving its own traffic untouched. Nothing about migrating is irreversible until you move DNS.
Better still, run it locally first and change nothing at all:
npx papervine dev
MDX files render as-is. Frontmatter, headings, links, images and code blocks behave the same.
docs.json groups, tabs, and anchors are read directly. No re-authoring.
Callouts, cards, tabs, steps, accordions, code groups and frames are all supported.
An OpenAPI spec still generates one page per operation, with a live “Try it” panel.
Migration is usually uneventful, but these are the things worth a look:
Components from the long tail. The common set is supported. Something unusual renders as its contents rather than failing — you get a plainer block, not a broken page. Skim your most component-heavy pages and see if anything reads oddly.
Config keys that aren’t acted on yet. Unknown keys are accepted with a warning rather than rejected, so your site builds either way — but a setting that silently does nothing is worth knowing about. The config reference lists what’s honored.
Redirects. If your current platform maintains a redirect map, that doesn’t come across automatically. Inventory it before cutover so old inbound links keep landing.
Anything generated by your old platform’s CLI. Files it produced from other sources aren’t reproduced by connecting the repo.
A fast, high-signal check: connect the repo, then click through your ten most-visited pages side by side with the current site. That finds real problems far quicker than reading a compatibility list.
Your existing site keeps serving. Nothing is affected yet.
Compare your highest-traffic pages, your API reference, and search results.
Enter the custom domain and let the certificate issue before you change DNS. Doing it in this order means the certificate is ready when traffic arrives. See using your own domain.
Point the record at Papervine. Readers move over as the change propagates; there’s no moment where the domain serves nothing.
Leave it running for a day or two. If anything surfaces, reverting is a DNS change back.
Beyond parity, connecting the repo turns on things that need no authoring work:
Papervine renders MDX plus a docs.json. Coming from a different system — a static site
generator, a wiki, a Word-shaped process — the content itself is the work, and the shape to
convert to is one .mdx file per page with title and description frontmatter, plus a
docs.json listing them. Writing content covers the target format.