Migrating to docmd
docmd provides a fully automated migration engine. Transition from legacy platforms with a single command. The engine eliminates the tedious work of moving Markdown files and restructuring directories.
How It Works
The migration command will:
- Detect your existing configuration file (e.g.,
docusaurus.config.js,mkdocs.yml). - Extract core metadata like your site’s
title. - Backup your existing files and directories safely into a
*-backup/directory. - Copy your Markdown content into the standard docmd
docs/directory. - Generate a fresh
docmd.config.jsontailored for your content.
You can then run npx @docmd/core dev immediately to see your content rendered.
What is Migrated
| Feature | Migrated Automatically? |
|---|---|
| Markdown Files | ✅ Yes, all .md and .mdx files are moved to docs/ |
| Directory Structure | ✅ Yes, your folder nesting is preserved |
| Site Title | ✅ Yes, extracted from your config |
| Container Syntax | ✅ Yes, VitePress/Docusaurus containers work without changes |
| Navigation / Sidebar | ⚠️ No, requires manual mapping |
| Localisation (i18n) | ⚠️ No, requires manual mapping |
| Versioning | ⚠️ No, requires manual mapping |
| Custom React/Vue Components | ❌ No, these must be replaced with docmd Containers |
Container syntax from VitePress (:::tip, :::warning, :::danger, :::info, :::details) and Docusaurus (:::note, :::caution) works without modification. Your existing admonitions and collapsible sections render correctly in docmd.
MkDocs uses !!! syntax, which requires manual conversion to ::: format.
Why Navigation and i18n Aren’t Automatically Migrated
Every platform handles navigation sidebars, translations, and multi-versioning differently. For example, Docusaurus uses complex JavaScript objects. MkDocs relies on strictly indented YAML structures.
Rather than risking a broken migration by guessing complex configurations, docmd moves your content safely. You must configure navigation, localisation, and versioning natively using docmd’s JSON-based APIs.
- Navigation: Learn how to create a
navigation.jsonin the Navigation Setup. - Localisation: See the Localisation Guide for setting up multi-language docs.
- Versioning: Refer to the Versioning Setup.
Supported Platforms
Select your current platform for specific migration instructions:
