split-pdf-by-toc 0.0.3

Splits a PDF by its TOC.

split-pdf-by-toc

A small command-line tool that splits a PDF into multiple files based on its table of contents (TOC).

It reads the embedded TOC entries of a PDF and uses them as cut points to generate one PDF per section.

Status

Status: usable / evolving Audience: CLI users, developers Python: 3.12+

Features

• Split PDFs using embedded TOC markers
• Limit splitting by TOC depth
• Filter TOC entries by name
• Optional overlapping page ranges
• Configurable output directory and filename prefix

Non-features

• No OCR for scanned PDFs
• No TOC generation or editing
• No GUI

---

Installation

Clone the repository and install dependencies:

cd split-pdf-by-toc
pip install -r requirements.txt

Usage

usage: split-pdf-by-toc [-h] [-o OUTPUT_DIR] [--overlap] [-d DEPTH]
                        [-f FILTER] [-p PREFIX]
                        pdf_path

Splits a PDF by TOC markers.

positional arguments:
  pdf_path              Set the input PDF

options:
  -h, --help            show this help message and exit
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Set the output directory
  --overlap             If provided, let output pages overlap with each other.
  -d DEPTH, --depth DEPTH
                        Set the maximum depth of TOC entries
  -f FILTER, --filter FILTER
                        Only select TOC entries matching a filter
  -p PREFIX, --prefix PREFIX
                        Set a prefix for the output files

Examples

• Split a PDF by its top-level TOC entries:

  $ split-pdf-by-toc book.pdf
  

• Only split up to depth 2 and write results to out/:

  split-pdf-by-toc -d 2 -o out book.pdf
  

• Only split sections whose titles contain "Chapter":

  split-pdf-by-toc -f Chapter book.pdf
  

Contributing

Contributions are very welcome. Please use ruff to format and lint.

Small changes (bug fixes, small improvements): please open a pull request directly.

Larger changes (new features, refactors, behavior changes): please open an issue first to discuss the idea and avoid wasted work.

If you add new behavior, tests are appreciated but not mandatory.

License

This project is licensed under the AGPL (Affero General Public License). See the LICENSE file for details.