Migrar desde mkdocs

Migrar desde mkdocs

bxSites migrate --from=mkdocs convierte un proyecto mkdocs - mkdocs.yml más su carpeta docs/ - en un proyecto bx-sites completo, en un solo comando:

bxSites migrate --source=/path/to/mkdocs-project --from=mkdocs

• --source (obligatorio) - el directorio raíz del proyecto mkdocs (debe contener mkdocs.yml)

A diferencia de migrar desde GitBook, esto es sobre todo una traducción de configuración, no de contenido. La propia carpeta docs/ de mkdocs ya usa las convenciones exactas de bx-sites - el anidamiento de carpetas es estructura de navegación, index.md es la página de inicio propia de una carpeta, y los enlaces .md relativos entre páginas simplemente funcionan. Más aún: la propia sintaxis de Markdown extendida de mkdocs-material es la misma sintaxis textual que bx-sites ya habla, porque bx-sites se modeló en mkdocs-material desde el principio (consulta Extensiones de Markdown). Así que los cuerpos de las páginas se copian byte a byte sin cambios - nada aquí necesita reescribir admoniciones !!! note, pestañas de contenido === "Tab", ni matemáticas $x^2$, porque ya son sintaxis válida de bx-sites.

Qué se convierte automáticamente

mkdocs.yml → bxsites.yaml:

Cualquier otra entrada de markdown_extensions que la propia sintaxis de mkdocs-material ya cubra de forma nativa - admonition, pymdownx.tabbed, pymdownx.details, pymdownx.superfences, pymdownx.highlight, toc, attr_list, y más - no necesita ningún cambio en bxsites.yaml en absoluto; bx-sites ya se comporta así de fábrica.

nav: → docs/nav.json:

# mkdocs.yml
nav:
  - Home: index.md
  - Guide:
      - Setup: guide/setup.md
      - Advanced: guide/advanced.md
  - About: about.md

se convierte en:

[
  { "title": "Home", "path": "index.md", "children": [] },
  { "title": "Guide", "path": "", "children": [
    { "title": "Setup", "path": "guide/setup.md", "children": [] },
    { "title": "Advanced", "path": "guide/advanced.md", "children": [] }
  ] },
  { "title": "About", "path": "about.md", "children": [] }
]

• una entrada de ruta simple (- about.md, sin título explícito) también se convierte - su título proviene del propio frontmatter/ primer encabezado de la página migrada, igual que cualquier entrada de docs/nav.json de bx-sites sin title establecido
• consulta Configuración: nav para el formato completo

Páginas y recursos:

• cada archivo .md se copia a la misma ruta bajo docs/, sin cambios
• cualquier otro archivo (imágenes, PDF, ...) se traslada a docs/assets/mkdocs/<same-relative-path> - el propio pipeline de recursos de bx-sites solo publica docs/assets/**, y mkdocs no tiene ninguna convención de carpeta de recursos única propia como sí lo es el .gitbook/assets/ de GitBook, así que las imágenes suelen estar dispersas junto a las páginas que las usan
• cada referencia a un recurso trasladado - ![diagram](img/diagram.png), por ejemplo - se reescribe a la ruta relativa correcta que llega a su nueva ubicación, teniendo en cuenta la profundidad a la que se encuentra la propia página que enlaza (la misma convención de "el autor escribe el número correcto de ../" que ya usa cualquier proyecto bx-sites - calculada por ti aquí en lugar de dejarse a un buscar-y-reemplazar)

Qué necesita revisión manual

Reportado como advertencias en la propia salida del comando, nada se descarta silenciosamente:

• una entrada markdown_extensions/plugins de mkdocs sin ningún equivalente en bx-sites (los propios códigos cortos de emoji de mkdocs-material, un plugin de terceros como awesome-pages o git-revision-date) - si necesitas el mismo comportamiento, consulta Plugins
• la propia personalización de color/fuente de mkdocs.yml (theme.palette/theme.font) no tiene ningún equivalente directo - consulta Personalizar colores una vez terminada la migración
• un theme.name distinto de material (por defecto pasa a bootstrap)

Ejemplo completo

bxSites new --projectRoot=my-docs
bxSites migrate --projectRoot=my-docs --source=../my-mkdocs-project --from=mkdocs
cd my-docs
bxSites serve

migrate escribe bxsites.yaml y el propio docs/ - el paso new de arriba solo está ahí para obtener una raíz de proyecto con docs/ lista para recibirlos; migrate crea docs/ por sí mismo también, así que no es estrictamente obligatorio. Revisa las propias advertencias del comando, y luego usa serve para ver el resultado antes de hacer commit.