Heading Hierarchy Configuration#

Overview#

By default, Docling's PDF layout model flags regions as SECTION_HEADER without assigning a level, leaving every heading at level=1 (a flat hierarchy). HeadingHierarchyOptions enables the HeadingHierarchyModel to run after the reading-order stage and infer proper SectionHeaderItem.level values from three signals in order of precedence:

1. PDF bookmarks — the document's own outline/ToC, most authoritative
2. Numbering patterns — outline numbering like PART I → 1. → 1.1 → (a) → (i)
3. Font style — font size approximated from parsed PDF cell heights, as a last resort

The feature is disabled by default (enabled=False). 1

Configuration: HeadingHierarchyOptions#

Defined in pipeline_options.py and nested under PdfPipelineOptions.heading_hierarchy_options.

Important: use_style requires PdfPipelineOptions.generate_parsed_pages=True. Without it, style inference is silently skipped but numbering still applies. 2

Inference Signals in Detail#

1. Bookmarks (_infer_from_bookmarks)#

Reads ConversionResult._pdf_outline (populated before pipeline stages start) 3 and fuzzily matches each bookmark to detected headings or list-items by title (via SequenceMatcher) and page number. 4

Key behaviors:

• Both the heading text and a marker-stripped version are compared, so "1.1 Definitions" matches a bookmark titled "Definitions". 5
• A bookmark-matched list-item is promoted to a SectionHeaderItem in place — fixing common layout-model misclassifications. 6
• Unmatched bookmarks fall back to numbering/style; partial outlines don't degrade other inference. 7
• Raw bookmark depths are compressed into contiguous 1-based levels. 8

2. Numbering (_infer_from_numbering)#

Parses each heading's leading marker with _parse_marker and assigns levels based on scheme family rank and dotted-decimal depth. 9

Default scheme order (highest → lowest): 10

part > chapter > article > roman_u > arabic (+ dotted by depth) > alpha_u > alpha_l > roman_l

Supported marker families:

• part — PART I, TITLE I, BOOK I
• chapter — CHAPTER 1
• article — ARTICLE 1, SECTION 2, Clause, § 1.2
• roman_u / roman_l — I., (ii)
• arabic / dotted — 1., 1.2, 1.2.3
• alpha_u / alpha_l — A., (a)

Single-letter ambiguous markers (e.g., I.) are resolved by scanning other markers in the document for context. 11

Override the scheme order via numbering_schemes:

HeadingHierarchyOptions(numbering_schemes=["arabic", "roman_u"])
# Arabic now outranks Roman

12

3. Style (_infer_from_style)#

Uses the median height of parsed PDF textline_cells overlapping the heading's bounding box as a font-size proxy. 13 Sizes are rounded and bucketed; larger size → lower level number (higher in hierarchy). 14 Only applies to headings that have no bookmark or numbering match.

Integration in the PDF Pipeline#

HeadingHierarchyModel is constructed with the options and called after ReadingOrderModel during _assemble_document. 3 The __call__ method pulls _pdf_outline from the ConversionResult and collected parsed pages, delegates to assign_heading_levels, then clears the transient outline. 15

assign_heading_levels also accepts a bare DoclingDocument without a pipeline, making it reusable in tests and offline tooling. 16

Quick Start#

from docling.datamodel.pipeline_options import PdfPipelineOptions, HeadingHierarchyOptions

options = PdfPipelineOptions(
    heading_hierarchy_options=HeadingHierarchyOptions(
        enabled=True,
        use_bookmarks=True,
        use_numbering=True,
        use_style=True,
        max_level=4,
    ),
    generate_parsed_pages=True, # required for use_style
)

Source References#