Convert PDF chapters into folders

[SlayerDevelopment]

Hi community, I’d like to know if anyone has implemented this and could help me out.

[kiril-buga]

Hi @SlayerDevelopment,

Yes, you can use Docling to infer the heading hierarchy, then split the exported Markdown into one folder per top-level section, keeping subsections together.

This approach was tested with Docling 2.126.0 and docling-core 2.96.0. In these versions, level-1 section headers export as ##, with subsections as ###, etc.

import re
from pathlib import Path

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    HeadingHierarchyOptions,
    PdfPipelineOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption

options = PdfPipelineOptions(
    heading_hierarchy_options=HeadingHierarchyOptions(enabled=True),
    generate_parsed_pages=True,
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=options)
    }
)

document = converter.convert("input.pdf").document
markdown = document.export_to_markdown()

# Top-level section headers export as "##" in the tested versions.
parts = re.split(r"(?m)^## ([^\r\n]+)[ \t]*$", markdown)

if len(parts) == 1:
    raise ValueError(
        "No matching section headings found. "
        "Inspect document.export_to_markdown() before splitting."
    )

output = Path("chapters")
output.mkdir(exist_ok=True)

# Preserve content before the first section.
if parts[0].strip():
    (output / "front-matter.md").write_text(
        parts[0].strip() + "\n",
        encoding="utf-8",
    )

for number, (title, content) in enumerate(
    zip(parts[1::2], parts[2::2]),
    start=1,
):
    slug = re.sub(r"[^\w.-]+", "-", title).strip("-_.")
    slug = slug[:80] or "chapter"

    # Numbering preserves order and avoids collisions between repeated titles.
    chapter_dir = output / f"{number:03d}-{slug}"
    chapter_dir.mkdir(exist_ok=True)

    (chapter_dir / "chapter.md").write_text(
        f"## {title}\n\n{content.strip()}\n",
        encoding="utf-8",
    )

The output looks like:

chapters/
├── front-matter.md # if present
├── 001-1.-Introduction/
│ └── chapter.md
├── 002-2.-Background/
│ └── chapter.md
└── ...

On a six-page test PDF, this produced six section folders and kept nested subsections inside their parent section.

This assumes the detected top-level sections correspond to your chapters. Review the extracted headings first: document titles can also become top-level sections, and chapters may sit below “Part” headings. The regex is a simple starting point; it can also match ## lines inside fenced code blocks. Images remain Markdown placeholders with these default export settings.

See Docling’s heading-hierarchy documentation for the inference options.