Markdown para PDF: 5 métodos comparados (Pandoc, VSCode, Online)

Resposta curta primeiro

Para a maioria, /markdown-to-pdf no navegador é a escolha certa — 5 segundos, sem instalar, Markdown completo incluindo realce de código, KaTeX e Mermaid. Pandoc é exagero a menos que você publique livros ou papers. Os outros três têm boas razões para existir, mas são mais nicho do que a internet sugere.

Testamos os cinco com um relatório Markdown de 30 páginas (com código, KaTeX, tabelas e Mermaid). Abaixo o que encontramos, por que cada método existe e onde realmente vence.

Método 1 — Conversor online (`/markdown-to-pdf`)

Bom para: conversão pontual, realce, fórmulas, diagramas, sem instalar.

Como: abra /markdown-to-pdf, cole, clique em PDF.

Tempo até o primeiro PDF: ~5 segundos.

Pró: zero instalação, funciona em qualquer navegador. Markdown completo com KaTeX e Mermaid. Temas claro/escuro. Sem marca d'água em contas gratuitas.

Contra: limite 1 MB. Um arquivo por vez — para lotes veja Converter vários Markdown para PDF em lote.

Quando: 95 % das conversões pontuais.

Método 2 — Pandoc

Bom para: trabalhos acadêmicos, templates LaTeX próprios, citações e referências, saída multi-formato (PDF + DOCX + EPUB de uma fonte).

Como:

brew install pandoc
brew install --cask basictex  # ou mactex (~5 GB)
pandoc input.md -o output.pdf

Tempo até o primeiro PDF: 30–90 minutos na primeira vez (instalar Pandoc + LaTeX, brigar com templates). Depois 5 segundos.

Pró: sólido, scriptável, templating LaTeX infinito. Citações nativas (--bibliography). Offline. Tipografia qualidade livro.

Contra: LaTeX ocupa 3–5 GB. Saída padrão tem estética acadêmica. Templates customizados são difíceis. Realce precisa --highlight-style e parece datado por padrões web. Mermaid exige filter plugin.

Quando: publica livro, tese, paper com bibliografia, ou mantém 3+ templates PDF versionados.

Método 3 — Plugin VSCode "Markdown PDF"

Bom para: quem escreve Markdown no VSCode o dia todo.

Como: instale o plugin "Markdown PDF" do yzane, clique direito → Markdown PDF: Export (pdf).

Tempo até o primeiro PDF: 10 segundos na primeira vez (baixa Chromium silenciosamente, ~150 MB).

Pró: um clique de onde você já está escrevendo. CSS configurável via user settings. Estilo padrão razoável.

Contra: primeiro export lento por causa do download. Estética só via CSS. KaTeX não funciona out of the box — precisa plugin Markdown+Math separado. Mermaid fica como código, não vira diagrama.

Quando: produz 5+ PDFs por semana e seu editor é VSCode.

Método 4 — Imprimir do navegador → Salvar como PDF

Bom para: Markdown já renderizado no navegador (README do GitHub, GitLab Wiki, site de docs).

Como: ⌘+P ou Ctrl+P → "Salvar como PDF".

Tempo até o primeiro PDF: 3 segundos.

Pró: já está lá. Sem instalação. Funciona em qualquer HTML renderizado.

Contra: quebras de página cortam tabelas e blocos de código imprevisivelmente. Realce perde cor no Firefox ao imprimir. Cabeçalho/rodapé padrão têm URL + página, geralmente precisam ser desligados manualmente. Não renderiza KaTeX ou Mermaid se a página origem não fizer.

Quando: precisa de um PDF agora de uma página Markdown já renderizada e detalhes ásperos não importam.

Método 5 — `md-to-pdf` (CLI npm)

Bom para: pipelines de build, CI/CD, docs automatizadas.

Como:

npm install -g md-to-pdf
md-to-pdf input.md

Tempo até o primeiro PDF: 10 segundos (empacota Chromium do Puppeteer, ~120 MB na primeira execução).

Pró: scriptável. YAML front-matter para tematizar por documento. Modo watch. Offline depois de instalado.

Contra: dependência Node + Chromium. Tematização só YAML + CSS, menos expressivo que Pandoc/LaTeX. Mermaid não out of the box — exige plugin markdown-it.

Quando: seu site de docs constrói PDFs em CI; quer PDFs no versionamento junto ao código.

Nota: evite o pacote antigo markdown-pdf (sem hífen) — sem atualização desde 2019, com avisos de segurança conhecidos. md-to-pdf é o sucessor mantido.

Comparação rápida

Método	Instalação	Primeiro PDF	Realce	Mate	Mermaid	Bom para
`/markdown-to-pdf`	0 MB	5 s	sim	sim (KaTeX)	sim	Pontual
Pandoc	3–5 GB	30–90 min	básico	sim (LaTeX)	filter	Livros, papers
Plugin VSCode	150 MB	10 s	sim	com plugin	não	Usuários VSCode
Imprimir navegador	0 MB	3 s	varia	não	não	Já renderizado
`md-to-pdf` CLI	120 MB	10 s	sim	configurável	plugin	CI/CD

Qual usar de fato?

Maioria → /markdown-to-pdf. Resposta para ~95 % dos casos.
Acadêmicos com citações → Pandoc.
Usuários VSCode diários → o plugin VSCode.
DocOps / CI → md-to-pdf CLI.
README do GitHub agora → imprimir do navegador, aceitar as asperezas.

A tentação com Markdown → PDF é over-engineering. Para um documento, não instale nada. Para mil, automatize com CLI. Raramente há meio-termo que justifique Pandoc fora do meio acadêmico.

Perguntas frequentes

Qual método preserva melhor o realce de código?

Os baseados em Chromium headless (/markdown-to-pdf, plugin VSCode, md-to-pdf CLI). Renderizam por Chromium real, então qualquer tema highlight.js/Prism passa. O --highlight-style do Pandoc parece datado pelos padrões web. Mais em Markdown para PDF com realce de código.

Qual faz conversão em lote?

A CLI faz nativamente (md-to-pdf chapter*.md). Para o web tool, ver Converter Markdown para PDF em lote.

Por que md-to-pdf e não markdown-pdf?

markdown-pdf (sem hífen) está parado desde 2019, com avisos de segurança. md-to-pdf é o sucessor mantido.

Existe API de Markdown para PDF?

Sim — ver nossa Markdown to Image API, com saída PDF para uso programático.

Qual lida melhor com CJK / caracteres chineses?

/markdown-to-pdf e md-to-pdf usam a pilha de fontes do navegador hospedeiro; CJK funciona se o sistema tem uma. Pandoc com XeLaTeX precisa mainfont: explícito. Plugin VSCode lida com CJK out of the box.

Qual sai mais barato em escala?

Para 100+ PDFs/semana, md-to-pdf em CI é praticamente grátis (só compute). Uso ocasional, web tool custa zero. Pandoc é grátis mas manter templates é custo oculto.

Encerramento

A escolha depende do volume. Um PDF → ferramenta web. Mil PDFs → CLI em CI. Livros com citações → Pandoc. Não pegue o martelo pesado antes de sentir a dor do leve.