# Migrating to Typemark

> Bring your docs from Mintlify, GitBook, ReadMe or anywhere else. Import a GitHub repository, convert a folder with the CLI, or let your coding agent do the rest.

Typemark reads the files your current platform already keeps in Git and converts them. Your pages keep their content and their URLs, and the import tells you exactly what it couldn't carry over.

<CardGroup cols={2}>
  <Card title="From Mintlify" icon="arrow-right-circle" href="https://docs.typemark.dev/migrating/mintlify">
    `docs.json` or `mint.json` with MDX pages. Your pages work as they are.
  </Card>
  <Card title="From GitBook" icon="arrow-right-circle" href="https://docs.typemark.dev/migrating/gitbook">
    A space synced to GitHub with Git Sync. Blocks become components.
  </Card>
  <Card title="From ReadMe" icon="arrow-right-circle" href="https://docs.typemark.dev/migrating/readme">
    A project synced to GitHub, or an export. Folders become navigation.
  </Card>
  <Card title="From anywhere else" icon="sparkles" href="https://docs.typemark.dev/migrating/other">
    Docusaurus, MkDocs, Fern, Notion, a live site. Your coding agent converts it.
  </Card>
</CardGroup>

## Three ways to migrate

| | How | Best for |
|---|---|---|
| **Import from GitHub** | Create a project, choose **Import from GitHub** and pick the repository. Typemark detects the platform and converts it. | Mintlify, GitBook and ReadMe sites in a GitHub repository |
| **The CLI** | `typemark migrate` converts the folder you're in, and `typemark check` finds what would break. | Sites that aren't on GitHub, or when you want to review the result before pushing |
| **Your coding agent** | `typemark migrate --agent claude` starts your coding agent with Typemark's migration guide. | Other platforms, and whatever the import leaves to you |

All three produce the same thing: a folder of `.mdx` pages and a [`typemark.json`](https://docs.typemark.dev/configuration/typemark-json) that describes your navigation.

## What the import does

1. **Detects the platform.** Typemark looks for `docs.json` or `mint.json` (Mintlify), `.gitbook.yaml` and `SUMMARY.md` (GitBook), or a `docs/` folder with `_order.yaml` files (ReadMe), at the root of the repository or up to two folders down.
2. **Writes `typemark.json`.** Navigation, page order, name, colour, logo and redirects come from your old config.
3. **Converts what needs converting.** Mintlify pages need nothing. GitBook blocks such as `{% hint %}` become Typemark components. ReadMe pages keep their MDX; files move to match ReadMe's URLs, and emoji callouts and `doc:` links are converted.
4. **Commits once.** Everything lands in one commit you can review, revert or diff.
5. **Builds your site** and shows an import summary on the project overview.

## The import summary

The project overview shows what happened until you dismiss it: pages found, pages in navigation, pages your navigation lists that don't exist, pages that exist but aren't in navigation, the components and blocks your pages use, and every setting Typemark didn't import, with the reason.

Nothing is dropped silently. If something is on that list, it's either fixed by hand in a few minutes or a good job for your [coding agent](https://docs.typemark.dev/migrating/other).

## Go-live checklist

New projects start offline, so you can check the site before anyone sees it.

<Steps>
  <Step title="Read the import summary">
    Fix missing pages and add any page you want published to navigation.
  </Step>
  <Step title="Run typemark check">
    In a local copy, `typemark check` reports navigation entries without a page, MDX that won't compile and broken links between pages.
  </Step>
  <Step title="Check your old URLs">
    Open a few of your most visited pages under the new site's address. Add a [redirect](https://docs.typemark.dev/configuration/typemark-json#redirects) for any path that changed.
  </Step>
  <Step title="Stop the old platform writing to your repository">
    Turn off GitBook's Git Sync or ReadMe's GitHub sync, so only Typemark and your team change the files from now on.
  </Step>
  <Step title="Go live and move your domain">
    Click **Go live** in **Settings** > **Publishing**, then point your [custom domain](https://docs.typemark.dev/configuration/custom-domain) at Typemark.
  </Step>
</Steps>
