> For a complete documentation index, see /llms.txt. To read any public page as Markdown, append .md to the URL.

Migrate an existing Docusaurus or MkDocs documentation site to a new CamelMind project with one command.

The migration tool detects your documentation framework, converts your Markdown files to MDX, and builds your CamelMind navigation from your existing sidebar or navigation structure. Your original repository stays as is in the same location.

<Callout type="tip">
If you are migrating a highly customized site, do not try to reproduce every Docusaurus or MkDocs customization all at once. Start with your content and information architecture, validate the migrated site, then replace framework-specific customizations with CamelMind features where possible.
</Callout>

---

## Before you start

Before you migrate a Docusaurus or MkDocs repository to CamelMind, verify these migration prerequisites:

- Node.js 20 or later
- A local copy of your Docusaurus or MkDocs repository
- A clean or committed working tree in your source repository

You do not need to install CamelMind before starting the migration. The migration command uses `npx` to fetch the latest CamelMind version automatically.

---

## Run the migration

From the directory containing your documentation repository, run:

```bash
npx camelmind@latest migrate path/to/your-docs-repo
```

CamelMind automatically detects:

- **Docusaurus** from `sidebars.js`, `sidebars.mjs`, or `sidebars.cjs`
- **MkDocs** from `mkdocs.yml`

The migration creates a new CamelMind project next to your source repository:

```text
parent-directory/
├── your-docs-repo/
└── your-docs-repo-camelmind/
```

The source repository remains unchanged.

### Preview a CamelMind migration

Before migrating your Docusaurus or MkDocs repository, use the CamelMind `migrate` command with `--dry-run` to preview the migration without creating or modifying files.

```bash
npx camelmind@latest migrate path/to/your-docs-repo --dry-run
```

The `--dry-run` option shows what the CamelMind migration would do while leaving your source repository unchanged.

---

## Review the migration report

Every migration ends with a report. The report identifies:

- Markdown files converted to MDX
- Navigation entries created
- CSS and other assets carried over
- Items that require manual attention

For example, the report includes a navigation entry if CamelMind cannot resolve it to a source file.

Review the **items need manual attention** section before moving on. These items do not necessarily mean the migration failed — they identify places where the source site's structure or customization requires a decision.

---

## Run your migrated CamelMind site

After migrating your Docusaurus or MkDocs repository, change to the new CamelMind project directory to run your site:

```bash
cd ../your-docs-repo-camelmind
```

If the migration did not install dependencies, run:

```bash
npm install
```

Then start the development server:

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) and review the migrated site.

---

## Recommended migration workflow

For most sites, we recommend migrating in stages rather than trying to reproduce the existing site on the first run.

<Steps>
<Step n={1} title="Migrate the content">

Start with the Markdown content and basic navigation.

Do not worry about making the site look like the original site yet. The goal is to establish that your documentation content migrated.

</Step>
<Step n={2} title="Review the navigation">

Compare your existing Docusaurus sidebar or MkDocs navigation with the generated `nav/nav.yml`. Check for missing/misplaced pages, broken/external links, custom navigation entries, and redirect rules.

Fix the navigation before spending time on visual customizations.

</Step>
<Step n={3} title="Review your content">

Open representative pages throughout the site. Pay particular attention to pages that use:

- Custom Markdown syntax
- MDX
- Embedded components
- HTML
- Tabs
- Admonitions
- Code blocks
- Images
- Custom links
- Frontmatter

The migration converts Markdown files to MDX, but framework-specific syntax may require manual changes.

</Step>
<Step n={4} title="Replace customizations">

Once the content and navigation are working, review your existing customizations.

This is where it is better to **adapt the documentation to CamelMind rather than recreate the old framework implementation**.

</Step>
<Step n={5} title="Validate the complete site">

Before switching to CamelMind, compare the migrated site with your existing documentation.

Check navigation, links, images, search, page metadata, custom content, and important URLs.

Keep the original site available until you've completed your validation.

</Step>
</Steps>

---

## Migrate customizations

Docusaurus and MkDocs sites often accumulate custom components, plugins, CSS, scripts, and theme modifications over time.

The migration tool imports content and structure, not framework-specific customizations. Evaluate if custom code is still needed before recreating it.

=== "Custom React components"

Docusaurus sites may contain custom React components used directly in MDX, for example:

```mdx
<CustomProductCard product="api" />
```

Instead of automatically rebuilding the component, determine whether CamelMind already provides the functionality you need.

- If the component provides a standard documentation pattern, replace it with the appropriate [CamelMind component](/getting-started/mdx-components).
- If it provides unique product functionality, evaluate whether that functionality is still necessary before rebuilding it.

=== "MkDocs plugins"

MkDocs sites often rely on plugins to add functionality to Markdown processing, navigation, search, or page generation. For each plugin, identify what it actually provides to the reader. Then:

1. Check whether CamelMind already provides the same capability.
2. Look for a simpler CamelMind-native implementation.
3. Recreate the plugin behavior only if you still require the functionality.

This avoids carrying framework-specific dependencies into your new site unnecessarily.

=== "Custom CSS and themes"

If your existing site has extensive CSS overrides, the migration may carry over relevant CSS.

Start with the migrated site and identify the visual customizations that matter to your users — brand colors, typography, logos, layout, callouts, code blocks, navigation, and custom page elements. Then adapt those elements to CamelMind rather than reproducing the entire Docusaurus or MkDocs theme.

=== "Custom navigation"

The migration uses your existing Docusaurus sidebar or MkDocs navigation to generate `nav/nav.yml`.

If your existing navigation contains custom logic, generated entries, or framework-specific behavior, review the generated navigation manually. Prefer [CamelMind's navigation configuration](/getting-started/navigation) over carrying forward scripts that existed only to generate the old framework's navigation.

=== "Custom landing pages"

Docusaurus and MkDocs sites sometimes use custom React pages or theme templates for their home page. Treat the landing page as a separate design task:

1. Identify the content and actions users need.
2. Recreate that experience in CamelMind.
3. Remove framework-specific code that no longer serves a purpose.

=== "Build scripts"

Review custom build scripts, plugins, and CI steps after the initial migration. Some scripts may no longer be necessary because CamelMind handles the underlying functionality. For each script, ask:

- Does this still solve a problem?
- Is this required for the content, or only for the old framework?
- Can CamelMind handle this natively?
- Can you simplify the workflow?

When migrating existing build scripts to a CamelMind project, convert them to TypeScript `.ts` files in `scripts/` to match the rest of the application code (`lib/, camelmind.config.ts`). Keep a plain `.sh` wrapper only when you need to glue together a few shell commands around a script.

===

---

## Migrate a highly customized site

If your documentation site has significant customizations, migrate a representative portion of the site first. For example, choose:

- A typical documentation page
- A page with custom components
- A page with code examples
- A page with images
- A page using special navigation
- Your home or landing page

Run the migration and use the result to determine what you need to adapt. Once you are comfortable with the approach, migrate the complete repository.

This is safer than trying to reproduce a highly customized site in a single migration pass.

---

## Migration options

| Option | Description |
|---|---|
| `--out <path>` | Specify the output directory. Defaults to `<repo-name>-camelmind`, next to the source repository. |
| `--docs <path>` | Specify the documentation directory relative to the source repository. Defaults to `docs`. |
| `--sidebars <path>` | Force Docusaurus mode and specify a `sidebars.js`, `.mjs`, or `.cjs` file. |
| `--no-install` | Skip `npm install` in the new project. |
| `--dry-run` | Preview the migration without writing files. |
| `-y`, `--yes` | Skip the overwrite confirmation when the output directory already exists. |

---

## Troubleshooting

<Details summary="CamelMind does not detect my site">

Make sure your repository contains the expected configuration file:

- Docusaurus: `sidebars.js`, `sidebars.mjs`, or `sidebars.cjs`
- MkDocs: `mkdocs.yml`

If necessary, use `--sidebars` to explicitly specify the Docusaurus sidebar configuration.

</Details>

<Details summary="Some navigation entries need manual attention">

Review the migration report and the generated `nav/nav.yml`. A navigation entry requires manual attention if CamelMind cannot automatically resolve its source page.

Check the original sidebar or `mkdocs.yml` configuration and make the appropriate adjustment in `nav/nav.yml`.
</Details>

<Details summary="A custom component does not work">

Replace broken components with native CamelMind equivalents, or rebuild only essential custom logic directly for CamelMind.
</Details>

<Details summary="My site has many customizations">

Migrate a representative sample of pages first to establish your pattern before converting the entire site.
</Details>

---

## Get help with your migration

Every documentation site is different, and heavily customized Docusaurus and MkDocs sites may require some additional work.

If you run into an issue during migration, use the [feedback widget](/features/feedback-widget) in CamelMind to reach out for support. When contacting us, include:

- Whether you're migrating from Docusaurus or MkDocs
- What you're trying to migrate
- Any relevant customization or plugin
- The migration command you ran
- The relevant portion of the migration report
- Any error message you encountered

This information helps us understand your migration and recommend the best approach, and helps us improve the migration experience in future releases.