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.
2026年11月19日更新5分で読めます
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
Create a project
Click New project, name it, and under Start from choose Import from GitHub. Click Create and connect GitHub.
Install the GitHub App
GitHub asks where to install the Typemark app. Give it access to your docs repository.
Pick the repository
Back in Typemark, select the repository. Typemark shows Mintlify site detected with the config it found, and selects Import from GitHub.
Import
Click Import and confirm. Typemark clones the repository, converts the config, commits
typemark.jsonto the root with the message "Add typemark.json (converted from docs.json)", pushes it to GitHub, and builds your site.Review the import summary
You land on the project overview, which shows what was imported. See below.
Go live
New projects start offline. When the site looks right, click Go live in Settings > Publishing. See Publishing.
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, 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. 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: 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 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 and 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
importandexportstatements 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 when Typemark can find the spec: named in the frontmatter (openapi: "openapi.json GET /users") or listed in navigation. The default spec fromdocs.jsonisn'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 inlinestyleandclasskeep sizes, spacing, layout and colours but not positioning (position,z-index,transform,fixed,z-50and the like). Put site-wide CSS in custom code instead (Pro and Enterprise). - The Mintlify config isn't synced. After the import,
typemark.jsonis what Typemark reads. Later changes todocs.jsonhave 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:
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:
typemark migrate --from mintlify --agent claude
The agent runs on your computer and follows the agent guide. See With your coding agent.
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. Before you switch your domain over, run through the go-live checklist.