> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Warning>
  The scraper can overwrite existing files.

  Run the scraper in an empty directory so it does not replace any existing files.
</Warning>

```bash theme={null}
mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://docs.example.com
```

If your Docusaurus documentation uses a route base path, filter to scrape that path:

```bash theme={null}
npx @mintlify/scraping@latest section https://example.com --filter=/docs
```

The 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 files
* `docusaurus.config.js` or `docusaurus.config.ts`
* `_category_.json`, `_category_.yml`, or `_category_.yaml` files
* The `static/` directory and assets stored beside documentation pages
* `versioned_docs/`, `versioned_sidebars/`, and `versions.json`
* Localized docs below `i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/`, such as `current/`
* React components imported by MDX pages

<Note>
  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/`.
</Note>

Copy Markdown and MDX pages into your Mintlify project. Every page needs frontmatter with at least a `title`.

```mdx Example frontmatter theme={null}
---
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`](/docs/components/tabs).           |
| `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger` | Use [`Note`, `Tip`, `Info`, `Warning`, or `Danger`](/docs/components/callouts). |
| `<details>` and `<summary>`                               | Use an [`Accordion`](/docs/components/accordions).                              |
| Tabbed code examples                                      | Use a [`CodeGroup`](/docs/components/code-groups) 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](/docs/components).
* Convert repeated content to a [reusable snippet](/docs/create/reusable-snippets).
* Add a [React component](/docs/customize/react-components) 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](/docs/guides/custom-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](/docs/create/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:

```mdx theme={null}
## Configure the client {/* #configure-client */}
```

Convert them to Mintlify's custom heading ID syntax when you must preserve inbound anchor links:

```mdx theme={null}
## 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.png` is 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](/docs/organize/navigation#versions). Decide whether `current`, the latest released version, or another version should be the default.

Map Docusaurus locale directories to Mintlify [language navigation](/docs/organize/navigation#languages). 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](/docs/deploy/authentication-setup) 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](/docs/api-playground/openapi-setup). 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](https://app.mintlify.com/settings/deployment/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](/docs/organize/settings-seo).
* Install any required [analytics integrations](/docs/integrations/analytics/overview), and optionally add a [custom 404 page](/docs/customize/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](/docs/deploy/preview-deployments). 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](/docs/customize/custom-domain), which covers the zero-downtime cutover for a domain that already serves documentation.
* After launch, monitor for 404 errors, redirect failures, and build failures.

## Docusaurus references

* [Docs plugin configuration](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs)
* [Sidebars](https://docusaurus.io/docs/sidebar)
* [Versioning](https://docusaurus.io/docs/versioning)
* [Internationalization](https://docusaurus.io/docs/i18n/introduction)
* [Static assets](https://docusaurus.io/docs/static-assets)
* [Heading IDs](https://docusaurus.io/docs/markdown-features/toc#heading-ids)


## Related topics

- [Migration overview](/docs/migration/index.md)
- [Migrate from Document360](/docs/migration/document360.md)
- [Migrate from Fern](/docs/migration/fern.md)