Migración
MkDocs

Migrar desde MkDocs

MkDocs es un generador de sitios estáticos basado en Python. docmd ofrece una experiencia orientada primero a Markdown creada sobre Node.js/Bun sin complejos entornos virtuales de Python ni dependencias adicionales de pip.

1. Ejecutar el motor de migración

Ejecuta el siguiente comando en la raíz de tu proyecto existente de MkDocs:

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

Qué sucede automáticamente

Copia de seguridad: Todo el directorio de tu proyecto (excluyendo node_modules, .git, package.json y archivos de bloqueo) se respalda de forma segura en un nuevo directorio mkdocs-backup/.
Migración de contenido: Tu carpeta docs/ se restaura en el directorio raíz para que la use docmd.
Generación de configuración: Se genera un docmd.config.json, extrayendo tu site_name y site_dir de mkdocs.yml.
Autotraducción de navegación: El bloque superior nav: en mkdocs.yml se analiza y traduce al formato del array navigation de docmd (incluyendo children anidados).

2. Previsualizar la salida de la migración

Previsualiza tu contenido en docmd de inmediato:

npm

pnpm

yarn

Bun

npx @docmd/core dev

pnpm dlx @docmd/core dev

yarn dlx @docmd/core dev

bunx @docmd/core dev

3. Configuración manual y mapeo de extensiones

MkDocs utiliza mkdocs.yml para definir la estructura de navegación y extensiones de PyMdown. Traduce cualquier configuración personalizada a contenedores de docmd.

Configuración de navegación

Los bloques superiores nav: en mkdocs.yml se traducen automáticamente al array navigation de docmd. Si requieres funciones avanzadas de navegación (como iconos personalizados o URLs externas), crea un archivo navigation.json en tu carpeta docs/:

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" }
    ]
  }
]

Reemplazar extensiones de Python Markdown

Convierte la sintaxis de las extensiones de PyMdown de MkDocs a los Contenedores nativos de docmd.

Convertir avisos

MkDocs utiliza la sintaxis de bloques !!!, la cual requiere conversión al formato :::.

MkDocs (PyMdown):

!!! note "Título opcional"
    Este es un bloque de contenido de aviso.

docmd:

::: callout info "Título opcional"
Este es un bloque de contenido de aviso.
:::

Convertir pestañas

MkDocs (SuperFences):

=== "Pestaña 1"
    Contenido para la pestaña 1.

=== "Pestaña 2"
    Contenido para la pestaña 2.

docmd:

::: tabs
== tab "Pestaña 1"
Contenido para la pestaña 1.

== tab "Pestaña 2"
Contenido para la pestaña 2.
:::

Siguientes pasos

docmd cuenta con búsqueda integrada. No se requieren plugins de búsqueda adicionales ni indexadores externos.
Explora las Opciones de temas para personalizar colores y marca y adaptarlos a tu tema anterior.