feat(cli): add --page-break-placeholder option for Markdown and Text exports

[Krishnachaitanyakc]

Summary

• Adds a new --page-break-placeholder CLI option to the convert command, exposing the existing page_break_placeholder parameter from DoclingDocument.save_as_markdown() to CLI users.
• When set, the specified string (e.g., ---, <!-- page-break -->) is inserted between pages in Markdown and Text exports.
• Includes a test for the new CLI option.

Closes #3175

Details

The Python API already supports page_break_placeholder in save_as_markdown() / export_to_markdown(), but the CLI did not expose this parameter. This change threads the option through:

1. A new --page-break-placeholder typer option on the convert command (default: None, preserving current behavior)
2. The export_documents helper function
3. Both save_as_markdown call sites (Markdown export and Text export)

Usage

docling my_document.pdf --to md --page-break-placeholder "---"
docling my_document.pdf --to md --page-break-placeholder "<!-- page-break -->"

Test plan

• Added test_cli_page_break_placeholder test that verifies the CLI accepts the option and produces output
• Existing test_cli_convert continues to pass (no regression without the flag)
• Default behavior (no --page-break-placeholder) is unchanged since the default is None

[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)(?:\(.+\))?(!)?:

[dosubot]

Related Documentation

1 document(s) may need updating based on files changed in this PR:

Docling

Content Layers

View Suggested Changes

@@ -109,6 +109,15 @@
 
 Currently, the ability to include furniture in exports is only available via the Python API. The `docling-serve` API and CLI exports do not support specifying content layers and will always export with the default (BODY only).
 
+However, the CLI does support the `page_break_placeholder` parameter for Markdown and Text exports. You can specify a custom page break placeholder string when using the `docling convert` command with the `--page-break-placeholder` option:
+
+```bash
+docling my_document.pdf --to md --page-break-placeholder "---"
+docling my_document.pdf --to txt --page-break-placeholder "<!-- page-break -->"
+```
+
+When set, the specified string is inserted between pages in the output, allowing CLI users to control page break formatting in both Markdown and Text exports.
+
 ## Customization and Post-processing
 
 Headers and footers are detected automatically by Docling’s layout model for `.docx` files. There is currently no rule-based mechanism to customize their detection during processing. However, you can manually remove or further process these elements after extraction if needed.

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[dolfim-ibm]

lgtm

[github-actions]

✅ DCO Check Passed

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

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/cli/main.py	88.88%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[dolfim-ibm]

@Krishnachaitanyakc Please follow the steps in #3184 (comment) to make sure your contribution is signed-off.

[smorand]

Great feature! One enhancement that could be valuable: supporting dynamic page numbers in the placeholder string via {prev_page} and {next_page} format variables.

Currently, the placeholder is static (the same string is inserted at every page break). But a common use case is annotating pages with their actual number, e.g.:

docling --to md --page-break-placeholder '---\n*[Page {next_page}]*\n---' input.pdf

Which would produce:

... content from page 1 ...

---
*[Page 2]*
---

... content from page 2 ...

The docling-core serializer internally tracks page numbers in its markers (#_#_DOCLING_DOC_PAGE_BREAK_{prev}_{next}_#_#) but discards them during replacement. This could be handled in the CLI layer with a small helper that uses a sentinel placeholder, then post-processes the output to format each break with the correct page numbers from the document's page list.

I propose a patch file attached.
0001-feat-cli-add-prev_page-and-next_page-format-variable.patch

[smorand]

Hi @Krishnachaitanyakc,

I see you've made the modifications, that's really nice.

One comment on my side: you use sequential counting instead of doc.pages. The point here, if you have a blank page then you will have wrong number.

If you have a 5-pages document with a blank page in the middle, as the serializer only inserts a page break sentinel when there is content you will get:
1, 2, 3, 4
instead of
1, 2, 3, 5

Proposed patch:
fix-dynamic-page-break-numbering.patch

Best regards and thank again for the reactivity.

[Krishnachaitanyakc]

@smorand Thanks for the review and the great catch on blank page numbering.

One note: rather than using doc.pages (which includes all pages the backend parsed, including blank ones), I'm using doc.iterate_items() to extract page numbers from item provenance.

[smorand]

Pull, reviewed and tested, good to me. Thanks to you @Krishnachaitanyakc, because I was going to work and propose this feature, you save me time!

[cau-git]

@Krishnachaitanyakc From a functional perspective this looks useful, however we can not accept this approach. It is doing more than just threading through an option to the CLI. It actually patches the exported markdown after the production with the dynamic markers. If we want to support such behaviour it must be done with an actual change to the MarkdownSerializer in docling-core. Please let us know if you want to make a companion PR on docling-core on which this PR could depend after the appropriate changes.

[cau-git]

Closing because of inactivity, please re-open if you intend to address the feedback.