Structure extraction → Headings hierarchy (breadcrumbs)
What it is
Authors organise documents with headings. The heading path above any paragraph tells you what the paragraph is about even when the paragraph itself uses pronouns and bare numbers. Parsers detect headings (font size/weight, numbering, layout-model section_header label, Markdown #, DOCX styles) and assign them a level. Walking the document while maintaining a heading stack gives each element its breadcrumb.
Uses:
- Prepend to chunk text before embedding → dense and BM25 retrieval both improve (cheap cousin of contextual retrieval, contextual retrieval).
- Chunk boundaries → structure-aware chunking cuts on headings (layout / structure-aware).
- Filters → "search only in section 'Definitions'" (self-query).
- Citations → "Handbook › Leave › Sick leave, p. 12" is what a user trusts (citations).
- Parent–child → the section under a heading is a natural parent (parent–child).
How to implement
- Detect headings with the parser's labels; supplement with heuristics on digital PDFs: relative font size (> body × 1.15), bold, numbering patterns (
^\d+(\.\d+)*\s), short line, whitespace above. - Assign levels: from Markdown/DOCX styles directly; from PDFs, cluster heading font sizes into levels (largest = h1), and/or parse numbering depth (
3.2.1→ level 3). - Maintain a stack while iterating elements in reading order (reading order): on heading level n, truncate the stack to n−1 and push. Each non-heading element gets
breadcrumb = " › ".join(stack). - Prepend document title (from metadata, first h1, or filename cleaned) as the root of every breadcrumb.
- Cap breadcrumb length (e.g. 4 levels / 120 tokens) — deep TOCs bloat chunks; keep the full path in metadata and a truncated version in text.
- Handle running headers (page-top repeated titles) — exclude from the stack (headers / footers / boilerplate stripping).
- Store
heading_path: list[str],heading_levels: list[int],section_id(hash of path) on each element/chunk.
Small example
import re
from collections import Counter
NUM = re.compile(r"^(\d+(?:\.\d+)*)[.)]?\s+\S")
def infer_levels(elements, body_size):
"""elements: [{type, text, font_size, bold}], from a digital parser. Returns list of (level|None)."""
sizes = sorted({round(e["font_size"], 1) for e in elements
if e["type"] == "heading" or (e["font_size"] > body_size * 1.15 and len(e["text"]) < 120)}, reverse=True)
size_level = {s: i + 1 for i, s in enumerate(sizes[:6])}
levels = []
for e in elements:
m = NUM.match(e["text"])
if m and len(e["text"]) < 120:
levels.append(min(m.group(1).count(".") + 1, 6)) # 3.2.1 → level 3
elif e["type"] == "heading" or round(e["font_size"], 1) in size_level:
levels.append(size_level.get(round(e["font_size"], 1), 2))
else:
levels.append(None)
return levels
def attach_breadcrumbs(elements, title, max_depth=4):
levels = infer_levels(elements, body_size=Counter(round(e["font_size"], 1) for e in elements).most_common(1)[0][0])
stack = []
for e, lvl in zip(elements, levels):
if lvl is not None:
stack = stack[: lvl - 1] + [e["text"].strip()]
e["type"], e["level"] = "heading", lvl
e["heading_path"] = [title] + stack
e["breadcrumb"] = " › ".join(([title] + stack)[-max_depth:])
return elements
Pros
- Deterministic and free — no LLM call; same input, same breadcrumb.
- Measurable retrieval lift on chunks with pronouns/numbers; improves BM25 as much as dense.
- Enables structure-aware chunking, section filters, parent–child, and trustworthy citations.
- Human-readable provenance.
Cons
- Heading detection errors: bold first sentences mistaken for headings, real headings missed on unusual templates, level inference wrong when fonts are inconsistent.
- Deep or noisy hierarchies (legal numbering to 6 levels, TOC pages) produce long breadcrumbs that cost tokens and dilute the chunk.
- Uninformative headings ("Section 4.2.1", "Overview") add little; contextual retrieval (contextual retrieval) is the complement.
- Cross-page state: a section that starts on a digital page and continues on a scanned page needs the stack carried across parsers (per-page classification and routing).
When to use
Always when the source has headings — Office docs, Markdown, HTML, structured PDFs. It's the default enrichment before any LLM-based one.
When NOT to use
- Sources without real headings (chat, email bodies, OCR'd letters): use title + source as the "breadcrumb" and rely on contextual retrieval if needed.
- Don't prepend breadcrumbs to display text — users see the original; breadcrumb belongs in the citation line.
Production at scale
Index text vs display text. text_indexed = breadcrumb + "\n" + text; text_display = text. Embeddings and BM25 use indexed; UI and citations use display + metadata (contextual retrieval makes the same split).
Level inference must be per document. Font sizes differ across templates; never use global thresholds. Cluster within the document. For OCR'd pages, use the layout model's title/section_header labels and numbering; font size from OCR is unreliable.
Numbering as ground truth. When present, numbering (1, 1.1, 1.1.1, Article 5, § 3.2) is the most reliable level signal; prefer it over font size. Build a per-corpus numbering regex library (legal, standards, and technical docs each have conventions).
Running headers/footers repeat the chapter title on every page; if they enter the stack they reset it on every page. Detect by frequency and position (headers / footers / boilerplate stripping) and exclude.
TOC and index pages are lists of headings; they produce garbage stacks. Detect (page with many short numbered lines and page numbers at the right margin) and skip for breadcrumb purposes (index them as their own element if at all).
Breadcrumb budget. Cap at ~4 levels and ~100 tokens in the indexed text; store the full path in metadata. Deep legal hierarchies otherwise put 300 tokens of path in front of a 200-token clause.
Section IDs for parent–child and filtering. section_id = sha256(doc_id + "/".join(heading_path)); stable across re-parses if headings don't change, which makes parents (parent–child) stable too.
Cross-parser stacks. When pages route to different parsers (per-page classification and routing), reassembly must carry the heading stack across page boundaries. Do breadcrumb assignment at reassembly, on the merged element stream, not inside each parser.
Monitoring. Per source: headings per document (0 is a regression), breadcrumb depth distribution, % elements with empty breadcrumb, heading-detection precision on the golden sample (test-time validation against a golden sample) on every parser upgrade.
Prod checklist
- Heading detection: parser labels + numbering + per-document font clustering
- Stack maintained in reading order at reassembly (cross-parser)
- Title as root; running headers and TOC pages excluded
- Breadcrumb capped in indexed text; full path in metadata
-
section_idstable hash for parents/filters - Indexed text (with breadcrumb) vs display text separated
- Heading precision/recall in the parsing golden eval
- Headings-per-doc and empty-breadcrumb dashboards per source
Metrics to watch
| Metric | Why |
|---|---|
| Headings per document by source | Detection regression |
| % chunks with empty breadcrumb | Coverage |
| Breadcrumb token p95 | Budget discipline |
| Heading precision/recall on golden sample | Parser upgrades |
| Recall@k lift with vs without breadcrumbs (A/B on golden set) | Prove the value |
Related
- Reading order — stack depends on it
- Boilerplate stripping — exclude running headers
- Layout-aware chunking, parent–child Parent–child — consumers
- Contextual retrieval — LLM complement for uninformative headings
- Citations