Choose a method
For complex sites, combine both methods. Scrape your public site to create an initial
docs.json and convert components, then compare the result with the source repository for missing content.
Migrate a public site
docs.json from the published navigation.
After the scraper finishes, compare the generated Mintlify navigation with your sidebars.js, sidebars.ts, or other Docusaurus navigation structure. Check for collapsed categories, external links, generated category index pages, and pages excluded from the published sidebar.
Migrate from source
Copy the following source content into a separate migration branch or working directory.- Your configured docs content directory, which is
docs/by default in Docusaurus sidebars.js,sidebars.ts, or other sidebar configuration filesdocusaurus.config.jsordocusaurus.config.ts_category_.json,_category_.yml, or_category_.yamlfiles- The
static/directory and assets stored beside documentation pages versioned_docs/,versioned_sidebars/, andversions.json- Localized docs below
i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/, such ascurrent/ - React components imported by MDX pages
Docusaurus can change its docs directory, route base path, sidebar generator, and included files in the docs plugin configuration. Depending on your configuration, your content may be in a different directory than
docs/.title.
Example frontmatter
Recreate navigation
Docusaurus sidebars are executable JavaScript or TypeScript, while Mintlify navigation is data indocs.json. Convert the resolved sidebar, not only its source text, if the sidebar uses functions or custom generators.
Docusaurus uses the file hierarchy for autogenerated sidebars. Mintlify lets you organize navigation independently from file locations, so you do not need to rename pages solely to match the sidebar.
Convert Docusaurus MDX
Standard Markdown usually works without changes. Review Docusaurus-specific syntax and imports.
Custom React components do not migrate automatically from your source repository. Determine whether each component is content, presentation, or application behavior.
- Replace content patterns with a Mintlify component.
- Convert repeated content to a reusable snippet.
- Add a React component when you need an interaction that no built-in component provides.
- Move full application pages outside the documentation site or rebuild them as custom page layouts.
Preserve routes and links
Docusaurus combines the docs pluginrouteBasePath, page frontmatter slug, version, and locale to create a URL. Create an inventory from the published sitemap rather than inferring every URL from filenames.
When you rename or reorganize a page, add its old published path to redirects. Test links with and without the former route base path, for example /docs/getting-started and /getting-started.
Review explicit Docusaurus heading IDs such as:
Migrate assets
Docusaurus supports global assets instatic/ and assets stored beside versioned pages. Copy both kinds into the Mintlify repository.
- A Docusaurus file at
static/img/logo.pngis normally published as/img/logo.png. Preserve that public path or update every reference. - Resolve
@site/static/...imports before removing Docusaurus imports. - Keep collocated versioned assets with the correct version or move them to version-specific asset directories.
- Check CSS background images and React component imports, which a Markdown-only inventory can miss.
- Do not leave required production assets on your former deployment unless you plan to keep that hosting after your migration.
Migrate versions and languages
Docusaurus stores frozen versions underversioned_docs/version-<name> and their navigation under versioned_sidebars/. Map each maintained version to a Mintlify version. Decide whether current, the latest released version, or another version should be the default.
Map Docusaurus locale directories to Mintlify language navigation. Preserve the locale prefix in redirects when the old site used paths such as /fr/docs/....
If your source repository contained unpublished or restricted pages, configure authentication and page visibility, then test your site as a signed-out user and as a member of each group.
Migrate API documentation
Locate OpenAPI or AsyncAPI files referenced by plugins, custom pages, or build scripts. Add the original specification to the Mintlify repository and configure OpenAPI-generated pages. Do not migrate rendered endpoint HTML when the source specification is available.Review your migration
Compare your migrated pages against your sidebar entries and published sitemap, then preview every maintained version and language. Search your converted files for leftover Docusaurus syntax, which renders as literal text or fails the build:@theme, @site, :::, DocCardList, useDocusaurusContext, and custom plugin imports.
Launch your new site
- Set a content freeze on your former site and track every change made to it after your migration snapshot.
- Confirm your production branch and repository on the Git settings page of your dashboard.
- Record your existing DNS records and keep your former site running until you verify your Mintlify deployment is live.
- Review the navbar, footer, favicon, logo, colors, and typography.
- Review site and page metadata, canonical URLs, and indexing preferences. See SEO and search settings.
- Install any required analytics integrations, and optionally add a custom 404 page.
- If you migrated an API reference, compare endpoint pages, navigation structure, server URLs, authentication schemes, and examples with your former site.
- Preview your exact launch commit in a preview deployment. Check desktop and mobile layouts, pages from every navigation section, search, and your redirects.
- Check the browser console and network tab for any errors on pages that use custom components or scripts.
- Switch your domain with the custom domain guide, which covers the zero-downtime cutover for a domain that already serves documentation.
- After launch, monitor for 404 errors, redirect failures, and build failures.