Markdown para PDF com realce de código: como preservar as cores de sintaxe
Manter as cores da sintaxe ao converter Markdown para PDF depende de toda a cadeia de renderização. O bloco de código precisa de indicar a linguagem, o renderizador tem de executar um realce de sintaxe e a exportação para PDF deve preservar o fundo, o tipo de letra e as quebras de linha.
Para um documento pontual, o caminho mais curto é o MarkdownToImage Markdown to PDF: cole ou carregue o ficheiro Markdown, verifique a pré-visualização, escolha o tema, o tipo de letra e a largura do documento e exporte. Para compilações automáticas ou muito personalizadas, use md-to-pdf, VS Code Markdown PDF ou Pandoc com definições explícitas.
A maioria das falhas pode ser reproduzida. Comece por estas três verificações:
- O bloco de código não declara a linguagem. Um bloco aberto apenas com três acentos graves é texto pré-formatado. Acrescente
javascript,python,bashou a linguagem suportada mais próxima depois da abertura. - Os gráficos de fundo estão desativados. Os temas de sintaxe dependem normalmente das cores do texto e do fundo do bloco. Uma exportação pelo navegador ou Chromium pode manter os elementos coloridos e remover o fundo.
- A pré-visualização e o PDF usam definições diferentes. Outro renderizador, tema, tipo de letra, largura de página ou CSS de impressão pode alterar as cores e as quebras de linha. Compare primeiro um exemplo pequeno antes de processar um documento longo.
Não vale a pena culpar o formato PDF de forma genérica. Um PDF consegue preservar texto colorido; o ponto decisivo é o que a cadeia de exportação renderizou antes de escrever o ficheiro.
Cole este bloco no mesmo documento e exporte-o antes do relatório completo:
const palette = ["cyan", "amber", "coral"];
function renderStatus(format) {
return `${format}: ${palette.length} colors`;
}
console.log(renderStatus("PDF"));
Verifique cinco detalhes na pré-visualização e no PDF: cor das palavras-chave, cor das cadeias, fundo do bloco de código, tipo de letra monoespaçado e quebra da linha com a cadeia de modelo. Se algum elemento mudar, corrija primeiro o tema ou a exportação.
A ferramenta Web gera o PDF num ambiente Chromium do servidor. Suporta blocos com realce de sintaxe, fórmulas KaTeX, diagramas Mermaid, tabelas, imagens incorporadas e listas de tarefas. A pré-visualização é a referência: defina o tema, o tipo de letra e a largura, exporte e compare o bloco de teste.
As exportações gratuitas incluem atualmente uma marca de água. Uma conta gratuita com sessão iniciada recebe, no total, cinco exportações sem marca de água. Os preços e limites podem mudar; consulte a página atual do conversor antes de criar um processo recorrente.
É a melhor opção quando pretende um resultado cuidado sem instalar ferramentas locais.
O md-to-pdf processa Markdown com Marked, aplica realce através do highlight.js e gera o PDF com Puppeteer/Chromium. O estilo predefinido é GitHub, embora seja possível escolher outro explicitamente.
md-to-pdf input.md --highlight-style github --pdf-options '{ "printBackground": true }'
A CLI é indicada quando o mesmo documento precisa de ser recompilado num script ou em CI. Se um tema escuro definir uma cor de fundo, mantenha printBackground ativo. Não processe Markdown não fiável sem o sanitizar; a documentação oficial do projeto também assinala esta questão de segurança.
A extensão Markdown PDF exporta através de um navegador baseado em Chromium e usa highlight.js nos blocos de código. O realce está ativo por predefinição e o tema é configurado separadamente com markdown-pdf.highlightStyle.
"markdown-pdf.highlightStyle": "github.css"
Depois de alterar a definição, volte a exportar o bloco de teste. A extensão usa atualmente highlight.js v11; alguns nomes antigos de temas podem ter sido alterados ou removidos. Escolha um estilo atual em vez de pressupor que um nome anterior continua disponível.
O Pandoc usa Skylighting nos blocos que declaram uma linguagem. As versões atuais suportam --syntax-highlighting; a forma antiga --highlight-style está obsoleta.
pandoc input.md -o output.pdf --syntax-highlighting=pygments
O Pandoc inclui estilos como kate, tango, zenburn e breezeDark, além de aceitar ficheiros JSON .theme personalizados. É uma opção especialmente forte quando já utiliza modelos Pandoc, citações ou um processo baseado em LaTeX. O tipo de letra e a paginação continuam dependentes do motor de PDF e do modelo, pelo que devem ser testados à parte.
Imprimir como PDF uma página Markdown já renderizada pode funcionar, mas o resultado depende totalmente do CSS de impressão da página. Alguns sites preservam cores e fundos; outros simplificam o aspeto para papel. Ative os gráficos de fundo na caixa de impressão, reveja as quebras de página e compare o bloco de teste.
A impressão pelo navegador é útil quando a página já está correta. Não é um processo de compilação reproduzível se não controlar também o HTML, o CSS, a versão do navegador e as definições de impressão.
- Declare a linguagem em cada bloco de código.
- Para documentos que poderão ser impressos, prefira um tema claro e de elevado contraste.
- Ative os gráficos de fundo quando o tema depender deles.
- Use um tipo de letra monoespaçado conhecido e confirme que existe no ambiente de exportação.
- Teste linhas longas com a largura final A4 ou Letter.
- Exporte primeiro o pequeno exemplo JavaScript antes de processar um relatório longo.
- Sanitize Markdown proveniente de utilizadores ou sistemas externos antes de o entregar a um conversor local.
- Abra o PDF final e verifique cores, texto selecionável, ligações, imagens e quebras de página.
Para comparar mais ferramentas, consulte cinco formas de converter Markdown para PDF. Para compilações repetíveis, continue com a conversão em lote através de CLI, Pandoc e CI.
Porque aparece o código colorido na pré-visualização e sem cores no PDF?
Ative primeiro os gráficos de fundo. Depois confirme que a exportação usa o mesmo tema e renderizador da pré-visualização. Uma folha de estilos de impressão também pode substituir as cores dos elementos.
Que tema devo usar num PDF para impressão?
Comece por GitHub ou outro tema claro. Normalmente mantém-se legível a cores e em escala de cinzentos. Os temas escuros podem funcionar em PDFs destinados ao ecrã, mas o fundo e o contraste devem ser verificados antes da partilha.
É possível preservar números de linha?
Apenas se o renderizador ou o tema os adicionar. Os blocos Markdown padrão não incluem números de linha. Para um resultado determinístico, use uma CLI ou folha de estilos sob o seu controlo e teste a largura final da página.
Posso converter vários ficheiros sem perder o realce?
Sim. Uma CLI baseada em Chromium mantém um estilo Web consistente; o Pandoc também pode usar um tema de sintaxe explícito. Fixe a versão da ferramenta e o tema em CI para evitar alterações inesperadas em compilações futuras.
Abra o conversor Markdown to PDF do MarkdownToImage, cole o pequeno bloco JavaScript deste guia e exporte um PDF. Compare a pré-visualização e o ficheiro lado a lado. Quando as cores, o fundo, o tipo de letra e as quebras coincidirem, substitua o exemplo pelo seu documento real.