docling-project / docling-project/docling-parse

Expose target page indices in table-of-contents bookmarks

Open
#340 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.