md-to-doc

Convierte una colección de ficheros Markdown en un documento: HTML autocontenido, o PDF.

Por qué existe

Todo repo con documentación seria acaba necesitando lo mismo — juntar los .md en algo que se pueda leer de corrido, imprimir o adjuntar. Y casi siempre se resuelve con un script ad-hoc que solo sirve para ese repo.

Los dos fallos que este skill ataca:

1. Documentos que no son autocontenidos. Un HTML que referencia ./img/diagrama.png deja de funcionar en cuanto se mueve. Aquí las imágenes van embebidas como data URI: el fichero viaja solo.
2. Diagramas que desaparecen. GitHub renderiza los fences ```mermaid de forma nativa, así que se escriben sin pensar. Al exportar a PDF no renderiza nadie: el diagrama sale como un bloque de texto plano o no sale. La capa diagrams los convierte a imagen antes de componer.

Cuándo invocar este skill

Triggers explícitos:

• "genera un PDF de la documentación"
• "exporta los docs a HTML"
• "compila el manual"
• "quiero un solo fichero con toda la doc"
• "los diagramas no salen en el PDF"
• "documentación offline"
• "export docs to PDF"

Triggers proactivos:

• Al preparar una entrega o release que incluya documentación
• Cuando el usuario necesita revisar los docs sin acceso al repo

Cómo se invoca

# Núcleo: cero dependencias
python ~/.agents/skills/md-to-doc/md_to_doc.py --src docs --out manual.html

# Con diagramas y resaltado
python ~/.agents/skills/md-to-doc/md_to_doc.py --src docs --layer diagrams --layer highlight

# Listo para imprimir
python ~/.agents/skills/md-to-doc/md_to_doc.py --src docs --profile print \
    --layer images --layer diagrams --layer pdf --out manual.pdf

Arquitectura por capas

El núcleo nunca depende de nada externo. Cada capa se pide explícitamente y, si su herramienta no está, el documento se genera igual con un aviso en la sección "Avisos de generación" del propio documento.

Orden de los documentos

1. El fichero de --order, si se pasa.
2. SUMMARY.md en el directorio origen (convención mdBook/GitBook).
3. Prefijo numérico (01-, 02-…) y después alfabético.

La capa diagrams y su caché

Los diagramas se cachean por sha256 de su contenido. Un diagrama que no cambió entre dos ejecuciones no se vuelve a renderizar — que importa cuando mmdc arranca un Chromium por invocación.

La capa exec

Solo ejecuta bloques marcados explícitamente:

```python run
print(sum(range(1, 11)))
```

La salida capturada se inserta debajo del código como bloque de consola. El valor es que la documentación muestra lo que el código hace de verdad, no lo que alguien recordaba que hacía cuando lo escribió.

⚠️ Ejecuta código del Markdown de origen. Está detrás de --layer exec, avisa por stderr al arrancar, corre con python -I (aislado de PYTHONPATH y del site del usuario) y con timeout. Aun así: úsala solo sobre fuentes en las que confías. Por defecto está desactivada.

Qué NO hace / limitaciones

• No es un renderizador CommonMark completo. Cubre encabezados, párrafos, énfasis, código inline y en bloque, listas, tablas, citas, reglas, enlaces e imágenes. No cubre listas anidadas de varios niveles, notas al pie, definiciones ni HTML crudo embebido.
• No descarga imágenes remotas. Una ![](https://…) se deja como enlace: el documento deja de ser autocontenido en ese punto y así se reporta.
• Solo ejecuta Python en la capa exec. Otros lenguajes se ignoran con aviso.
• El PDF hereda los límites de xhtml2pdf: soporte CSS parcial y fuentes del sistema. Para tipografía compleja o emoji, revisa el resultado.
• No modifica los .md de origen. Solo lee.

Dependencias

Ver docs/supply-chain-security.md sobre por qué pnpm en lugar de npm.

Ejemplo de salida

✓ HTML autocontenido generado: /repo/manual.html
  documentos procesados: 40
  perfil: color · capas: diagrams, highlight
  ⚠ imagen no encontrada: ./img/archivo.png (desde web-snap)