Converter Markdown em PDF

Qual Markdown, e no que ele se transforma

Markdown é uma família, e não uma especificação única. O núcleo comum — títulos, ênfase, listas, links, imagens, citações em bloco, blocos de código — é igual em todo lugar, e além disso cada implementação é diferente. O que é suportado aqui é o conjunto estendido amplamente aceito: tabelas, blocos de código delimitados com realce de sintaxe, listas de tarefas, tachado, notas de rodapé e front matter. Isso cobre o que quase todo mundo escreve, e vale mais conhecer o limite do que descobri-lo na prática.

Os títulos viram estrutura real do PDF, e não apenas texto maior: eles têm níveis de estrutura de tópicos, então o PDF ganha uma barra lateral de marcadores para navegar. Os links viram anotações de link que funcionam. Os blocos de código são compostos em uma fonte monoespaçada com realce, que é a diferença entre um documento agradável de ler e uma parede cinza. O tamanho da página e as margens são escolhidos para a leitura, e não herdados, já que um arquivo Markdown não tem opinião sobre papel.

As imagens precisam estar acessíveis, e essa é a decepção mais comum. Um arquivo Markdown faz referência às imagens, em vez de contê-las, então um caminho relativo só funciona se a imagem for solta junto com o arquivo, e um endereço da web só funciona se aquele servidor permitir que outros sites a busquem. Uma imagem que não é encontrada é sinalizada no PDF, em vez de deixar um buraco silencioso, então um diagrama faltando fica visível, e não é algo que você só percebe depois de enviar o documento.

Duas coisas aparecem como código de propósito, em vez de serem renderizadas. Fórmulas matemáticas em notação LaTeX e diagramas Mermaid precisam, cada um, do próprio renderizador, e renderizá-los errado é pior do que mostrar o código-fonte — uma equação mal renderizada fica errada de um jeito que ninguém percebe. HTML puro dentro do Markdown é tratado para formatação simples em linha, e não para layout, já que um bloco qualquer de marcação não tem lugar em um documento paginado.

Quando você precisa de outra coisa

O Pandoc é a ferramenta séria para isso, e é gratuito. pandoc doc.md -o doc.pdf --pdf-engine=xelatex faz a composição via LaTeX, o que gera um resultado realmente bonito, com hifenização correta, controle de linhas viúvas e um sumário de verdade — e, com um modelo, você controla todos os aspectos do design. Ele também renderiza matemática LaTeX corretamente, que é justamente a lacuna daqui. O custo é instalar uma distribuição TeX, que não é pequena.

Para documentação, e não um documento avulso, um gerador de sites estáticos ou o mdBook produz algo melhor que um PDF: pesquisável, com links e legível no celular. Converta para PDF quando o documento precisar ser impresso, anexado ou arquivado — e, de qualquer forma, mantenha o Markdown como fonte da verdade, porque é a versão que pode ser editada e comparada.