Markdown a PDF con resaltado de código: cómo conservar los colores de sintaxis
Para convertir Markdown a PDF manteniendo el resaltado de código (colores, fuente, números de línea), usa una herramienta basada en Chromium headless. /markdown-to-pdf lo hace sin configuración — los bloques cercados se renderizan con color completo de Prism / highlight.js, fuente monoespaciada y ajuste de línea correcto. El PDF es exactamente lo que muestra la vista previa.
La guía explica por qué la mayoría de herramientas Markdown → PDF eliminan los colores, las tres cosas que deben alinearse para preservarlos y cómo se comportan las herramientas comunes.
Tres modos de fallo típicos:
- El renderer nunca resaltó. Un
pandoc input.md -o output.pdfdesnudo usa Listings/Skylighting; los colores son anticuados y de bajo contraste. Sin--highlight-stylepuede salir monocromo. - El highlighter corrió, pero el CSS de impresión lo mató. Al hacer ⌘+P en navegador, muchos sitios resetean
color: black !importantvía hoja de impresión. Los bloques quedan en negro — legibles, pero sin estructura visual. - El motor PDF eliminar colores. Algunas librerías viejas pasan todo a escala de grises según el perfil de impresora. Síntoma: los enlaces siguen azules pero los bloques pierden verde/naranja.
Si exportas Markdown y ves código monocromo donde esperabas un tema de sintaxis, casi siempre es uno de estos tres.
Mantener el resaltado en PDF es una cadena. Si un eslabón falla, los colores no sobreviven:
- Un highlighter real procesa el código. Prism, highlight.js, Shiki o Skylighting de Pandoc. Sin uno, el código es solo texto monoespaciado.
- El tema sobrevive el camino de impresión. O la herramienta exporta el render de pantalla directo (Chromium headless), o tiene una hoja de impresión que no resetea colores.
- Las fuentes y colores cumplen la intención del tema. Temas oscuros (Dracula, One Dark) sobre papel blanco se ven mal; temas claros (GitHub Light, Solarized Light) imprimen bien.
La vía navegador cumple los tres por defecto — el render de pantalla y el de PDF son la misma captura de Chromium.
Usa Chromium headless y captura la vista previa exacta como PDF. Bloques cercados con Prism por defecto, tema claro afinado para impresión. Líneas largas se ajustan suavemente sin desbordar la página. code en línea conserva fondo y monoespaciada.
Veredicto: funciona out of the box, sin configurar.
También Chromium headless por debajo, controlas el tema highlight.js vía YAML front-matter:
---
stylesheet:
- https://cdn.jsdelivr.net/npm/highlight.js/styles/github.css
---
Veredicto: color completo, pero traes el tema. Para imprimir github.css, para PDF oscuro atom-one-dark.css.
También Chromium, pero el tema por defecto sigue al editor. VSCode oscuro = PDF oscuro — bien en pantalla, caro en tóner. Sobreescribe en settings:
"markdown-pdf.highlightStyle": "github.css"
Veredicto: funciona, pero revisa el tema antes de imprimir.
Usa Skylighting (no highlight.js / Prism). Los colores lucen anticuados por estándares web. --highlight-style=tango (o pygments, kate) cambia paleta, pero ninguno coincide con un tema web moderno.
Para tema web vía Pandoc, conviene exportar a HTML primero y luego imprimir desde navegador.
pandoc input.md -o output.html --highlight-style=pygments --self-contained
Veredicto: funciona, pero indirecto.
Depende del CSS de impresión de la página. github.com mantiene colores decentemente, otras documentaciones los eliminan. Probar antes de entregar.
Veredicto: aleatorio.
- Temas claros imprimen mejor. GitHub Light, Solarized Light, Atom One Light.
- Evita colores muy saturados. Rojo/verde puro luce duro en papel.
- Prueba sin números de línea primero.
- Cuida la fuente monoespaciada. Inter, JetBrains Mono, Fira Code son buenos defaults.
- Líneas largas desbordan. Añade
pre { white-space: pre-wrap; }o quiebra líneas manualmente. - Tabs vs espacios. Normaliza a espacios si la alineación importa.
- Comillas tipográficas. Algunas Markdown-engines convierten comillas dentro de backticks — desactiva (Pandoc:
--from=markdown-smart). - Emojis en comentarios. Muchas fuentes PDF no cargan emojis a color.
¿/markdown-to-pdf soporta temas Prism / highlight.js?
Usa Prism con un tema afinado para impresión. Para tema específico, la ruta CLI es más flexible. Ver comparativa de 5 métodos.
¿Por qué mi vista previa tiene color y el PDF no?
La causa habitual es la hoja de impresión de la página origen. La impresión del navegador respeta @media print que suele resetear colores. La web de /markdown-to-pdf no pasa por ese camino.
¿Cómo conservo números de línea en el PDF?
La herramienta web no los muestra por defecto. Si los necesitas, md-to-pdf CLI con un tema highlight.js que incluya .hljs-ln-numbers los conserva.
¿Mejor tema para PDF impreso?
GitHub Light. Familiar, imprime bien en color y B/N.
¿Puedo convertir en lote y mantener resaltado?
Sí — ver Convertir Markdown a PDF en lote. Los métodos CLI son ideales para lotes.
Mantener resaltado en una Markdown → PDF es directo si usas Chromium real. /markdown-to-pdf lo maneja sin configuración; la CLI npm da control de tema por documento; el resto es trade-off entre comodidad y fidelidad de color.