Markdown Export Configuration#

Docling's markdown export pipeline converts a parsed DoclingDocument to a Markdown string. The main entry points are DoclingDocument.export_to_markdown() and DoclingDocument.save_as_markdown(). Both delegate to MarkdownDocSerializer, which orchestrates format-specific sub-serializers for text, tables, pictures, lists, and code blocks.

All configuration is captured in MarkdownParams, a Pydantic model that extends CommonParams. MarkdownParams is constructed from the keyword arguments of export_to_markdown() and threaded through the serializer hierarchy.

MarkdownParams Reference#

MarkdownParams defines all tunable fields for the serializer. Key fields:

The pages field comes from the parent CommonParams class and gates serialization: any item whose provenance page number is not in the set is added to the excluded-refs list by get_excluded_refs().

Page Breaks#

When page_break_placeholder is set to any non-None string, requires_page_break() returns True. During document iteration, the base DocSerializer.get_parts() calls _iterate_items() with add_page_breaks=True, which inserts _PageBreakNode objects at page transitions 4. These produce internal tokens matching the pattern #_#_DOCLING_DOC_PAGE_BREAK_{prev}_{next}_#_#.

In MarkdownDocSerializer.serialize_doc(), after concatenating all parts, every internal token is replaced with the caller-supplied page_break_placeholder string (or "" if the field is set but empty). Setting page_break_placeholder=None (the default) suppresses the entire mechanism — no tokens are generated and no replacements are made.

Summary of values:

Page Filtering#

Single-page export is exposed via the page_no parameter on export_to_markdown() and save_as_markdown(). Internally, page_no is converted to a one-element set and passed as MarkdownParams.pages 5.

For multi-page subsets, construct a MarkdownDocSerializer directly and pass pages={1, 3, 5} inside MarkdownParams.

Element-level filtering (first/last item index) is handled by start_idx / stop_idx in CommonParams, which correspond to the from_element / to_element arguments of export_to_markdown() 6.

Usage in docling-serve and docling-jobkit#

In docling-serve, markdown export is configured through ConvertDocumentsOptions. The markdown-specific field is:

The empty-string default means no break is shown unless the caller sets a non-empty value. Downstream, the value is coerced with or None before being forwarded to export_to_markdown(), which aligns with the None-means-disabled semantics of MarkdownParams.page_break_placeholder.

docling-serve does not call export_to_markdown() directly. Conversion tasks are delegated to workers via the orchestrator (Ray / RQ / Local). The actual export is performed by docling-jobkit:

• results.py → _export_document_as_content() calls export_to_markdown(image_mode=…, page_break_placeholder=md_page_break_placeholder or None) for in-memory results.
• export.py → _materialize_document_exports() calls save_as_markdown(…, page_break_placeholder=md_page_break_placeholder or None) when writing files.

The page_range field in ConvertDocumentsOptions 8 controls which pages are processed during conversion (a pipeline-level filter), not which pages appear in the markdown output. To filter at serialization time, use page_no / MarkdownParams.pages.

Key Source References#