Repository navigation
[Improvement] Support PDF heading hierarchy inference (HeadingHierarchyOptions) in ConvertDocumentOptions #754
Description
Description
In Python Docling (docling.datamodel.pipeline_options.PdfPipelineOptions), HeadingHierarchyOptions (heading_hierarchy_options) allows reconstructing a true H1 -> H6 heading tree from PDF bookmarks, outline numbering (1.1, 1.2.1), and font/visual styles instead of emitting all detected section_header elements flat at level 1:
from docling.datamodel.pipeline_options import HeadingHierarchyOptions, PdfPipelineOptions
pipeline_options = PdfPipelineOptions(
heading_hierarchy_options=HeadingHierarchyOptions(
enabled=True,
max_level=6,
use_bookmarks=True,
use_numbering=True,
use_style=True,
use_font_style=True,
)
)Currently, there is no way to enable or configure HeadingHierarchyOptions via ConvertDocumentOptions in docling-java (nor via a DOCLING_SERVE_* container environment variable).
Why this is important for Java RAG pipelines
When using docling-java with Spring AI or LangChain4j for RAG ingestion, structure-aware chunkers (HybridChunker / HierarchicalChunker) rely on the document's heading levels to group sections and build hierarchical metadata paths (e.g., Chapter 1 > 1.2 Methodology). Without HeadingHierarchyOptions, PDF headings frequently remain flat at level 1.
Proposed Change
Expose heading hierarchy configuration in ConvertDocumentOptions (and the underlying docling-serve options schema), e.g.:
doHeadingHierarchy(Boolean)/headingHierarchyOptions(HeadingHierarchyOptions)(enabled,maxLevel,useBookmarks,useNumbering,useStyle,useFontStyle).
Activity
edeandrea commentedon Oct 22, 2026
Thanks @Krambamboli for this issue! I'll get working on it!
feat(docling-serve-api): expose PDF heading hierarchy options in Conv…
edeandrea commentedon Oct 22, 2026
@all-contributors add @Krambamboli for ideas
allcontributors commentedon Oct 22, 2026
@edeandrea
This project's configuration file has malformed JSON: .all-contributorsrc. Error:: Unexpected string in JSON at position 6440
edeandrea commentedon Oct 22, 2026
@all-contributors add @Krambamboli for ideas
allcontributors commentedon Oct 22, 2026
@edeandrea
I've put up a pull request to add @Krambamboli! 🎉
feat(docling-serve-api): expose PDF heading hierarchy options in Conv…
feat(api): expose PDF heading hierarchy options in ConvertDocumentOpt…
feat(api): expose PDF heading hierarchy options in ConvertDocumentOpt…
feat(api): expose PDF heading hierarchy options in ConvertDocumentOpt…
docling-java-ops commentedon Oct 22, 2026
🎉 This issue has been resolved in
v0.7.1(Release Notes)Krambamboli commentedon Oct 23, 2026
@edeandrea Thank you so much for the fast response, I really appreciate it. This makes our ingestion pipeline way better.
edeandrea commentedon Oct 23, 2026
You're very welcome! Keep the reports coming! Its hard to keep up with Docling's pydantic model. Everything is manual unfortunately.