Mehrere Markdown-Dateien stapelweise zu PDF konvertieren

Drei typische Batch-Aufgaben:

1. Eine Markdown-Datei → eine PDF, für viele Dateien wiederholt: md-to-pdf *.md (npm-CLI).
2. Viele Markdown-Dateien → eine kombinierte PDF (Buch, Mehrkapitel-Bericht): pandoc chapter*.md -o book.pdf.
3. Viele Markdown-Dateien → eine PDF pro Commit: GitHub-Actions-Workflow mit der npm-CLI.

Das Browser-Tool /markdown-to-pdf ist Single-File; für Batch-Jobs braucht es eine CLI. Der Artikel führt durch die drei Szenarien mit Copy-Paste-Befehlen und ein paar Stolperfallen.

Einfachster Fall. Sie haben chapter01.md, chapter02.md ... und wollen chapter01.pdf, chapter02.pdf ...

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

Fertig — standardmäßig schreibt es eine .pdf neben jede .md. Ein Stylesheet für das Aussehen:

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

Für hunderte Dateien parallelisieren:

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

-P 4 macht vier PDFs parallel. Über 4-8 begrenzt der Chromium-Startaufwand.

Für Bücher, technische Berichte, mehrteilige Onboarding-Docs.

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

pandoc chapter*.md -o book.pdf  # alphabetisch, ok wenn Sie Nullen aufgefüllt haben

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

GitHub-Actions-Workflow für PDFs auf jeden Push nach 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'

Führt md-to-pdf auf alle Markdowns unter docs/ aus, lädt PDFs als Build-Artifact hoch. Auf Tag-Push umstellen, um sie an Releases zu hängen.

1. Bildpfade brechen in der kombinierten PDF. Wenn chapter01.md ./images/a.png aus seinem Verzeichnis referenziert, bricht das Pfad nach Verkettung. Pfade absolut machen, Bilder als Data-URI einbetten oder --resource-path=. bei Pandoc.
2. Front-Matter-Konflikte. Jede .md kann eigenes YAML-Front-Matter haben. Pandoc nimmt das erste, md-to-pdf per-Datei nimmt jedes eigene. Bei Konflikt vor dem Verketten strippen.
3. Seitenzahlen reset zwischen Kapiteln. Pandoc löst das mit --top-level-division=chapter; Cat-and-Convert nicht (Seitenzahlen sind durchgängig, was für ein Buch meist gewollt ist).
4. Unicode / CJK-Schriften. Für Chinesisch/Japanisch/Koreanisch: Pandoc mit XeLaTeX braucht --pdf-engine=xelatex -V mainfont:"Source Han Serif CN". Headless-Chromium-Tools (md-to-pdf, /markdown-to-pdf) erben den System-Font-Stack und funktionieren einfach.
5. Speicher bei großen Batches. 500+ Dateien via md-to-pdf startet Chromium hunderte Male. xargs -P parallelisieren, aber Parallelität auf CPU-Cores deckeln.

• Eine Datei gelegentlich → /markdown-to-pdf. Schneller als npm zu installieren.
• Gleiches Template, dutzende Dateien, einmalig → md-to-pdf CLI.
• Gleiches Template, viele Dateien, pro Commit → CLI in CI.
• Bücher, Berichte, Mehrkapitel → Pandoc mit --top-level-division=chapter --toc.
• Heterogene Templates pro Kapitel → Per-Datei-PDFs (Szenario 1) erzeugen, danach mit pdfunite oder qpdf zusammenführen.

Mehr zu Tool-Trade-offs: Markdown-zu-PDF-Methodenvergleich und Code-Highlighting im PDF.

Wenn schon einzelne PDFs erzeugt wurden und nur verkettet werden sollen, ohne neu zu rendern:

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

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

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

Kein Re-Render bedeutet verlustfrei und schnell (unter einer Sekunde für 100 Dateien).

Kann ich mit dem Web-/markdown-to-pdf batchen?

Das Web-Tool ist Single-File. Für Batch-Jobs CLI; für Einmal-Use Web. Manche zippen das Resultat manuell nach CLI-Konvertierungen.

Wie behalte ich Code-Highlighting in allen Dateien des Batches?

Die CLI übernimmt das via --stylesheet. Selbes Theme überall für Konsistenz. Mehr in Markdown zu PDF mit Code-Highlighting.

Maximalgröße einer kombinierten PDF?

Funktional unbegrenzt — 5000 Seiten klappen. Praktisch: Suche in PDF-Readern wird ab ~1000 Seiten langsam, E-Mail-Anhänge sind oft auf 25 MB begrenzt. Für Riesendokumente in Bände teilen.

Gibt es eine API für Batch-Konvertierung?

Ja — unsere Markdown-to-Image-API unterstützt format=pdf, sodass Batch-Konvertierung aus jeder HTTP-fähigen Sprache scriptbar ist. Nützlich, wenn man keine Node-Abhängigkeit in CI will.

Bewahrt Pandoc Mermaid-Diagramme im Batch?

Nicht nativ. Benötigt pandoc-mermaid-filter oder Mermaid vorher zu SVG konvertieren und referenzieren. Die npm-CLI braucht im Batch ebenfalls ein markdown-it-Mermaid-Plugin.

Das richtige Batch-Tool hängt davon ab, was Sie produzieren:

• 1-zu-1 PDFs → md-to-pdf '*.md'
• Viele-zu-1 Buch → pandoc chapter*.md --toc -o book.pdf
• Continuous Build → GitHub Actions + npm-CLI
• Bestehende PDFs verketten → pdfunite oder qpdf

Für einen einmaligen Batch ohne installiertes Werkzeug ist der Weg mit der geringsten Reibung: Web-/markdown-to-pdf pro Datei einmal aufrufen, dann mit pdfunite zusammenführen.