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:

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

Mit niedriger Parallelität beginnen und unter Beobachtung von CPU und Speicher erhöhen; jeder Worker kann einen Browserprozess starten.

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  # 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

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: 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'

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- und CJK-Schriften. Bei Pandoc mit XeLaTeX eine installierte Schrift explizit setzen, etwa --pdf-engine=xelatex -V mainfont:"Source Han Serif CN". Lokale Chromium-Tools nutzen Fonts ihrer Runtime; gehostete Renderer mit echten Zeichen testen.
5. Speicher bei großen Batches. Browserbasiertes Rendering ist ressourcenintensiv. Parallelität begrenzen, Speicher beobachten und sehr große Jobs in fortsetzbare Teile zerlegen.

• 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

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

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

Das Zusammenführen rendert nicht neu und erhält daher die Inhaltsqualität; die Dauer hängt von Anzahl, Größe, Speicher und Tool ab.

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?

Es gibt kein universelles Seitenlimit: Arbeitsspeicher, Bilder, Schriften, Renderer und PDF-Viewer wirken zusammen. Große Beispieldokumente testen, CI-Timeouts setzen und sehr große Handbücher in Bände teilen.

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.

Produktgrenzen und Befehle wurden anhand dieser aktuellen Primärquellen geprüft:

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

Öffne MarkdownToImage, rendere Markdown und wähle das passende Ausgabeformat. Vor einem Batch zuerst ein repräsentatives Dokument testen.