docling-project/docling

Add_node_items doesn't update caption reference

Open

#2298 opened on Sep 22, 2025

View on GitHub
 (4 comments) (0 reactions) (1 assignee)Python (59,751 stars) (4,140 forks)batch import
bugdocling-documentgood first issue

Description

Bug

DoclingDocument's add_node_items doesn't update caption reference.

Steps to reproduce

convert a document:

source = "https://arxiv.org/pdf/2408.09869"  # document per local path or URL
converter = DocumentConverter()
result = converter.convert(source)

create a new one, only from the first table:

new_document = DoclingDocument(name="Table0")

new_document.add_node_items(doc=document, 
                            parent=new_document.body, 
                            node_items=[document.tables[0]])

The caption's text reference remains '#/texts/72' instead of '#/texts/0'

  "tables": [
    {
      "self_ref": "#/tables/0",
      "parent": {
        "cref": "#/body"
      },
      "children": [
        {
          "cref": "#/texts/0"
        }
      ],
      "content_layer": "body",
      "label": "table",
      "prov": [
        {
          "page_no": 5,
          "bbox": {
            "l": 133.27708435058594,
            "t": 634.9401245117188,
            "r": 478.2610168457031,
            "b": 542.4001007080078,
            "coord_origin": "BOTTOMLEFT"
          },
          "charspan": [
            0,
            0
          ]
        }
      ],
      "captions": [
        {
          "cref": "#/texts/72"
        }
      ],

Docling version

2.53.0

Python version

3.12

Contributor guide

Tech stack
python
Domain
backend
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
basic Pythonunderstanding of Docling's document model
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
50
Research direction
Investigate the `add node items` method in the `DoclingDocument` class, likely in `docling/document.py`. The issue shows that caption references (e.g., `#/texts/72`) are not updated to reflect the new document's numbering after adding items. Look for where `self ref` and `cref` are assigned and ensure that caption references are remapped when items are added to a new parent. Check if similar logic exists for other reference updates (e.g., children) and extend it to captions.