PDF not having hierarchial structure.

[ravi2345]

Bug

When processing a .docx file with the simple pipeline, the doctags output correctly preserves the hierarchical structure of headings (section_header_level_1 through section_header_level_4).

However, when the same document is converted to .pdf and processed using pdfpipeline(), the doctags output only contains section_header_level_1. All nested heading levels (2–4) are flattened or lost.

Does this mean hybrid chunking for docling documents is not working here ?(Using only section_header_level_(1) for chunking?)

...

Docling version

Docling version: 2.32.0
...

Python version

Python 3.10.12

...

[dosubot]

Hi @ravi2345! I'm Dosu and I’m helping the docling team.

This is a known limitation of the PDF pipeline in Docling: when processing PDFs, the StandardPdfPipeline uses a layout model that only labels headings generically as SECTION_HEADER, without distinguishing between heading levels. As a result, all headings are flattened to section_header_level_1 in the doctags output, and the hierarchical structure (levels 2–4) is lost. This isn't a failure of hybrid chunking itself—it's that the pipeline doesn't provide the necessary hierarchy for the chunker to use, so only top-level headings are available for chunking in PDFs. In contrast, DOCX files preserve heading levels because the structure is explicit in the file format and is read directly by the SimplePipeline reference.

There is no out-of-the-box configuration in Docling 2.32.0 to improve multi-level heading detection for PDFs. However, there is a community workaround: if your PDFs contain bookmarks (TOC), you can use the pymupdf library to extract TOC information and modify the pipeline to insert a TocModel after the LayoutModel, then replace the ReadingOrderModel with a custom ReadingOrderWHierarchyModel. This approach restores heading hierarchy in the doctags output, but requires custom code and only works with PDFs that have a TOC/bookmarks details and example.

If you need hierarchical chunking for PDFs without bookmarks, you would need to implement additional heuristics (like font size or boldness) or wait for future enhancements to the pipeline.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[krrome]

Hi @ravi2345,

I have been working on this topic. I'm hoping to open a docling-PR on this topic, but due to the complexity of integrating the solution I decided to make a little package docling-hierarchical-pdf, that is tailored exactly to work with Docling and adds inference of PDF hierarhies - it works with scanned PDFs as well as text-based PDFs.

It is still in an early stage, but please do give it a try and give feedback. I ran a bunch of tests and was happy with the performance. The limitation, if any, seems to be more on the docling document parsing side.
The package attempts to read the TOC from PDF metadata as well as inferring document hierarchy based on header numbering and header styles.

Please try it out and report bugs related to header hierarchy parsing here. I promise I will create PR for docling using the insights and code in my package.