Migrate from Docusaurus or MkDocs
Migrate an existing Docusaurus or MkDocs site to CamelMind with one command, then review and adapt the result.
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.
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.
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:
npx camelmind@latest migrate path/to/your-docs-repo
CamelMind automatically detects:
- Docusaurus from
sidebars.js,sidebars.mjs, orsidebars.cjs - MkDocs from
mkdocs.yml
The migration creates a new CamelMind project next to your source repository:
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.
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:
cd ../your-docs-repo-camelmind
If the migration did not install dependencies, run:
npm install
Then start the development server:
npm run dev
Open 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.
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.
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.
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.
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.
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.
Docusaurus sites may contain custom React components used directly in MDX, for example:
<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.
- If it provides unique product functionality, evaluate whether that functionality is still necessary before rebuilding it.
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:
- Check whether CamelMind already provides the same capability.
- Look for a simpler CamelMind-native implementation.
- Recreate the plugin behavior only if you still require the functionality.
This avoids carrying framework-specific dependencies into your new site unnecessarily.
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.
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 over carrying forward scripts that existed only to generate the old framework's navigation.
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:
- Identify the content and actions users need.
- Recreate that experience in CamelMind.
- Remove framework-specific code that no longer serves a purpose.
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
CamelMind does not detect my site
Make sure your repository contains the expected configuration file:
- Docusaurus:
sidebars.js,sidebars.mjs, orsidebars.cjs - MkDocs:
mkdocs.yml
If necessary, use --sidebars to explicitly specify the Docusaurus sidebar configuration.
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.
A custom component does not work
Replace broken components with native CamelMind equivalents, or rebuild only essential custom logic directly for CamelMind.
My site has many customizations
Migrate a representative sample of pages first to establish your pattern before converting the entire site.
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 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.