Migrating from MkDocs : docmd docs

Migración
MkDocs

MkDocs is a Python-based static site generator. docmd provides a fast, Markdown-first experience built on Node.js/Bun without complex Python virtual environments or extra pip dependencies.

1. Run the Migration Engine

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

npm

pnpm

yarn

Bun

npx @docmd/core migrate --mkdocs

pnpm dlx @docmd/core migrate --mkdocs

yarn dlx @docmd/core migrate --mkdocs

bunx @docmd/core migrate --mkdocs

What Happens Automatically

Backup: Your entire project directory (excluding node_modules, .git, package.json, and lockfiles) is backed up safely 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 and site_dir from mkdocs.yml.
Navigation Auto-Translation: The top-level nav: block in mkdocs.yml is parsed and translated into docmd’s navigation array format (including nested children).

2. Preview the Migration Output

Preview your content in docmd immediately:

npm

pnpm

yarn

Bun

npx @docmd/core dev

pnpm dlx @docmd/core dev

yarn dlx @docmd/core dev

bunx @docmd/core dev

3. Manual Configuration & Extension Mapping

MkDocs uses mkdocs.yml to define navigation structure and PyMdown extensions. Translate any custom setup to docmd containers.

Navigation Setup

Top-level nav: blocks in mkdocs.yml are translated to docmd’s navigation array automatically. If you require advanced navigation features (such as custom icons or external URLs), create a navigation.json in your docs/ folder:

mkdocs.yml

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

navigation.json

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

Replacing Python Markdown Extensions

Convert MkDocs PyMdown extension syntax to docmd’s native Containers.

Converting Admonitions

MkDocs uses !!! block syntax, which requires conversion to ::: format.

MkDocs (PyMdown):

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

docmd:

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

Converting Tabs

MkDocs (SuperFences):

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

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

docmd:

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

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

Next Steps

docmd features built-in search. No extra search plugins or external indexers are required.
Explore the Theming options to customise colours and branding to match your previous theme.