# From Mintlify

> Import a Mintlify docs repo from GitHub or convert it in your terminal. Typemark converts docs.json and publishes your MDX pages without touching them.

Your Mintlify pages work on Typemark as they are. On import, Typemark reads your `docs.json` (or older `mint.json`), writes a `typemark.json` next to it, and publishes your existing MDX pages. Your pages and your Mintlify config aren't changed.

## Before you start

- Your docs are in a GitHub repository you can install the Typemark GitHub App on.
- The repository is 100 MB or smaller and has no Git submodules.
- The Mintlify config is at the repository root or up to two folders down, such as `docs/docs.json`.

## Import your site

<Steps>
  <Step title="Create a project">
    Click **New project**, name it, and under **Start from** choose **Import from GitHub**. Click **Create and connect GitHub**.
  </Step>
  <Step title="Install the GitHub App">
    GitHub asks where to install the Typemark app. Give it access to your docs repository.
  </Step>
  <Step title="Pick the repository">
    Back in Typemark, select the repository. Typemark shows **Mintlify site detected** with the config it found, and selects **Import from GitHub**.
  </Step>
  <Step title="Import">
    Click **Import** and confirm. Typemark clones the repository, converts the config, commits `typemark.json` to the root with the message "Add typemark.json (converted from docs.json)", pushes it to GitHub, and builds your site.
  </Step>
  <Step title="Review the import summary">
    You land on the project overview, which shows what was imported. See below.
  </Step>
  <Step title="Go live">
    New projects start offline. When the site looks right, click **Go live** in **Settings** > **Publishing**. See [Publishing](https://docs.typemark.dev/configuration/publishing).
  </Step>
</Steps>

Already have a project? Go to **Settings** > **GitHub** > **Connect to GitHub** and pick the repository. The import replaces that project's current docs.

## The import summary

The project overview shows a summary until you dismiss it:

| Section | What it tells you |
|---------|-------------------|
| **Pages found**, **In navigation**, **Missing pages** | How many pages are in the repo, how many your navigation lists, and how many it lists that don't exist |
| **Referenced in navigation but not found** | Navigation entries with no matching file. Fix the path or remove the entry. |
| **Pages not in navigation (not published)** | Files your navigation doesn't list. Add them to a group to publish them. |
| **Components** | Which components your pages use, and which ones Typemark doesn't render |
| **Settings not imported** | Each setting Typemark dropped, and why |

## What gets converted

| Mintlify | Typemark |
|----------|----------|
| `name` | `name` |
| `colors.primary` | `colors.primary` (other colors are dropped; Typemark derives its shades from the primary) |
| `logo`, `favicon` | `logo`, `favicon` |
| Tabs, anchors, dropdowns, and products | Tabs |
| Nested groups | Groups placed right after their parent, since Typemark groups don't nest |
| Languages (`navigation.languages`) | [`languages`](https://docs.typemark.dev/configuration/languages), the default language first. Every language uses the default language's navigation, and Typemark finds each translation at `<code>/<page>`, such as `fr/quickstart`. The summary names any translated pages that aren't there; rename them to match. Languages inside tabs or versions: only the default one is imported. |
| Versions | Only the default one is imported |
| OpenAPI endpoint entries, such as `GET /users` | One `{ "source": "openapi.json" }` entry that generates a page per endpoint. Remote specs are skipped; add the spec file to the repo instead. |
| Navbar links, top bar links, and global anchors with a URL | `top_navigation` |
| Footer socials and link columns | `footer` |
| `redirects` | `redirects` (wildcard redirects are skipped) |
| `seo.metatags["og:image"]` | `seo.og_image` |
| `integrations` (`analytics` in `mint.json`) for Google Analytics 4, Google Tag Manager, Plausible, Fathom, Hotjar, and Intercom | [`integrations`](https://docs.typemark.dev/configuration/custom-code#integrations). Other tools are listed under **Settings not imported**; paste their snippet under **Settings** > **Custom code**. |
| `.css` and `.js` files in your docs folder | [`custom_code`](https://docs.typemark.dev/configuration/custom-code#in-your-repository): CSS files under `css`, JavaScript files under `body`. JavaScript runs on your verified custom domain only. Custom code needs Pro or Enterprise. |

Anything else, such as theme, fonts, icons in navigation, API playground settings, and other SEO tags, is dropped and listed under **Settings not imported**. The import never fails because of a setting it doesn't understand.

If your docs live in a subfolder, `typemark.json` gets a [`docs_root`](https://docs.typemark.dev/configuration/typemark-json#docs_root) so page paths keep working. Typemark also turns on search, table of contents, and code copy buttons.

## Components

These Mintlify components render on your Typemark site:

`Note`, `Info`, `Tip`, `Check`, `Warning`, `Danger`, `Callout`, `Tabs`, `Tab`, `CodeGroup`, `Accordion`, `AccordionGroup`, `Card`, `CardGroup`, `Columns`, `Steps`, `Step`, `Frame`, `Expandable`, `ParamField`, `ResponseField`, `Tooltip`, `Icon`, `Badge`, `Update`, `Panel`, `RequestExample`, `ResponseExample`

Videos embedded with `<iframe>` (YouTube, Vimeo, Loom, Wistia) or `<video>`, and ```` ```mermaid ```` diagrams, work as they are. See [Videos](https://docs.typemark.dev/components/videos) and [Diagrams](https://docs.typemark.dev/components/diagrams).

Any other component still renders its content, in a plain container, instead of breaking the page.

In the visual editor, `<Note>`, `<Info>`, `<Tip>`, `<Check>`, `<Warning>`, and `<Danger>` open as callouts, and `<Columns>` opens as a card group. They save back under their original names, so your files keep Mintlify's syntax. Components the editor doesn't know stay as raw blocks and are saved exactly as written.

## Known limits

- **Snippets don't render.** Typemark strips `import` and `export` statements for security, and doesn't support `<Snippet>`. Paste snippet content into the page instead. The summary lists the pages that use them.
- **`openapi:` frontmatter** pages show their [endpoint](https://docs.typemark.dev/api-reference/openapi#write-an-endpoints-page) when Typemark can find the spec: named in the frontmatter (`openapi: "openapi.json GET /users"`) or listed in navigation. The default spec from `docs.json` isn't applied, so the summary lists pages whose endpoint isn't found; they show only their MDX body until you name the spec.
- **A page's styles stay inside the page.** Typemark removes `<style>` and `<script>` tags from pages, and inline `style` and `class` keep sizes, spacing, layout and colours but not positioning (`position`, `z-index`, `transform`, `fixed`, `z-50` and the like). Put site-wide CSS in [custom code](https://docs.typemark.dev/configuration/custom-code) instead (Pro and Enterprise).
- **The Mintlify config isn't synced.** After the import, `typemark.json` is what Typemark reads. Later changes to `docs.json` have no effect.
- **Protected branches.** If GitHub rejects the push of `typemark.json`, for example because of branch protection, the import still finishes. The commit goes out with your next save.

## From your terminal

To migrate a Mintlify site that isn't on GitHub, or to publish it to a project Typemark hosts, use the [Typemark CLI](https://docs.typemark.dev/automation/cli#migrate-from-another-platform):

```bash
typemark migrate             # writes typemark.json next to docs.json, then offers to create the project and push it
```

Answer yes twice and your site is on Typemark, offline until you publish it. In CI or with a coding agent, use `typemark migrate --create "My Docs" --push` instead.

It uses the same conversion as the GitHub import, so the tables above apply.

## With your coding agent

For what the import leaves to you, such as snippets or `openapi:` pages without a spec, hand the folder to your coding agent:

```bash
typemark migrate --from mintlify --agent claude
```

The agent runs on your computer and follows [the agent guide](https://docs.typemark.dev/migrating/other#the-guide-your-agent-follows). See [With your coding agent](https://docs.typemark.dev/migrating/other).

## After the import

Your project stays connected to the repository. Edit in Typemark or keep pushing from your editor, and both update your site. See [Sync](https://docs.typemark.dev/github/sync). Before you switch your domain over, run through the [go-live checklist](https://docs.typemark.dev/migrating/overview#go-live-checklist).
