Markdown: documentación estructurada y ecosistema técnico

Este curso está dirigido a desarrolladores y perfiles técnicos que ya redactan documentación básica en Markdown y necesitan dar el salto a documentos estructurados, mantenibles e integrados en flujos de trabajo reales. El participante aprenderá a diseñar READMEs y changelogs profesionales, a comparar los principales dialectos de Markdown, a depurar documentos con linters y a integrar la documentación en sitios estáticos y pipelines de CI/CD. Al finalizar, será capaz de mantener un repositorio de documentación con estándares de calidad automatizados y validados en cada pull request.

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

• Diseñar un README completo para un proyecto de software real con secciones de instalación, uso, contribución y licencia respetando la jerarquía semántica de encabezados
• Comparar al menos tres dialectos de Markdown (CommonMark, GFM y MDX) identificando diferencias de sintaxis concretas que afectan al renderizado en cada plataforma destino
• Justificar la elección de una estructura de documentación (página única vs. carpeta wiki) en función del tipo de contenido y la audiencia
• Depurar un documento Markdown con al menos cinco errores de sintaxis usando markdownlint hasta obtener cero advertencias
• Integrar un sitio de documentación estático con MkDocs o Docusaurus verificando la navegación y el renderizado en local
• Adaptar un documento técnico en formato Word o texto plano a Markdown válido para GitHub sin pérdida de información
• Diseñar una plantilla de changelog siguiendo el estándar Keep a Changelog con entradas versionadas bajo SemVer y secciones diferenciadas por tipo de cambio
• Integrar un flujo de validación de Markdown en un pipeline de CI que bloquee merges cuando markdownlint detecta errores críticos

1. Diseño de documentación de proyecto READMEs profesionales: secciones esenciales (instalación, uso, contribución, licencia), jerarquía semántica de encabezados, badges e índices; decisión justificada entre página única y wiki según audiencia y tipo de contenido; adaptación de documentos Word o texto plano a Markdown GitHub-compatible preservando jerarquía, código y referencias cruzadas
2. Dialectos y compatibilidad CommonMark vs. GFM vs. MDX: diferencias de sintaxis relevantes para el renderizado en GitHub, portales de documentación y entornos React; criterios para elegir el dialecto según la plataforma destino
3. Calidad con linters y estándares Instalación y configuración de markdownlint, interpretación de reglas y severidades, corrección sistemática de errores frecuentes (tablas rotas, listas mal anidadas, enlaces vacíos); diseño de plantilla CHANGELOG.md con Keep a Changelog y SemVer
4. Integración en ecosistema y CI/CD Generación de sitios estáticos con MkDocs o Docusaurus: estructura de proyecto, configuración básica, navegación local; integración de markdownlint en GitHub Actions para bloquear merges con errores críticos

• Node.js 18 o superior (para markdownlint-cli y Docusaurus)
• Python 3.10 o superior con pip (para MkDocs)
• markdownlint-cli instalado globalmente (npm install -g markdownlint-cli)
• Git y cuenta en GitHub con acceso para crear repositorios y pull requests
• VS Code con extensión markdownlint para feedback en tiempo real

→ MKD01 — Markdown: fundamentos y documentación técnica (Iniciación, 8h)

• Identificar y nombrar los elementos esenciales de la sintaxis Markdown (encabezados, listas, énfasis, código, enlaces, imágenes)
• Aplicar la sintaxis de encabezados, listas y bloques de código en documentos de estructura guiada
• Construir un README básico con todas sus secciones esenciales