HTML Export Format

HTML Export Format#

Docling exports DoclingDocument objects to self-contained HTML via HTMLDocSerializer in docling_core/transforms/serializer/html.py. Two output styles are available, controlled by the HTMLOutputStyle enum:

SINGLE_COLUMN (default) — all content in a single scrollable <div class='page'>.
SPLIT_PAGE — each document page is rendered as a row in a <table>, with the original page image in the left <td> and the extracted content in the right <td>.

Entry Points#

Method	Location	Returns
`export_to_html()`	`DoclingDocument`	`str` (HTML)
`save_as_html()`	`DoclingDocument`	writes to file

Both accept identical parameters. save_as_html additionally takes filename and optional artifacts_dir.

# Return HTML string
html = doc.export_to_html()

# Split-page view (page images alongside content)
html = doc.export_to_html(split_page_view=True)

# Save to file
doc.save_as_html("output.html", split_page_view=True)

Key Parameters#

All parameters flow into HTMLParams :

Parameter	Default	Purpose
`split_page_view`	`False`	Enables `SPLIT_PAGE` output style
`image_mode`	`PLACEHOLDER`	How images are handled: `PLACEHOLDER`, `EMBEDDED` (base64), or `REFERENCED`
`formula_to_mathml`	`True`	Render LaTeX formulas as MathML
`page_no`	`None`	Export a single page only
`from_element` / `to_element`	`0` / `maxsize`	Slice document items by index
`labels`	all	Filter by `DocItemLabel`
`included_content_layers`	`BODY`	Content layers to include
`include_annotations`	`True`	Include item annotations
`enable_chart_tables`	`True`	Render chart data as HTML tables
`html_lang`	`"en"`	`lang` attribute on `<html>`
`html_head`	`None`	Override entire `<head>` block
`css_styles`	`None`	Override default CSS

Split-Page Rendering#

When split_page_view=True, serialize_doc orchestrates the two-column layout:

It calls requires_page_break() , which returns True for SPLIT_PAGE mode, enabling page break marker insertion during item iteration.
The serialized content stream contains inline markers of the form #_#_DOCLING_DOC_PAGE_BREAK_{prev}_{next}_#_# produced by _create_page_break in the base DocSerializer.
_get_page_breaks uses the regex r"#_#_DOCLING_DOC_PAGE_BREAK_(\d+)_(\d+)_#_#" to split the stream into per-page slices.
Each page slice is placed in a <td> next to the corresponding page image .

Page images are resolved in priority order: visualizer output → embedded base64 ImageRef → PIL image object → fallback placeholder .

The outer table uses _get_css_for_split_page() for styling: border-collapse: collapse, vertical-align: top cells, and a white .page div capped at max-width: 1000px.

Single-Column Rendering#

The default SINGLE_COLUMN style wraps all content in <div class='page'> with a centered, boxed layout via _get_css_for_single_column(). This style does not use page break markers.

Serializer Components#

HTMLDocSerializer composes format-specific sub-serializers for each content type :

Sub-serializer	Handles
`HTMLTextSerializer`	Headings, paragraphs, code, formulas, list items
`HTMLTableSerializer`	`<table>` with rowspan/colspan; supports `RichTableCell`
`HTMLPictureSerializer`	`<figure><img>` with EMBEDDED/REFERENCED image modes
`HTMLListSerializer`	`<ul>` / `<ol>` auto-detected from first item
`HTMLKeyValueSerializer`	`<dl>` or nested `<ul>` via `_HTMLGraphDataSerializer`
`HTMLMetaSerializer`	`<details class="docling-meta">` collapsible block

Formulas are converted from LaTeX to MathML via latex2mathml, with an image fallback when image_mode=EMBEDDED and no LaTeX text is available .

Source Files#

File	Purpose
`docling_core/transforms/serializer/html.py`	`HTMLDocSerializer`, `HTMLParams`, `HTMLOutputStyle`, all sub-serializers
`docling_core/transforms/serializer/html_styles.py`	CSS for `SPLIT_PAGE` and `SINGLE_COLUMN` modes
`docling_core/transforms/serializer/common.py`	`DocSerializer` base, `_create_page_break`, `_get_page_breaks`
`docling_core/types/doc/document.py`	`DoclingDocument.export_to_html`, `save_as_html`