Markdown para PDF

Markdown é um formato de escrita, deliberadamente próximo do texto puro: legível em qualquer editor, comparável em controle de versão e livre do estado invisível que torna arquivos de processador de texto desconfortáveis de colaborar. O que ele não é é um formato de entrega. Um arquivo .md entregue a alguém fora desse hábito é um arquivo de texto cheio de cerquilhas e asteriscos.

O PDF é o complemento. Ele fixa a aparência, pagina o conteúdo, abre em qualquer coisa sem editor nem renderizador, e imprime direito. Escrever em Markdown e entregar em PDF dá as duas metades: uma fonte que você pode guardar em um repositório e revisar como texto, e um artefato que qualquer pessoa consegue ler.

Os casos típicos são documentação entregue a um cliente, um README transformado em referência imprimível, notas técnicas para uma reunião, e escrita acadêmica ou pessoal rascunhada em texto puro e entregue como documento.

Há duas formas de fazer um PDF a partir de Markdown, e elas produzem arquivos bem diferentes. O atalho é renderizar o Markdown como página da web e fotografá-la, o que é rápido e resulta em um documento feito de figuras — não pesquisável, não copiável, invisível para leitores de tela e borrado quando impresso em qualquer tamanho diferente daquele em que foi capturado.

A outra forma dispõe o conteúdo em uma página de verdade: texto desenhado a partir de fontes incorporadas nos tamanhos escolhidos, parágrafos fluídos em uma medida, quebras de página colocadas entre blocos em vez de no meio deles. É isso que acontece aqui, e é por isso que o resultado se comporta como um documento e não como uma sequência de imagens.

A diferença aparece nas coisas comuns que as pessoas fazem com PDFs depois. Buscar um termo funciona. Copiar um trecho de código devolve código. Imprimir em A4 um documento diagramado para A4 produz tipos nítidos em qualquer zoom.

Os títulos viram uma hierarquia de tamanhos de verdade, e não texto em negrito, então o documento tem estrutura visível. A ênfase é renderizada como itálico e negrito. Listas ordenadas e não ordenadas se aninham corretamente, com uma indentação que deixa os níveis legíveis. Citações são destacadas do corpo, e as linhas horizontais viram filetes.

O código recebe o tratamento mais cuidadoso porque é o menos tolerante. O código embutido é composto em uma fonte monoespaçada, para que se leia como código no meio da frase; os blocos delimitados mantêm o espaçamento exatamente e não são reorganizados, já que a indentação tem significado na maioria das linguagens. A única coisa a conferir em uma listagem impressa é a largura das linhas, porque uma página não rola para o lado.

As tabelas são renderizadas com colunas alinhadas e limites de célula de verdade. Os links mantêm o texto e continuam visíveis como links. As imagens referenciadas na fonte são inseridas no fluxo, em um tamanho que cabe na página.

Alguns hábitos melhoram o resultado mais do que qualquer ajuste. Use um único título de primeiro nível e aninhe de forma consistente abaixo dele — um documento que pula de um título de primeiro nível para um de terceiro produz uma hierarquia que parece quebrada na página, mesmo que renderize bem em um navegador.

Mantenha as linhas de código abaixo de uns oitenta caracteres quando a listagem importa, porque é mais ou menos o que cabe confortavelmente em uma página em retrato com fonte monoespaçada. Tabelas longas valem ser divididas em duas mais estreitas em vez de deixar as colunas comprimirem.

Para documentos que precisam de matemática, diagramas ou prévia ao vivo enquanto se escreve, o Editor de Markdown é o ponto de partida melhor — ele renderiza LaTeX e Mermaid, salva automaticamente e exporta para PDF, Word e HTML. Markdown para Word é o caminho quando quem recebe precisa editar em vez de ler.