Doc Splitter

Split DOCX and PDF documents by headings while keeping their original format and styling.

Install the Python package to get the doc-splitter command.

Installation · Usage · API · Development

Doc Splitter turns structured DOCX and PDF documents into smaller files at their heading boundaries. Each output remains in the source format and is derived from a complete copy of the original document, preserving the formatting and styling of the retained content.

Installation

Requires Python 3.11 or newer:

python -m pip install doc-splitter

This provides the doc-splitter command:

doc-splitter --help

Usage

Inspect

Open a document and display its extracted heading hierarchy without calculating output paths or writing files:

doc-splitter inspect <input.docx|input.pdf> [--json]

doc-splitter inspect "manual.docx"

Plan

Calculate the exact output filenames and document ranges without creating them:

doc-splitter plan <input.docx|input.pdf> [split options] [--json]

doc-splitter plan "manual.docx" --level 2 --parent-headings folders

Split

Plan and create the output documents. The split workflow does not require a split command word:

doc-splitter <input.docx|input.pdf> [options]

Split a DOCX document at level 1:

doc-splitter "manual.docx" --level 1 --output ".\output"

Split a PDF document at level 2:

doc-splitter "book.pdf" --level 2 --output ".\chapters"

Paths containing spaces or Unicode characters can be quoted normally:

doc-splitter "C:\Documents\manual.pdf" --output "C:\Documents\Split Files"

Options

Split options apply to both plan and the default split workflow. --output, --subfolder, and --yes apply only when creating files.

The input document is never modified. Existing output files are not overwritten.

API

The import name is doc_splitter. The API follows an inspect-plan-execute workflow:

from doc_splitter import (
    DEFAULT_SPLIT_OPTIONS,
    execute_split,
    inspect_document,
    plan_split,
)

inspection = inspect_document("manual.docx")
plan = plan_split(inspection, DEFAULT_SPLIT_OPTIONS)
result = execute_split(
    inspection,
    plan,
    "./output",
    output_directory_mode="direct",
)

print(f"Created {result.created_files} files.")

inspect_document reads and retains the input snapshot, plan_split calculates filenames and document ranges, and execute_split creates the planned outputs. The API raises DocSplitterError for document, planning, or output failures.

Behavior

Doc Splitter splits at heading boundaries without rebuilding the selected content in a blank document. This keeps each output in the original document format and preserves the formatting and styling of its retained content.

• Supported inputs are .docx and .pdf, matched case-insensitively.
• DOCX ranges use top-level Open XML body-element indexes.
• PDF ranges use zero-based page indexes.
• Split ranges include the start and exclude the end.
• Heading text is whitespace-normalized before use in filenames.
• Unsafe filename characters are removed or replaced.
• Windows reserved device names receive a trailing _.
• Outputs retain the source document format, formatting, and styling.
• Each output begins with a complete source-derived document and removes content outside its planned range.

When a document begins with exactly one level-1 heading followed by lower-level headings, Doc Splitter omits that single top heading from the returned hierarchy and promotes its descendants by one level. Content before the first returned heading can become a cover output.

Development

This package lives in the python/ directory of the Doc Splitter repository. Shared fixtures are in the repository test-data/ directory.

cd python
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m compileall -q src
python -m pytest

Generated split documents belong in temporary directories or .artifacts/, not in test-data/. If a committed fixture changes intentionally, update its SHA-256 and affected expectations in the same change.

License

MIT