PDF Table of Contents Splitter

Command line tool that splits a PDF file by its table of contents. Written in Python.

Installation

Install the project and its development tools with uv:

uv sync

Run the tests with make test, and format the Python files with make format.

Splitting a PDF

uv run pdf-toc-splitter <OPTIONS> file.pdf

There are six options:

• --dry-run: Simulates the split. Prints the filenames, but does not create any files. Useful when checking if the options have been set correctly.
• --depth INTEGER: The level of depth at which the splits will occur. See figure 1 for a visual explanation. Default value is set to 1.
• --max-filename-length INTEGER If set to anything but 0 (the default), created file names will not exceed this length.
• --regex TEXT: Selects outline items that match a RegEx pattern. For example --regex "^Chapter" will only select outline items that start with the string Chapter.
• --overlap: Overlaps split points. By default, if Chapter 1 starts at page 1 and Chapter 2 starts at page 10, Chapter 1.pdf will contain pages 1–9, and Chapter 2.pdf will contain pages 10–.... By including the --overlap option, Chapter 1.pdf will now contain pages 1–10, and Chapter 2.pdf will contain pages 10..., etc. This is a useful option, if a section can start in the middle of a page.
• --prefix TEXT: Adds a prefix to the output filenames. Supports the {n} placeholder for an n-th item index. For example, --prefix "CLRS_{n}_" results in CLRS_1_<name>.pdf.

Figure 1: Different levels of depth in a PDF outline

License

Licensed under AGPL.