docling-project / docling-project/docling
Bold/monospace CLI command examples misclassified as Section-header instead of Code
- Dominant language
- Python
- Stars
- 66.4k
- Forks
- 4.8k
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 84
Description
### Bug
...
When a PDF renders a single-line CLI command example in bold/monospace styling (a common pattern in technical/operator manuals — an "Example" caption followed by one bold command line), Docling's layout model (docling-layout-heron) classifies the command line as Section-header (mapped to SectionHeaderItem, level: 1) instead of Code or Text. This is notable because Code already exists as a distinct class in the model's own label space (classes_map id 12, alongside Section-header id 7) — so this isn't a missing capability, it's a misclassification within an existing one.
The result corrupts document hierarchy for any downstream consumer that uses section_header/level to detect section boundaries: a bold command example gets treated as the start of a new top-level section, at the same level: 1 rank as real chapter headings, fragmenting it away from the surrounding procedural text that explains it.
### Steps to reproduce
...
Example
Source PDF (bold-styled single command line under an "Example" caption):
Example
create...
Expected DoclingDocument output:
json
{"label": "section_header", "text": "Example", "level": 1} {"label": "code", "text": "create..."}
(or at minimum "label": "text", not section_header)
Actual output (texts[] array):
json
{"label": "section_header", "text": "Example", "level": 1} {"label": "section_header", "text": "create...", "level": 1}
Same pattern recurs at multiple points in the same document — every misclassified entry is a bold, single-line CLI command, and nearly all sit immediately after a section_header node whose text is literally "Example".
Impact
For technical documentation that intersperses short CLI examples throughout procedures (common in telecom/networking/infra vendor manuals), this silently inflates the document's heading count and breaks any hierarchy-based chunking, navigation, or table-of-contents generation built on section_header/level.
Environment
· Docling version: 2.113.0
· Layout model: docling-layout-heron (default)
· Extraction path: standard PDF pipeline, DoclingDocument JSON export
Hypothesis on root cause
The Code class already exists in the layout model's label space, so this looks like a training-data distribution gap rather than an architectural limitation: the model may have been trained predominantly on multi-line, fenced/boxed code blocks (common in software documentation), and may underrepresent short, single-line, bold-styled CLI command patterns that appear inline in operator/procedural manuals. Worth checking whether single-line command examples are a systematically underrepresented sub-pattern within the Code class's training data.
Possible signal for a stopgap heuristic
Independent of a model retrain, a section_header node whose text matches a CLI-command-like pattern (e.g., ^\w+_\w+\s+-\w+) and whose immediately preceding sibling is a section_header with text "Example" is very likely a false positive — this could be used as a post-classification correction pass in the reading-order/assembly stage.
Minimal repro suggestion
A short PDF with an "Example" heading followed by a single bold, monospace-styled command line should reproduce this.
### Docling version
...
Docling version: 2.113.0
Layout model: docling-layout-heron (default)
Extraction path: standard PDF pipeline, DoclingDocument JSON export
### Python version
...
Python 3.11
<
!-- ⚠️ ATTENTION: When sharing screenshots, attachments, or other data make sure not to include any sensitive information. -->
Contributor guide
Research direction
Start by reproducing the issue through the standard PDF pipeline with docling-layout-heron and inspect the DoclingDocument JSON export for an “Example” heading followed by a bold, monospace command. Trace the reading-order or assembly stage where layout labels become section_header, code, or text. Done means the command is no longer emitted as a level-1 section_header while the “Example” heading remains one.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- machine-learning
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100