With your coding agent
Migrate from Docusaurus, MkDocs, Fern, Nextra, Notion, Confluence or a live site by handing the job to Claude Code, Codex, Cursor or Gemini. The agent follows this guide and checks its work with typemark check.
Updated Nov 19, 20264 min read
For platforms Typemark doesn't import automatically, your coding agent does the conversion. The Typemark CLI starts it in your folder with this page as its instructions, and the agent keeps going until typemark check passes.
The agent runs on your computer, under your own login with your agent's provider. Your content doesn't pass through Typemark until you push it.
Run it
Install the CLI and your agent
npm install -g @gettypemark/cliYou also need one of these agents installed and signed in: Claude Code (
claude), Codex (codex), Cursor's CLI (cursor-agent) or Gemini CLI (gemini).Start the migration
Make an empty folder for your new site and run the migration from it, pointing
--sourceat your old docs: a folder, a Git repository or the address of the live site.mkdir my-docs && cd my-docs typemark migrate --agent claude --source ../old-docsUse
--agent codex,--agent cursoror--agent geminifor the others. Add--from gitbook,--from readmeor--from mintlifywhen you're finishing one of those imports.Review and publish
When the agent is done, it lists what didn't carry over. Preview the site with
typemark dev, then publish it:typemark login typemark create "My Docs" # creates the project and links this folder typemark push --prune --wait
Using another agent? Run typemark migrate --guide to print the instructions, and paste them into it.
The guide your agent follows
The rest of this page is written for the agent. It's also a good checklist if you migrate by hand.
Goal
Turn the source docs into a Typemark site in the current folder: a typemark.json at the root and one .mdx file per page. Keep every page, keep the page URLs where possible, and finish only when typemark check reports no errors.
Rules
- Never change the source. Read from
--source; write only in the current folder. - Use
typemark migratefirst when the source is Mintlify, GitBook or ReadMe. It converts most of the site; you finish the rest. - Keep URLs. A page at
/guides/authon the old site goes toguides/auth.mdx. When a path has to change, add a redirect intypemark.json. - Content only. Typemark never runs code from a page. Remove
importandexportstatements, and turn custom React components and JavaScript expressions into Markdown or the components below. Literal props such ascols={3}are fine. - Don't invent content. Copy text as it is. If something can't be converted, leave a short note in your final report instead of guessing.
- Save a live site first. When the source is a URL, download every page you need into a scratch folder before converting, then work from those files.
Steps
-
Inventory. List every page in the source and its URL. Find the navigation:
sidebars.js(Docusaurus),mkdocs.ymlnav(MkDocs),docs.yml(Fern),_meta.jsonfiles (Nextra), the sidebar in.vitepress/config(VitePress), or the folder structure of an export. -
Write
typemark.json. Tabs hold groups, groups hold pages, and a page is its path without the extension:{ "$schema": "https://typemark.dev/schema.json", "name": "Acme Docs", "colors": { "primary": "#4f46e5" }, "navigation": { "tabs": [ { "tab": "Documentation", "groups": [ { "group": "Getting started", "pages": ["introduction", "quickstart"] }, { "group": "Guides", "pages": ["guides/auth", "guides/webhooks"] } ] }, { "tab": "API Reference", "groups": [{ "group": "Endpoints", "pages": [{ "source": "openapi.yaml" }] }] } ] }, "redirects": [{ "from": "/old-path", "to": "/new-path" }] }Groups don't nest: put a nested section's pages in its own group, right after its parent. See typemark.json and Navigation.
-
Convert each page to
.mdxwith frontmatter.titleis required; the site shows it as the page heading, so remove a first# Headingthat repeats it. Adddescriptionwhen the source has one.--- title: Authentication description: Authenticate requests with an API key. --- -
Map components with the table below.
-
Move images into
images/(or keep their folder) and update the links. Download images hosted on the old platform's servers. -
Move translations, if the source has any (such as Docusaurus's
i18n/<locale>/folders): list the languages underlanguagesintypemark.json, the default language first, and put each translated page at<code>/<page>.mdx, the same path as the page it translates under a folder named after its language code. Don't add translations to navigation. See Languages. -
Check with
typemark checkand fix every error. Repeat until it passes. Preview withtypemark devif you can. -
Report what didn't carry over: pages skipped, components you simplified, redirects added.
Components
| In the source | In Typemark |
|---|---|
Admonitions: :::note, :::tip, :::warning, :::danger (Docusaurus, VitePress), !!! note (MkDocs), > [!NOTE] (GitHub) | <Callout type="info">, type="tip", type="warning" or type="danger". Add title="…" for a custom title |
| Tabs | <Tabs> with <Tab title="…"> children |
| Tabbed code blocks | <CodeGroup> with one fenced block per tab, each with a title: ```bash npm |
| A code block with a file name | ```js title="index.js" |
Collapsible sections, <details> | <Accordion title="…">; several in a row go in <AccordionGroup> |
| Numbered walkthroughs | <Steps> with <Step title="…"> children |
| Link cards and tiles | <Card title="…" icon="…" href="/path"> inside <CardGroup cols={2}> |
| Images with captions | <Frame caption="…"><img src="/images/x.png" alt="…" /></Frame> |
| API parameters | <ParamField query="name" type="string" required>, or path, header or body in place of query |
| Response fields | <ResponseField name="…" type="…"> |
| Changelog entries | <Update label="March 2026"> |
| Badges | <Badge>Beta</Badge> |
| OpenAPI specs | Copy the spec into the folder and add { "source": "openapi.yaml" } to navigation |
| Anything else | Plain Markdown that keeps the meaning |
Icons are Heroicons names, such as rocket-launch. Full syntax for each component is under MDX Components in the sidebar, for example Callouts and Cards.
Done when
typemark checkreports no errors.- Every page in the inventory is in navigation, redirected, or listed in your report.
- The source folder is unchanged.