pdfpost

Command-line tool to add a bookmark/outline tree and an initial clickable TOC page to a PDF.

Installation (development)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Usage

python pdfpost.py -i input.pdf -o output.pdf -v

Options:

• -i / --input: path to input PDF
• -o / --output: path to output PDF
• -v / --verbose: verbose logging
• --min-font-size: minimum font size (pt) for heading detection (default: 20.0)

How headings are detected

• Level 1 headings are auto-detected when a line's maximum span font size is ≥ the specified minimum (default: 20pt).
• Use --min-font-size to adjust the threshold (e.g., --min-font-size 16 for smaller headings).
• A clickable, styled Table of Contents is inserted at the beginning. Long TOCs are automatically paginated across multiple pages.

Notes:

• Bookmarks point to the correct pages with the TOC page offset applied.

Building a standalone executable (PyInstaller)

Ensure the virtualenv is active and dependencies installed, then:

pip install pyinstaller
pyinstaller --onefile --name pdfpost pdfpost.py

This produces dist/pdfpost (macOS/Linux) or dist/pdfpost.exe (Windows).

Run it:

./dist/pdfpost -i input.pdf -o output.pdf -v

Signed macOS binaries for arm64/x86_64

Use the provided make_binary.sh to build signed, hardened binaries with entitlements for each architecture and optionally create a universal binary:

# arm64
./make_binary.sh -t arm64

# x86_64 (builds under Rosetta)
./make_binary.sh -t x86_64

# universal (lipo both)
./make_binary.sh

Logging Examples

• Adding bookmark: Chapter 1 → page 4
• Writing TOC page
• Writing output PDF

Limitations

• Auto-detection is heuristic and may miss or over-include headings.
• TOC links and bookmarks target pages; if the PDF has unusual structures, results may vary.