Migrate from Mintlify to Typemark

Your Mintlify docs are already MDX files in a Git repository, so there isn’t much to move. Connect the repository or run one command in your terminal. Typemark converts your docs.json, and your pages and components work as they are.

Checked against Typemark’s Mintlify import and the Typemark CLI, November 2026.

Before and after

Your pages don’t change. The import adds one file, typemark.json, converted from your docs.json.

Before: docs.json, Mintlify
{  "name": "Acme",  "colors": { "primary": "#0D9373" },  "navigation": {    "tabs": [      {        "tab": "Guides",        "groups": [          { "group": "Get started", "pages": ["index", "quickstart"] }        ]      }    ]  },  "redirects": [    { "source": "/start", "destination": "/quickstart" }  ]}
After: typemark.json, added by the import
{  "$schema": "https://typemark.dev/schema.json",  "name": "Acme",  "colors": { "primary": "#0D9373" },  "navigation": {    "tabs": [      {        "tab": "Guides",        "groups": [          { "group": "Get started", "pages": ["index", "quickstart"] }        ]      }    ]  },  "redirects": [    { "from": "/start", "to": "/quickstart" }  ],  "features": { "search": true, "table_of_contents": true, "copy_code_button": true }}

Steps

  1. Step 1: Start a GitHub import

    Create a new project and, under “Start from”, choose “Import from GitHub”, then “Create and connect GitHub”. New accounts see the same option during setup: “Moving from another platform? Import from GitHub”. Already have a project? Go to Settings → GitHub → Connect to GitHub.

  2. Step 2: Install the Typemark GitHub App

    GitHub opens the Typemark app’s install page. Grant it access to the repository that holds your docs. The app only sees the repositories you choose.

  3. Step 3: Pick the repository

    You land back on Settings → GitHub. Choose the repository. When docs.json or mint.json is at its root or in docs/, Typemark shows “Mintlify site detected” with “Import from GitHub” already selected. Click Import and confirm.

  4. Step 4: Typemark converts your config

    Typemark clones the repository, finds your Mintlify config (at the root or up to two directories deep), commits a typemark.json at the repository root, pushes it, and builds your site. Your Mintlify config and MDX files are never modified.

  5. Step 5: Review the import summary

    The project overview shows what was imported: pages found, pages in navigation, missing pages, pages not in navigation, the components your pages use (supported or not) and the settings that weren’t imported. It stays until you dismiss it.

  6. Step 6: Go live, with two-way GitHub sync

    When you’re happy, click Go live in Settings → Publishing. From then on, push from your own editor or edit in Typemark, and both land in the same repository. typemark.json is now the source of truth, so later edits to docs.json aren’t synced.

From your terminal

Docs that aren’t on GitHub, or that you’d rather publish to a project Typemark hosts, move with the Typemark CLI. It uses the same conversion as the GitHub import and never changes your Mintlify files.

  • typemark migrate finds docs.json or mint.json up to two directories deep, writes typemark.json next to it, lists every setting it dropped and checks the folder the way the build does. Then it offers to create a project, link the folder and push your site in place of the starter pages.
  • typemark migrate --create --push does all of that in one go with no questions, for CI and coding agents.
  • typemark push --wait publishes your later changes, and returns once they’re live.
  • Needs Node.js 22 or later. Read the CLI guide.
Terminal
npm install -g @gettypemark/clicd my-mintlify-docstypemark logintypemark migrate  # converts, then offers to create and push

What converts

Your config lands in a new typemark.json, committed with the message “Add typemark.json (converted from docs.json)”. A site that lives in a subdirectory gets "docs_root": "docs" (or wherever it lives).

  • Name, primary colour, logo and favicon
  • Tabs, groups and pages, including group root pages
  • Nested groups, as sibling groups (the summary warns you) (partly)
  • Anchors, dropdowns and products, as tabs
  • Navbar links and button, as top navigation
  • Footer socials and link columns, as your site footer
  • Exact-path redirects
  • The SEO og:image
  • $ref files
  • OpenAPI references in your repository, as generated endpoint pages
  • Google Analytics, Tag Manager, Plausible, Fathom, Hotjar and Intercom integrations (Pro)
  • Custom CSS and JavaScript files (Pro; scripts run on your custom domain)
  • Legacy mint.json: tabs by URL prefix, anchors, topbar links and CTA, footerSocials and openapi

Components

Rendered on your site and editable as blocks in the visual editor. Callout-style tags become callouts, and the original tag names are kept when you save:

  • <Note>
  • <Info>
  • <Tip>
  • <Check>
  • <Warning>
  • <Danger>
  • <Callout>
  • <Card>
  • <CardGroup>
  • <Columns>
  • <Tabs>
  • <Tab>
  • <Steps>
  • <Step>
  • <Accordion>
  • <AccordionGroup>
  • <CodeGroup>

Rendered on your site and kept as raw blocks in the editor, so they come back unchanged when you save:

  • <Frame>
  • <Expandable>
  • <ParamField>
  • <ResponseField>
  • <Tooltip>
  • <Icon>
  • <Badge>
  • <Update>
  • <Panel>
  • <RequestExample>
  • <ResponseExample>

About 90 common Font Awesome icon names are mapped. A component Typemark doesn't know renders its content instead of breaking the page.

What doesn’t carry over

Each of these shows up as a warning in the import summary. None of them stops the import.

Versions
Only the default version is imported.
Per-language navigation
Every language comes across, with the default language’s navigation. A translation is found at fr/<page> next to the page it translates.
Wildcard redirects
Exact-path redirects come across; add the others to typemark.json by hand.
Remote OpenAPI URLs
Specs in your repository work. Add a remote spec’s file to the repository.
Look and feel settings
Theme, fonts, appearance, background, banner, contextual menu, playground and search settings, and integrations other than the ones above.
Snippet imports and <Snippet>
Typemark never executes imports from your docs, for security. Paste the snippet’s content into the page.
Pages generated from openapi: frontmatter
The text you wrote on the page shows, but not the endpoint Mintlify generated from it.
Unknown components
The text inside them still shows, so the page doesn’t break.

Snippets aren't rendered because Typemark never executes code from your docs. Here's why.

With your coding agent

Let Claude Code, Codex or Cursor finish the job.

Snippets, wildcard redirects or anything else the summary flags are a good job for your coding agent. It runs on your computer under your own account, follows our Mintlify guide and keeps checking its work until the site builds cleanly.
npm install -g @gettypemark/clitypemark migrate --agent claude  # or codex, cursor, gemini

Using another agent? typemark migrate --guide prints the guide so you can paste it in.

After the import

Edit typemark.json from now on; changes to docs.json aren't synced. A new project stays offline until you click Go live in Settings → Publishing. Add your custom domain in the project settings (free on every plan) and point your DNS at Typemark. Invite your team: on Pro, up to 10 people can edit, and they don't need Git to do it.

How fast is it? From our own testing, not customer numbers: Mintlify's official starter template imported and built in under a second, and a real 267-page Mintlify site built 251 pages in about seven seconds with no compile failures.

Still deciding? Compare Typemark and Mintlify side by side, or read how Mintlify pricing works.

Questions

Do I have to rewrite my MDX?
No. Typemark renders your pages as they are, including Mintlify components such as Note, Info, Tip, Check, Warning, Danger, Card, Tabs, Steps, Accordion and CodeGroup. When you edit a page in Typemark, the original tag names are kept on save.
What happens to my docs.json or mint.json?
Typemark never modifies it. The import commits a new typemark.json at the repository root, converted from your Mintlify config. After that, typemark.json is the source of truth: later changes to docs.json are not synced.
What doesn’t carry over?
Versions, per-language navigation, wildcard redirects, remote OpenAPI URLs, theme and appearance settings, snippet imports, pages generated from openapi frontmatter, and unknown components. Each one appears as a warning in the import summary. The import never fails because of them.
My docs live in a subdirectory. Does that work?
Yes. Typemark finds docs.json or mint.json up to two directories deep, and the generated typemark.json points at that directory (for example "docs_root": "docs").
Do I need GitHub?
No. The GitHub import reads your repository through the Typemark GitHub App, which only sees the repositories you choose. Without GitHub, run typemark migrate and typemark push in the folder that holds your docs: the Typemark CLI uses the same conversion and publishes to a project Typemark hosts. Either way, your team can then edit in Typemark’s visual editor without touching Git.
Can I migrate from my terminal or CI?
Yes. Install the Typemark CLI (npm install -g @gettypemark/cli, Node.js 22 or later), run typemark migrate in your docs folder and let it create the project and push, or run typemark migrate --create --push to do it in one go. In CI, the same push with an API token publishes your docs on every merge.

Bring your Mintlify docs over.

Connect your repository and read the import summary. Typemark adds one file, typemark.json, and leaves your Mintlify config and pages untouched.

14-day Pro trial, no card. Your content stays in Git.