TongoRender — HTML to PDF, Image & Screenshot API for Developers

Você escolheu uma API de HTML para PDF e escreveu seu primeiro template — mas o resultado não ficou perfeito. O texto é cortado nos limites de página, imagens estão faltando, as fontes estão erradas e o layout quebra em documentos com múltiplas páginas. Soa familiar? Este guia cobre as boas práticas comprovadas que vão ajudá-lo a produzir PDFs perfeitos a partir de HTML toda vez.

Use CSS Otimizado para Impressão

O navegador tem dois modos de renderização: tela e impressão. Ao gerar PDFs, o motor de renderização muda para o modo de impressão, o que significa que suas regras @media print entram em vigor. Essa é sua ferramenta mais poderosa para controlar a saída PDF.

/* Estilos base se aplicam tanto à tela quanto à impressão */
body {
  font-family: 'Inter', sans-serif;
  color: #333;
  line-height: 1.6;
}

/* Sobrescritas específicas para impressão */
@media print {
  /* Remova navegação, barras laterais e outros elementos de UI */
  nav, .sidebar, .footer, .no-print { display: none; }

  /* Garanta que fundos sejam impressos */
  body { -webkit-print-color-adjust: exact; print-color-adjust: exact; }

  /* Defina margens da página */
  @page { margin: 20mm 15mm; }

  /* Melhore a tipografia para impressão */
  body { font-size: 11pt; line-height: 1.5; }
  h1 { font-size: 22pt; }
  h2 { font-size: 16pt; }
}

Pontos importantes:

Sempre inclua print-color-adjust: exact (e o prefixo -webkit-) se quiser que cores de fundo e imagens apareçam no PDF. Por padrão, navegadores removem fundos no modo de impressão.
Use a regra @page para controlar as margens da página. Isso é separado das margens do body e controla a área efetivamente imprimível.
Use unidades físicas como pt, mm e cm para impressão — elas são mais previsíveis do que px ou rem em um contexto paginado.

Gerencie Quebras de Página Corretamente

Quebras de página são a fonte mais comum de frustração na renderização de PDFs. Sem regras de quebra adequadas, o Chromium vai dividir o conteúdo onde quer que o espaço acabe — frequentemente no meio de uma linha de tabela, um título ou um bloco de código.

/* Evite que títulos fiquem órfãos no final de uma página */
h1, h2, h3, h4 {
  page-break-after: avoid;
  break-after: avoid;
}

/* Mantenha imagens e figuras juntas */
figure, img {
  page-break-inside: avoid;
  break-inside: avoid;
}

/* Evite que linhas de tabela se dividam entre páginas */
tr {
  page-break-inside: avoid;
  break-inside: avoid;
}

/* Repita cabeçalhos de tabela em cada página */
thead {
  display: table-header-group;
}

/* Force uma quebra de página antes de uma nova seção */
.nova-secao {
  page-break-before: always;
  break-before: page;
}

/* Evite viúvas e órfãos */
p {
  widows: 3;
  orphans: 3;
}

As propriedades widows e orphans controlam quantas linhas de um parágrafo devem aparecer no topo ou no final de uma página. Definir ambas como 3 garante que você nunca tenha uma linha solitária no início ou fim de uma página.

Fontes Web: Garantindo Que Renderizem

Fontes são uma fonte frequente de problemas de renderização de PDF. Se uma fonte não carregar, o navegador recorre a uma fonte padrão do sistema, e seu template cuidadosamente projetado fica com aparência errada. Aqui estão as regras:

Use Google Fonts via Tag Link

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">

Google Fonts são hospedadas em um CDN rápido e funcionam de forma confiável com a maioria das APIs de PDF. O parâmetro display=swap garante que a fonte seja baixada prontamente.

Hospede Fontes Críticas Você Mesmo

Para máxima confiabilidade, hospede suas fontes usando declarações @font-face com URLs absolutas:

@font-face {
  font-family: 'FonteCustomizada';
  src: url('https://seudominio.com.br/fontes/FonteCustomizada-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

Sempre Especifique Fontes de Fallback

body {
  font-family: 'Inter', 'Helvetica Neue', Arial, sans-serif;
}

Imagens: Use URLs Absolutas

Esta é uma regra simples que previne inúmeros problemas: sempre use URLs absolutas para imagens. Quando a API de PDF renderiza seu HTML, ela precisa buscar imagens pela rede. URLs relativas como ./images/logo.png vão falhar porque o servidor da API não tem acesso ao seu sistema de arquivos local.

<!-- Errado: URL relativa -->
<img src="./images/logo.png" />

<!-- Correto: URL absoluta -->
<img src="https://suaempresa.com.br/images/logo.png" />

Para imagens que não são publicamente acessíveis, você tem duas opções:

Inline como base64 — Codifique a imagem como data URI: <img src="data:image/png;base64,iVBOR..." />. Funciona, mas aumenta significativamente o tamanho do HTML.
URLs pré-assinadas — Gere uma URL temporária do seu provedor de armazenamento (S3, GCS) que concede acesso de leitura por tempo limitado.

Cabeçalhos, Rodapés e Numeração de Páginas

Cabeçalhos e rodapés são renderizados fora da área de conteúdo principal da página. A maioria das APIs de PDF (incluindo o TongoRender) permite que você os defina como templates HTML separados:

{
  headerTemplate: `
    <div style="font-size: 9px; color: #999; width: 100%; text-align: center; padding: 5px 0;">
      CONFIDENCIAL — Acme Ltda
    </div>
  `,
  footerTemplate: `
    <div style="font-size: 9px; color: #999; width: 100%; display: flex; justify-content: space-between; padding: 5px 20px;">
      <span>Gerado em 01/03/2026</span>
      <span>Página <span class="pageNumber"></span> de <span class="totalPages"></span></span>
    </div>
  `,
  displayHeaderFooter: true,
  margin: { top: '30mm', bottom: '25mm', left: '15mm', right: '15mm' }
}

Observações importantes sobre cabeçalhos e rodapés:

As classes CSS .pageNumber e .totalPages são especiais — o Chromium automaticamente substitui seu conteúdo com os números de página atuais e totais.
Cabeçalhos e rodapés são renderizados dentro da área de margem, então certifique-se de que suas margens são grandes o suficiente para acomodá-los.
Templates de cabeçalho e rodapé são renderizados em um contexto isolado — eles não podem acessar estilos do documento principal. Inclua todos os estilos inline.

Dicas de Teste e Depuração

Use a Pré-Visualização de Impressão do Chrome DevTools

Antes de enviar HTML para uma API, teste localmente usando a emulação de impressão do Chrome. Abra o DevTools, pressione Cmd/Ctrl+Shift+P, digite "Rendering" e habilite "Emulate CSS media type: print". Isso mostra exatamente como seus estilos CSS de impressão serão aplicados.

Adicione Bordas Visíveis Durante o Desenvolvimento

/* Debug: mostrar limites dos elementos */
* { outline: 1px solid rgba(255, 0, 0, 0.2); }

Teste com Diferentes Comprimentos de Conteúdo

Seu template pode ficar ótimo com uma página de conteúdo, mas quebrar com três páginas. Teste com:

Conteúdo mínimo (meia página)
Conteúdo típico (2-3 páginas)
Conteúdo máximo (10+ páginas com tabelas longas)

Valide com Dados Reais

Templates frequentemente quebram com dados de casos extremos: nomes de empresa muito longos, endereços com caracteres especiais, itens com descrições extremamente longas. Teste com dados realistas, não apenas texto placeholder.

Conclusão

Gerar PDFs a partir de HTML é simples uma vez que você entende as regras do contexto de renderização de impressão. Use CSS de impressão, gerencie quebras de página explicitamente, sirva fontes de forma confiável, use URLs absolutas para imagens e teste minuciosamente com conteúdo variado. Essas práticas vão economizar horas de depuração e garantir que seus PDFs tenham aparência profissional toda vez.

O TongoRender cuida da infraestrutura de renderização para que você possa focar em criar templates excelentes. Com renderização Chromium completa, suporte a CSS moderno e cabeçalhos e rodapés configuráveis, seu fluxo de HTML para PDF nunca foi tão simples.

Comece com o TongoRender — 100 renderizações gratuitas por mês, sem necessidade de cartão de crédito.