Markdown para PDF em lote: ZIP no navegador, CLI, Pandoc e CI

Três tarefas comuns de lote:

1. Um Markdown → um PDF, repetido para muitos ficheiros: 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.

Também existe uma opção no navegador: a exportação em lote gera saídas separadas sem instalar CLI. A página /markdown-to-pdf continua indicada para um documento. Escolha lotes no navegador, automatização local ou PDF combinado conforme a entrega.

Abra a exportação em lote, carregue até 15 Markdown, escolha PDF e definições comuns e execute a exportação. Estão disponíveis PNG, JPEG, WebP, PDF e DOCX. É uma função paga; o Creator inclui 20 execuções de lotes por mês.

O ZIP contém uma saída por cada entrada bem-sucedida. Se um ficheiro falhar, leia a respetiva nota .error.txt, em vez de considerar todo o lote concluído. Uma execução com pelo menos um ficheiro gerado consome uma execução da quota. Um ZIP com 15 PDF continua a ser uma coleção de 15 documentos, não um livro combinado.

Use esta amostra como um dos ficheiros de entrada. Compare o título, a lista e a nota final com a pré-visualização e o PDF descarregável; depois examine as restantes saídas.

# Chapter 01: export checks

## Scope
This sample represents one source file in a multi-file export.

- Keep one output per input file
- Check every generated file
- Inspect the ZIP for error notes

> A ZIP of PDFs is different from one merged PDF.

Descarregar o PDF de exemplo

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 ficheiros, 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-ficheiro.

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. Front matter. Em Pandoc, um bloco YAML posterior substitui o mesmo campo de um anterior. Unifique os metadados do livro; consulte as regras de metadados.
3. Numeração. --top-level-division=chapter altera o tipo de divisão, não a política de paginação. Configure-a no motor e no modelo e examine o PDF; consulte as opções de divisão.
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 documento → /markdown-to-pdf.
• Até 15 ficheiros com definições comuns → lotes pagos.
• Reconstruir a cada commit → CLI em CI.
• Um livro com capítulos ordenados → Pandoc com --top-level-division=chapter --toc.
• PDF existentes com paginações diferentes → combinar com pdfunite ou qpdf.

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

Se já tem PDF separados, escolha montagem de páginas ou reescrita PDF conforme o que precisa de preservar:

# 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

Use pdfunite ou qpdf para montar páginas. O pdfwrite do Ghostscript cria um PDF novo; não é uma concatenação sem perdas. Verifique fontes, ligações, marcadores e compressão de imagens; consulte a documentação.

Posso exportar em lote no navegador?

Para vários ficheiros, abra a exportação em lote: esta ferramenta paga aceita até 15 Markdown por execução e descarrega um ZIP com uma saída por entrada. O Creator inclui 20 execuções por mês. A opção PDF gera documentos separados; para um documento combinado, use Pandoc.

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?

Verifique o renderizador; não assuma que os blocos Mermaid se tornam diagramas. Nas receitas locais, prepare imagens ou configure pré-processamento compatível. Confirme que não faltam diagramas nem estão cortados no PDF.

A ferramenta certa depende do produto:

• Ficheiros separados num ZIP → lotes pagos.
• PDF individuais por script → md-to-pdf '*.md'.
• Um livro combinado → pandoc chapter*.md --toc -o book.pdf.
• Compilação contínua → GitHub Actions + CLI.
• PDF existentes → pdfunite ou qpdf.

Para um grupo ocasional, comece pelos lotes no navegador e examine o ZIP. Os PDF não são fundidos num documento. Se precisar de um único PDF, use a receita ordenada de Pandoc ou combine os PDF já exportados com uma ferramenta própria.

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.

Inicie uma exportação em lote no navegador.

• Escolha um método PDF
• Preserve as cores ao exportar