Markdown para PDF com realce de código: como preservar as cores de sintaxe
Para converter Markdown em PDF mantendo o realce de código (cores, fonte, números de linha), use uma ferramenta baseada em Chromium headless. /markdown-to-pdf faz isso sem configuração — blocos cercados renderizam com cor completa Prism / highlight.js, fonte monoespaçada e quebra correta. O PDF é exatamente o que a pré-visualização mostra.
O restante explica por que a maioria das ferramentas Markdown → PDF removem cores, as três coisas que precisam estar alinhadas para preservá-las e como cada ferramenta se sai.
Três modos típicos de falha:
- O renderer nunca realgou.
pandoc input.md -o output.pdfpuro usa Listings/Skylighting; cores datadas e baixo contraste. Sem--highlight-stylepode sair monocromático. - O highlighter rodou, mas o CSS de impressão matou. Ao ⌘+P pelo navegador, muitos sites resetam
color: black !importantvia stylesheet de impressão. Blocos viram preto puro — legíveis, mas sem estrutura visual. - O motor PDF removeu cores. Bibliotecas antigas achatam tudo em escala de cinza em certos perfis. Sintoma: links continuam azuis mas blocos perdem verde/laranja.
Se ao exportar Markdown você vê código monocromático onde esperava tema de sintaxe, quase sempre é um destes três.
Manter realce no PDF é uma corrente. Se um elo quebra, as cores somem:
- Um highlighter real processa o código. Prism, highlight.js, Shiki ou Skylighting do Pandoc. Sem ele, código é só texto monoespaçado.
- O tema sobrevive ao caminho de impressão. Ou a ferramenta exporta o render da tela direto (Chromium headless), ou tem stylesheet de impressão que não reseta cores.
- Fontes e cores condizem com o tema. Temas escuros (Dracula, One Dark) em papel branco ficam ruins; temas claros (GitHub Light, Solarized Light) imprimem bem.
A via navegador entrega os três por padrão — render de tela e PDF são o mesmo snapshot Chromium.
Usa Chromium headless e captura a pré-visualização como PDF. Blocos cercados com Prism por padrão, tema claro ajustado para impressão. Linhas longas quebram suavemente sem ultrapassar página. code inline mantém fundo e fonte monoespaçada.
Veredito: funciona out of the box, sem configurar.
Também Chromium headless por baixo; você controla o tema highlight.js via YAML front-matter:
---
stylesheet:
- https://cdn.jsdelivr.net/npm/highlight.js/styles/github.css
---
Veredito: cor total, mas você traz o tema. Para imprimir github.css, para PDF escuro atom-one-dark.css.
Também Chromium, mas o tema padrão segue o editor. VSCode escuro = PDF escuro — bom na tela, caro em toner. Sobrescreva em settings:
"markdown-pdf.highlightStyle": "github.css"
Veredito: funciona, mas confira o tema antes de imprimir.
Usa Skylighting (não highlight.js / Prism). Cores parecem datadas pelos padrões web. --highlight-style=tango (ou pygments, kate) muda paleta, mas nenhum bate com tema web moderno.
Para tema web via Pandoc, exporte primeiro para HTML e imprima do navegador.
pandoc input.md -o output.html --highlight-style=pygments --self-contained
Veredito: funciona, mas indireto.
Depende do CSS de impressão da página. github.com mantém cores razoavelmente, outras docs removem. Teste antes de entregar.
Veredito: aleatório.
- Temas claros imprimem melhor. GitHub Light, Solarized Light, Atom One Light.
- Evite cores muito saturadas. Vermelho/verde puros doem na vista no papel.
- Teste sem números de linha primeiro.
- Cuide da fonte monoespaçada. Inter, JetBrains Mono, Fira Code são defaults seguros.
- Linhas longas vazam. Adicione
pre { white-space: pre-wrap; }ou quebre antes de exportar. - Tabs vs espaços. Normalize para espaços se o alinhamento importa.
- Aspas tipográficas. Alguns processadores convertem aspas em backticks — desative (Pandoc:
--from=markdown-smart). - Emojis em comentários. Muitas fontes PDF não renderizam emojis em cor.
/markdown-to-pdf suporta temas Prism / highlight.js?
Usa Prism com tema afinado para impressão. Para tema específico, a rota CLI é mais flexível. Veja comparação de 5 métodos.
Por que minha pré-visualização tem cor mas o PDF não?
Causa comum: stylesheet de impressão da página origem. Impressão do navegador respeita @media print que costuma resetar cores. A web /markdown-to-pdf não passa por esse caminho.
Como mantenho números de linha no PDF?
O web tool não mostra por padrão. Se precisar, md-to-pdf CLI com um tema highlight.js que inclua .hljs-ln-numbers mantém.
Melhor tema para PDF impresso?
GitHub Light. Familiar, imprime bem em cor e P&B.
Posso converter em lote e manter o realce?
Sim — veja Converter Markdown para PDF em lote. Métodos CLI são ideais para lotes.
Manter realce em Markdown → PDF é direto se você usar Chromium real. /markdown-to-pdf faz sem configuração; a CLI npm dá controle de tema por documento; o resto é trade-off entre conveniência e fidelidade de cor.