Elegiste una API de HTML a PDF y escribiste tu primera plantilla — pero el resultado no se ve del todo bien. El texto se corta en los límites de página, las imágenes faltan, las fuentes están mal y el diseño se rompe en documentos de múltiples páginas. ¿Te suena familiar? Esta guía cubre las mejores prácticas probadas en batalla que te ayudarán a producir PDFs perfectos a partir de HTML cada vez.
Usa CSS Optimizado para Impresión
El navegador tiene dos modos de renderización: pantalla e impresión. Al generar PDFs, el motor de renderización cambia al modo de impresión, lo que significa que tus reglas @media print entran en vigor. Esta es tu herramienta más poderosa para controlar la salida PDF.
/* Estilos base aplican tanto a pantalla como a impresión */
body {
font-family: 'Inter', sans-serif;
color: #333;
line-height: 1.6;
}
/* Sobrescrituras específicas para impresión */
@media print {
/* Elimina navegación, barras laterales y otros elementos de UI */
nav, .sidebar, .footer, .no-print { display: none; }
/* Asegura que los fondos se impriman */
body { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
/* Establece márgenes de página */
@page { margin: 20mm 15mm; }
/* Mejora la tipografía para impresión */
body { font-size: 11pt; line-height: 1.5; }
h1 { font-size: 22pt; }
h2 { font-size: 16pt; }
}Puntos clave:
- Siempre incluye
print-color-adjust: exact(y el prefijo-webkit-) si quieres que los colores de fondo e imágenes aparezcan en el PDF. Por defecto, los navegadores eliminan los fondos en modo de impresión. - Usa la regla
@pagepara controlar los márgenes de la página. Esto es separado de los márgenes del body y controla el área efectivamente imprimible. - Usa unidades físicas como
pt,mmycmpara impresión — son más predecibles quepxoremen un contexto paginado.
Maneja los Saltos de Página Correctamente
Los saltos de página son la fuente más común de frustración en la renderización de PDFs. Sin reglas de salto adecuadas, Chromium dividirá el contenido donde sea que se agote el espacio — frecuentemente en medio de una fila de tabla, un encabezado o un bloque de código.
/* Evita que los títulos queden huérfanos al final de una página */
h1, h2, h3, h4 {
page-break-after: avoid;
break-after: avoid;
}
/* Mantén imágenes y figuras juntas */
figure, img {
page-break-inside: avoid;
break-inside: avoid;
}
/* Evita que las filas de tabla se dividan entre páginas */
tr {
page-break-inside: avoid;
break-inside: avoid;
}
/* Repite encabezados de tabla en cada página */
thead {
display: table-header-group;
}
/* Fuerza un salto de página antes de una nueva sección */
.nueva-seccion {
page-break-before: always;
break-before: page;
}
/* Evita viudas y huérfanos */
p {
widows: 3;
orphans: 3;
}Las propiedades widows y orphans controlan cuántas líneas de un párrafo deben aparecer arriba o abajo de una página. Establecer ambas en 3 asegura que nunca tengas una línea solitaria al inicio o final de una página.
Fuentes Web: Asegurando que se Rendericen
Las fuentes son una fuente frecuente de problemas de renderización de PDF. Si una fuente no carga, el navegador recurre a una fuente predeterminada del sistema, y tu plantilla cuidadosamente diseñada se ve mal. Estas son las reglas:
Usa Google Fonts vía Etiqueta Link
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">Google Fonts están alojadas en un CDN rápido y funcionan de manera confiable con la mayoría de las APIs de PDF. El parámetro display=swap asegura que la fuente se descargue prontamente.
Hospeda las Fuentes Críticas Tú Mismo
Para máxima confiabilidad, hospeda tus fuentes usando declaraciones @font-face con URLs absolutas:
@font-face {
font-family: 'FuentePersonalizada';
src: url('https://tudominio.com/fuentes/FuentePersonalizada-Regular.woff2') format('woff2');
font-weight: 400;
font-style: normal;
font-display: swap;
}Siempre Especifica Fuentes de Respaldo
body {
font-family: 'Inter', 'Helvetica Neue', Arial, sans-serif;
}Imágenes: Usa URLs Absolutas
Esta es una regla simple que previene innumerables problemas: siempre usa URLs absolutas para imágenes. Cuando la API de PDF renderiza tu HTML, necesita obtener las imágenes de la red. Las URLs relativas como ./images/logo.png fallarán porque el servidor de la API no tiene acceso a tu sistema de archivos local.
<!-- Incorrecto: URL relativa -->
<img src="./images/logo.png" />
<!-- Correcto: URL absoluta -->
<img src="https://tuempresa.com/images/logo.png" />Para imágenes que no son públicamente accesibles, tienes dos opciones:
- Inline como base64 — Codifica la imagen como data URI:
<img src="data:image/png;base64,iVBOR..." />. Funciona pero aumenta significativamente el tamaño del HTML. - URLs pre-firmadas — Genera una URL temporal de tu proveedor de almacenamiento (S3, GCS) que otorga acceso de lectura por tiempo limitado.
Encabezados, Pies de Página y Números de Página
Los encabezados y pies de página se renderizan fuera del área de contenido principal de la página. La mayoría de las APIs de PDF (incluyendo TongoRender) te permiten definirlos como plantillas HTML separadas:
{
headerTemplate: `
<div style="font-size: 9px; color: #999; width: 100%; text-align: center; padding: 5px 0;">
CONFIDENCIAL — Acme Corp
</div>
`,
footerTemplate: `
<div style="font-size: 9px; color: #999; width: 100%; display: flex; justify-content: space-between; padding: 5px 20px;">
<span>Generado el 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' }
}Notas importantes sobre encabezados y pies de página:
- Las clases CSS
.pageNumbery.totalPagesson especiales — Chromium automáticamente reemplaza su contenido con los números de página actuales y totales. - Los encabezados y pies de página se renderizan dentro del área de margen, así que asegúrate de que tus márgenes sean lo suficientemente grandes para acomodarlos.
- Las plantillas de encabezado y pie de página se renderizan en un contexto aislado — no pueden acceder a estilos del documento principal. Incluye todos los estilos inline.
Consejos de Prueba y Depuración
Usa la Vista Previa de Impresión de Chrome DevTools
Antes de enviar HTML a una API, pruébalo localmente usando la emulación de impresión de Chrome. Abre DevTools, presiona Cmd/Ctrl+Shift+P, escribe "Rendering" y habilita "Emulate CSS media type: print". Esto te muestra exactamente cómo se aplicarán tus estilos CSS de impresión.
Agrega Bordes Visibles Durante el Desarrollo
/* Debug: mostrar límites de elementos */
* { outline: 1px solid rgba(255, 0, 0, 0.2); }Prueba con Diferentes Longitudes de Contenido
Tu plantilla puede verse genial con una página de contenido pero romperse con tres páginas. Prueba con:
- Contenido mínimo (media página)
- Contenido típico (2-3 páginas)
- Contenido máximo (10+ páginas con tablas largas)
Verifica el Soporte de Derecha a Izquierda (RTL)
Si atiendes usuarios en árabe, hebreo u otros idiomas RTL, prueba tus plantillas con dir="rtl" en el elemento HTML.
Valida con Datos Reales
Las plantillas frecuentemente se rompen con datos de casos extremos: nombres de empresa muy largos, direcciones con caracteres especiales, conceptos con descripciones extremadamente largas. Prueba con datos realistas, no solo texto de relleno.
Conclusión
Generar PDFs a partir de HTML es sencillo una vez que entiendes las reglas del contexto de renderización de impresión. Usa CSS de impresión, maneja los saltos de página explícitamente, sirve las fuentes de forma confiable, usa URLs absolutas para imágenes, y prueba exhaustivamente con contenido variado. Estas prácticas te ahorrarán horas de depuración y asegurarán que tus PDFs se vean profesionales cada vez.
TongoRender maneja la infraestructura de renderización para que puedas enfocarte en crear plantillas excelentes. Con renderización Chromium completa, soporte para CSS moderno y encabezados y pies de página configurables, tu flujo de trabajo de HTML a PDF nunca ha sido más simple.
Comienza con TongoRender — 100 renderizaciones gratuitas al mes, sin necesidad de tarjeta de crédito.