docling-project / docling-project/docling
Feature Request: Spatial Ordering Option for Markdown Export
- Dominant language
- Python
- Stars
- 66.4k
- Forks
- 4.8k
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 84
Description
# Feature Request: Spatial Ordering Option for Markdown Export
## Problem
For scanned PDFs (pure images), Docling uses OCR engine return order for `body.children`, which doesn't guarantee spatial/reading order. This causes elements to appear in incorrect order in markdown export (e.g., title appearing after introduction).
## Current Behavior
- Docling uses OCR return order directly for `body.children`
- No spatial reordering is performed
- For scanned documents, this often results in incorrect reading order
## Proposed Solution
Add a configuration option to enable spatial reordering based on bounding box coordinates:
### Option 1: Pipeline Option
```python
pipeline_options = PdfPipelineOptions(
ocr_options=TesseractOcrOptions(...),
# New option
spatial_ordering=True, # Reorder elements by (page, Y, X) before building body
)
```
### Option 2: Export Option
```python
markdown = doc.export_to_markdown(
spatial_ordering=True, # Reorder body.children by spatial position
...
)
```
### Option 3: Both
- Pipeline option: Reorder during document building (affects all exports)
- Export option: Reorder only for this export (more flexible)
## Implementation Details
1. **Use existing data**: `prov.bbox` already contains spatial coordinates
2. **Sort key**: `(page_no, -top_y, left_x)` for top-to-bottom, left-to-right
3. **Preserve nesting**: Only reorder top-level `body.children`, don't break nested structures
4. **Default**: `False` (backward compatible)
## Use Cases
- **Scanned academic papers**: Title/author should appear before introduction
- **Multi-column documents**: Proper reading order (top-to-bottom, left-to-right)
- **Documents with headers/footers**: Correct semantic ordering
## Trade-offs
### Pros
- Solves real problem for scanned documents
- Uses data already available (prov.bbox)
- Backward compatible (opt-in)
- Common use case
### Cons
- May break ordering for documents where OCR order is intentionally preserved
- Additional processing overhead (sorting)
- Need to handle edge cases (overlapping elements, nested structures)
## Alternative: Post-processing
Currently, users can implement this as post-processing (as we did in `fix_markdown_order.py`), but:
- Requires modifying `body.children` before export
- Not discoverable
- Users have to implement it themselves
## Recommendation
**Option 3 (Both)**:
- Pipeline option for documents where spatial order is always desired
- Export option for flexibility when order matters only for specific exports
This provides maximum flexibility while maintaining backward compatibility.
## Related Issues
- GitHub Issue #2245: "Header placed at the end of the page" (similar ordering issue)
Contributor guide
Assessment
This issue has not been assessed yet.