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:

ls chapters/*.md | xargs -P 4 -I {} md-to-pdf {}

-P 4 roda quatro PDFs em paralelo. Mais que 4-8 você fica limitado pelo custo de subir Chromium.

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  # alfabético, ok se você preencheu zeros

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

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

echo "" > combined.md
for f in chapter*.md; do
  cat "$f" >> combined.md
  echo -e "\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: 20
      - 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 / CJK. Para chinês/japonês/coreano: Pandoc com XeLaTeX precisa --pdf-engine=xelatex -V mainfont:"Source Han Serif CN". Ferramentas Chromium headless (md-to-pdf, /markdown-to-pdf) herdam a pilha de fontes do sistema.
5. Memória em lotes grandes. 500+ arquivos via md-to-pdf sobe Chromium centenas de vezes. Use xargs -P para paralelizar, mas limite a concorrência ao número de cores.

• 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 chapter01.pdf chapter02.pdf chapter03.pdf book.pdf
qpdf --empty --pages chapter*.pdf -- book.pdf
gs -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=book.pdf chapter*.pdf

Sem re-render é sem perda e rápido (menos de um segundo para 100 arquivos).

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?

Funcionalmente ilimitado — vimos 5000 páginas funcionar. Prático: leitores PDF ficam lentos depois de ~1000 páginas, anexos de e-mail cabem em 25 MB.

Existe API de lote?

Sim — nossa Markdown to Image API suporta format=pdf, scriptável de qualquer linguagem com HTTP.

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.