Migration
MkDocs

Migrating from MkDocs to docmd

MkDocs is a popular Python-based generator. docmd provides a similar Markdown-first experience. It relies on Node.js/Bun for incredibly fast builds without complex Python extensions.

Step 1: Run the Migration Engine

Run the following command at the root of your existing MkDocs project:

npx @docmd/core migrate --mkdocs

What Happens Automatically

Backup: Your entire project is safely moved into a new mkdocs-backup/ directory.
Content Migration: Your docs/ folder is restored to the root directory for docmd to use.
Config Generation: A docmd.config.json is generated, extracting your site_name from mkdocs.yml.

Step 2: Test the Setup

Once the command finishes, preview your content in docmd:

npx @docmd/core dev

Your Markdown files will compile, but your navigation sidebar will be empty.

Step 3: Manual Configuration

MkDocs uses mkdocs.yml to define site navigation and extensions. You must translate this setup to docmd manually.

In MkDocs, navigation is strictly defined in the nav key of mkdocs.yml.

Action required: Create a navigation.json inside your docs/ folder.

MkDocs (mkdocs.yml):

nav:
  - Home: index.md
  - Guide:
    - Setup: setup.md
    - Usage: usage.md

docmd (navigation.json):

[
  {
    "title": "Home",
    "path": "/"
  },
  {
    "title": "Guide",
    "collapsible": true,
    "children": [
      { "title": "Setup", "path": "/setup" },
      { "title": "Usage", "path": "/usage" }
    ]
  }
]

2. Replacing Python Markdown Extensions

If you used “Material for MkDocs”, you likely relied on Python Markdown extensions for tabs or admonitions.

Action required: Convert MkDocs-specific extension syntax to docmd’s native Containers.

Example: Converting Admonitions

MkDocs (PyMdown):

!!! note "Optional Title"
    This is an admonition content block.

Manual Conversion Required

MkDocs uses !!! syntax for admonitions, which differs from docmd’s ::: syntax. You must convert these manually or use a find-and-replace tool.

Mapping:

!!! note → ::: callout info or :::note
!!! tip → ::: callout tip or :::tip
!!! warning → ::: callout warning or :::warning
!!! danger → ::: callout danger or :::danger
!!! example → ::: callout info

docmd:

::: callout info "Optional Title"
This is an admonition content block.
:::

Example: Converting Tabs

MkDocs (SuperFences):

=== "Tab 1"
    Content for tab 1.

=== "Tab 2"
    Content for tab 2.