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

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

<Steps>
  <Step title="Install the CLI and your agent">
    ```bash
    npm install -g @gettypemark/cli
    ```
    You also need one of these agents installed and signed in: [Claude Code](https://claude.com/claude-code) (`claude`), Codex (`codex`), Cursor's CLI (`cursor-agent`) or Gemini CLI (`gemini`).
  </Step>
  <Step title="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.

    ```bash
    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.
  </Step>
  <Step title="Review and publish">
    When the agent is done, it lists what didn't carry over. Preview the site with `typemark dev`, then publish it:

    ```bash
    typemark login
    typemark create "My Docs"    # creates the project and links this folder
    typemark push --prune --wait
    ```
  </Step>
</Steps>

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:

    ```json title="typemark.json"
    {
      "$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](https://docs.typemark.dev/configuration/typemark-json) and [Navigation](https://docs.typemark.dev/configuration/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.

    ```mdx
    ---
    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](https://docs.typemark.dev/configuration/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 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](https://heroicons.com) names, such as `rocket-launch`. Full syntax for each component is under **MDX Components** in the sidebar, for example [Callouts](https://docs.typemark.dev/components/callouts) and [Cards](https://docs.typemark.dev/components/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.
