Migrate from Mintlify | NookDocs

Mintlify → NookDocs is the CLI's best-supported path. The migrator reads docs.json / mint.json, walks every .mdx file, copies your assets, and writes a flat NookDocs repo. Most of the Mintlify component set shares NookDocs' component names, so pages render unchanged on first load; only genuinely-renamed components are rewritten, and anything Mintlify-proprietary is flagged in the report for you to review.

The migrator writes the flat layout by default — nookdocs.config.json, content .mdx, and openapi.json all land at the output directory's root (the docs base), with navigation page refs carrying no docs/ prefix. If you'd rather nest content in a subfolder, move the files and set contentRoot in nookdocs.config.json after migrating. See Content root.

End-to-end walkthrough

Clone your Mintlify repo

git clone https://github.com/acme/mintlify-docs.git
cd mintlify-docs

Any Mintlify-shaped repo works — official Mint Starter Kit clones, legacy mint.json repos, or full production docs trees.

Run the CLI

nookdocs migrate . --output ../acme-nookdocs

The CLI auto-detects Mintlify from docs.json / mint.json. Add --dry-run first if you want to see the report before any files land on disk.

Review the report

The summary prints at the end:

  Migration complete! (mintlify → NookDocs)

  ✓ Config:    docs.json → nookdocs.config.json
  ✓ Pages:     18 files converted
  ✓ Assets:    2 dirs (5 files), 1 file
  ✓ OpenAPI:   api-reference/openapi.json → api-reference/openapi.json

  Transforms applied:
    essentials/markdown.mdx: <Latex> → <Math>

  Manual review needed:
    ! contextual config not migrated — set contextual options if needed.
    ! essentials/reusable-snippets.mdx: snippet import detected — review manually

Transforms applied = components the migrator renamed for you. Manual review needed = things to eyeball (config keys with no direct equivalent, snippet imports). There are no TODO markers injected into your MDX — the review list lives in this report.

Commit the output to a new repo

cd ../acme-nookdocs
git init
git add .
git commit -m "initial NookDocs migration from Mintlify"
git remote add origin git@github.com:acme/nookdocs-docs.git
git push -u origin main

Hook up via the NookDocs dashboard

Sign in at app.nookdocs.com, click New project, pick "Connect your own repo", and authorise the GitHub App on the repo you just pushed. Your docs are live on {slug}.nookdocs.site within a minute.

Resolve the review list

Work through the Manual review needed items from the report. These are config keys with no direct NookDocs equivalent and snippet imports that need converting to the <Snippet file="..."> component. Any custom or Mintlify-proprietary component that isn't in the NookDocs library passes through verbatim — smoke-test each page to catch these.

What converts automatically

Config (`docs.json` / `mint.json` → `nookdocs.config.json`)

Mintlify key	NookDocs key	Notes
`name`	`name`	Direct copy
`$schema`	`$schema`	Rewritten to `https://nookdocs.com/schema.json`
—	`contentRoot`	Set to `"/"` — the flat canonical layout (content at the repo root)
—	`theme`	Set to `"larch"` — the current NookDocs starter default
`logo.light` / `logo.dark`	`colors.logo.light` / `colors.logo.dark`	Paths preserved; `colors.logo.href` set to `/`
`colors.primary` / `light` / `dark`	`colors.primary` / `light` / `dark`	Direct copy
`navigation.tabs` (or legacy group array)	`navigation`	Full tree-walk preserves the tab → group → pages hierarchy
`navigation.global.anchors`	`global.anchors`	`anchor` / `href` / `icon` preserved
`navbar.links`	`navbar.links`	Direct copy
`navbar.primary`	`navbar.primaryCta`	`{label, href}`
`footer.socials`	`footer.socials`	Direct copy
(spec present) `api-reference/openapi.json`	`api.openapi` + `api.playground`	Set when an OpenAPI spec is found; spec copied to `api-reference/openapi.json`

Keys without a NookDocs equivalent are noted in the report's Manual review needed section rather than silently dropped — currently Mintlify's contextual and backgroundImage.

Frontmatter

Page frontmatter is left untouched, and NookDocs reads the same field names, so title, description, icon, tag, sidebarTitle and hidden keep working after the move — a page with sidebarTitle: DPA still shows "DPA" in the rail. See frontmatter for every field NookDocs recognises.

Components (MDX → MDX)

NookDocs implements the Mintlify component set under the same tag names, so the migrator leaves them untouched — they render as-is. Only two components are genuinely renamed:

Mintlify component	NookDocs equivalent	Notes
`<Latex>`	`<Math>`	Renamed; body and props preserved
`<Tree>`	`<FileTree>`	Renamed; body and props preserved

Everything else passes through verbatim with its props intact, including <Card> / <CardGroup>, the callout family <Note> / <Tip> / <Warning> / <Info> / <Check> (these are five distinct NookDocs components — there is no single <Callout type="…"> wrapper), <Accordion> / <AccordionGroup>, <Steps> / <Step>, <Tabs> / <Tab>, <CodeGroup>, <Frame>, <ParamField> / <ResponseField>, <Snippet>, <Icon>, <Expandable>, <Update>, <Mermaid>, and <RequestExample> / <ResponseExample>.

Any component not in the NookDocs library (Mintlify-proprietary or custom React) is left in place verbatim — the migrator does not inject TODO markers. Smoke-test each page after migrating to catch unsupported components; the report also flags snippet imports for manual review.

See the component library for the full list of NookDocs components.

Assets

Images, PDFs, and other public files copy byte-for-byte to matching paths in the output directory. If your Mintlify MDX has <img src="/images/hero.png"> and images/hero.png exists at the repo root, the migrator copies it to <output>/images/hero.png so the link keeps working.

What doesn't convert (review checklist)

After a migration, review these items in the output:

Manual-review report items — the CLI lists config keys it couldn't map (contextual, backgroundImage) and snippet imports it detected. Work through each.
Unsupported components — any component not in the NookDocs library stays in the MDX verbatim (no auto-substitution). Smoke-test pages to find them.
Custom React components — if your repo imports custom .tsx / .jsx files, those imports stay in the MDX but NookDocs doesn't execute arbitrary React. Refactor to the built-in component library.
Snippet imports — Mintlify's import … from '/snippets/…' is flagged in the report. NookDocs uses the <Snippet file="…"> component instead; convert each one.
Environment-specific URLs — absolute Mintlify URLs like https://yoursite.mintlify.app/... need rewriting to your new NookDocs domain.
OpenAPI spec path — the spec is copied to api-reference/openapi.json and api.openapi points there. Verify the reference resolves in the flat layout.

Post-migration checklist

Known limitations

Custom CSS classes. Mintlify supports Tailwind classes in MDX attributes. NookDocs accepts them too but only a subset (the ones that don't conflict with theme tokens). Check visually after migration.
Mintlify-only features. Speakeasy SDK pages, PDF export, Mintlify Assistant-specific analytics don't have direct equivalents. File a GitHub issue if you need them.
Docusaurus / GitBook / Nextra / Fumadocs — detection scaffolded, migrators not yet implemented. PRs welcome; file an issue so we know the demand.

Overview — what the CLI does
Install — prerequisites + upgrade
Migrate command — flags + detection + report output
Component library — every component the migrator targets
Schema reference — the nookdocs.config.json fields the config pass produces