fix: add failed pages to DoclingDocument for page break consistency

[jhchoi1182]

Description

When some PDF pages fail to parse, they were not added to DoclingDocument.pages, causing page break markers to be incorrect during export.

This PR adds failed/skipped pages with their size info (if available from the backend) to maintain correct page numbering and structure in the final document.

Changes

• Added _add_failed_pages_to_document() method in StandardPdfPipeline
• Failed pages are now added to DoclingDocument.pages with:
  • Page number (page_no)
  • Size information (retrieved from backend if possible, otherwise defaults to 0.0 x 0.0)
  • No content (empty PageItem)
• This ensures export functions generate correct <page_break> markers even when some pages fail

Related Issue

This change is required to properly support the page break marker fix in docling-core:

• Export functions fail to generate <page_break> tags for non-consecutive (skipped) pages docling-core#472
• fix: generate page_break for skipped pages in export functions docling-core#466

Without this fix, DoclingDocument.pages would be missing failed pages, causing the page break logic in docling-core to produce incorrect results.

---

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

[github-actions]

✅ DCO Check Passed

Thanks @jhchoi1182, all your commits are properly signed off. 🎉

[dosubot]

Related Documentation

Checked 14 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

🟢 Require two reviewer for test updates

Wonderful, this rule succeeded.

When test data is updated, we require two reviewers

• #approved-reviews-by >= 2

[Copilot]

Pull request overview

Ensures PDFs with skipped/failed pages still preserve correct page numbering in DoclingDocument.pages, so downstream exports can emit consistent page-break markers.

Changes:

• Add _add_failed_pages_to_document() to StandardPdfPipeline to insert placeholder PageItems for missing pages (with best-effort size info).
• Invoke the new helper during document assembly to backfill missing page entries.
• Add pytest coverage validating page presence and size info for skipped-page PDFs.

Reviewed changes

Copilot reviewed 2 out of 5 changed files in this pull request and generated 3 comments.

File	Description
docling/pipeline/standard_pdf_pipeline.py	Adds logic to backfill missing/failed pages into DoclingDocument.pages and updates some typing annotations.
tests/test_failed_pages.py	Adds tests asserting failed/skipped pages are still represented in DoclingDocument.pages with size info.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 84.37500% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/pipeline/standard_pdf_pipeline.py	84.37%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

[jhchoi1182]

Hi @cau-git, just checking in on this PR. Is there anything else needed from my end to move this forward? Let me know if you need any changes.

[cau-git]

@jhchoi1182 Thanks for this contribution! Your changes pass tests and look legitimate.

[PeterStaar-IBM]

🎖️

[jhchoi1182]

Hi @PeterStaar-IBM @cau-git, apologies for the dismissal. I just pushed a small fix to the test case (checking for PARTIAL status) based on feedback. Could you please take a quick look again?

[jhchoi1182]

The test-pip-install-no-lock failure on Python 3.11 appears to be a dependency resolution issue — openai-whisper v20250625 resolves to numba==0.63.1 (with llvmlite==0.46.0) on Python 3.10, but to numba==0.53.1 (with llvmlite==0.36.0, which only supports Python <3.10) on Python 3.11.
Let me know if there's anything I should do on my end.

[cau-git]

@jhchoi1182 thanks for the updates. Could you please rebase to main once more, it brings the fix for the test-pip-install-no-lock in.

[jhchoi1182]

@cau-git
Done, rebased onto the latest main!

[dolfim-ibm]

lgtm