{"schemaVersion":1,"title":"Migrate from Mintlify","url":"https://appgram.github.io/docsy/guides/tutorials/migrate-mintlify","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/tutorials/migrate-mintlify","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/tutorials/migrate-mintlify.json","version":"current","locale":"en","markdown":"# Migrate from Mintlify\n\nPreserve native MDX and supported components from a local Mintlify export, with navigation, assets, and redirects.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nImport a **local source export**, not a hosted website. Native `.mdx` files stay MDX by default; supported JSX components render with Docsy's existing UI. The source directory is never modified, source JavaScript is never executed by the importer, and the destination must be new and outside that directory.\n\n## Run the importer\n\nFrom an existing Docsy checkout or generated site:\n\n```bash\nnpm run docsy -- migrate mintlify \\\n  --source ../mintlify-export \\\n  --out ../migrated-docs \\\n  --base /docs \\\n  --ci\n\ncd ../migrated-docs\nnpm install\nnpm run validate\nnpm run build\nnpm run preview\n```\n\nAdd `--repo https://github.com/OWNER/REPOSITORY` to configure article source/edit links. Migration never pushes, creates a repository, or deploys. Review `migration/report.json` before adopting the result.\n\nThe generated YAML enables MDX with `content.mdx.allowJavaScript: false`. To deliberately use the older, limited conversion to plain Markdown, add `--format markdown`. [Native MDX authoring](../native-mdx) explains components, YAML settings, custom modules and the trust boundary.\n\n## What is preserved\n\n* Explicit navigation groups/pages in `docs.json` or legacy `mint.json`, nested groups, and tabs containing groups. Tab groups become labelled navigation sections.\n* Article titles/descriptions, Markdown and native MDX bodies, internal links, and page ordering.\n* Referenced local images/PDFs and configured logos, copied under `public/assets/migrated/`; unrelated files, fonts, credentials, scripts, and orphan pages are not copied.\n* Original article paths, frontmatter aliases, and explicit redirect entries, mapped to their new `/guides/...` routes. Redirects are scoped by `site.basePath`, not domain-root redirects.\n* Native Note/Info/Tip/Check/Warning/Danger callouts, nested callouts, Tabs/Tab, Steps/Step, Accordion/AccordionGroup, CodeGroup, Card/CardGroup and Frame components, using Docsy's theme. Literal attributes such as `cols={2}` are supported without enabling executable JavaScript.\n* Fenced and inline code examples remain unchanged; AST-based link rewriting handles Markdown links/images, MDX reference definitions, and quoted JSX `href`/`src` attributes.\n\nThe report records source and asset hashes, route mappings, warnings, and `published: false`. Preserve upstream license/notice files along with imported content.\n\nThe native path has been built against the two real articles from `mintlify/starter` at commit `8dc589095a85335165d18ed0aa5d273360dffd04`, preserving its cards, callouts, numbered steps and code examples. The internal evidence file `docs/evidence/mintlify-native-mdx.json` records the source hashes and checks. This small starter is a compatibility smoke test, not proof that every production Mintlify site will migrate unchanged.\n\n## Explicit limits\n\nUnknown components, unsupported HTML/props, executable imports/exports and non-literal JavaScript expressions fail before destination creation. The importer never turns on trusted JavaScript or copies arbitrary component modules. Map custom components manually after reviewing their code; there is no claim of universal Mintlify component compatibility.\n\nDynamic/API navigation, missing linked pages, symlinks, and unsafe paths also fail. Export one version/locale first; multi-context navigation is not silently flattened. There are file, page-count, and total-byte limits. With `--format markdown`, conversion retains the previous narrower limits: only simple cards/steps/callouts, without nested callouts, reference-style links or custom JSX.\n\nOpenAPI setup needs Docsy's existing OpenAPI importer; it is not inferred from generated API navigation. Global header links, SEO settings, contextual actions, custom JavaScript, advanced component behavior, and original visual styling require manual mapping. Remote links/assets are retained as URLs, not downloaded. This is a bounded migration path, not universal Mintlify compatibility.\n\n## Correct a page after migration\n\n```yaml\nreader:\n  editUrl: https://github.com/OWNER/REPOSITORY/edit/main/{source}\n  reportUrl: https://github.com/OWNER/REPOSITORY/issues/new\n  editLabel: Edit this page\n  reportLabel: Report a problem\n```\n\nEdit URLs support `{source}`, `{version}`, and `{locale}` placeholders. Reports prefill the canonical page URL, version, and locale, not runtime query parameters. Links are optional and make no network request until clicked. Localize labels through `localization.messages` keys `editPage`, `reportProblem`, and `documentationFeedback`. Users need repository access for a private project.\n\n","contentLocale":"en","isFallback":false,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/migrate-mintlify.md"}