Converter MD para PDF

Esta é a diferença em relação a toda outra conversão de documento no site. Um arquivo Word sabe seu tamanho de página, suas margens e suas fontes; um arquivo Markdown não sabe nada disso, porque o formato de propósito registra estrutura e deixa a aparência para quem quer que o renderize.

Então toda decisão sobre a página — tamanho, margens, tipografia, onde cai uma quebra — é tomada pelo conversor, e nenhuma delas está no seu arquivo. Essa é a troca que o Markdown faz, e costuma ser boa: o mesmo documento vira uma página web, uma apresentação de slides e um PDF sem ser reescrito. O custo aparece aqui, porque um conversor a quem nunca se ensinou a ler Markdown não tem nada para renderizar e recorre a apenas tipografar os caracteres.

Cada caractere do arquivo chega na página, na ordem, numa tipografia só. Uma linha escrita ## Requisitos sai como ## Requisitos. Um item de lista escrito com hífen é uma linha começando com hífen. Um bloco de código ainda carrega seus três acentos graves acima e abaixo. Negrito mantém seus quatro asteriscos. Nada é descartado e nada é interpretado, porque o motor de documentos por trás deste par lê texto e nunca recebeu um filtro de Markdown.

Vale ser preciso sobre o que isso deixa. Quebras de linha, linhas em branco e recuo são preservados exatamente, então um documento cujo valor está nos comandos e na configuração converte para algo utilizável. Um documento cujo valor está na hierarquia de títulos não converte bem, e a resposta ali é renderizar o Markdown na ferramenta em que você escreveu — uma prévia de editor, um build de site estático, um pipeline de documentação — e imprimir o PDF a partir dali. Esta conversão serve para fixar o texto de um arquivo, não para diagramá-lo.

Um documento Markdown mostrando seis diagramas não contém diagrama nenhum. Contém seis caminhos, e as imagens vivem ao lado no disco ou num servidor. Isso surpreende quem converte pela primeira vez, e é o motivo mais comum de um PDF chegar com buracos.

A correção é fazer os caminhos resolverem antes de converter. Caminhos relativos precisam apontar para arquivos que realmente acompanham o documento; endereços web absolutos dependem de esse servidor estar acessível. Se as imagens são o ponto do documento, este é o passo a acertar, não os ajustes da conversão.

Muitos arquivos Markdown começam com um bloco delimitado por três hífens contendo título, data e algumas etiquetas. Geradores de site estático, construtores de documentação e aplicativos de notas leem isso como metadado e removem antes de renderizar qualquer coisa.

Esta conversão não conhece a convenção e imprime o bloco como tudo o mais, então o PDF começa com três hífens e uma lista de pares chave-valor antes do documento propriamente dito. Apagar o bloco antes de converter é a correção inteira, e vale fazer numa cópia para o original continuar funcionando na ferramenta que o escreveu.

A descrição original do Markdown, de 2004, era informal, o CommonMark é a especificação precisa que a maioria das ferramentas segue, e as tabelas com pipe, listas de tarefas, notas de rodapé e riscado que todo mundo usa são extensões por cima dela. Qual delas uma ferramenta implementa costuma ser a pergunta que decide como um documento sai.

Não é a pergunta nesta página. Nada aqui implementa nenhuma delas, nem o núcleo tampouco, então uma tabela do GitHub e um título CommonMark são tratados de forma idêntica — como linhas de texto. Isso ao menos é previsível: não há sabor para adivinhar nem renderizador para testar, e o que você vê no seu editor com o destaque de sintaxe desligado é o que o PDF vai conter.

Porque o público não é você. Um cliente, um advogado, uma comissão ou um responsável por compliance quer um documento que possa abrir, imprimir, assinar ao redor e arquivar — não um arquivo que a máquina dele oferece abrir num editor de código, e não um repositório que ele tem de navegar. As cerquilhas viajam junto, então isso é uma cópia fixa, não uma apresentável.

Um PDF também congela o estado. Um README muda toda semana; um PDF dele é o que era verdade no dia em que foi anexado a alguma coisa, que é exatamente o que uma revisão, uma submissão ou um anexo contratual precisa. Continue escrevendo em Markdown e exporte no momento em que alguém de fora precisar de uma cópia.

HTML quando o destino é uma página web ou um site de documentação, já que o Markdown foi desenhado como uma taquigrafia para isso e a conversão é mais uma tradução do que uma renderização.

DOCX numa situação específica e comum: o destinatário só aceita um arquivo Word, e quer adicionar controle de alterações. Markdown não tem nenhum fluxo de revisão, então um documento indo para uma rodada de comentários é melhor entregue como DOCX e lido de volta depois — e PDF é para a versão que está pronta. Esse destino passa pelo mesmo motor, então a marcação chega no arquivo Word também como texto; a diferença é que o revisor consegue corrigir um título e você não consegue corrigir um num PDF.

Este par roda no nosso servidor, não no navegador: montar um PDF a partir de texto exige um motor de documentos completo, e é por isso que o limite gratuito aqui é 25 megabytes por arquivo em vez dos 100 megabytes que uma conversão no navegador aceita. O arquivo viaja por conexão criptografada e a pasta de trabalho é apagada assim que o job termina.

O plano gratuito também conta cem conversões de servidor por visitante a cada dia UTC, com um teto de rajada de cinco pedidos por minuto contra uso automatizado. Nada disso se aplica às conversões deste site que rodam no seu navegador — só aos pares de servidor, e este é um deles.