Convertir Markdown a PDF

Qué Markdown, y en qué se convierte

Markdown es una familia más que una única especificación. El núcleo común (títulos, énfasis, listas, enlaces, imágenes, citas en bloque, bloques de código) es igual en todas partes, y más allá de eso cada implementación es distinta. Aquí se admite el conjunto ampliado en el que casi todos coinciden: tablas, bloques de código delimitados con resaltado de sintaxis, listas de tareas, tachado, notas al pie y front matter. Eso cubre lo que escribe casi todo el mundo, y vale la pena conocer el límite en lugar de descubrirlo.

Los títulos se convierten en estructura real del PDF y no solo en texto más grande: llevan niveles de esquema, así que el PDF tiene una barra lateral de marcadores por la que puedes navegar. Los enlaces se convierten en anotaciones de enlace que funcionan. Los bloques de código se componen en una fuente monoespaciada con resaltado, que es la diferencia entre un documento agradable de leer y un muro gris. El tamaño de página y los márgenes se eligen pensando en la lectura en lugar de heredarse, porque un archivo Markdown no tiene ninguna opinión sobre el papel.

Las imágenes tienen que estar accesibles, y esta es la decepción más común. Un archivo Markdown hace referencia a las imágenes en lugar de contenerlas, así que una ruta relativa solo se resuelve si la imagen se suelta junto con el archivo, y una dirección web solo se resuelve si ese servidor permite que otros sitios la descarguen. Una imagen que no se encuentra se señala en el PDF en lugar de dejar un hueco silencioso, así que un diagrama que falta se ve, en vez de ser algo que notas después de enviar el documento.

Dos cosas se muestran a propósito como código en lugar de renderizarse. Las fórmulas matemáticas en notación LaTeX y los diagramas de Mermaid necesitan cada uno su propio renderizador, y renderizarlos mal es peor que mostrar el código fuente: una ecuación mal renderizada es incorrecta de una forma que nadie puede ver. El HTML sin procesar dentro del Markdown se maneja para formato en línea sencillo y no para diseño, porque un bloque arbitrario de marcado no tiene cabida en un documento paginado.

Si buscas otra cosa

Pandoc es la herramienta seria para esto, y es gratis. pandoc doc.md -o doc.pdf --pdf-engine=xelatex compone a través de LaTeX, que produce un resultado realmente bonito, con separación silábica correcta, control de líneas viudas y un índice de verdad, y con una plantilla controlas cada aspecto del diseño. Además renderiza correctamente las fórmulas LaTeX, que es justo lo que falta aquí. El precio es instalar una distribución de TeX, que no es pequeña.

Para documentación, y no para un documento puntual, un generador de sitios estáticos o mdBook produce algo mejor que un PDF: se puede buscar, enlazar y leer en el celular. Convierte a PDF cuando el documento tenga que imprimirse, adjuntarse o archivarse, y en cualquier caso conserva el Markdown como fuente original, porque es la versión que se puede editar y comparar.