Typemark Documentation

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

  1. Install the CLI and your agent

    npm install -g @gettypemark/cli

    You also need one of these agents installed and signed in: Claude Code (claude), Codex (codex), Cursor's CLI (cursor-agent) or Gemini CLI (gemini).

  2. Start the migration

    Make an empty folder for your new site and run the migration from it, pointing --source at 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-docs

    Use --agent codex, --agent cursor or --agent gemini for the others. Add --from gitbook, --from readme or --from mintlify when you're finishing one of those imports.

  3. 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 migrate first when the source is Mintlify, GitBook or ReadMe. It converts most of the site; you finish the rest.
  • Keep URLs. A page at /guides/auth on the old site goes to guides/auth.mdx. When a path has to change, add a redirect in typemark.json.
  • Content only. Typemark never runs code from a page. Remove import and export statements, and turn custom React components and JavaScript expressions into Markdown or the components below. Literal props such as cols={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

  1. Inventory. List every page in the source and its URL. Find the navigation: sidebars.js (Docusaurus), mkdocs.yml nav (MkDocs), docs.yml (Fern), _meta.json files (Nextra), the sidebar in .vitepress/config (VitePress), or the folder structure of an export.

  2. 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.

  3. Convert each page to .mdx with frontmatter. title is required; the site shows it as the page heading, so remove a first # Heading that repeats it. Add description when the source has one.

    ---
    title: Authentication
    description: Authenticate requests with an API key.
    ---
  4. Map components with the table below.

  5. Move images into images/ (or keep their folder) and update the links. Download images hosted on the old platform's servers.

  6. Move translations, if the source has any (such as Docusaurus's i18n/<locale>/ folders): list the languages under languages in typemark.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.

  7. Check with typemark check and fix every error. Repeat until it passes. Preview with typemark dev if you can.

  8. Report what didn't carry over: pages skipped, components you simplified, redirects added.

Components

In the sourceIn 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 specsCopy the spec into the folder and add { "source": "openapi.yaml" } to navigation
Anything elsePlain 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 check reports no errors.
  • Every page in the inventory is in navigation, redirected, or listed in your report.
  • The source folder is unchanged.