Markdown: arquitectura, automatización y documentación a escala

Este curso está dirigido a desarrolladores y technical writers con experiencia en Markdown y generadores de sitios estáticos que necesitan diseñar, mantener y automatizar ecosistemas de documentación técnica a escala. El participante aprenderá a arquitecturar sistemas docs-as-code multi-repositorio, a automatizar pipelines de validación y publicación, a gestionar extensiones con criterio y a evaluar trade-offs entre variantes y herramientas. Al finalizar, será capaz de definir y desplegar una arquitectura completa de documentación con pipelines automatizados, plantillas reutilizables y criterios de calidad medibles para equipos distribuidos.

Al finalizar el curso, el participante será capaz de:

• Arquitecturar un sistema de documentación docs-as-code multi-repositorio con convenciones de estructura, variante de Markdown y estrategia de versionado justificadas
• Evaluar críticamente al menos tres variantes de Markdown (CommonMark, GFM, MDX) contrastando capacidades, limitaciones y compatibilidad de herramientas según requisitos de un proyecto real
• Automatizar un pipeline de validación y publicación de contenido Markdown con linting, comprobación de enlaces rotos y despliegue condicional en CI/CD
• Optimizar el rendimiento de un sitio generado desde Markdown reduciendo tiempo de build y tamaño de salida con métricas concretas antes y después
• Diseñar un sistema de plantillas y snippets reutilizables para documentación técnica que garantice consistencia de estilo en equipos distribuidos
• Evaluar la estrategia de extensiones y plugins de un generador de sitios estáticos identificando riesgos de mantenimiento, dependencias y lock-in
• Automatizar la generación de documentación de referencia desde artefactos de código (docstrings, OpenAPI) integrándola en un flujo Markdown existente sin intervención manual
• Anticipar y resolver conflictos de renderizado entre entornos (GitHub, portal de documentación, IDE) estableciendo un contrato de compatibilidad documentado
• Optimizar la experiencia de contribución de un repositorio de documentación definiendo flujos de revisión, reglas de linting automatizadas y criterios de aceptación medibles

1. Arquitectura docs-as-code a escala Diseño de sistemas multi-repositorio: convenciones de estructura, selección de variante Markdown y estrategia de versionado; evaluación comparativa de CommonMark, GFM y MDX según capacidades, limitaciones y compatibilidad de herramientas; criterios de decisión y documentación de trade-offs
2. Automatización de pipelines de contenido Pipeline completo de validación y publicación: linting, comprobación de enlaces rotos (broken-link checkers), despliegue condicional en CI/CD; automatización de documentación de referencia desde docstrings y especificaciones OpenAPI integrada en flujos Markdown existentes
3. Optimización, plantillas y extensibilidad Optimización de tiempos de build y tamaño de salida de sitios estáticos: métricas antes/después, técnicas de configuración; diseño de sistema de plantillas y snippets reutilizables para equipos distribuidos; auditoría de extensiones y plugins: riesgos de mantenimiento, dependencias y lock-in
4. Compatibilidad entre entornos y gobernanza de contribución Gestión de conflictos de renderizado entre GitHub, portales de documentación e IDEs; definición de un contrato de compatibilidad por entorno con casos de prueba; flujos de revisión de documentación: reglas de linting automatizadas, criterios de aceptación medibles y métricas de calidad

• Node.js 18 o superior con markdownlint-cli y un broken-link checker (lychee o link-checker)
• Python 3.10 o superior con MkDocs, mkdocs-material y mkdocstrings
• Git y cuenta en GitHub con permisos para configurar GitHub Actions en repositorios de práctica
• Docker (opcional, para reproducir entornos de build controlados)
• Acceso a un proyecto real o de práctica con código documentado (docstrings en Python o equivalente)
• VS Code con extensiones markdownlint y REST Client (para verificar OpenAPI)

→ MKD02 — Markdown: documentación estructurada y ecosistema técnico (Intermedio, 8h)

• Diseñar READMEs y changelogs profesionales siguiendo estándares establecidos (Keep a Changelog, SemVer)
• Depurar documentos Markdown con markdownlint hasta cero advertencias
• Integrar un sitio de documentación con MkDocs o Docusaurus y validar el renderizado en local
• Configurar un flujo de validación en CI/CD con GitHub Actions