fix: restore floating-item footnotes in markdown/html exports

Signed-off-by: Hassan Raza <raihassanraza10@gmail.com>

Author: M-Hassan-Raza

docling_core/transforms/chunker/hierarchical_chunker.py

@@ -100,6 +100,13 @@ def serialize(
                     table_text = ". ".join(table_text_parts)
                     parts.append(create_ser_result(text=table_text, span_source=item))
 
+        ftn_res = doc_serializer.serialize_footnotes(
+            item=item,
+            **kwargs,
+        )
+        if ftn_res.text:
+            parts.append(ftn_res)
+
         text_res = "\n\n".join([r.text for r in parts])
 
         return create_ser_result(text=text_res, span_source=parts)

docling_core/transforms/serializer/common.py

@@ -316,6 +316,29 @@ def get_excluded_refs(self, **kwargs: Any) -> set[str]:
             self._excluded_refs_cache[params_json] = refs
         return refs
 
+    def _serialize_referenced_text_items(
+        self,
+        refs: Iterable[Any],
+        **kwargs: Any,
+    ) -> list[SerializationResult]:
+        """Serialize referenced text items while bypassing the top-level skip path."""
+        excluded_refs = self.get_excluded_refs(**kwargs)
+        results: list[SerializationResult] = []
+
+        for ref in refs:
+            if isinstance(it := ref.resolve(self.doc), TextItem) and it.self_ref not in excluded_refs:
+                results.append(
+                    self.text_serializer.serialize(
+                        item=it,
+                        doc_serializer=self,
+                        doc=self.doc,
+                        is_inline_scope=True,
+                        **kwargs,
+                    )
+                )
+
+        return results
+
     @abstractmethod
     def serialize_doc(
         self,
@@ -621,18 +644,12 @@ def serialize_footnotes(
     ) -> SerializationResult:
         """Serialize the item's footnotes."""
         params = self.params.merge_with_patch(patch=kwargs)
-        results: list[SerializationResult] = []
         if DocItemLabel.FOOTNOTE in params.labels:
-            results = [
-                create_ser_result(text=it.text, span_source=it)
-                for ftn in item.footnotes
-                if isinstance(it := ftn.resolve(self.doc), TextItem)
-                and it.self_ref not in self.get_excluded_refs(**kwargs)
-            ]
+            results = self._serialize_referenced_text_items(item.footnotes, **kwargs)
             # FIXME: using the caption_delimiter for now ...
             text_res = params.caption_delim.join([r.text for r in results])
-            text_res = self.post_process(text=text_res)
         else:
+            results = []
             text_res = ""
         return create_ser_result(text=text_res, span_source=results)
 

docling_core/transforms/serializer/html.py

@@ -363,10 +363,10 @@ def serialize(
         **kwargs: Any,
     ) -> SerializationResult:
         """Serializes the passed table item to HTML."""
-        res_parts: list[SerializationResult] = []
+        table_parts: list[SerializationResult] = []
         cap_res = doc_serializer.serialize_captions(item=item, tag="caption", **kwargs)
         if cap_res.text:
-            res_parts.append(cap_res)
+            table_parts.append(cap_res)
 
         if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
             body = ""
@@ -416,10 +416,18 @@ def serialize(
 
             if body:
                 body = f"<tbody>{body}</tbody>"
-                res_parts.append(create_ser_result(text=body, span_source=span_source))
+                table_parts.append(create_ser_result(text=body, span_source=span_source))
+
+        res_parts: list[SerializationResult] = []
+        if table_parts:
+            table_text = "".join([r.text for r in table_parts])
+            res_parts.append(create_ser_result(text=f"<table>{table_text}</table>", span_source=table_parts))
+
+        ftn_res = doc_serializer.serialize_footnotes(item=item, **kwargs)
+        if ftn_res.text:
+            res_parts.append(ftn_res)
 
         text_res = "".join([r.text for r in res_parts])
-        text_res = f"<table>{text_res}</table>" if text_res else ""
 
         return create_ser_result(text=text_res, span_source=res_parts)
 
@@ -610,6 +618,10 @@ def get_img_row(imgb64: str, ind: int) -> str:
                 details_html = f"<details><summary>Meta</summary>{meta_res.text}</details>"
                 res_parts.append(create_ser_result(text=details_html, span_source=[meta_res]))
 
+        ftn_res = doc_serializer.serialize_footnotes(item=item, **kwargs)
+        if ftn_res.text:
+            res_parts.append(ftn_res)
+
         text_res = "".join([r.text for r in res_parts])
         if text_res:
             text_res = f"<figure>{text_res}</figure>"
@@ -1210,6 +1222,47 @@ def serialize_captions(
             text_res = f"<{tag}>{text_res}</{tag}>"
         return create_ser_result(text=text_res, span_source=results)
 
+    @override
+    def serialize_footnotes(
+        self,
+        item: FloatingItem,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize the item's footnotes."""
+        params = self.params.merge_with_patch(patch=kwargs)
+        if DocItemLabel.FOOTNOTE not in params.labels:
+            return create_ser_result()
+
+        raw_results = self._serialize_referenced_text_items(item.footnotes, **kwargs)
+        if not raw_results:
+            return create_ser_result()
+
+        results: list[SerializationResult] = []
+        for idx, ser_res in enumerate(raw_results):
+            dir_str = ""
+            if ser_res.spans and isinstance(ser_res.spans[0].item, TextItem):
+                text_dir = get_text_direction(ser_res.spans[0].item.text)
+                dir_str = f' dir="{text_dir}"' if text_dir == "rtl" else ""
+
+            margin_top = "0" if idx == 0 else "0.35em"
+            results.append(
+                create_ser_result(
+                    text=(
+                        f'<div class="footnote"{dir_str} style="margin-top: {margin_top};">{ser_res.text}</div>'
+                    ),
+                    span_source=[ser_res],
+                )
+            )
+
+        text_res = "".join([r.text for r in results])
+        text_res = (
+            '<div class="footnotes" role="note" '
+            'style="margin-top: 0.65em; padding-top: 0.45em; border-top: 1px solid #ddd; '
+            'color: #666; font-size: 0.95em; line-height: 1.5; text-align: left;">'
+            f"{text_res}</div>"
+        )
+        return create_ser_result(text=text_res, span_source=results)
+
     def _generate_head(self) -> str:
         """Generate the HTML head section with metadata and styles."""
         params = self.params

docling_core/transforms/serializer/markdown.py

@@ -561,6 +561,13 @@ def serialize(
             if table_text:
                 res_parts.append(create_ser_result(text=table_text, span_source=item))
 
+        ftn_res = doc_serializer.serialize_footnotes(
+            item=item,
+            **kwargs,
+        )
+        if ftn_res.text:
+            res_parts.append(ftn_res)
+
         text_res = "\n\n".join([r.text for r in res_parts])
 
         return create_ser_result(text=text_res, span_source=res_parts)
@@ -621,6 +628,14 @@ def serialize(
                 md_table_content = temp_table.export_to_markdown(temp_doc)
                 if len(md_table_content) > 0:
                     res_parts.append(create_ser_result(text=md_table_content, span_source=item))
+
+        ftn_res = doc_serializer.serialize_footnotes(
+            item=item,
+            **kwargs,
+        )
+        if ftn_res.text:
+            res_parts.append(ftn_res)
+
         text_res = "\n\n".join([r.text for r in res_parts if r.text])
 
         return create_ser_result(text=text_res, span_source=res_parts)
@@ -911,6 +926,21 @@ def post_process(
         )
         return res
 
+    @override
+    def serialize_footnotes(
+        self,
+        item: FloatingItem,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize footnotes as separate Markdown blocks."""
+        params = self.params.merge_with_patch(patch=kwargs)
+        if DocItemLabel.FOOTNOTE not in params.labels:
+            return create_ser_result()
+
+        results = self._serialize_referenced_text_items(item.footnotes, **kwargs)
+        text_res = "\n\n".join([r.text for r in results])
+        return create_ser_result(text=text_res, span_source=results)
+
     @override
     def serialize_doc(
         self,

test/test_hierarchical_chunker.py

@@ -180,6 +180,31 @@ def test_triplet_table_serializer_single_column():
     expected = "Country = Italy. Country = Canada. Country = Switzerland"
     assert result.text == expected, f"Expected '{expected}', got '{result.text}'"
 
+
+def test_triplet_table_serializer_includes_footnotes():
+    """Regression: table footnotes must be preserved in chunking serialization."""
+
+    doc = DoclingDocument(name="table_footnotes")
+    table_data = TableData(num_cols=1)
+    table_data.add_row(["Country"])
+    table_data.add_row(["Italy"])
+    doc.add_table(data=table_data)
+
+    table_item = next(iter(doc.iterate_items()))[0]
+    footnote = doc.add_text(label=DocItemLabel.FOOTNOTE, text="Country footnote")
+    table_item.footnotes.append(footnote.get_ref())
+
+    serializer = ChunkingDocSerializer(doc=doc)
+    result = TripletTableSerializer().serialize(
+        item=table_item,
+        doc_serializer=serializer,
+        doc=doc,
+    )
+
+    assert result.text == "Country = Italy\n\nCountry footnote"
+    assert result.text.count("Country footnote") == 1
+
+
 def test_chunk_rich_table_custom_serializer(rich_table_doc: DoclingDocument):
     doc = rich_table_doc