Como converter vários arquivos Markdown para PDF em lote

Três tarefas comuns de lote:

1. Um Markdown → um PDF, repetido para muitos arquivos: md-to-pdf *.md (CLI npm).
2. Muitos Markdown → um PDF combinado (livro, relatório com capítulos): pandoc chapter*.md -o book.pdf.
3. Muitos Markdown → um PDF a cada commit: workflow GitHub Actions com a CLI npm.

O /markdown-to-pdf do navegador é single-file; lotes precisam de CLI. Este guia percorre os três cenários com comandos copiáveis e armadilhas.

Caso simples. Você tem chapter01.md, chapter02.md, ... e quer chapter01.pdf, chapter02.pdf, ...

npm install -g md-to-pdf
md-to-pdf 'chapters/*.md'

Pronto — por padrão escreve um .pdf ao lado de cada .md. Adicione um stylesheet para controlar a aparência:

md-to-pdf 'chapters/*.md' --stylesheet ./style.css

Para centenas de arquivos, paralelize:

find chapters -name '*.md' -print0 | xargs -0 -P 4 -I {} md-to-pdf '{}'

Comece com baixa concorrência e aumente observando CPU e memória; cada worker pode iniciar um processo de navegador.

Livros, relatórios técnicos, docs de onboarding multi-arquivo.

pandoc chapter01.md chapter02.md chapter03.md -o book.pdf

pandoc chapter*.md -o book.pdf  # alphabetical order, fine if you've zero-padded

pandoc chapter*.md --toc -o book.pdf

pandoc chapter*.md --toc --top-level-division=chapter -o book.pdf

: > combined.md
for f in chapter*.md; do
  cat "$f" >> combined.md
  printf '\n\n<div style="page-break-before: always;"></div>\n\n' >> combined.md
done
md-to-pdf combined.md

Workflow GitHub Actions para PDFs a cada push em main:

# .github/workflows/build-pdfs.yml
name: Build PDFs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install -g md-to-pdf
      - run: md-to-pdf 'docs/**/*.md'
      - uses: actions/upload-artifact@v4
        with:
          name: pdfs
          path: 'docs/**/*.pdf'

Roda md-to-pdf sobre todos os Markdowns em docs/, faz upload dos PDFs como artifact. Mude para tag push para anexá-los a um Release.

1. Caminhos de imagem quebram no PDF combinado. Se chapter01.md referencia ./images/a.png, ao concatenar o caminho quebra. Reescreva para absoluto, embuta como data URI ou use --resource-path=. no Pandoc.
2. Conflitos de front-matter. Cada .md pode ter o seu YAML. Pandoc pega o primeiro; md-to-pdf por arquivo lê o seu. Tire o front-matter antes de concatenar se conflitar.
3. Números de página resetam entre capítulos. Pandoc resolve com --top-level-division=chapter; cat-and-convert não (números contínuos, geralmente o desejado para livro).
4. Fontes Unicode e CJK. Com Pandoc e XeLaTeX defina uma fonte instalada, por exemplo --pdf-engine=xelatex -V mainfont:"Source Han Serif CN". Chromium local usa fontes do runtime; em serviços hospedados teste os caracteres reais.
5. Memória em lotes grandes. Renderização baseada em navegador consome recursos. Limite a concorrência, monitore a memória e divida tarefas enormes em blocos retomáveis.

• Um arquivo ocasionalmente → /markdown-to-pdf. Mais rápido que instalar npm.
• Mesmo template, dezenas de arquivos, uma vez → md-to-pdf CLI.
• Mesmo template, muitos arquivos, a cada commit → CLI em CI.
• Livros, relatórios, multi-capítulo → Pandoc com --top-level-division=chapter --toc.
• Templates heterogêneos por capítulo → PDFs por arquivo (Cenário 1) e depois pdfunite ou qpdf.

Mais sobre trade-offs em comparação de métodos e em realce de código no PDF.

Se já produziu PDFs separados e quer concatenar sem re-renderizar:

# pdfunite (poppler-utils)
pdfunite chapter01.pdf chapter02.pdf chapter03.pdf book.pdf

# or qpdf
qpdf --empty --pages chapter*.pdf -- book.pdf

# or ghostscript
gs -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=book.pdf chapter*.pdf

Mesclar evita renderizar novamente e preserva a qualidade; o tempo depende da quantidade e tamanho dos arquivos, armazenamento e ferramenta.

Posso fazer lote com o web /markdown-to-pdf?

O web é single-file. Para lote, CLI; para uso pontual, web.

Como mantenho realce em lote?

A CLI herda o que você passa em --stylesheet. Mesmo tema em todos. Ver Markdown para PDF com realce.

Limite do PDF combinado?

Não há limite universal de páginas: memória, imagens, fontes, renderizador e leitor PDF influenciam. Teste documentos grandes, defina timeouts no CI e divida manuais enormes em volumes.

Pandoc preserva Mermaid em lote?

Não nativamente. Precisa pandoc-mermaid-filter ou converter Mermaid em SVG antes.

A ferramenta certa depende do produto:

• 1 a 1 PDF → md-to-pdf '*.md'
• N a 1 livro → pandoc chapter*.md --toc -o book.pdf
• Build contínuo → GitHub Actions + npm CLI
• Concatenar PDFs existentes → pdfunite ou qpdf

Para um lote único sem nada instalado, o caminho mais fácil é: web /markdown-to-pdf por arquivo, depois pdfunite.

Os limites e comandos acima foram verificados nestas fontes primárias atuais:

• https://pandoc.org/MANUAL.html
• https://github.com/simonhaenisch/md-to-pdf
• https://docs.github.com/en/actions

Abra MarkdownToImage, renderize Markdown e escolha o formato adequado. Antes de automatizar um lote, teste um documento representativo.