Document Tree Traversal#

Overview#

DoclingDocument.iterate_items() is the primary API for depth-first traversal of the document element tree. It yields (NodeItem, int) tuples — the node and its nesting level — and accepts filters for content layers, item types, and page scope.

Source: iterate_items() definition in docling_core/types/doc/document.py. The public method delegates all heavy lifting to _iterate_items_with_stack().

Method Signature#

def iterate_items(
    self,
    root: Optional[NodeItem] = None,
    with_groups: bool = False,
    traverse_pictures: bool = False,
    page_no: Optional[int] = None,
    included_content_layers: Optional[set[ContentLayer]] = None,
    _level: int = 0, # deprecated
) -> Iterable[tuple[NodeItem, int]]:

1

Parameters#

How Traversal Works#

_iterate_items_with_stack() performs an iterative depth-first walk starting at root (defaults to self.body) 2. For each node, it evaluates three conditions before yielding 3:

1. Type gate — skip GroupItem unless with_groups=True
2. Page gate — skip DocItem nodes whose prov list doesn't contain page_no (when set)
3. Layer gate — skip nodes whose content_layer is not in included_content_layers (or DEFAULT_CONTENT_LAYERS)

Children are resolved via RefItem.resolve(doc) and recursed 4. When traverse_pictures=False (the default), children of a PictureItem that are not captions are skipped 5.

The yielded int level equals len(stack) at the point of yield — the stack tracks child indices, not depth explicitly 6.

Content Layers#

ContentLayer controls which functional layer an item belongs to 7:

DEFAULT_CONTENT_LAYERS = {ContentLayer.BODY} means furniture, notes, and other layers are silently excluded unless explicitly requested. To include them:

from docling_core.types.doc import ContentLayer

# Include headers and footers in iteration
for item, level in doc.iterate_items(
    included_content_layers={ContentLayer.BODY, ContentLayer.FURNITURE}
):
    ...

To get everything: included_content_layers=set(ContentLayer) — this is the pattern used by print_element_tree() and export_to_element_tree().

Key Usage Patterns#

Basic iteration (leaf content nodes only):

for item, level in doc.iterate_items():
    ...

8

Including group container nodes:

for item, level in doc.iterate_items(with_groups=True):
    if isinstance(item, GroupItem):
        ...

OCR text in scanned PDFs — OCR text is stored as children of PictureItem; you must opt in with traverse_pictures=True 9:

for item, level in doc.iterate_items(traverse_pictures=True):
    ...

Single-page extraction:

for item, level in doc.iterate_items(page_no=3):
    ...

Custom root — traverse a subtree rooted at any NodeItem:

for item, level in doc.iterate_items(root=some_section_node):
    ...

Downstream Consumers#

iterate_items() is the backbone for all export methods. They all accept the same filtering parameters and thread them through to the traversal:

• export_to_markdown() — via internal calls
• export_to_html(), export_to_text() — same pattern 7
• print_element_tree() / export_to_element_tree() — use with_groups=True, traverse_pictures=True, included_content_layers=set(ContentLayer) to dump the full tree

Key Source References#