mintlify__docs/migration/docusaurus.mdx

---
title: "Migrate from Docusaurus"
description: "Migrate Docusaurus documentation to Mintlify, including MDX pages, sidebars, versions, localized content, assets, and custom components."
keywords: ["Docusaurus migration", "Docusaurus to Mintlify", "sidebars.js", "versioned_docs"]
---

import MigrationLaunchChecklist from "/snippets/migration-launch-checklist.mdx";

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
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
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
---
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`](/components/tabs). |
| `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger` | Use [`Note`, `Tip`, `Info`, `Warning`, or `Danger`](/components/callouts). |
| `<details>` and `<summary>` | Use an [`Accordion`](/components/accordions). |
| Tabbed code examples | Use a [`CodeGroup`](/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](/components).
- Convert repeated content to a [reusable snippet](/create/reusable-snippets).
- Add a [React component](/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](/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](/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
## Configure the client {/* #configure-client */}
```

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

```mdx
## 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](/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](/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](/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](/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.

<MigrationLaunchChecklist />

## 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)