docling-project / docling-project/docling

Feature Request: Spatial Ordering Option for Markdown Export

Open
#2,683 3 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.