fix(html): prevent hierarchy reset in rich table cells (#2716)

Vdaleke · web-flow · commit aebe25cf0027 · 2025-12-03T18:52:23.000+01:00
* fix(html): restore parents after rich cell walking

Signed-off-by: Matvei Smirnov &lt;vdalekesmirnov@gmail.com&gt;

* fix(html): add table cell context manager, update tests

Signed-off-by: Matvei Smirnov &lt;vdalekesmirnov@gmail.com&gt;

* fix(html): table with heading test data

Signed-off-by: Matvei Smirnov &lt;vdalekesmirnov@gmail.com&gt;

---------

Signed-off-by: Matvei Smirnov &lt;vdalekesmirnov@gmail.com&gt;
diff --git a/docling/backend/html_backend.py b/docling/backend/html_backend.py
@@ -459,10 +459,8 @@ def parse_table_data(
                 rich_table_cell = self._is_rich_table_cell(html_cell)
                 if rich_table_cell:
                     # Parse table cell sub-tree for Rich Cells content:
-                    table_level = self.level
-                    provs_in_cell = self._walk(html_cell, doc)
-                    # After walking sub-tree in cell, restore previously set level
-                    self.level = table_level
+                    with self._use_table_cell_context():
+                        provs_in_cell = self._walk(html_cell, doc)
 
                     group_name = f"rich_cell_group_{len(doc.tables)}_{col_idx}_{start_row_span + row_idx}"
                     rich_table_cell, ref_for_rich_cell = (
@@ -829,6 +827,21 @@ def _use_footer(self, tag: Tag, doc: DoclingDocument):
             self.level -= 1
             self.content_layer = current_layer
 
+    @contextmanager
+    def _use_table_cell_context(self):
+        """Preserve the hierarchy level and parents during table cell processing.
+
+        While the context manager is active, the hierarchy level and parents can be modified.
+        When exiting, the original level and parents are restored.
+        """
+        original_level = self.level
+        original_parents = self.parents.copy()
+        try:
+            yield
+        finally:
+            self.level = original_level
+            self.parents = original_parents
+
     def _handle_heading(self, tag: Tag, doc: DoclingDocument) -> list[RefItem]:
         added_ref = []
         tag_name = tag.name.lower()
diff --git a/tests/data/groundtruth/docling_v2/example_01.html.json b/tests/data/groundtruth/docling_v2/example_01.html.json
@@ -1,10 +1,10 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_01",
   "origin": {
     "mimetype": "text/html",
-    "binary_hash": 13726679883013609282,
+    "binary_hash": 3245959421868226348,
     "filename": "example_01.html"
   },
   "furniture": {
diff --git a/tests/data/groundtruth/docling_v2/example_02.html.json b/tests/data/groundtruth/docling_v2/example_02.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_02",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/example_03.html.json b/tests/data/groundtruth/docling_v2/example_03.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_03",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/example_04.html.json b/tests/data/groundtruth/docling_v2/example_04.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_04",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/example_05.html.json b/tests/data/groundtruth/docling_v2/example_05.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_05",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/example_06.html.json b/tests/data/groundtruth/docling_v2/example_06.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_06",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/example_07.html.json b/tests/data/groundtruth/docling_v2/example_07.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_07",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/example_08.html.json b/tests/data/groundtruth/docling_v2/example_08.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "example_08",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/formatting.html.json b/tests/data/groundtruth/docling_v2/formatting.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "formatting",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/html_code_snippets.html.json b/tests/data/groundtruth/docling_v2/html_code_snippets.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "html_code_snippets",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/html_rich_table_cells.html.json b/tests/data/groundtruth/docling_v2/html_rich_table_cells.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "html_rich_table_cells",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/hyperlink_01.html.json b/tests/data/groundtruth/docling_v2/hyperlink_01.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "hyperlink_01",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/hyperlink_02.html.json b/tests/data/groundtruth/docling_v2/hyperlink_02.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "hyperlink_02",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/hyperlink_03.html.json b/tests/data/groundtruth/docling_v2/hyperlink_03.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "hyperlink_03",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/hyperlink_04.html.json b/tests/data/groundtruth/docling_v2/hyperlink_04.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "hyperlink_04",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/hyperlink_05.html.json b/tests/data/groundtruth/docling_v2/hyperlink_05.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "hyperlink_05",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/table_01.html.json b/tests/data/groundtruth/docling_v2/table_01.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "table_01",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/table_02.html.json b/tests/data/groundtruth/docling_v2/table_02.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "table_02",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/table_03.html.json b/tests/data/groundtruth/docling_v2/table_03.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "table_03",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/table_04.html.json b/tests/data/groundtruth/docling_v2/table_04.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "table_04",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/table_05.html.json b/tests/data/groundtruth/docling_v2/table_05.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "table_05",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/table_06.html.json b/tests/data/groundtruth/docling_v2/table_06.html.json
@@ -1,6 +1,6 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "name": "table_06",
   "origin": {
     "mimetype": "text/html",
diff --git a/tests/data/groundtruth/docling_v2/table_with_heading_01.html.itxt b/tests/data/groundtruth/docling_v2/table_with_heading_01.html.itxt
diff --git a/tests/data/groundtruth/docling_v2/table_with_heading_01.html.json b/tests/data/groundtruth/docling_v2/table_with_heading_01.html.json
@@ -1,11 +1,11 @@
 {
   "schema_name": "DoclingDocument",
-  "version": "1.7.0",
-  "name": "table_with_heading",
+  "version": "1.8.0",
+  "name": "table_with_heading_01",
   "origin": {
     "mimetype": "text/html",
     "binary_hash": 5578561753677933781,
-    "filename": "table_with_heading.html"
+    "filename": "table_with_heading_01.html"
   },
   "furniture": {
     "self_ref": "#/furniture",
diff --git a/tests/data/groundtruth/docling_v2/table_with_heading_01.html.md b/tests/data/groundtruth/docling_v2/table_with_heading_01.html.md
diff --git a/tests/data/groundtruth/docling_v2/table_with_heading_02.html.itxt b/tests/data/groundtruth/docling_v2/table_with_heading_02.html.itxt
@@ -0,0 +1,9 @@
+item-0 at level 0: unspecified: group _root_
+  item-1 at level 1: title: Main Title
+    item-2 at level 2: text: Before the table
+    item-3 at level 2: table with [2x2]
+      item-4 at level 3: unspecified: group rich_cell_group_1_0_0
+        item-5 at level 4: section_header: A
+        item-6 at level 4: text: text
+    item-7 at level 2: section_header: Section After
+      item-8 at level 3: text: After the table
diff --git a/tests/data/groundtruth/docling_v2/table_with_heading_02.html.json b/tests/data/groundtruth/docling_v2/table_with_heading_02.html.json
diff --git a/tests/data/groundtruth/docling_v2/table_with_heading_02.html.md b/tests/data/groundtruth/docling_v2/table_with_heading_02.html.md
diff --git a/tests/data/groundtruth/docling_v2/unit_test_01.html.json b/tests/data/groundtruth/docling_v2/unit_test_01.html.json
diff --git a/tests/data/groundtruth/docling_v2/wiki_duck.html.json b/tests/data/groundtruth/docling_v2/wiki_duck.html.json
diff --git a/tests/data/html/table_with_heading_01.html b/tests/data/html/table_with_heading_01.html
diff --git a/tests/data/html/table_with_heading_02.html b/tests/data/html/table_with_heading_02.html

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"schema_name": "DoclingDocument",`
`3`		`- "version": "1.7.0",`
	`3`	`+ "version": "1.8.0",`
`4`	`4`	`"name": "example_02",`
`5`	`5`	`"origin": {`
`6`	`6`	`"mimetype": "text/html",`