bundle-binder

bundle-binder

Assemble a multi-document PDF binder from a project's SOPs and flowcharts.

Configuration: binders.yaml

The project must have a binders.yaml at its root. Example shape:

binders:
  household-emergency:
    title: "Household Emergency Binder"
    subtitle: "Jerusalem Apartment — Revision 2"
    cover: covers/emergency-cover.png       # optional
    footer: "Household Emergency Binder · Revision 2 · 2026"
    toc: true                                # generate table of contents
    page_numbers: true
    output: output/household-emergency-binder.pdf
    documents:
      - sops/rocket-missile-alert-response.typ
      - sops/preparing-home-for-emergencies.typ
      - sops/choosing-protected-space.typ
      - flowcharts/which-shelter.typ
      - checklists/emergency-equipment.typ

  first-aid-kit:
    title: "First Aid Quick Reference"
    output: output/first-aid-kit.pdf
    page_numbers: true
    documents:
      - sops/first-aid-choking-adult.typ
      - sops/first-aid-burns.typ
      - sops/first-aid-cpr-adjunct.typ

If no binders.yaml exists, offer to create one for the user with a starter binder based on the SOPs already in the project.

Inputs to gather

1. Binder name — the key in binders.yaml to build. If only one binder is defined, use it without asking.

What to do

1. Read binders.yaml and select the named binder.
2. For each document in documents::
   • If it's a .typ file, ensure its PDF is up to date (compile if the PDF is missing or older than the source).
   • If a referenced .typ embeds a .mmd/.d2, render the SVG first (delegate to compile's logic).
3. If toc: true, generate a TOC page. Approach: build a small Typst doc that lists each document title with its starting page number, compile it to PDF, and prepend.
4. If cover: is set, build a cover page (Typst with title, subtitle, cover image) and prepend it.
5. Concatenate the PDFs in order:

   qpdf --empty --pages cover.pdf toc.pdf doc1.pdf doc2.pdf ... -- <output>
   

   (or pdfunite as fallback)
6. If page_numbers: true, stamp consistent page numbers across the bundle. Approach: use qpdf overlay with a Typst-generated page-number layer, or re-render each component with a footer that knows its starting offset.
7. Write to the configured output: path. Report file size and page count (pdfinfo <output> | grep Pages).

Pre-flight

• command -v qpdf (or pdfunite from poppler-utils)
• command -v typst
• command -v pdfinfo (poppler-utils — for the final report)

Notes

• A binder rebuild can be slow if many docs need recompiling. Do a quick "what's stale" pass first and tell the user how many will be recompiled before starting.
• If a referenced document doesn't exist, fail fast with a clear list of missing files — don't produce a partial binder silently.
• Page numbering across a multi-source bundle is the trickiest part. The simplest robust approach: render the entire concatenation, then run a single qpdf overlay pass that stamps {page} / {total} from a Typst-generated overlay. Document this approach in code comments where it's implemented.