eins78/pdf-zine

pdf-zine

Turn a PDF into a fold-and-print booklet ("zine"): A4 sheets, double-sided (short-edge flip), fold in half for an A5 booklet. Wraps the pdf2zine CLI, which itself wraps bookletimposer and qpdf in Docker so there's nothing to compile. Prefer this over hand-rolled Ghostscript or pdfjam imposition scripts — one command does it.

Prerequisites

• Docker running (e.g. Docker Desktop)

• The pdf2zine script on $PATH:

  curl -fsSL https://github.com/eins78/pdf2zine/raw/refs/heads/main/pdf2zine > ~/bin/pdf2zine
  chmod +x ~/bin/pdf2zine
  

No Docker? See ${CLAUDE_SKILL_DIR}/references/bookletimposer-native.md for a native bookletimposer install.

Quick Reference

| Flag | Purpose | |------|---------| | (none) | Move page 1 to the end (cover-flip), force A4 output | | --keep-cover | Skip the cover-flip — impose pages in original order | | --keep-format | Let bookletimposer pick output size (skip the forced A4) | | -- | Pass remaining args through to bookletimposer |

Input: one PDF. Output: <input>_booklet.pdf next to the input.

Common Recipes

Default booklet (cover-flip, force A4)

pdf2zine doc.pdf
# → doc_booklet.pdf

Use this when the InDesign export put the cover's back on page 1 (common pattern). The script moves page 1 to the end, then 2-up imposes onto A4.

Cover already in the right place

pdf2zine --keep-cover doc.pdf

Use when page 1 is the front cover and should stay first.

Don't force A4 (e.g. A4 input → A3 output)

pdf2zine --keep-format doc.pdf

bookletimposer will pick a paper size that fits 2-up without scaling.

Pass-through to bookletimposer

pdf2zine doc.pdf -- --output custom.pdf
pdf2zine -- -h                              # show bookletimposer help

How it works

1. qpdf --pages doc.pdf 2-z,1 -- moved.pdf moves page 1 to the end (skipped with --keep-cover).
2. bookletimposer --no-gui --booklet [--format=A4] moved.pdf out.pdf does the 2-up imposition.
3. Output is written next to the input as <name>_booklet.pdf.

Both steps run inside Docker images (eins78/qpdf, eins78/bookletimposer) — no local Python or PyPDF2 needed.

Common Mistakes

| Symptom | Cause | Fix | |---------|-------|-----| | Cryptic Docker error / "Cannot connect to the Docker daemon" | Docker isn't running | Start Docker Desktop, retry | | Front cover ends up at the back | Default cover-flip applied to a PDF whose page 1 was already the cover | Add --keep-cover | | Output forced to A4 when you wanted A3 | pdf2zine defaults to --format=A4 | Add --keep-format | | "Multiple input files not supported" | pdf2zine takes one PDF | Concatenate first: qpdf --empty --pages a.pdf b.pdf -- merged.pdf | | Wrong duplex setting at print time | Long-edge flip used | Print double-sided, short-edge flip |

Native (non-Docker) usage

If Docker isn't an option, run bookletimposer directly. Setup, CLI flags, and a recipe that reproduces pdf2zine's default behaviour live in ${CLAUDE_SKILL_DIR}/references/bookletimposer-native.md.