feat(pdf): infer PDF heading levels so the hierarchy isn't flattened

[DanielNg0729]

Infer PDF heading levels so the hierarchy isn't flattened

The problem

I hit this while converting legal contracts to Markdown for an LLM pipeline: every heading Docling pulls out of a PDF comes back as a level-1 #, so the whole document goes flat. Something structured like

PART I
1. Definitions
1.1 Interpretation
(a) ...

ends up as a flat run of # headings, and the parent/child relationship between the parts, the numbered sections and the sub-clauses is just gone. Anything downstream that leans on heading depth to understand the document (RAG, summarisation, navigation) loses that structure.

This is the issue reported in #3555, and the same thing has come up before in #386, #1170 and #2774. There were also two earlier attempts to infer levels from font information (#2676, #2421) that never landed. The standalone post-processor krrome/docling-hierarchical-pdf (MIT) already does this after conversion — this PR brings the same idea into the pipeline itself.

Why it happens

It isn't really a detection bug — Docling finds the headings fine, it just never gives them a level. In readingorder_model.py, both places that create a heading call add_heading() with no level=, so it falls back to 1:

# _handle_text_element (the SECTION_HEADER branch)
new_item = out_doc.add_heading(
    text=cap_text, prov=prov, hyperlink=element.hyperlink
)  # no level= -> defaults to 1

# _add_child_elements
doc.add_heading(parent=doc_item, text=c_text, prov=c_prov)  # no level=

DoclingDocument.add_heading() already accepts a level (1–100) and the Markdown/HTML exporters already render it. The DOCX, LaTeX and HTML backends pass it because they have real heading markup to read; the PDF path has none, so nothing ever computes a level. So this is closer to a missing feature than a regression.

What I changed

I added a small, self-contained step (docling/models/stages/reading_order/heading_hierarchy.py) that runs from ReadingOrderModel.__call__ once the document is assembled. It walks the headings in reading order and assigns each one a level. It only rewrites levels — it never adds, removes or reorders anything.

Doing this inside the pipeline (instead of as a post-processor on the finished document) matters: the font data lives on conv_res.pages[i].parsed_page and never makes it into the final DoclingDocument, so only an in-pipeline step can actually use it. It also fixes every PDF/image backend at once, since they all share this stage.

There are two signals, with numbering as the primary one.

Numbering

A small grammar reads each heading's leading marker and maps it to a scheme:

Example marker	Scheme
PART I, TITLE II	part
Article 1, Section 2, § 1.2	article
I., II., III.	upper roman
1., 2.	arabic
1.1, 1.1.1	dotted decimal (depth from segment count)
(a), A.	alpha
(i), (ii)	lower roman

Levels are worked out relatively from the schemes that actually appear, so a document that starts at 1. isn't forced to start at depth 2, and 1.1 / 1.1.1 nest by how many segments they have. I went with numbering as the main signal on purpose — in legal and regulatory documents the numbering is far more reliable than the styling, which is often completely uniform.

Single letters that are also valid Roman numerals (I, V, C, …) are genuinely ambiguous, so they're resolved from the surrounding markers: I. / II. / III. reads as Roman, while A. / B. / C. reads as alphabetic. There's also a numbering_schemes option to override the ordering for house styles.

Style (fallback)

For headings that have no recognisable number, it falls back to font size: it matches the heading's box against the parsed PDF cells and uses their median height as a size proxy — bigger text becomes a higher level. There's no explicit font-size field on the cells, so height is the best proxy available.

One caveat worth knowing: the parsed pages get dropped right before the reading-order stage unless you keep them, so the style fallback needs generate_parsed_pages=True. Without it, style just no-ops and numbering still works.

How to use it

It's opt-in and off by default, so nothing changes for anyone unless they turn it on:

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

opts = PdfPipelineOptions()
opts.heading_hierarchy_options = HeadingHierarchyOptions(enabled=True)
opts.generate_parsed_pages = True  # only needed for the style fallback

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)}
)
doc = converter.convert("contract.pdf").document
print(doc.export_to_markdown())

The new options:

enabled: bool = False          # master switch
use_numbering: bool = True     # primary signal
use_style: bool = True         # fallback; needs generate_parsed_pages=True
use_bookmarks: bool = False    # reserved for the follow-up below
numbering_schemes: list[str] | None = None
max_level: int = 6

Tests

tests/test_heading_hierarchy.py covers the headline case (Roman sections staying above Arabic subsections), the full legal stack (PART → 1. → 1.1 → (a) → (i)), relative/compressed levels, dotted-decimal depth, custom scheme order, max_level clamping, the Roman-vs-alpha disambiguation, the negative cases (plain words and bare numbers shouldn't be treated as markers), and the end-to-end effect on export_to_markdown.

No reference data changes, since the feature is off by default and existing fixtures stay byte-identical.

What I deliberately left out

• Bookmarks / PDF outline. This is usually the most authoritative signal, but it needs new plumbing in the PDF backends (the outline isn't surfaced anywhere today), so I kept it out to keep this PR focused. _infer_from_bookmarks() is already there as a no-op extension point, so it can be added later without disturbing this structure.
• Bold/italic from font names. A natural extension to the style signal, but not needed for the legal use case and easy to bolt on afterwards.

Honest limitations

• The style fallback relies on geometric matching between the heading box and the parsed cells, which has rough edges (multi-line headings, rotated text, OCR cells with no font), so numbering carries the weight.
• On scanned / VLM-parsed PDFs the font data is often missing, so it degrades to numbering-only.
• A lone (i) with no sibling (ii) next to an (a) list can be misread — it needs a real sequence to anchor the Roman-vs-alpha call.

A couple of things I'd like your take on

• Off by default (what I went with) vs. on with regenerated references?
• I assign the level in a post-assembly pass rather than at the add_heading call sites — happy to move it if you'd prefer.
• Should style auto-keep parsed_page when it's enabled, instead of asking the user to also set generate_parsed_pages=True?
• Is building on the krrome/docling-hierarchical-pdf approach (with attribution) fine?

Closes #3555.

[github-actions]

✅ DCO Check Passed

Thanks @DanielNg0729, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[PeterStaar-IBM]

@DanielNg0729 thank you so much for this PR, really wonderful initiative!

[codecov]

Codecov Report

❌ Patch coverage is 92.07317% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...tages/heading_hierarchy/heading_hierarchy_model.py	91.39%	13 Missing ⚠️

📢 Thoughts on this report? Let us know!

[DanielNg0729]

Hi Dr @PeterStaar-IBM. This is ready for review whenever you or the team have a moment. I left a few open questions at the bottom of the description (default-off vs. on, the post-assembly pass vs. setting the level at the add_heading call sites, and whether style should auto-keep parsed_page), and I'm happy to adjust any of it.

[PeterStaar-IBM]

@cau-git Let's discuss this later and give @DanielNg0729 some feedback.

[cau-git]

@DanielNg0729 Thanks for this proposal. We definitely appreciate seeing this topic addressed.

Regarding your code and questions:

• The provided functionality and logic looks good!
• Post-modifying an already constructed DoclingDocument is fine in terms of approach
• Off-by-default is a sensible choice
• I would like to suggest moving it outside of the reading-order model, since that model is already impure in terms of separation of concerns and we don't want to add more debt there. Find some detailed comments below.
• Building on krrome/docling-hierarchical-pdf should be fine as it is also MIT licensed.
• We would be very interested if you take this further in a downstream iteration with PDF bookmarks / ToC as a signal

Proposal to move / refactor the code

• Ideally, make it an own HeadingHierarchy model which accepts ConversionResult and emits (modified) DoclingDocument object.
• Place the call to it right after the reading-order model in these places:
  • def _assemble_document in StandardPdfPipeline
  • def _assemble_document in LegacyStandardPdfPipeline
• The options class can work as proposed, analog to the ReadingOrderOptions, not nested inside.
• Ideally, the code would be internally factored such that it can be re-used also outside the pipeline code (e.g. providing a way to also call it with a bare DoclingDocument, or DoclingDocument + list of SegmentedPage (second iteration).

[DanielNg0729]

Thanks for the detailed review, Dr @cau-git, Dr @PeterStaar-IBM. I've pushed a refactor addressing all the points:

• Own model: extracted a standalone HeadingHierarchyModel (docling/models/stages/heading_hierarchy/heading_hierarchy_model.py) that takes a ConversionResult and returns the modified DoclingDocument.
• Out of reading-order: the call now happens right after the reading-order model in _assemble_document of both StandardPdfPipeline and LegacyStandardPdfPipeline. The reading-order model is fully decoupled again.
• Options not nested: ReadingOrderOptions no longer carries it; HeadingHierarchyOptions stays standalone on PdfPipelineOptions.
• Reusable outside the pipeline: assign_heading_levels(document, parsed_pages=None) works on a bare DoclingDocument; the style fallback takes the parsed pages explicitly (page height from SegmentedPdfPage.dimension), so it no longer depends on ConversionResult. This sets up the DoclingDocument + list[SegmentedPage] path you mentioned for the next iteration.
• Also added a style-fallback test to cover the font-size path. Let me know if the placement/naming looks right!

For the bookmarks/ToC signal, before it's only a reserved no-op hook (_infer_from_bookmarks returns {}, and use_bookmarks defaults to False and does nothing), since surfacing the PDF outline needs new plumbing in the backends. So i drop it for now and I'd be happy to open a separate PR for it as the downstream iteration that extracting the outline from the PDF backends and feeding bookmark depth + page/title matching into the same model. One quick question i have:

• Is there any preference on where outline extraction should live: a method on PdfDocumentBackend (e.g. get_document_outline()), implemented per backend (pypdfium2 / docling-parse)?

Happy to get started on it once this one lands. Thank you very much!

[DanielNg0729]

Hi Dr @cau-git. I've pushed a fix for the failing checks (the new heading_hierarchy package wasn't registered in tach.toml, which tripped the tach boundary check and, through it, the lint job). Could you kindly re-trigger the CI run when you have a moment? Thanks alot!

[cau-git]

@DanielNg0729 Thanks for the updates. I added a small test method that uses an actual PDF from our test data and checks assertions about the levels. Seems to work fine!

[PeterStaar-IBM]

wonderful!