HTML a PDF pierde estilos CSS: por qué ocurre y cómo solucionarlo
Convertir páginas web o documentos HTML a PDF es útil para archivar contenido digital, generar facturas, crear informes o distribuir contenido sin dependencias de navegador. Pero cuando el PDF resultante no se parece nada al original — sin colores, sin fuentes personalizadas, sin layout, con imágenes rotas — la conversión se vuelve inútil. Este problema afecta especialmente a desarrolladores web, diseñadores y empresas que generan documentos PDF automáticamente desde sus sistemas: facturas de comercio electrónico, contratos generados por formularios, reportes de bases de datos. Cuando los estilos fallan, los documentos se ven poco profesionales o directamente ilegibles. Esta guía explica las causas más comunes de la pérdida de estilos en la conversión HTML a PDF y cómo solucionarlas.
Por qué los estilos CSS fallan en la conversión HTML a PDF
La conversión de HTML a PDF no es simple porque los convertidores deben renderizar el HTML de manera similar a un navegador, pero en un contexto diferente con acceso potencialmente limitado a recursos externos. La causa más común de pérdida de estilos es que los archivos CSS están vinculados como archivos externos con rutas relativas. Si el conversor no puede acceder a esos archivos CSS (porque la conversión se realiza de forma local sin servidor web, o porque las rutas son relativas al servidor pero el conversor solo tiene el archivo HTML), los estilos no se aplican. Las fuentes web (Google Fonts, fuentes de Adobe, fuentes personalizadas cargadas con @font-face) requieren acceso a Internet o a los archivos de fuente locales. Si el conversor no puede descargar estas fuentes, las sustituye por fuentes del sistema que pueden verse muy diferentes. Las imágenes referenciadas con URLs relativas o con rutas de servidor tienen el mismo problema: si el conversor no puede resolver esas URLs, las imágenes aparecen rotas o ausentes en el PDF. Las propiedades CSS que dependen de características del navegador (viewport, variables CSS complejas, CSS Grid avanzado, animaciones) pueden no ser soportadas por el motor de renderizado del conversor, produciendo un layout diferente al esperado.
- 1Verifica que todos los archivos CSS están accesibles para el conversor.
- 2Comprueba que las URLs de imágenes son absolutas o que el conversor puede resolver las relativas.
- 3Verifica que las fuentes web están disponibles o usa fuentes del sistema como alternativa.
- 4Prueba el HTML en el conversor y compara sección por sección con el original en el navegador.
- 5Identifica qué propiedades CSS específicas no se renderizaron correctamente.
Cómo preparar el HTML para una conversión perfecta
La clave para una buena conversión HTML a PDF es preparar el HTML de manera que el conversor tenga acceso a todos los recursos necesarios sin depender de ninguna ruta relativa o recurso externo. La técnica más efectiva es incrustar todos los estilos CSS directamente en el HTML usando la etiqueta `<style>` en el `<head>` del documento, en lugar de vincular archivos CSS externos. Esto elimina completamente el problema de acceso a archivos CSS. Para las imágenes, puedes incrustarlas en el HTML como Base64 en lugar de usar URLs. Una imagen Base64 está codificada directamente en el código HTML y no requiere ninguna URL externa. Es una técnica más pesada pero garantiza que las imágenes siempre estén disponibles para el conversor. Para las fuentes, incluye las fuentes críticas de forma incrustada o usa fuentes web seguras (Arial, Georgia, Times New Roman, Courier, Verdana) que están disponibles en todos los sistemas. Si necesitas fuentes personalizadas, descarga los archivos de fuente e inclúyelos con @font-face usando rutas absolutas o Base64. Si conviertes páginas web públicas (no HTML local), asegúrate de proporcionar la URL completa con protocolo (https://), no solo el nombre de dominio. Muchos conversores necesitan la URL completa para acceder correctamente a todos los recursos de la página.
- 1Mueve todos los estilos CSS a etiquetas `<style>` internas en el `<head>` del HTML.
- 2Convierte imágenes críticas a Base64 e inclúyelas directamente en el HTML.
- 3Usa fuentes del sistema como fallback o incluye las fuentes como Base64.
- 4Cambia todas las URLs relativas de imágenes y recursos a URLs absolutas.
- 5Prueba el HTML resultante en el navegador antes de convertir a PDF.
Ajustar el CSS específicamente para impresión PDF
CSS tiene un mecanismo específico para estilos de impresión: la media query `@media print`. Puedes usarla para definir cómo debe verse el documento cuando se imprime o convierte a PDF, independientemente de cómo se ve en pantalla. Usando `@media print`, puedes ocultar elementos que no deben aparecer en el PDF (menú de navegación, barras laterales, botones), ajustar márgenes para el formato de papel, cambiar tamaños de fuente para mejor legibilidad en papel, y asegurarte de que el contenido no se corta en los saltos de página. Las propiedades CSS `page-break-before`, `page-break-after` y `page-break-inside` te permiten controlar exactamente dónde ocurren los saltos de página en el PDF. Por ejemplo, puedes asegurarte de que las tablas no se corten en la mitad, o que cada sección importante comience en una nueva página. Esta preparación específica para impresión es especialmente importante si generas PDFs de forma programática desde sistemas web: facturas, contratos, reportes. Un CSS bien preparado para `@media print` garantiza resultados consistentes independientemente del conversor utilizado.
- 1Añade un bloque `@media print` en tu CSS para estilos específicos de impresión.
- 2Oculta elementos de navegación e interfaz que no deben aparecer en el PDF.
- 3Usa `page-break-before` y `page-break-after` para controlar los saltos de página.
- 4Ajusta márgenes y tamaños de fuente para lectura en papel.
- 5Prueba la vista de impresión en el navegador (Ctrl+P) para previsualizar antes de convertir.
Herramientas de diagnóstico para identificar qué falla
Cuando la conversión HTML a PDF falla, el diagnóstico sistemático ayuda a identificar exactamente qué recursos no se cargaron. La consola de desarrollo del navegador (F12) puede mostrar los errores de carga de recursos si conviertes con herramientas basadas en navegador como Puppeteer. Busca errores de tipo 'Failed to load resource' que indican qué archivos CSS, fuentes o imágenes no pudieron cargarse. Compara el HTML que genera el sistema con el HTML que renderiza correctamente en el navegador. Si son diferentes, el problema está en la generación del HTML, no en el conversor. Para diagnóstico rápido, simplifica el HTML gradualmente: elimina secciones hasta que encuentres cuál contiene el elemento que causa el problema de estilo. Este proceso de bisección te ayuda a identificar rápidamente el problema específico.
Preguntas frecuentes
¿Por qué las imágenes no aparecen en mi PDF convertido desde HTML?
Las imágenes probablemente usan URLs relativas que el conversor no puede resolver, o URLs que requieren autenticación. Cambia las URLs de imágenes a URLs absolutas (https://...) o incrusta las imágenes como Base64 directamente en el HTML.
¿Por qué las fuentes personalizadas no aparecen en el PDF?
El conversor no puede acceder a los archivos de fuente referenciados en tu @font-face o desde Google Fonts. Incluye los archivos de fuente convertidos a Base64 directamente en el CSS, o usa fuentes del sistema (Arial, Georgia, etc.) que siempre están disponibles.
¿Cómo puedo controlar dónde se cortan las páginas en el PDF?
Usa las propiedades CSS de salto de página: `page-break-before: always` fuerza un salto antes de un elemento, `page-break-inside: avoid` evita que un elemento se corte en la mitad. Añade estas propiedades en un bloque `@media print` de tu CSS.
¿El PDF generado desde HTML puede ser diferente en cada conversor?
Sí, porque diferentes conversores usan diferentes motores de renderizado con diferente soporte de CSS. Para resultados consistentes, usa CSS simple y bien soportado, evita propiedades experimentales y prueba con el conversor específico que usarás en producción.