docling-project / docling-project/docling-parse
Expose target page indices in table-of-contents bookmarks
- Dominant language
- C++
- Stars
- 333
- Forks
- 80
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 10
Description
## Summary
The table-of-contents APIs exposed by `docling-parse` do not preserve the target page for each bookmark. Consumers therefore cannot constrain bookmark resolution to headings on the intended page.
## Current behavior
Both `docling_parser` and `docling_threaded_parser` return ToC entries with title/level information but without the bookmark destination page index.
Downstream code must either:
- match each bookmark against heading candidates from every page, which is unnecessarily expensive; or
- use a separate PDF library to read outline destinations.
The latter is undesirable because it expands the PDFium/pypdfium integration surface in downstream backends.
## Expected behavior
Extend the native ToC result from both parser backends so every bookmark can carry its zero-based target page index when one is available.
The API should preserve existing behavior for bookmarks whose destinations cannot be resolved.
## Why this matters
Page-aware bookmark matching:
- prevents matching a bookmark to a similarly named heading on an unrelated page;
- reduces candidate matching from document-wide to page-local;
- lets Docling consume native `docling-parse` ToC data without separately
querying PDFium.
## Scope
- Update both `docling_parser` and `docling_threaded_parser`.
- Keep their ToC schemas/semantics aligned.
- Add regression tests for direct page destinations and nested outlines.
- Consider resolving named destinations where supported.
## Related context
- https://github.com/docling-project/docling/pull/4169
- https://github.com/docling-project/docling/pull/4169#issuecomment-5538190417
Contributor guide
Research direction
Start with the ToC entry points in docling_parser and docling_threaded_parser, then trace how outline destinations are currently read and represented. Add regression coverage for direct page destinations and nested outlines, including unresolved destinations, and verify both backends expose aligned zero-based page indices.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100