Converter HTML em PDF

O que a página pode acessar e o que o CSS controla

A conversão não tem acesso à rede e não executa scripts, e as duas coisas são decisões de segurança, não recursos que faltam. Um conversor que buscasse tudo o que uma página enviada pedisse poderia muito bem ser apontado para endereços que só o nosso servidor enxerga, e um que executasse scripts estaria rodando código de um desconhecido. Então uma folha de estilos vinculada a um CDN não chega, uma imagem com um endereço web comum não carrega, uma fonte web é substituída sem aviso, e uma página que se desenha com JavaScript é convertida do jeito que a marcação está antes de qualquer coisa rodar. A solução é sempre a mesma: coloque o CSS inline em um bloco style e incorpore as imagens como data URIs. Os navegadores oferecem isso diretamente — “Salvar página como → Página web completa” no Firefox, ou “Salvar como MHTML” —, e uma página salva em arquivo único é convertida com fidelidade.

O CSS de impressão é o que realmente manda no resultado, e essa é a segunda coisa que vale saber. A página é montada como se fosse impressa, então um bloco @media print entra em vigor e uma folha de estilos comum de tela pode não entrar — é por isso que uma página com uma regra de impressão que esconde a navegação é convertida lindamente, e uma sem essa regra traz junto todo o cabeçalho e o menu do site. O @page controla o papel: tamanho, orientação e margens são lidos dele. break-before, break-after e break-inside: avoid decidem onde as páginas se dividem, então uma tabela que não pode ser partida ou uma seção que precisa começar em página nova ficam inteiramente sob o seu controle.

Os fundos são o esquecimento clássico. Os navegadores não imprimem cores e imagens de fundo por padrão, então um cabeçalho escuro pode sair branco, a menos que a folha de estilos diga -webkit-print-color-adjust: exact — uma linha só, e é a diferença entre um documento com a sua identidade visual e um documento sem graça. O texto continua sendo texto de verdade, os links continuam funcionando, e os títulos podem virar marcadores do PDF quando a marcação usa elementos de título de verdade.

Se nosso servidor estiver fora do ar, a página avisa e reconstrói o documento localmente, o que mantém o texto, as imagens e o layout simples, mas simplifica tudo o que exige um cálculo de layout de verdade — grid, flexbox, floats e posicionamento, entre outros. Um documento simples é convertido quase idêntico; um documento elaborado, não.

Quando você precisa de outra coisa

Para converter uma URL ao vivo — algo que esta página deliberadamente não faz —, a mesma renderização que roda no nosso servidor roda no seu: chrome --headless --disable-gpu --print-to-pdf=out.pdf https://example.com carrega a página com a rede disponível, scripts e tudo. Essa é toda a diferença, e é o motivo para recorrer a ele.

Para ter controle real sobre cabeçalhos, rodapés, números de página e margens, o WeasyPrint e o Prince implementam direito a especificação CSS Paged Media: cabeçalhos corridos com @top-center, contadores de página, notas de rodapé e referências cruzadas que viram números de página. O WeasyPrint é gratuito e é o que a maioria dos fluxos de documentação usa. O Chrome não suporta quase nada disso, então um relatório gerado com “Página 3 de 12” no rodapé precisa de um deles, e não disto.