I found this three separate ways while building a RAG pipeline over a hospital's internal documents: eleven PDFs (nursing procedures, a diagnostic reference, drug formularies, policies) and one billing guide in Markdown. Each time the symptom was different, the cause was different, and the logs were clean. This post is the three failures, the one that was my own mistake, and the check I now run on every parse.

Before the failures, four words this post leans on. Docling reads a document into a tree of items, each with a label: section_header, text, list_item, table, footnote, page_header. Items can have children; a table's children are its caption and footnotes. A chunker walks that tree and cuts it into the pieces that get embedded and indexed. Docling ships one, HybridChunker. If a line never lands in a chunk, no query will ever find it, however good the parse was.

In short. Docling can return a parse that looks complete with pages missing. A threading race in docling-parse up to 7.16 with the default four-thread PDF backend drops whole pages with no error, and Docling's chunker never emits table footnotes. Three numbers catch it: pages returned versus pages in the file, items per page, and the share of raw text-line words that survived, which is 0.83 to 0.92 on a clean parse. Until you are on a parser without the race, parse on one thread.

Failure one: the parse that changes between runs

The first sign was a unit test that passed, then failed on the next run with no code change. It asserted that a chunk carried its section heading. The heading was gone. Later, a staff handbook came back with 54 items where the previous run had produced 94. Same file. Then the crashes started, roughly one run in six: exit 134 (an abort; on macOS the message is "pointer being freed was not allocated", Linux prints a different free() complaint) or exit 139 (a segfault). Both mean native code, not Python.

Am I affected. Docling has a backend per format. The PDF backend is docling-parse, a C++ library that pulls text lines out of the file before the layout model, the vision model that labels each box on the rendered page, runs. Docling 2.123 made a threaded version of that backend the default: four native threads decode pages at the same time. docling-parse up to 7.16.0 has a data race in that path. Two threads occasionally write the same memory at once, and what happens next depends on timing. Sometimes the process dies. Sometimes one thread's work is quietly overwritten and the document comes back short. Check where you stand:

pip show docling docling-parse | grep -E "^(Name|Version)"

Docling ≥ 2.123 with default settings, or an earlier version with ThreadedDoclingParseDocumentBackend opted in, is exposed. The issue is docling #4147.

What it looks like. Here is a 9-page reference guide parsed five times with default settings, each in a fresh process:

run 1: exit 134
run 2: result.pages = 7   pages present: 2 4 5 6 7 8 9      words kept 97%
run 3: result.pages = 6   pages present: 1 3 5 7 8 9        words kept 97%
run 4: result.pages = 7   pages present: 2 4 5 6 7 8 9      words kept 97%
run 5: result.pages = 6   pages present: 1 4 5 7 8 9        words kept 97%

Single-threaded, three runs: 9 pages, identical items, every time.

The missing pages are not empty. They are absent. len(result.pages) is 6 or 7 while result.input.page_count still says 9. Page 2 in run 2 holds the whole introduction, seven items:

section_header  1. Introduction to Mobile Networks
text            Mobile networks have evolved through several generations...
text            2G (GSM) networks introduced digital voice and basic data...
text            3G (UMTS/HSPA) networks brought mobile broadband...
text            4G (LTE) networks delivered a major leap forward...
text            5G networks represent the current frontier...
text            Network coverage depends on the frequency band used...

In run 3, page 2 does not exist. No item, no page object, no raw text lines. Every page that did survive is internally perfect, so nothing downstream complains. That matters for the check later: a test that asks "does every page have content" passes, because the lost pages are not there to be asked about.

Fix. Parse on one thread until you are on a docling-parse build you have verified against this:

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.backend.docling_parse_backend import ThreadedDoclingParseBackendOptions

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            backend_options=ThreadedDoclingParseBackendOptions(parser_threads=1)
        )
    }
)

Cost: none I could measure. An eight-page manual took 5.0 seconds on four threads and 5.1 on one, because the layout model dominates, not page decoding. docling-parse 7.17.0 shipped shortly after with a parse speed-up; its release notes do not mention the race and the issue was still open when I checked (September 2026). Run the five-process test above on your own files before you drop the setting.

Aside, if you also see exit 134 at shutdown: onnxruntime 1.29, pulled in for OCR (on by default), aborts from its telemetry thread when the interpreter exits (recursive_mutex lock failed). Harmless to results, same exit code, easy to confuse with the real crash. ORT_DISABLE_TELEMETRY=1 removes it.

Failure two: the footnote under the table

The diagnostic reference has a table of radiology reporting flags, and under it two lines:

Modality             Urgent means                              Routine TAT
Chest X-ray (CXR)    Pneumothorax, free air, mis-placed line   Reported within 24 h
CT head              Bleed, mass effect, acute infarct         Reported within 12 h
USS abdomen          Free fluid, obstruction, aneurysm         Reported within 24 h
· Urgent radiology turnaround: verbal/critical alert within 1 hour of acquisition.
· Reports are viewed on the PACS system; clinicians acknowledge critical reports.

Real rules, the kind a clinician asks about. Docling parsed them correctly, labelled them footnote, and made them children of the table:

table   (3 columns, 7 rows)
├── footnote  · Urgent radiology turnaround: verbal/critical alert within 1 hour of acquisition.
└── footnote  · Reports are viewed on the PACS system; clinicians acknowledge critical reports.

Then the chunker dropped them. When HybridChunker reaches a table it converts the whole table to text in one go, then skips everything under it in the tree so nothing is emitted twice. Captions go into that text. Footnotes do not. The chunk under that heading, before any fix:

headings: ['7. Radiology Reporting Flags']
text:     Chest X-ray (CXR), Urgent means = Pneumothorax, free air, mis-placed line.
          Chest X-ray (CXR), Routine TAT = Reported within 24 h. CT head, Urgent means = ...

Grep every chunk for "Urgent radiology turnaround": nothing. Ask "how fast must a critical radiology finding be phoned through?" and the table chunk may come back, but the one-hour rule is not in it.

My first fix was to relabel the two items from footnote to text. Grep again: still nothing. The label was never the problem. Their position in the tree was. The fix that works moves them up one level, so they sit after the table instead of under it. prov is provenance, the page and box an item came from; it is carried across so page counts stay right.

from docling_core.types.doc import DocItemLabel

for table in doc.tables:
    notes = [ref.resolve(doc) for ref in table.children]
    notes = [n for n in notes if getattr(n, "label", None) == DocItemLabel.FOOTNOTE]
    anchor = table
    for note in notes:
        anchor = doc.insert_text(
            sibling=anchor, label=DocItemLabel.TEXT, text=note.text,
            prov=note.prov[0] if note.prov else None, after=True,
        )
    if notes:
        doc.delete_items(node_items=notes)

After the fix the two lines are ordinary paragraphs under 7. Radiology Reporting Flags, and the chunker merges them into the same chunk as the table. Two items in one file out of twelve. Small, but it is a clinical timing rule.

The third loss was mine

Docling's Markdown backend splits a list item at every inline formatting boundary. This line from the billing guide:

2. Admission note with **provisional diagnosis** and matching ICD-10 code from `billing_codes.pdf`.

comes out as six items:

list_item  ''
text       'Admission note with'
text       'provisional diagnosis'
text       'and matching ICD-10 code from'
code       'billing_codes.pdf'
text       '.'

Each chunk records which items it was built from, in chunk.meta.doc_items. I ran a coverage check: is every item in the document referenced by at least one chunk? 85 of 239 were not. I wrote "85 items dropped, the checklists are gutted" and started fixing it.

Then I checked the words instead of the references. The chunk text:

2. Admission note with **provisional diagnosis** and matching ICD-10 code from `billing_codes.pdf` .

All 85 unreferenced fragments were present. The chunker's list serialiser had stitched them back together and simply not recorded the pieces as sources. Nothing was lost.

What was wrong is visible in that same line: the ** and the backticks survived into the text that went to the embedding model. 96 bold markers and 44 backticks across the file, and phrases broken by them. The source says the claim deadline is "typically 30 days post-discharge"; grep the chunk text for typically 30 days post-discharge and you get nothing, because two asterisks sit in the middle. A real problem, worth the Markdown-stripping pass I had already written. Not the problem I had claimed.

The lesson generalises. Item counts, reference counts, node counts measure the tree, not the words. When you suspect content loss, probe for the words. Pick five phrases you know are in the source and grep the output for them. If they are there, the tree shape is a detail.

The check that catches the first failure

Two of the three failures were invisible in the logs and visible in the numbers. So every parse now ends with a check, and a parse that fails it is retried once, then rejected. Three signals, in the order the code runs them.

Pages returned equals pages in the file. len(result.pages) against result.input.page_count. This is the only signal that catches the race, because the lost pages vanish entirely. Nothing else you compute from result can see them.

Every returned page has content. Page headers, footers and page numbers are furniture, present on every page and worthless in a chunk; they do not count. A page with zero real items is a page the layout model gave up on.

Raw words survive. Before the layout model runs, the PDF parser extracts text lines into result.pages[i].parsed_page.textline_cells. Every word in the final tree had to come from one of those lines, so their count is the ceiling. Count the words in the final items too, table cells separately because a TableItem has no .text, and compare. On a clean parse 83 to 92 percent survive across my eleven PDFs; the rest is furniture. This signal catches a page the layout model half-read: items present, paragraphs missing. It does not catch the race, because the lost pages take their text lines with them (the racy runs above all scored 97 percent).

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.backend.docling_parse_backend import ThreadedDoclingParseBackendOptions
from docling_core.types.doc import DocItemLabel

FURNITURE = {DocItemLabel.PAGE_HEADER, DocItemLabel.PAGE_FOOTER}

def parse_problems(result, min_ratio=0.8):
    doc = result.document
    problems = []

    if result.input.page_count and len(result.pages) != result.input.page_count:
        problems.append(f"{len(result.pages)} of {result.input.page_count} pages returned")

    per_page = {}
    for item, _ in doc.iterate_items():
        if item.prov and item.label not in FURNITURE:
            per_page[item.prov[0].page_no] = per_page.get(item.prov[0].page_no, 0) + 1
    empty = [p.page_no for p in result.pages if per_page.get(p.page_no, 0) == 0]
    if empty:
        problems.append(f"empty pages {empty}")

    raw = sum(len(c.text.split()) for p in result.pages if p.parsed_page
              for c in p.parsed_page.textline_cells)
    kept = 0
    for item, _ in doc.iterate_items():
        if item.label in FURNITURE:
            continue
        if item.label == DocItemLabel.TABLE:
            kept += sum(len(c.text.split()) for c in item.data.table_cells)
        else:
            kept += len((getattr(item, "text", "") or "").split())
    if raw and kept / raw < min_ratio:
        problems.append(f"only {kept / raw:.0%} of raw words survived")

    return problems


opts = PdfPipelineOptions(generate_parsed_pages=True)   # keeps textline_cells; without it raw is 0
converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(
        pipeline_options=opts,
        backend_options=ThreadedDoclingParseBackendOptions(parser_threads=1),
    )}
)

for attempt in range(2):
    result = converter.convert(path)
    problems = parse_problems(result)
    if not problems:
        break
    print(f"parse attempt {attempt + 1} of {path}: {problems}")
else:
    raise RuntimeError(f"{path} failed the parse check: {problems}")

What it prints on the nursing manual, single thread:

pages   8 of 8 returned, 8 with content
items   [3, 21, 15, 14, 10, 15, 16, 15]
words   998 of 1203 raw (83%)
problems []

And on the 9-page guide with the threaded backend, exactly as the loop prints it, three separate processes:

parse attempt 1 of guide.pdf: ['6 of 9 pages returned']
pages   9 of 9 returned, 9 with content     <- second attempt
words   2695 of 2785 raw (97%)
problems []

parse attempt 1 of guide.pdf: ['7 of 9 pages returned']
pages   9 of 9 returned ...

parse attempt 1 of guide.pdf: ['6 of 9 pages returned']
pages   9 of 9 returned ...

Three for three: the first attempt lost pages, the second got them all. Note the word ratio on the bad first attempts was 97 percent; only the page count saw the loss.

Two things to set expectations. The 0.8 floor is below my clean range with margin; measure your own clean floor first and set the threshold under it. And on scanned PDFs the parser has no text lines, raw is zero, and the word check silently skips itself; the page checks still run.

The retry is there for the threaded case above, and for whatever the next intermittent thing turns out to be. With parser_threads=1 it should never fire; when it does, that is information.

What this check does not catch. The footnotes. Their words are in the tree, so every ratio is happy; it is the chunker that drops them. For that, grep the chunk text, not the document: five phrases from the source, checked after chunking. The half-parsed 54-item handbook I never measured with this check; it happened before the check existed and I have not reproduced it since.

One habit

Before you trust a parse, print three numbers per document: pages returned versus pages in the file, items per page, and the share of raw words that survived. Then pick five phrases from the source and grep the chunk text for them. Thirty lines of code, a few seconds per file.

Docling will not tell you when it drops something. The numbers will. Make them part of the parse, not a thing you run when a test fails.

Questions this post answers

Why does Docling return fewer pages on some runs? A data race in the docling-parse PDF backend when Docling decodes pages on four threads. Set ThreadedDoclingParseBackendOptions(parser_threads=1) and compare len(result.pages) to result.input.page_count on every parse.

Why are my table footnotes missing from the chunks? HybridChunker serialises a table as one unit and marks its children as visited without emitting footnotes. Re-insert them as text items after the table with doc.insert_text(sibling=table, after=True); relabelling them does not help.

What do exit codes 134 and 139 mean during Docling parsing? 134 is an abort and 139 a segmentation fault, both from native code. Mid-parse they are the docling-parse race. At interpreter exit only, it is onnxruntime's telemetry thread; set ORT_DISABLE_TELEMETRY=1.

In short. Docling's PDF pipeline gives every heading level 1 by default. Of six ways to fix it, the built-in HeadingHierarchyOptions(enabled=True) with generate_parsed_pages=True nested headings correctly on all eleven test documents with no other change. A third-party post-processor, a regex rule, font-size clustering and the vision pipeline each fell short on this corpus.

The setup

Docling reads a PDF into labelled items. A layout model looks at each rendered page and decides what each box is: text, table, list_item, section_header. Every section_header carries an integer level; 1 is the top. A nested document should come out 1, 2, 3.

One page of an ICU nursing manual, seven SOPs (standard operating procedures):

SOP 1 - Central Venous Catheter (CVC) Care     <- 16pt bold heading
    Frequency                                  <- 12pt bold sub-heading
    Dressing change every 72 hours...
    Equipment checklist                        <- sub-heading
    Procedure                                  <- sub-heading
    1 Perform hand hygiene...                  <- numbered step, a list item
SOP 2 - Mechanical Ventilator Management
    Initial settings

Docling's HybridChunker walks those items and attaches to each chunk the headings above it, one per level, in chunk.meta.headings. That list is the breadcrumb, the only place the hierarchy reaches the retriever. If the 72-hour chunk's breadcrumb is ['Frequency'], it never says which line it is about. When I measured it, the chunk still ranked first on its body text, but the next two results were Procedure chunks from two different SOPs with identical breadcrumbs, and nothing in the retrieved text lets a reader or a model tell them apart.

A PDF can also carry bookmarks, the outline in a viewer's sidebar. Each entry has a depth, so a bookmarked PDF already knows its levels. PDFs converted from HTML get them free from <h1>, <h2>, <h3>. PDFs from ReportLab, which produced all of mine, and from most internal generators, have none.

The corpus: eleven ReportLab PDFs, zero bookmarks. The ICU manual above; an equipment manual with four devices, each with its own Fault codes section; treatment protocols A to G, each with Diagnostic criteria and Monitoring; a drug formulary of numbered tables; a staff FAQ grouped into themes; and six policy documents with 1., 2., 3. sections (billing codes, diagnostic reference, code of conduct, leave policy, staff handbook, infection control).

What correct means here

Two checks, both scriptable.

First, do the levels nest? Print (level, text) for every section_header and read it. SOP 1 should be above Frequency, not beside it.

Second, do repeated sub-headings get distinct parents? Fault codes appears four times in the equipment manual. After chunking, each of those four chunks should carry a different device in its breadcrumb. If they all say Manual > Fault codes, the hierarchy did not reach the chunker, whatever the levels claim. This is the check that matters for retrieval, and the one that catches tools that look right on a heading dump.

from collections import defaultdict
from docling.chunking import HybridChunker

def repeated_subheadings(doc):
    """Headings that label more than one chunk, and how many of those have >1 distinct parent path."""
    parents, seen = defaultdict(set), defaultdict(int)
    for chunk in HybridChunker().chunk(doc):
        path = chunk.meta.headings or []          # the breadcrumb
        if path:
            parents[path[-1]].add(tuple(path[:-1])); seen[path[-1]] += 1
    repeated = {h for h, n in seen.items() if n > 1}
    separated = {h for h in repeated if len(parents[h]) > 1}
    return separated, repeated

separated/repeated is the number I report below. Read it as a change: 0/2 -> 2/2 means two sub-headings that shared one parent now have their own; 0/4 -> 0/4 means four sections merely span several chunks each, which is fine.

Six approaches follow, in three families: do nothing, infer the levels outside Docling (a package, a regex, font sizes, a vision model), or let Docling infer them.

1. The default gives every heading level 1

from docling.document_converter import DocumentConverter
doc = DocumentConverter().convert("manual.pdf").document
print(sorted({t.level for t in doc.texts if t.label == "section_header"}))   # doc.texts: every text item; headings carry .level

Every document: [1]. Breadcrumb on the 72-hour chunk: ['Frequency']. The layout model decides that a box is a heading. It never compares two headings to each other, so it has no idea SOP 1 is bigger than Frequency. Docling has a separate stage that does compare them, and it is off unless you switch it on. That is approach 6. Here is what I did before finding it.

2. A package that is right with bookmarks and confidently wrong without

Search for the problem and you find docling-hierarchical-pdf, which describes itself as a package that "enables inference of header hierarchy in the docling PDF parsing pipeline." It installs as docling-hierarchical-pdf and imports as hierarchical. You run it on the conversion result after Docling is done:

from docling.document_converter import DocumentConverter
from hierarchical.postprocessor import ResultPostprocessor

result = DocumentConverter().convert("manual.pdf")
ResultPostprocessor(result).process()

Three signals in order: PDF bookmarks read with pymupdf, then heading numbering, then font size and style. On a PDF converted from HTML with 54 bookmarks it produced a perfect three-level tree, the case its README leads with.

On my bookmark-less corpus, results split. The FAQ, the treatment protocols and the staff handbook nested correctly. The ICU manual went from 34 headings to 56: the numbering pass read 1 Perform hand hygiene, 2 Remove the old dressing and twenty other procedure steps as numbered headings, promoted those 22 list items, and built a six-level tree out of them. SOP 1 stayed at level 1; the 72-hour breadcrumb stayed ['Frequency'].

The lesson is not "avoid this package". A heuristic tuned for bookmarks and outline numbering does something confident and wrong on a corpus with neither, and you only find out by printing the tree.

3. A regex that works until the twelfth document

If the package's numbering heuristic is too loose for your corpus, write a tighter one. On the default output, headings that start with 1., A. or SOP n are sections; the rest are sub-sections:

import re
SECTION = re.compile(r"^(\d+\.\s|[A-Z]\.\s|SOP\s\d+|Appendix\b)")   # corpus-specific

first = True
for t in doc.texts:
    if t.label != "section_header":
        continue
    if first:
        t.level = 1; first = False          # document title
    elif SECTION.match(t.text.strip()):
        t.level = 2                         # section
    else:
        t.level = 3                         # sub-section

HybridChunker honours whatever level you set, so this works; the 72-hour breadcrumb becomes ['ICU Nursing Procedures Manual', 'SOP 1 - …', 'Frequency']. Thirty lines with edge cases. Correct on all eleven documents because I wrote it after reading all eleven; useless on the twelfth if it numbers sections differently. Right for a corpus you control, wrong for a pipeline that will see documents you have not read.

4. Font sizes from pymupdf, and a segfault

Headings in these files are printed at 26, 16, 12, 10.8 and 9.3 points, cleanly tiered. So: read every text span with its size using pymupdf, match Docling's headings to spans, assign levels by size rank.

Two problems killed it. Matching a heading's text back to a span is fuzzy, because Docling joins wrapped lines and normalises whitespace while pymupdf returns one span per line and style run; six of about two hundred headings matched the wrong span or none (from my notes, not re-measured). And pymupdf and Docling's PDF parser both bundle native PDF code: import pymupdf before any Docling module and the process segfaults the moment Docling runs; import Docling first and it works. The package in approach 2 gets away with it because its own modules import Docling before pymupdf. Not an ordering constraint I want in an ingestion job.

5. The vision pipeline reads the page and still says level 1

Docling's default pipeline detects boxes on the page and reads the text out of each. Its VLM pipeline instead hands the whole page image to a small vision-language model that writes the structured output directly, the way a person reads a scan. If any approach could see that one heading is bigger than another, I expected this one.

Recalled numbers, not re-run, because nine minutes per document makes eleven documents a ninety-minute job: nine minutes for the eight-page ICU manual, one page absent from the output for a reason I never established, and every heading still at level 1. Reading the page like a human and ranking headings are different problems. This pipeline exists for scans and dense layouts.

6. The option that was there all along

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   # without this the font-size signal is silently skipped

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

Docling ships its own heading-hierarchy stage. Same three signals as the package, but it runs inside the pipeline on Docling's own parsed text cells, never touches list items unless a bookmark confidently says so (exactly what tripped the package on the ICU manual), and needs no second PDF library.

The same ICU page, six ways. Tree = (level, text) for the first headings; breadcrumb = chunk.meta.headings on the 72-hour chunk. Rows 1, 2, 3 and 6 re-run for this post; 4 and 5 recalled.

Level 4 in row 6 is the callout labels (Escalate, Safety, Principle) printed smaller inside a sub-section.

One thing to know before the results: the levels are relative to the document, not absolute. A file whose headings come out [1, 3, 4] has three tiers; nothing is missing at 2.

Results on all eleven documents, re-measured for this post. "Separated" is the second check: repeated sub-headings with distinct parents, default versus native.

Every document nests. Chunk counts are identical before and after: the chunker groups the same text and just labels it correctly. In the ICU manual only Procedure (SOP 1 and 6) and Safety (SOP 3 and 6) recur across SOPs, so 2/2 is the whole set. Fault codes now has four different parents. Zero promoted list items.

Two quirks worth knowing, with the lines each needs. Numbered sections like 1. Scope often land at level 1 beside the document title, so the title drops out of paths under them:

title = next(t.text for t in doc.texts if t.label == "section_header")   # first heading = the title
path = list(chunk.meta.headings or [])
if path[:1] != [title]:
    path = [title, *path]

And in the ICU manual the callout labels sit at level 4 under a level-3 sub-section, so if you only want three tiers, cap them:

HeadingHierarchyOptions(enabled=True, max_level=3)

The ten-minute evaluation

Run this on your corpus before choosing anything. Both checks, every PDF, default versus native.

from collections import defaultdict
from pathlib import Path
from docling.chunking import HybridChunker
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import HeadingHierarchyOptions, PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

default = DocumentConverter()
opts = PdfPipelineOptions(generate_parsed_pages=True, heading_hierarchy_options=HeadingHierarchyOptions(enabled=True))
native = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})

def levels(doc):
    return sorted({t.level for t in doc.texts if t.label == "section_header"})

def repeated_subheadings(doc):
    parents, seen = defaultdict(set), defaultdict(int)
    for chunk in HybridChunker().chunk(doc):
        path = chunk.meta.headings or []
        if path:
            parents[path[-1]].add(tuple(path[:-1])); seen[path[-1]] += 1
    repeated = {h for h, n in seen.items() if n > 1}
    return len({h for h in repeated if len(parents[h]) > 1}), len(repeated)

for pdf in sorted(Path("docs").rglob("*.pdf")):
    d0, d1 = default.convert(str(pdf)).document, native.convert(str(pdf)).document
    s0, r0 = repeated_subheadings(d0); s1, r1 = repeated_subheadings(d1)
    print(f"{pdf.name:30} levels {levels(d0)} -> {levels(d1)}   separated {s0}/{r0} -> {s1}/{r1}")

Two lines of its output, one document that needed the option and one that did not:

equipment_manual.pdf           levels [1] -> [1, 3, 4]   separated 0/2 -> 2/2
code_of_conduct.pdf            levels [1] -> [1, 3]      separated 0/0 -> 0/0

Read the output, then one document's heading tree by hand. If the native option nests and the repeated sub-headings separate, you are done. If not, your corpus has neither bookmarks nor consistent numbering nor size tiers, and you are in regex territory with your eyes open.

Which approach, by document

I spent a day getting to the sixth approach. The option was in the pipeline the whole time, one flag away, documented on a page I had not read. The three signals are the whole story: bookmarks, numbering, style. Find out which ones your PDFs carry before you write a line.

Questions this post answers

Why are all my Docling headings level 1? Docling's layout model classifies boxes as headings but does not rank them, and the pipeline stage that assigns levels is off by default. Enable HeadingHierarchyOptions and keep generate_parsed_pages=True so the font-size signal has data.

Does docling-hierarchical-pdf fix heading levels? When the PDF carries bookmarks, yes. Without bookmarks it inferred levels from numbering and promoted numbered procedure steps to headings on my documents. The built-in option uses the same signals with stricter guardrails.

Will Docling's VLM pipeline give better heading levels? No. On an eight-page manual it took nine minutes, dropped a page, and still returned every heading at level 1. Layout awareness and heading hierarchy are different problems.

Layout-aware and hierarchical are not alternatives. They happen at different stages. You will almost always use both, and the real decisions are how much layout machinery you need and whether your heading structure is trustworthy. This post is what each one actually does, where each one runs, and how to decide.

In short. Layout-aware and hierarchical chunking are not two strategies to choose between. Layout awareness is a property of the parser: Docling's default PDF pipeline already finds headings, tables and reading order from the page image. Hierarchical chunking is the step after it: HybridChunker walks the parsed tree and attaches each chunk's heading path. You use both; the real decisions are whether the default parser reads your pages (check labels per page) and whether the heading levels it returns are trustworthy (print them). The heavier vision-language pipeline is for scans and broken reading order, not for heading levels or missing pages.

Parse, then chunk

A document goes through two steps before it becomes chunks.

PDF or Markdown  ──parse──▶  document tree  ──chunk──▶  chunks
                 (layout-aware)              (hierarchical)

Parsing turns pixels or markup into a tree of labelled items. A page of a procedures manual comes out roughly like this:

section_header  SOP 1 - Central Line Care
  section_header  Frequency
    text            Dressing change every 72 hours...
  section_header  Equipment checklist
    list_item       Sterile gloves
    list_item       Chlorhexidine 2%

This is where layout awareness lives. It is the parser's job to know that a two-column page reads top-to-bottom per column, that a grid of numbers is a table, that a bold line at the top is a heading.

Chunking walks that tree and decides where one retrievable piece ends and the next begins. Hierarchical chunking uses the heading structure the parser found. It has no idea what the page looked like. It only sees the tree.

So "layout-aware chunking" is really "chunking a tree that was built by a layout-aware parser". If the parser got the layout wrong, no chunker can fix it. If the parser got it right, a hierarchical chunker is the natural way to consume it.

What layout-aware parsing means in practice

The code in this post uses Docling, the open-source document converter I work with (pip install docling; this is Docling 2.123 with docling-core 2.92). It turns PDF, DOCX, HTML and Markdown into one tree type, DoclingDocument, and ships the chunkers that walk it. The code is Docling. The argument is not.

Docling's default PDF pipeline is already layout-aware. A layout model, an object-detection model trained on page images, looks at each rendered page and draws labelled boxes. It does not read the words; it decides what each box is. A table model recovers rows and columns. OCR runs on regions with no text layer, the invisible run of characters a digital PDF carries under its pixels, the thing that lets you select text. The pipeline then reconstructs reading order.

from collections import Counter
from docling.document_converter import DocumentConverter

doc = DocumentConverter().convert("nursing_manual.pdf").document
# iterate_items() yields (item, depth); depth is tree position, not heading level
print(Counter(item.label.value for item, _ in doc.iterate_items()))

On an eight-page procedures manual that prints:

Counter({'list_item': 58, 'section_header': 34, 'text': 13, 'table': 4})

Every bullet is a list_item, every paragraph is text, every table is a table (its cells live inside it, not as separate items), every heading is a section_header. I configured none of that. Five seconds on a warm run.

A bad parse looks different, and you can see it in the same counter. Here is the same manual after a heading-inference tool promoted its numbered procedure steps to headings:

Counter({'section_header': 56, 'list_item': 36, 'text': 13, 'table': 4})

Twenty-two list items became headings, the tree went six levels deep, and every downstream chunk inherited a breadcrumb like Procedure > 1 Perform hand hygiene. The counter caught it before anything else did.

There is a heavier form of layout awareness: Docling's VLM pipeline. A vision-language model is an LLM that takes an image as input; this pipeline replaces the layout model, table model and OCR with one model that looks at the page and writes it back out as markup. I tried it hoping "reads the page like a human" would also mean "knows which heading is bigger", because heading levels come from font size and the layout model does not compare fonts.

Layout awareness and heading hierarchy are different problems. The VLM path is for documents the default layout model cannot read: scans with no text layer, dense multi-column layouts, figure-heavy pages. It is not an upgrade for clean digital text. Check which kind you have with pdffonts file.pdf (from poppler): if it lists fonts, there is a text layer and the default pipeline will read it.

What hierarchical chunking means in practice

Take the tree from above and walk it. Docling's HierarchicalChunker emits one chunk per leaf item, tagged with the heading path it sits under. List items under the same heading are merged into one chunk by default (merge_list_items=True). Headings are never chunk bodies; they only update the current path.

The page of the manual:

SOP 1 - Central Line Care          <- heading
    Frequency                      <- sub-heading
    Dressing change every 72 hours...
    Equipment checklist            <- sub-heading
    - Sterile gloves
    - Chlorhexidine 2%
    - Sterile drape

Becomes two chunks. chunk.meta.headings is the path, chunk.text is the body. Manual is the document title; Docling puts it at the root of every path.

headings: ['Manual', 'SOP 1 - Central Line Care', 'Frequency']
text:     Dressing change every 72 hours...

headings: ['Manual', 'SOP 1 - Central Line Care', 'Equipment checklist']
text:     - Sterile gloves
          - Chlorhexidine 2%
          - Sterile drape

That path is what I mean by breadcrumb from here on. Embed it together with the body and the chunk carries its own context.

I wanted to see what that buys over a plain window, so I indexed the same manual twice: once through this chunker (28 chunks), once through a 500-character window with 50 overlap over the Markdown export (23 chunks). Query: how often do I change a central line dressing. Both found the paragraph. What came with it differed.

fixed window, top hit:
  #### Frequency | Dressing change every 72 hours, or sooner if the dressing is
  soiled... | #### Equipment checklist | - Sterile gloves and sterile dressing pack...

hierarchical, top hit:
  ICU Nursing Procedures Manual > SOP 1 - Central Venous Catheter (CVC) Care > Frequency
  Dressing change every 72 hours, or sooner if the dressing is soiled...

The window has a heading fragment and half of the next section. Nothing in it says which line it is about. The hierarchical chunk names the SOP. Ask something where the discriminating word lives only in the heading and the gap opens: safety rules when suctioning the airway returned, as the window's first hit, the tail of the restraint-documentation section with the suctioning heading dangling at the bottom; the hierarchical first hit was the suctioning SOP itself, and the second was SOP 6 - Endotracheal Suctioning > Procedure > Safety with the one-line rule. Windows straddle section boundaries. Tree chunks do not.

HybridChunker adds a token budget on top. Every embedding model has a hard input limit counted in its own tokens, so you hand the chunker the same tokenizer and max_tokens becomes that limit in the model's units. It splits any chunk that is too long, then merges undersized neighbours that share a heading path (merge_peers=True), so three one-line paragraphs under one heading come out as one chunk and a nine-step procedure stays together. A 16-row drug table gets split by rows, and every piece still says which column is which, because Docling does not embed a table as a grid. Each cell becomes row header, column header = value:

Amoxicillin, Class = Penicillin. Amoxicillin, Route = Oral. Amoxicillin, Standard Dose = 500 mg TDS. ...

A piece holding rows 9 to 16 still knows what every value means.

from docling.chunking import HybridChunker
from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer
from transformers import AutoTokenizer

tokenizer = HuggingFaceTokenizer(
    tokenizer=AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2"),
    max_tokens=128,   # MiniLM accepts 256; 128 here so the splits below are easy to see
)
chunker = HybridChunker(tokenizer=tokenizer, merge_peers=True)

for chunk in chunker.chunk(doc):
    text_to_embed = chunker.contextualize(chunk)   # heading path + body: embed this
    body = chunk.text                               # body alone: store and show this

Two things the docs say quietly and I learned loudly.

First, max_tokens caps the body. contextualize() adds the heading path afterwards. On the antimicrobials table, one piece had a body of 123 tokens and a contextualized text of 130, over the cap of 128. The two tokens past the cap were the end of 1.2 g Q8H, the dosing frequency of the last drug in the piece. The worst piece in that document was 145 tokens; everything after 128 was antihistamine vs antihypertensive. clonazepam, confused with =, the second half of a look-alike-drug warning. If your embedding model truncates at exactly the cap, those tails are never embedded. The text is still stored, so the chunk looks complete when you print it; the vector simply does not know the end of it. Nineteen of the 38 chunks in that document were over the cap, and all nineteen were table pieces. Tables hit the cap because the splitter packs rows right up to it (table bodies: median 124 tokens, max 128); prose ends at paragraph boundaries and rarely gets close (median 63, max 96). Set the cap below the model limit by the length of your longest heading path:

longest_path = max(tokenizer.count_tokens("\n".join(c.meta.headings)) for c in chunks)  # 28 on my corpus

Then max_tokens = 256 - longest_path, with a little margin.

Second, hierarchical chunking is only as good as the heading levels in the tree. Docling's PDF parser emits every heading at level 1 unless you enable its heading-hierarchy option. With flat levels the chunker keeps one heading per level, so Frequency overwrites SOP 1 and the 72-hour chunk comes out as:

flat levels:    headings: ['Frequency']
nested levels:  headings: ['ICU Nursing Procedures Manual', 'SOP 1 - Central Venous Catheter (CVC) Care', 'Frequency']

Same chunk boundaries, same body. Only the breadcrumb changed, and with it whether the chunk knows it is about a central line. The fix is one option on the PDF pipeline:

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

opts = PdfPipelineOptions(generate_parsed_pages=True,
                          heading_hierarchy_options=HeadingHierarchyOptions(enabled=True))
converter = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})

I wrote that one up separately: Docling Flattens Your PDF Headings. Notice what kind of bug it is. A parse-stage setting that you only see at the chunk stage. That is this whole post in one bug.

Where each one is the wrong tool

Hierarchical chunking is wrong when there is no hierarchy. A CSV of FAQ rows, a flat list of product descriptions, a transcript. The tree is one heading and a hundred paragraphs. You get a hundred chunks with the same breadcrumb, which is fixed-size chunking with extra steps. For rows, make each row a chunk with its own fields as text. For flat prose, a plain token-window splitter does the same job with less machinery.

Hierarchical chunking is also wrong when the hierarchy is a lie. Sub-headings the parser missed, or numbered steps the parser mistook for headings, like the 56-heading counter above. Print the heading levels first (the snippet is in the last section). If the tree does not match the page, fix the parse before you chunk.

Extra layout machinery is wrong when the default already reads the page. The VLM pipeline costs a hundred times the time and, on my manual, lost a page of its own. Reach for it when the default pipeline mangles reading order or returns a page as one text blob with no headings and no tables. You can check for that by counting labels per page. A page that is missing altogether is a different problem. On my corpus it turned out to be a threading bug in the PDF parser (docling-parse up to 7.16 with the default multi-threaded backend, docling issue #4147), not a layout limit, and a heavier layout model would not have brought it back. A separate post covers that bug. Here is the check, run on a nine-page PDF with the default backend:

from collections import Counter
# prov is provenance: the page and box each item was read from. [0] because an item can span pages.
per_page = Counter(item.prov[0].page_no for item, _ in doc.iterate_items() if item.prov)
print(sorted(per_page.items()))   # every page should appear with a non-zero count

run 1:  [(1, 3), (3, 9), (4, 8), (5, 8), (6, 7), (7, 7), (8, 11), (9, 8)]   # page 2 gone
run 2:  [(1, 3), (4, 8), (5, 8), (6, 7), (7, 7), (8, 11), (9, 8)]           # pages 2 and 3 gone
run 3:  [(1, 3), (3, 9), (5, 8), (7, 7), (8, 11), (9, 8)]                   # pages 2, 4 and 6 gone

Different pages each run, no error, and the parse reported success every time. A page missing from that list is a parser problem. No chunking strategy will bring it back, and neither will a heavier layout model. Check the parser version before you change pipeline.

The decision, as a table

The left column is the only real decision. Look at the document, not the strategy list.

One habit

Before ingesting anything, print four things for one document. Thirty seconds.

from collections import Counter
from docling_core.types.doc import DocItemLabel

print(Counter(item.label.value for item, _ in doc.iterate_items()))          # 1. labels

for item, _ in doc.iterate_items():                                            # 2. heading levels
    if item.label == DocItemLabel.SECTION_HEADER:
        print(item.level, item.text)

chunk = next(iter(chunker.chunk(doc)))                                         # 3. one chunk, with its token count
text = chunker.contextualize(chunk)
print(tokenizer.count_tokens(text), text)

per_page = Counter(item.prov[0].page_no for item, _ in doc.iterate_items() if item.prov)
print(sorted(per_page.items()))                                                # 4. pages

The second print, on the manual with the hierarchy option on:

1 ICU Nursing Procedures Manual
2 SOP 1 - Central Venous Catheter (CVC) Care
3 Frequency
3 Equipment checklist
3 Procedure
4 Escalate
2 SOP 2 - Mechanical Ventilator Management

If the labels look right, layout awareness is done. If the levels nest, the hierarchy is trustworthy. If the contextualized chunk reads like something you would want an answer built from and its token count is under your model's limit, the chunker is doing its job. If every page is in the fourth list, the parser read the whole file. Those four checks caught every problem in this post before it reached the vector store.

Questions this post answers

What is the difference between layout-aware and hierarchical chunking? Layout-aware describes parsing: turning a page into labelled blocks (headings, tables, lists) using a layout model. Hierarchical describes chunking: splitting along the heading tree the parser produced and keeping each chunk's heading path. They run at different stages, so you use both.

When should I use Docling's VLM pipeline instead of the default? When the default pipeline mangles reading order or returns a page as one text blob with no headings or tables. Not for heading levels (it still returns level 1) and not for missing pages, which on my documents were a threading bug in the PDF parser, not a layout limit.

Why do my table chunks exceed the embedding token limit? HybridChunker caps the chunk body, then contextualize() prepends the heading path. Table pieces are packed right up to the cap, so the added headings push them over and the tail is silently never embedded. Set the cap to the model limit minus your longest heading path.

I hit this building a RAG pipeline over a set of internal hospital manuals, where each chunk carries the headings above it so a paragraph about "72 hours" still knows it is about central lines. This post is what I learned figuring out why the headings were flat, what the fix is, and which PDFs make the fix trivial. Docling 2.123 throughout; older versions do not have the option described below.

In short. Docling's PDF pipeline labels every heading level 1 because the stage that ranks headings is off by default. Turn on HeadingHierarchyOptions(enabled=True) and set generate_parsed_pages=True on the PDF pipeline options; headings then nest from bookmarks, numbering or font size, and each chunk's heading path carries its parent section again. PDFs converted from HTML already have bookmarks and get exact levels from that one flag; PDFs from ReportLab and most internal generators rely on numbering and font size.

What Docling gives you

Docling reads a document into a tree. Every piece of content becomes an item with a label. The two that matter here are section_header and text; tables, lists and page furniture get their own labels. Each section_header also carries a level: 1 for a title, 2 for a section under it, 3 for a sub-section, exactly what #, ##, ### mean in Markdown.

How Docling gets there depends on the format. For Markdown it reads the syntax, so the level is free. For a PDF, a layout model, a vision model that looks at the rendered page, draws a box around each block and classifies it, decides what each box is. It judges one box at a time. It can say "this is a heading". It has no idea whether this heading is bigger than the one above it.

You can inspect the headings directly:

from docling.document_converter import DocumentConverter

doc = DocumentConverter().convert("manual.pdf").document
for item in doc.texts:                     # every text-like item, in reading order
    if item.label == "section_header":     # only headings carry a meaningful .level
        print(item.level, item.text)

On a Markdown billing guide from the same corpus that prints the nesting you would expect:

1 Purpose & Scope
2 How claims flow
1 1. Cashless Claim Process
2 1.1 Pre-authorisation timeline
2 1.2 Documents required for pre-authorisation

On a PDF nursing manual it prints this:

1 ICU Nursing Procedures Manual
1 SOP 1 - Central Venous Catheter (CVC) Care
1 Frequency
1 Equipment checklist
1 Procedure
1 Escalate
1 SOP 2 - Mechanical Ventilator Management

Every heading level 1. Every time, with the default settings, whatever the PDF looks like. If you prototype on Markdown and switch to PDFs later, this is the moment everything changes: same code, same chunker, different results.

The heading problem

That manual looks like this on the page:

ICU Nursing Procedures Manual                <- title, 26pt bold
SOP 1 - Central Venous Catheter (CVC) Care   <- section, 16pt bold
    Frequency                                <- sub-section, 10.8pt bold
    Dressing change every 72 hours...           body, 9.7pt
    Equipment checklist                      <- sub-section, 10.8pt bold
    - Sterile gloves...
    Procedure                                <- sub-section, 10.8pt bold
    1. Perform hand hygiene...

SOP 2 - Mechanical Ventilator Management     <- section, 16pt bold
    Initial settings                         <- sub-section, 10.8pt bold
    ...

Three heading sizes. Anyone can see Frequency belongs to SOP 1.

Docling's layout model classifies "this box is a heading" and stops. Docling does have a later pipeline stage that ranks headings against each other, but it is switched off by default, so every detected heading is emitted at level=1, even when the file carries a perfectly good outline. The tree says SOP 1, Frequency, Procedure, SOP 2 are siblings.

Now feed that to a hierarchical chunker. A chunker cuts a document into pieces small enough to embed and retrieve. A hierarchical one also writes down the headings each piece sits under and puts them in front of the text before embedding. That heading path is the breadcrumb, and it is the only way a paragraph about "72 hours" knows it is about central lines. Docling's default chunker, HybridChunker, does this.

Here is how it tracks the path. Think of one slot per level. SOP 1 arrives at level 1 and goes in slot 1. Frequency also arrives at level 1, so it goes in slot 1 and evicts SOP 1. When the chunker reaches the paragraph about 72 hours, slot 1 holds Frequency and nothing else exists. The text it hands to the embedding model, chunker.contextualize(chunk), is:

Frequency
Dressing change every 72 hours, or sooner if the dressing is soiled, loose or no longer occlusive.

Frequency of what? The chunk does not say. The words "central line" appear nowhere in it.

I expected retrieval to miss it. It did not. I asked "how often do I change a central line dressing" against a store built from this flat parse and the 72-hour chunk came back first, because the dense embedding matched "dressing change". What broke was everything after rank one:

#1  Manual > Frequency          Dressing change every 72 hours...
#2  Manual > Procedure          1 Perform hand hygiene and don PPE...
#3  Manual > Procedure          1 Hand hygiene; don gloves, apron and eye protection...

Two Procedure chunks from two different SOPs, indistinguishable. Ask "how often should I change the dressing" and the top three include Frequency: 72 hours and Cannula change: 72-96 hours with no way to tell the central line rule from the cannula rule. The LLM that gets those three chunks has to guess which applies. Multiply by every manual with repeated sub-headings (Fault codes under four devices, Monitoring under seven protocols) and the answers degrade while the retrieval metrics look fine.

This is not a chunker bug. The chunker did exactly what the tree told it. The tree was flat.

Some PDFs make the fix trivial. Check yours.

A PDF can carry an outline: the bookmarks sidebar you see in a PDF viewer. Each entry already has a level. PDFs converted from HTML (wkhtmltopdf, a browser's print-to-PDF, most documentation-site exporters) get one automatically, because <h1>, <h2>, <h3> become bookmarks with their depth intact. Once you switch Docling's heading-hierarchy stage on, it matches that outline to the detected headings and, when the match is confident, uses it as the hierarchy. No inference involved.

PDFs from ReportLab, many Word exports, scanners, and the internal systems I have seen have no outline at all. For those, Docling has to infer the hierarchy from numbering and font style. It can, but it is guessing, so you check the result.

Find out which kind you have before you spend a day on chunking:

import pymupdf
print(pymupdf.open("manual.pdf").get_toc()[:3])

On an HTML-converted policy document with 54 bookmarks:

[[1, 'HR Policies', 1], [2, 'Employment & Onboarding', 1], [3, 'Offer and Joining Formalities', 1]]

The first number in each entry is the level. On the ReportLab nursing manual the list is empty. Empty means you are in the inference case. Either way, the next step is the same flag. On that 54-bookmark file the default converter gave [1] for the set of levels; with the flag on, [1, 2, 3].

The fix is built in and off by default

Docling has a heading-hierarchy stage that assigns SectionHeaderItem.level. It is off by default. My guess at why: a wrong level silently breaks a downstream chunker, while a flat level is at least predictable, so Docling leaves the choice to you.

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

pipeline_options = PdfPipelineOptions()
pipeline_options.heading_hierarchy_options = HeadingHierarchyOptions(enabled=True)
pipeline_options.generate_parsed_pages = True   # keeps font sizes for the style signal; see below

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
doc = converter.convert("manual.pdf").document

generate_parsed_pages needs a sentence now, not later. Docling normally throws away the low-level parser output (each run of text with its font, size and weight) once the document tree is built. This flag keeps it. The font-size signal reads from there, so without it that signal has nothing to look at.

With both lines on, the same manual comes out as:

1 ICU Nursing Procedures Manual
2   SOP 1 - Central Venous Catheter (CVC) Care
3     Frequency
3     Equipment checklist
3     Procedure
4       Escalate
2   SOP 2 - Mechanical Ventilator Management
3     Initial settings

And the text handed to the embedding model for the same chunk becomes:

ICU Nursing Procedures Manual
SOP 1 - Central Venous Catheter (CVC) Care
Frequency
Dressing change every 72 hours, or sooner if the dressing is soiled, loose or no longer occlusive.

Same chunk boundaries as before. Only the heading path changed. The same three queries against a store built from this parse:

#1  Manual > SOP 1 - Central Venous Catheter (CVC) Care > Frequency          72 hours
#2  Manual > SOP 1 - Central Venous Catheter (CVC) Care > Procedure
#3  Manual > SOP 1 - Central Venous Catheter (CVC) Care > Equipment checklist

And for "how often should I change the dressing", the two 72-hour rules now read SOP 1 - Central Venous Catheter > Frequency and SOP 4 - IV Cannula Insertion > Cannula change. The LLM no longer has to guess.

Three signals, in order

The stage tries three signals per heading. The first one that applies wins.

1. Bookmarks. The PDF outline, matched to detected headings by title and page. A confident match is authoritative.
2. Numbering. Leading markers in the heading text: PART I, CHAPTER 2, 1., 1.1, A., (a), (i).
3. Visual style. Font size first. Then, if two headings share a size, weight (bold above regular), slant (upright above italic) and letter case (all-caps above mixed).

Bookmarks and numbering work on the parsed text alone. Style needs the raw text cells, which is what generate_parsed_pages = True keeps around. Forget that flag and the style pass is skipped silently. On my manuals, which have no bookmarks and whose sub-headings carry no numbering, forgetting it gave back exactly the flat tree from the default run, every heading level 1, and I spent twenty minutes convinced the option did nothing. It was doing everything it could with the two signals it had, and those two had nothing to say.

The two options you might touch

Most documents need nothing beyond enabled=True. Two worth knowing: use_style=False when a document uses the same font for everything and style inference invents levels that are not there, and max_level when you know the corpus never goes deeper than a few levels and want callout labels clipped. The full option list (numbering schemes, size tolerance, bookmark match threshold) is in the Docling docs.

Applying it to a document you already parsed

If you cached converted documents and do not want to pay for the layout model again, you can run the same stage on a DoclingDocument after the fact. One constraint first: the standalone call only sees the document. The parsed pages that style inference needs live on the conversion result, not the document, so style cannot run here. Bookmarks and numbering can. Turn style off and run it:

from docling.datamodel.pipeline_options import HeadingHierarchyOptions
from docling.models.stages.heading_hierarchy.heading_hierarchy_model import HeadingHierarchyModel

model = HeadingHierarchyModel(options=HeadingHierarchyOptions(use_style=False))
model.assign_heading_levels(doc)

If you run Docling as a server instead of a library, the same switch is do_pdf_heading_hierarchy: true in the request, with the options under pdf_heading_hierarchy_options.

One habit that would have saved me a day

Print the heading tree for every document, before and after, and read it:

headers = [(t.level, t.text) for t in doc.texts if t.label == "section_header"]
print(sorted({level for level, _ in headers}))
for level, text in headers:
    print("  " * (level - 1), text)

A healthy tree indents. A flat one is a list of 1s flush left, and that is the output that tells you to go back and check bookmarks, numbering and the parsed-pages flag. The whole recipe is three lines: count the bookmarks, turn on enabled=True with generate_parsed_pages=True, print the tree and read it. Docling is doing the hard part well. It just needs to be told that headings have ranks, and then checked.

Questions this post answers

Why are all my Docling headings level 1? The layout model decides that a box is a heading but never compares two headings, and the pipeline stage that assigns levels is disabled by default. Every PDF heading comes out at level 1 until you enable it; Markdown keeps its #/## levels.

Does Docling use PDF bookmarks for heading levels? Only once HeadingHierarchyOptions(enabled=True) is on. With the default converter a PDF with 54 bookmarks still returned every heading at level 1; with the flag it returned a clean three-level tree.

What does generate_parsed_pages do in Docling? It keeps the raw text cells from the PDF parser, which carry font size and weight. The font-style signal of the heading-hierarchy stage reads them; without the flag that signal is skipped silently and only bookmarks and numbering apply.

Claude Code’s native memory is useful, but it is mostly organised around the current project (cwd) or repository. That works well when your work is repo-shaped. It breaks when your work is feature-shaped.

And most meaningful software work is feature-shaped. That is the gap I am trying to solve with layered-memory.

What Claude Code already gives you

Before building anything new, it is worth being clear about what already exists. Claude Code has three different mechanisms that get grouped under “memory”.

CLAUDE.md

This is the memory file you author. It is plain markdown. You can keep instructions, project conventions, commands, architectural notes and working preferences in it. Claude loads it into context when you start a session.

The important point is this: CLAUDE.md is not really learning. It is configuration. You write it. You maintain it. It is authoritative and always loaded.

Auto Memory

Claude Code also has Auto Memory. It can record learnings by itself: build commands, debugging notes, conventions and other facts it discovers while working. This is much closer to actual memory. The useful design choice is progressive disclosure. Claude does not load every detail at startup. It keeps a lightweight index and loads detailed topic files only when needed. That part is good.

The limitation is where things get interesting: Auto Memory is organised per project (cwd) or repository. If your feature spans multiple repos, the memory gets split across multiple silos.

Transcripts / context

Every Claude Code session is saved as a transcript you can resume, but the conversation history lives only within that session. As the context window fills, response quality degrades ("context rot"), so Claude Code auto-compacts — summarising turns to free up space. That summary is lossy, and some details and decisions can get dropped along the way.

The clean mental model is:

CLAUDE.md → rules; you author

Auto Memory → facts Claude learns, mostly per repo

Transcript → session level history

Useful? Yes. Enough for multi-repo product work? Not for me.

Where it breaks

Here is the actual situation we run into regularly at work. We work on a product that spans multiple repositories. Each repo has a specific role. But features do not care about repo boundaries.

One feature may involve:

• repo1 + repo2

• repo1 + repo2 + repo3

• repo1 only

• repo2 first, then repo1 later

• repo1, repo2 and a Kafka pipeline which I discover while exploring

But Claude’s native memory does not naturally think in terms of features. It thinks in terms of the current project derived from current working directory.

So the same feature ends up fragmented like this: (here read repo as cwd)

• ~/.claude/projects/repo1/memory/

• ~/.claude/projects/repo2/memory/

• ~/.claude/projects/repo3/memory/

We may have solved half the problem yesterday in repo2, but when we open repo1 today, that knowledge is not naturally available in the same feature context.

The memory exists. It is just in the wrong place.

There is a workaround. You can point multiple repos to one shared memory directory, or work from the base folder containing all repos. We do this when we already know a problem is going to involve multiple repositories.But that creates a different problem. Everything collapses into one shared heap. Now memories from unrelated features sit together in one flat space. You have avoided fragmentation, but created mush.

That is the core gap:

Claude Code gives you repo memory or shared memory. What I wanted was feature memory. Cross-repo, feature-organised, progressively loaded memory.

layered-memory is my attempt to solve this.

What I am building: layered-memory

Instead of keying memory only by repository, it reads what actually happened across Claude Code sessions and organises the useful parts by a theme.

A theme is a durable topic. In practice, the theme is usually a feature, a subsystem, a long-running bug, a design decision, or a recurring workflow.

The storage is deliberately boring:

~/.claude/memory/
├── index.md # lightweight (always loaded at session start)
└── themes/
    ├── <slug>.md  # one file per theme (loaded on demand)
    └── ...

Plain markdown. Readable. Editable.Portable. No mystery database. No hidden vector store. No black box.

The system has three parts:

• Build — read transcripts and extract durable memory.

• Reconcile — merge duplicates and clean overlaps.

• Recall — load the right theme when it is useful.

Build: mine the history, not just the current repo

The build step walks through Claude Code session transcripts across repositories. It reads the actual history of work: what was tried, what broke, what got fixed, what decisions were made, which files mattered and what conventions emerged. Each transcript is distilled into durable facts and grouped by theme. This matters because a lot of useful memory does not get written down in the moment.

It appears across the shape of the whole session:

• the first assumption that turned out wrong

• the actual root cause

• the final working fix

• the file that mattered but was not obvious

• the command that became reliable

• the convention discovered after three failed attempts

Native memory may capture some of this. But layered-memory looks back at the full transcript after the fact and asks:

• What should survive this session?

That is the difference. It is not just jotting notes.... It is mining history....

Reconcile: keep memory coherent

Once you start building memory from many sessions, another problem appears.

Themes overlap. You get things like:

• foo-plugin

• foo-plugin-setup

• foo-plugin-debugging

• foo-plugin-tuning

They may all be the same real topic.

So layered-memory has a reconcile step.It looks across the full set of themes and merges duplicates or near-duplicates. It preserves distinct facts, removes true redundancy and keeps the theme focused.

The goal is simple:

Memory should not become a junk drawer. It should become sharper over time.

Recall: load only what matters

The final part is recall. This is where the system becomes useful inside a real Claude Code session.

At startup, Claude sees only a small index:

• theme name

• one-line summary

• keywords

That gives Claude awareness of what memory exists without stuffing the whole past into context. When the current task matches a theme, the recall skill loads the full theme file on demand. So if I am working on an authorisation issue, Claude can load the authorisation theme. It does not need to load memories about governance workflows, plugin setup, release automation, or some old debugging session from another feature.

That is the point:

Index always. Detail only when relevant.

This mirrors the best part of Claude’s native memory, but applies it across repositories and themes rather than keeping it trapped inside repo boundaries.

What this gives me

With layered-memory, the unit of memory becomes the work itself. Not the repo. Not the folder. Not the current shell location. The work.

That means:

• a feature spanning three repos can have one coherent memory

• old debugging lessons can resurface in the right context

• related sessions can consolidate into a single theme

• memory can stay readable as markdown

• context stays lean because only the relevant theme is loaded

It does not replace Claude Code’s native memory.It adds another layer on top. That is why I called it layered-memory.

What is coming next

This is just the beginning. I have already hit and solved several issues while building layered-memory. Some are still open. Some I probably have not discovered yet.

The next entries will go issue by issue.

Not theory. Actual problems from the build: what broke, what I tried, what worked, what failed and how the system improved.

This first post is the map. The rest of the series is the build log.