DoclingDocument Builder API#

DoclingDocument can be constructed programmatically using a set of add_* and insert_* methods defined directly on the class, independent of the converter pipeline. The canonical implementation lives in docling_core/types/doc/document.py.

Initialization#

Construct an empty document with a name 1:

from docling_core.types import DoclingDocument
doc = DoclingDocument(name="My Document")

Optionally add page metadata with add_page(page_no, size, image) 2.

add_* Builder Methods#

All add_* methods append to the appropriate flat list (texts, tables, pictures, groups, etc.), assign a JSON Pointer self_ref, and wire up parent–child links automatically. The parent parameter defaults to doc.body when omitted.

Provenance is attached by passing a ProvenanceItem — a (page_no, bbox, charspan) tuple — to the prov parameter. Formatting (bold, italic, underline, strikethrough, script) is controlled by a Formatting instance.

A complete, annotated construction example (nested lists, tables with captions, pictures with ImageRef, inline groups, key-value graphs, rich formatting) is in test/conftest.py.

Sibling-Relative Insertion (insert_* Methods)#

For inserting at a specific position rather than appending, a parallel set of insert_* methods accepts a sibling node and an after: bool flag 3:

• insert_list_group(sibling, name, after=True)
• insert_list_item(sibling, text, enumerated, after=True)
• insert_inline_group(sibling, name, after=True)
• insert_group(sibling, label, name, after=True)
• insert_text(sibling, label, text, after=True)

Building Tables#

Construct TableData from TableCell objects, then pass to add_table 4. For tables with rich (structured) cells, use RichTableCell (which holds a ref to another document item) and register via add_table_cell(table_item, cell) 5. TableData also exposes convenience methods add_row, insert_row, and remove_row for post-construction edits 6.

Importing from DocTags Format#

DocTags is an XML-like token format emitted by vision models (e.g. SmolDocling). To import it:

1. Build a DocTagsDocument — either from per-page (tokens_str, PIL.Image) pairs via DocTagsDocument.from_doctags_and_image_pairs, or from a multipage string with <page_break> separators via from_multipage_doctags_and_images.
2. Convert to a DoclingDocument with the static method DoclingDocument.load_from_doctags(doctag_document, document_name).

The parser maps DocTags XML tags to DocItemLabel values 7, extracts <loc_N> bounding boxes (normalised by /500), and calls the same add_* builder methods internally. Supported tags include title, section_header_level_[1-6], text, otsl (table), picture, list_item, ordered_list, unordered_list, caption, footnote, code, formula, key_value_region, page_header, page_footer, and inline.

To round-trip back to DocTags, use export_to_doctags() / save_as_doctags().

Document-Level Utilities#

• Merge documents: DoclingDocument.concatenate(docs) — merges multiple documents, re-numbering pages and re-assigning refs.
• Filter by page: doc.filter(page_nrs={1, 2})
• Hierarchize headings: doc._hierarchize() restructures flat body items into heading-based subtrees 8.
• Delete items: doc.delete_items(node_items=[...]) removes items and heals all cross-references.

Key Source Files#