Seeing what Docling saw

Exported Markdown is what the document looks like. iterate_items is what it is, and it is the tool to reach for every time the output surprises you.

A converted document is a tree of pieces. iterate_items walks that tree in reading order and hands you each piece with how deeply it is nested.

from docling.document_converter import DocumentConverter

document = DocumentConverter().convert("shipping.md").document
for item, depth in document.iterate_items():
    print(depth, item.self_ref, item.label)

Six pieces. Four sit at depth one and two at depth two, because the two list items live inside a list. self_ref is that piece's address inside the document and label is what Docling decided it was; both get a lesson of their own, in 5 and 6.

Adding the text

for item, depth in document.iterate_items():
    print(depth, item.label, "|", item.text[:40])

Now the shape and the words are side by side. Shipping came out as a title and the two lower headings as section headers, which is Docling reading the hash count rather than guessing.

Use it on the file that surprised you

Run the same loop on the HTML file and the table appears as a single piece.

html = DocumentConverter().convert("refunds.html").document
for item, depth in html.iterate_items():
    print(depth, item.self_ref, item.label)

One entry for the whole table, at #/tables/0, and no entry for any of its rows. A table is a piece with a grid inside it rather than a pile of text pieces, which is why lesson 8 can hand it straight to pandas. The depths also differ from the Markdown file: this backend nests everything under the title, so the table sits three levels down.

Where a piece is not

The loop does not show #/groups/0, the list that holds the two list items. Groups are containers rather than content, so they are skipped here and reached through the tree in lesson 7.