Migrate from Docusaurus
Migrate Docusaurus documentation to Mintlify, including MDX pages, sidebars, versions, localized content, assets, and custom components.
Migrate a public Docusaurus 2 or 3 site with the Mintlify scraper. If you need more precise control over versions, localized content, or custom React components, migrate from your source repository.
Choose a method
| Method | Use it when |
|---|---|
| Scraper | Your complete documentation site is public and most content uses standard Docusaurus components. |
| Source migration | Your site is private or uses versioning, localization, custom plugins, custom React components, or unpublished pages. |
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
The scraper can overwrite existing files.
Run the scraper in an empty directory so it does not replace any existing files.
mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://docs.example.comIf your Docusaurus documentation uses a route base path, filter to scrape that path:
npx @mintlify/scraping@latest section https://example.com --filter=/docsThe scraper detects Docusaurus, expands its sidebar, downloads reachable images, converts common rendered components to Mintlify components, and creates a 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/.
Copy Markdown and MDX pages into your Mintlify project. Every page needs frontmatter with at least a title.
---
title: "Get started"
description: "Install the SDK and make your first request."
---Recreate navigation
Docusaurus sidebars are executable JavaScript or TypeScript, while Mintlify navigation is data in docs.json. Convert the resolved sidebar, not only its source text, if the sidebar uses functions or custom generators.
| Docusaurus | Mintlify |
|---|---|
doc item or doc ID | Page path in a pages array |
category | Nested group with group and pages |
| Category linked to a doc | Group with a root page |
| Generated category index | Create an overview page and use it as the group root |
link item | An anchor, tab, menu item, or page that links to the external destination |
| Multiple sidebars | Separate tabs, anchors, products, or groups |
| Autogenerated sidebar | Mirror the file hierarchy or list the generated order explicitly |
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.
| Docusaurus source | Mintlify replacement |
|---|---|
import Tabs from '@theme/Tabs' and TabItem | Remove the imports and use Tabs and Tab. |
:::note, :::tip, :::info, :::warning, :::danger | Use Note, Tip, Info, Warning, or Danger. |
<details> and <summary> | Use an Accordion. |
| Tabbed code examples | Use a CodeGroup when every tab contains code. |
@site/... imports and theme components | Replace them with Mintlify components, snippets, or standard MDX. |
| Custom Markdown plugin syntax | Convert the generated syntax or recreate the behavior in supported MDX. |
| Swizzled theme components | Recreate the user-facing behavior with Mintlify settings or components. |
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 plugin routeBasePath, 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:
## Configure the client {/* #configure-client */}Convert them to Mintlify’s custom heading ID syntax when you must preserve inbound anchor links:
## Configure the client [#configure-client]Migrate assets
Docusaurus supports global assets in static/ 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 under versioned_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.