Markdown a PDF

El Markdown es un formato para escribir, deliberadamente cercano al texto plano: legible en cualquier editor, comparable línea a línea en el control de versiones y libre del estado invisible que vuelve incómodos los archivos de procesador de textos a la hora de colaborar. Lo que no es es un formato de entrega. Un archivo .md entregado a alguien que no tiene la costumbre es un archivo de texto lleno de almohadillas y asteriscos.

El PDF es el complemento. Fija la apariencia, pagina el contenido, se abre en cualquier cosa sin editor ni motor de representación, y se imprime bien. Escribir en Markdown y entregar en PDF te da las dos mitades: un origen que puedes guardar en un repositorio y revisar como texto, y una pieza que cualquiera puede leer.

Los casos típicos son la documentación entregada a un cliente, un README convertido en una referencia imprimible, unas notas técnicas para una reunión, y la escritura académica o personal redactada en texto plano y entregada como documento.

Hay dos formas de hacer un PDF a partir de Markdown y producen archivos muy distintos. El atajo consiste en representar el Markdown como una página web y fotografiarla, que es rápido y da un documento hecho de imágenes: no se puede buscar, no se puede copiar, es invisible para los lectores de pantalla y sale borroso al imprimirlo a cualquier tamaño que no sea aquel con el que se capturó.

La otra forma coloca el contenido sobre una página de verdad: texto dibujado a partir de fuentes incrustadas en los tamaños elegidos, párrafos ajustados a un ancho de medida y saltos de página colocados entre bloques en vez de a través de ellos. Eso es lo que ocurre aquí, y por eso el resultado se comporta como un documento y no como un pase de imágenes.

La diferencia se nota en las cosas corrientes que la gente hace después con un PDF. Buscar un término funciona. Copiar un fragmento de código te devuelve código. Imprimir en A4 un documento maquetado para A4 produce una letra nítida a cualquier ampliación.

Los títulos se convierten en una jerarquía de tamaños de verdad y no en texto en negrita, así que el documento tiene una estructura visible. El énfasis se representa como cursiva y negrita. Las listas ordenadas y sin ordenar se anidan correctamente, con una sangría que hace legibles los niveles. Las citas se separan del cuerpo y las líneas horizontales se convierten en filetes.

El código recibe el trato más cuidadoso porque es el que menos perdona. El código en línea se compone con una fuente monoespaciada para que se lea como código dentro de la frase; los bloques delimitados conservan sus espacios exactamente y no se recomponen, porque en la mayoría de los lenguajes la sangría significa algo. Lo único que conviene comprobar en un listado impreso es el ancho de línea, porque una página no se puede desplazar en horizontal.

Las tablas se representan con columnas alineadas y bordes de celda reales. Los enlaces conservan su texto y siguen viéndose como enlaces. Las imágenes referenciadas en el origen se colocan en su sitio a un tamaño que quepa en la página.

Unas pocas costumbres mejoran el resultado más que cualquier ajuste. Usa un único título de primer nivel y anida por debajo de él de forma coherente: un documento que salta de un título de primer nivel a uno de tercero produce una jerarquía que se ve rota sobre la página aunque se represente bien en un navegador.

Mantén las líneas de código por debajo de unos ochenta caracteres cuando el listado importe, porque eso es aproximadamente lo que cabe con holgura en una página vertical con una fuente monoespaciada. Las tablas largas merecen dividirse en dos más estrechas en lugar de dejar que las columnas se compriman.

Para documentos que necesiten fórmulas, diagramas o una vista previa en vivo mientras escribes, el Editor de Markdown es mejor punto de partida: representa LaTeX y Mermaid, guarda solo y exporta a PDF, Word y HTML. Markdown a Word es el camino cuando quien lo recibe necesita editar en vez de leer.