docling-project / docling-project/docling

PDF: hyphenated line wraps inside list items split into multiple items

Open
#3,881 2 comments 0 reactions 0 assignees View on GitHub
triage/close-fixed
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
3d 4h
Merged PRs (30d)
98

Description

### Bug

When a list item wraps across a line break at a hyphenated word (e.g. "algo-rithms"), docling splits it into two separate list items. The continuation fragment gets a new list-item number, corrupting the entire list numbering.

Example from a real PDF:
```
1. Digital Competence for Deep Learning - this step moves beyond mere computer literacy, demanding that students master data-interpretation skills, generate and critique artificial intelligence (AI) outputs, and understand the algo-
2. rithms embedded in clinical imaging devices;
3. Evidence-Based Practice with Quality Digital Resources - ...
4. Learning Environments with Applicable Digital Technology - ...
5. Synergy Between Human Teachers and Trustworthy AI - ...
```

Item "2. rithms" is a continuation of item 1 — "algorithms" was split across lines. This corrupts the numbering (should be 4 items, not 5).

### Steps to reproduce

```python
from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("fuerea_digital_transformation_2026.pdf")
md = result.document.export_to_markdown()

# The orphaned fragment appears in the output
assert "2. rithms" in md # Bug: continuation treated as new item
```

### Expected behavior

The hyphenated wrap should be detected and merged back into the parent list item. The word "algorithms" should appear complete, and the list should have exactly 4 items.

### Source location

`readingorder_model.py:363-412`: list items are emitted one-per-cluster. The merge machinery at `:414 _merge_elements` and `:457 predict_merges` exists, but only merges `TEXT` labels — `LIST_ITEM` is explicitly excluded at line 193. The wrap fragment gets a distinct cluster ID from the layout stage and never enters `el_merges_mapping`.

### Suggestion

Extend `predict_merges` to handle hyphenated wraps inside `LIST_ITEM` clusters. The heuristic: if a list item ends with `-` (or soft hyphen `\u00ad`) and the next list item starts with a lowercase letter, merge them. GROBID uses this exact rule.

### Docling version

2.115.0

### Regression test PDF

- `fuerea_digital_transformation_2026.pdf` (1.5 MB) — 2-column bilingual review paper, list items at lines 53-56 of the markdown output demonstrate the bug

Contributor guide

Open the contributing guide

Research direction

Start in readingorder_model.py:363-412, then inspect _merge_elements at :414 and predict_merges at :457, especially the LIST_ITEM exclusion at line 193. Reproduce with fuerea_digital_transformation_2026.pdf through DocumentConverter and compare exported Markdown. Done means the hyphenated continuation merges into its parent, algorithms is complete, and the output has four list items.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.