docling-core 2.97.2__tar.gz → 2.98.1__tar.gz

{docling_core-2.97.2 → docling_core-2.98.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-core
-Version: 2.97.2
+Version: 2.98.1
 Summary: A python library to define and validate data types in Docling.
 Author-email: Cesar Berrospi Ramis <ceb@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>
 Maintainer-email: Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>, Cesar Berrospi Ramis <ceb@zurich.ibm.com>

{docling_core-2.97.2 → docling_core-2.98.1}/docling_core/transforms/deserializer/doclang.py

@@ -353,11 +353,14 @@ class DocLangDocDeserializer(BaseDocDeserializer, BaseModel):
             # holding a picture or a table is not a float.
             if group_name := el.getAttribute(DocLangAttributeKey.NAME.value):
                 self._parse_named_group(doc=doc, el=el, parent=parent, name=group_name)
-            # Float + footnote siblings: parse as one unit (not a Docling GroupItem).
-            elif self._first_child(el, DocLangToken.TABLE.value) or self._first_child(el, DocLangToken.INDEX.value):
-                self._parse_table(doc=doc, el=el, parent=parent)
-            elif self._first_child(el, DocLangToken.PICTURE.value):
-                self._parse_picture(doc=doc, el=el, parent=parent)
+            # Float + satellites (extra captions, footnotes): parse as one unit (not a Docling GroupItem).
+            elif (host_el := self._float_group_host(el)) is not None:
+                if host_el.tagName == DocLangToken.PICTURE.value:
+                    self._parse_picture(doc=doc, el=el, parent=parent)
+                elif host_el.tagName == DocLangToken.CODE.value:
+                    self._parse_code_group(doc=doc, el=el, code_el=host_el, parent=parent)
+                else:
+                    self._parse_table(doc=doc, el=el, parent=parent)
             else:
                 self._walk_children(doc=doc, el=el, parent=parent)
         elif name in {DocLangToken.TABLE.value, DocLangToken.INDEX.value}:
@@ -482,6 +485,8 @@ class DocLangDocDeserializer(BaseDocDeserializer, BaseModel):
                 content_layer=content_layer,
             )
             self._apply_initial_text_provenance(item, text=code_text, prov_list=prov_list)
+            if (caption := self._extract_caption(doc=doc, el=el)) is not None:
+                item.captions.append(caption.get_ref())
             if thread_id:
                 self._register_thread(thread_id=thread_id, host=nm, item=item)
             self._apply_custom_meta_from_element(item=item, el=el)
@@ -606,6 +611,7 @@ class DocLangDocDeserializer(BaseDocDeserializer, BaseModel):
                     DocLangToken.LOCATION.value,
                     DocLangToken.LAYER.value,
                     DocLangToken.LABEL.value,
+                    DocLangToken.CAPTION.value,
                 }:
                     continue
                 elif nm_child == DocLangToken.BR.value:
@@ -1463,23 +1469,23 @@ class DocLangDocDeserializer(BaseDocDeserializer, BaseModel):
         return DocItemLabel.TABLE
 
     def _parse_table(self, *, doc: DoclingDocument, el: Element, parent: NodeItem | None) -> None:
-        """Parse ``<table>``, ``<index>``, or a ``<group>`` wrapping them (with footnotes)."""
+        """Parse ``<table>``, ``<index>``, or a ``<group>`` wrapping them (with satellites)."""
         otsl_el: Element | None
+        extra_captions: list[TextItem] = []
         footnotes: list[TextItem] = []
         if el.tagName in {DocLangToken.TABLE.value, DocLangToken.INDEX.value}:
             caption = self._extract_caption(doc=doc, el=el)
             otsl_el = el
             table_label = self._table_label_from_otsl_element(el)
         else:
-            footnotes = self._extract_footnotes(doc=doc, el=el)
+            extra_captions, footnotes = self._extract_satellites(doc=doc, el=el)
             otsl_el = self._first_child(el, DocLangToken.TABLE.value) or self._first_child(el, DocLangToken.INDEX.value)
             caption = self._extract_caption(doc=doc, el=el)
             if caption is None and otsl_el is not None:
                 caption = self._extract_caption(doc=doc, el=otsl_el)
             if otsl_el is None:
                 tbl = doc.add_table(data=TableData(), caption=caption, parent=parent)
-                for ftn in footnotes:
-                    tbl.footnotes.append(ftn.get_ref())
+                self._attach_satellites(item=tbl, captions=extra_captions, footnotes=footnotes)
                 return
             table_label = self._table_label_from_otsl_element(otsl_el)
 
@@ -1543,18 +1549,18 @@ class DocLangDocDeserializer(BaseDocDeserializer, BaseModel):
             tbl.prov.append(p)
         if thread_id:
             self._register_thread(thread_id=thread_id, host=table_host, item=tbl)
-        for ftn in footnotes:
-            tbl.footnotes.append(ftn.get_ref())
+        self._attach_satellites(item=tbl, captions=extra_captions, footnotes=footnotes)
 
     def _parse_picture(self, *, doc: DoclingDocument, el: Element, parent: NodeItem | None) -> None:
-        """Parse ``<picture>`` or a ``<group>`` wrapping it (with footnotes)."""
+        """Parse ``<picture>`` or a ``<group>`` wrapping it (with satellites)."""
         picture_el: Element | None
+        extra_captions: list[TextItem] = []
         footnotes: list[TextItem] = []
         if el.tagName == DocLangToken.PICTURE.value:
             caption = self._extract_caption(doc=doc, el=el)
             picture_el = el
         else:
-            footnotes = self._extract_footnotes(doc=doc, el=el)
+            extra_captions, footnotes = self._extract_satellites(doc=doc, el=el)
             picture_el = self._first_child(el, DocLangToken.PICTURE.value)
             caption = self._extract_caption(doc=doc, el=el)
             if caption is None and picture_el is not None:
@@ -1576,8 +1582,7 @@ class DocLangDocDeserializer(BaseDocDeserializer, BaseModel):
             self._source_recorder.bind_item(picture_el, pic)
         for p in prov_list[1:]:
             pic.prov.append(p)
-        for ftn in footnotes:
-            pic.footnotes.append(ftn.get_ref())
+        self._attach_satellites(item=pic, captions=extra_captions, footnotes=footnotes)
 
         if picture_el is not None:
             if label_val := self._extract_label_value(el=picture_el):
@@ -1763,23 +1768,72 @@ class DocLangDocDeserializer(BaseDocDeserializer, BaseModel):
         self._source_recorder.bind_item(cap_el, item)
         return item
 
-    def _extract_footnotes(self, *, doc: DoclingDocument, el: Element) -> list[TextItem]:
+    def _float_group_host(self, el: Element) -> Element | None:
+        """Return the host of a float group, or ``None`` if ``el`` is not one.
+
+        DocLang has no dedicated construct for a float's extra captions and footnotes
+        yet, so by convention they are emitted as ``<text>`` and ``<footnote>`` siblings
+        of the host inside an unnamed ``<group>``. Such a group wraps exactly one
+        ``<picture>``, ``<table>``, ``<index>`` or ``<code>`` and nothing but satellites
+        besides it.
+        """
+        host_tags = {
+            DocLangToken.PICTURE.value,
+            DocLangToken.TABLE.value,
+            DocLangToken.INDEX.value,
+            DocLangToken.CODE.value,
+        }
+        satellite_tags = {DocLangToken.TEXT.value, DocLangToken.FOOTNOTE.value, DocLangToken.CAPTION.value}
+        hosts: list[Element] = []
+        for node in el.childNodes:
+            if not isinstance(node, Element):
+                continue
+            if node.tagName in host_tags:
+                hosts.append(node)
+            elif node.tagName not in satellite_tags:
+                return None
+        return hosts[0] if len(hosts) == 1 else None
+
+    def _extract_satellites(self, *, doc: DoclingDocument, el: Element) -> tuple[list[TextItem], list[TextItem]]:
+        """Extract the satellites of a float group: ``<text>`` as captions, ``<footnote>`` as footnotes."""
+        labels = {
+            DocLangToken.TEXT.value: DocItemLabel.CAPTION,
+            DocLangToken.FOOTNOTE.value: DocItemLabel.FOOTNOTE,
+        }
+        captions: list[TextItem] = []
         footnotes: list[TextItem] = []
         for node in el.childNodes:
-            if isinstance(node, Element) and node.tagName == DocLangToken.FOOTNOTE.value:
+            if isinstance(node, Element) and (label := labels.get(node.tagName)) is not None:
                 text = self._get_text(node).strip()
                 if text:
                     prov_list = self._extract_provenance(doc=doc, el=node)
                     item = doc.add_text(
-                        label=DocItemLabel.FOOTNOTE,
+                        label=label,
                         text=text,
                         prov=(prov_list[0] if prov_list else None),
                     )
                     for p in prov_list[1:]:
                         item.prov.append(p)
                     self._source_recorder.bind_item(node, item)
-                    footnotes.append(item)
-        return footnotes
+                    (captions if label == DocItemLabel.CAPTION else footnotes).append(item)
+        return captions, footnotes
+
+    def _parse_code_group(
+        self, *, doc: DoclingDocument, el: Element, code_el: Element, parent: NodeItem | None
+    ) -> None:
+        """Parse a ``<group>`` wrapping a ``<code>`` with its satellites."""
+        extra_captions, footnotes = self._extract_satellites(doc=doc, el=el)
+        num_texts = len(doc.texts)
+        self._parse_text_like(doc=doc, el=code_el, parent=parent)
+        if (code := next((t for t in doc.texts[num_texts:] if isinstance(t, CodeItem)), None)) is not None:
+            self._attach_satellites(item=code, captions=extra_captions, footnotes=footnotes)
+
+    @staticmethod
+    def _attach_satellites(*, item: FloatingItem, captions: list[TextItem], footnotes: list[TextItem]) -> None:
+        for cap in captions:
+            item.captions.append(cap.get_ref())
+        for ftn in footnotes:
+            item.footnotes.append(ftn.get_ref())
 
     def _first_child(self, el: Element, tag_name: str) -> Element | None:
         for node in el.childNodes:

{docling_core-2.97.2 → docling_core-2.98.1}/docling_core/transforms/serializer/doclang.py

@@ -89,6 +89,7 @@ from docling_core.types.doc import (
     PictureItem,
     PictureMeta,
     ProvenanceItem,
+    RefItem,
     Script,
     SectionHeaderItem,
     Size,
@@ -397,13 +398,158 @@ def _serialize_floating_caption_head(
     params: DocLangParams,
     **kwargs: Any,
 ) -> str:
-    """Serialize referenced caption(s) for inclusion in the host element head."""
-    if not params.add_referenced_caption or not item.captions:
+    """Serialize the first referenced caption for inclusion in the host element head.
+
+    The element head holds at most one ``<caption>``; any further captions are emitted
+    next to the host by ``_serialize_floating_satellites``.
+    """
+    if not params.add_referenced_caption:
+        return ""
+    captions = _resolve_satellites(refs=item.captions, doc_serializer=doc_serializer, doc=doc, **kwargs)
+    if not captions:
         return ""
-    cap_res = doc_serializer.serialize_captions(item=item, **kwargs)
+    head_item = item.model_copy(update={"captions": [captions[0].get_ref()]})
+    cap_res = doc_serializer.serialize_captions(item=head_item, **kwargs)
     return cap_res.text or ""
 
 
+def _resolve_satellites(
+    *,
+    refs: list[RefItem],
+    doc_serializer: BaseDocSerializer,
+    doc: DoclingDocument,
+    **kwargs: Any,
+) -> list[TextItem]:
+    """Resolve caption or footnote references, skipping excluded ones."""
+    excluded = doc_serializer.get_excluded_refs(**kwargs)
+    return [sat for ref in refs if ref.cref not in excluded and isinstance(sat := ref.resolve(doc), TextItem)]
+
+
+def _serialize_satellite(
+    *,
+    item: TextItem,
+    tag: DocLangToken,
+    content_type: ContentType,
+    doc: DoclingDocument,
+    params: DocLangParams,
+) -> str:
+    """Serialize a caption or footnote of a floating item as a standalone element."""
+    head = _element_head_prefix(item=item, doc=doc, params=params)
+    content = _escape_text(item.text, params) if item.text and content_type in params.content_types else ""
+    text = f"{head}{content}"
+    return _wrap(text=text, wrap_tag=tag.value) if text else ""
+
+
+def _top_left_bbox(prov: ProvenanceItem, doc: DoclingDocument) -> BoundingBox | None:
+    """Return the provenance bbox in top-left origin, or ``None`` if the page height is unknown."""
+    if prov.bbox.coord_origin == CoordOrigin.TOPLEFT:
+        return prov.bbox
+    page = doc.pages.get(prov.page_no)
+    if page is None:
+        return None
+    return prov.bbox.to_top_left_origin(page_height=page.size.height)
+
+
+def _satellite_placement(
+    *,
+    sat: DocItem,
+    host: FloatingItem,
+    doc: DoclingDocument,
+) -> tuple[bool, tuple[int, float, float]] | None:
+    """Place a satellite (extra caption or footnote) relative to its host by layout.
+
+    The satellite goes after the host if it sits on a later page, entirely below the
+    host, or (when overlapping it vertically) entirely to its right; if it overlaps
+    the host in both directions, if its bbox center is lower. Returns this decision
+    together with the satellite's reading-order sort key, or ``None`` if the position
+    cannot be determined.
+    """
+    if not sat.prov or not host.prov:
+        return None
+    sat_prov = sat.prov[0]
+    if (sat_bbox := _top_left_bbox(sat_prov, doc)) is None:
+        return None
+    key = (sat_prov.page_no, sat_bbox.t, sat_bbox.l)
+    host_pages = [p.page_no for p in host.prov]
+    if sat_prov.page_no < min(host_pages):
+        return False, key
+    if sat_prov.page_no > max(host_pages):
+        return True, key
+    host_prov = next((p for p in host.prov if p.page_no == sat_prov.page_no), None)
+    if host_prov is None or (host_bbox := _top_left_bbox(host_prov, doc)) is None:
+        return None
+    # clearly above or below the host
+    if sat_bbox.b <= host_bbox.t:
+        return False, key
+    if sat_bbox.t >= host_bbox.b:
+        return True, key
+    # beside the host
+    if sat_bbox.r <= host_bbox.l:
+        return False, key
+    if sat_bbox.l >= host_bbox.r:
+        return True, key
+    # overlapping the host
+    sat_y = (sat_bbox.t + sat_bbox.b) / 2
+    host_y = (host_bbox.t + host_bbox.b) / 2
+    return sat_y > host_y, key
+
+
+def _serialize_floating_satellites(
+    *,
+    item: FloatingItem,
+    doc_serializer: BaseDocSerializer,
+    doc: DoclingDocument,
+    params: DocLangParams,
+    **kwargs: Any,
+) -> tuple[list[SerializationResult], list[SerializationResult]]:
+    """Serialize the extra captions and the footnotes of a floating item.
+
+    Captions beyond the first one (which goes in the host element head) become
+    ``<text>`` elements, footnotes become ``<footnote>`` elements. Each is placed
+    before or after the host by layout (see ``_satellite_placement``), and sorted in
+    reading order (page, top, left) on either side. Satellites without a determinable
+    position fall back to extra captions before and footnotes after the host.
+
+    Returns the ``(before, after)`` serialization results.
+    """
+    sats: list[tuple[TextItem, str, bool]] = []
+    if params.add_referenced_caption:
+        captions = _resolve_satellites(refs=item.captions, doc_serializer=doc_serializer, doc=doc, **kwargs)
+        for cap in captions[1:]:
+            text = _serialize_satellite(
+                item=cap, tag=DocLangToken.TEXT, content_type=ContentType.REF_CAPTION, doc=doc, params=params
+            )
+            sats.append((cap, text, False))
+    if params.add_referenced_footnote:
+        footnotes = _resolve_satellites(refs=item.footnotes, doc_serializer=doc_serializer, doc=doc, **kwargs)
+        for ftn in footnotes:
+            text = _serialize_satellite(
+                item=ftn, tag=DocLangToken.FOOTNOTE, content_type=ContentType.REF_FOOTNOTE, doc=doc, params=params
+            )
+            sats.append((ftn, text, True))
+
+    before_unplaced: list[SerializationResult] = []
+    after_unplaced: list[SerializationResult] = []
+    before: list[tuple[tuple[int, float, float], SerializationResult]] = []
+    after: list[tuple[tuple[int, float, float], SerializationResult]] = []
+    for sat, text, default_after in sats:
+        if not text:
+            continue
+        res = create_ser_result(text=text, span_source=sat)
+        if (placement := _satellite_placement(sat=sat, host=item, doc=doc)) is None:
+            (after_unplaced if default_after else before_unplaced).append(res)
+        else:
+            goes_after, key = placement
+            (after if goes_after else before).append((key, res))
+
+    before.sort(key=lambda x: x[0])
+    after.sort(key=lambda x: x[0])
+    return (
+        before_unplaced + [res for _, res in before],
+        [res for _, res in after] + after_unplaced,
+    )
+
+
 def _element_label_for_serialization(
     *,
     raw_label: str | None,
@@ -723,6 +869,7 @@ class DocLangTextSerializer(BaseModel, BaseTextSerializer):
                     visited=visited,
                     is_inline_scope=is_inline_scope,
                     thread_id=thread_id,
+                    include_caption_head=idp == 0,
                     **kwargs,
                 )
                 res.append(tres)
@@ -814,14 +961,17 @@ class DocLangTextSerializer(BaseModel, BaseTextSerializer):
         is_inline_scope: bool = False,
         visited: set[str] | None = None,
         thread_id: str | None = None,
+        include_caption_head: bool = True,
         **kwargs: Any,
     ) -> SerializationResult:
         """Serialize a ``TextItem`` into DocLang markup.
 
         Depending on parameters, emits meta blocks, location tokens, and the
         item's textual content (prefixing code language for ``CodeItem``). For
-        floating items, captions may be appended. The result can be wrapped in a
-        tag derived from the item's label when applicable.
+        floating items, the first caption goes in the element head and further
+        captions and footnotes are emitted around it (see
+        ``_serialize_floating_satellites``). The result can be wrapped in a tag
+        derived from the item's label when applicable.
 
         Args:
             item: The text-like item to serialize.
@@ -935,6 +1085,12 @@ class DocLangTextSerializer(BaseModel, BaseTextSerializer):
                 params=params,
             )
 
+        caption_head = ""
+        if include_caption_head and isinstance(item, FloatingItem):
+            caption_head = _serialize_floating_caption_head(
+                item=item, doc_serializer=doc_serializer, doc=doc, params=params, **kwargs
+            )
+
         include_href = not is_inline_scope
         if not skip_location:
             parts.append(
@@ -943,6 +1099,7 @@ class DocLangTextSerializer(BaseModel, BaseTextSerializer):
                     doc=doc,
                     params=params,
                     label_value=code_label,
+                    caption_text=caption_head or None,
                     custom_text=custom_head or None,
                     include_href=include_href,
                     thread_id=thread_id,
@@ -966,24 +1123,46 @@ class DocLangTextSerializer(BaseModel, BaseTextSerializer):
             or (isinstance(item, FormulaItem) and ContentType.TEXT_FORMULA in params.content_types)
             or (not isinstance(item, CodeItem | FormulaItem) and ContentType.TEXT_OTHER in params.content_types)
         ):
-            if item.children and not item.text:
-                # Check if first child is InlineGroup - if so, only serialize that as text content
-                first_child_ref = item.children[0]
-                first_child_item = first_child_ref.resolve(doc)
-
-                if isinstance(first_child_item, InlineGroup):
-                    # Only serialize the first child (InlineGroup) as the text content
-                    # Other children are hierarchical subordinates and will be serialized separately
-                    text_part = doc_serializer.serialize(item=first_child_item, visited=my_visited, **kwargs).text
+            first_child_item = item.children[0].resolve(doc) if item.children else None
+            if isinstance(first_child_item, InlineGroup):
+                # Only serialize the first child (InlineGroup) as the text content
+                # Other children are hierarchical subordinates and will be serialized separately.
+                # The item's own text, when present, precedes the runs within the same element:
+                # emitting the runs as siblings instead yields invalid DocLang and loses content.
+                inline_part = doc_serializer.serialize(item=first_child_item, visited=my_visited, **kwargs).text
+                if item.text:
+                    own_part = _escape_text(item.text, params)
+                    own_part = doc_serializer.post_process(
+                        text=own_part,
+                        formatting=item.formatting,
+                        hyperlink=None,
+                    )
+                    if item.label == DocItemLabel.HANDWRITTEN_TEXT:
+                        own_part = _wrap(text=own_part, wrap_tag=DocLangToken.HANDWRITING.value)
+                    elif item.label in [
+                        DocItemLabel.CHECKBOX_SELECTED,
+                        DocItemLabel.CHECKBOX_UNSELECTED,
+                    ]:
+                        # Add checkbox token before the text
+                        checkbox_token = DocLangVocabulary._create_checkbox_token(
+                            selected=(item.label == DocItemLabel.CHECKBOX_SELECTED)
+                        )
+                        own_part = checkbox_token + own_part
+                    # Join with a plain space rather than the pretty-printing delimiter:
+                    # own_part and inline_part are two runs of the same inline flow, so
+                    # they need a real word boundary even in minimized (non-pretty) output.
+                    text_part = " ".join([p for p in (own_part, inline_part) if p])
                 else:
-                    # Serialize all children as text content
-                    sub_parts: list[str] = []
-                    for child_ref in item.children:
-                        child_item = child_ref.resolve(doc)
-                        if isinstance(item, ListItem) and _list_item_segment_sibling(child_item):
-                            continue
-                        sub_parts.append(doc_serializer.serialize(item=child_item, visited=my_visited, **kwargs).text)
-                    text_part = _get_delim(params=params).join(sub_parts)
+                    text_part = inline_part
+            elif item.children and not item.text:
+                # Serialize all children as text content
+                sub_parts: list[str] = []
+                for child_ref in item.children:
+                    child_item = child_ref.resolve(doc)
+                    if isinstance(item, ListItem) and _list_item_segment_sibling(child_item):
+                        continue
+                    sub_parts.append(doc_serializer.serialize(item=child_item, visited=my_visited, **kwargs).text)
+                text_part = _get_delim(params=params).join(sub_parts)
             else:
                 text_part = _escape_text(item.text, params)
                 text_part = doc_serializer.post_process(
@@ -1006,18 +1185,6 @@ class DocLangTextSerializer(BaseModel, BaseTextSerializer):
             if text_part:
                 parts.append(text_part)
 
-        if params.add_referenced_caption and isinstance(item, FloatingItem):
-            cap_text = doc_serializer.serialize_captions(item=item, **kwargs).text
-            if cap_text:
-                cap_text = _escape_text(cap_text, params)
-                parts.append(cap_text)
-
-        if params.add_referenced_footnote and isinstance(item, FloatingItem):
-            ftn_text = doc_serializer.serialize_footnotes(item=item, **kwargs).text
-            if ftn_text:
-                ftn_text = _escape_text(ftn_text, params)
-                parts.append(ftn_text)
-
         text_res = "".join(parts)
 
         # Special handling for ListItems with suppress_empty_elements
@@ -1043,6 +1210,17 @@ class DocLangTextSerializer(BaseModel, BaseTextSerializer):
                 elif item.label in (DocItemLabel.FIELD_KEY, DocItemLabel.FIELD_VALUE):
                     text_res = _wrap_field_kv_markup_if_needed(text=text_res, item=item, doc=doc)
 
+        if include_caption_head and isinstance(item, FloatingItem) and not is_inline_scope:
+            before, after = _serialize_floating_satellites(
+                item=item, doc_serializer=doc_serializer, doc=doc, params=params, **kwargs
+            )
+            if before or after:
+                # Wrap the host with its satellites so that they can be re-attached on deserialization.
+                text_res = _wrap(
+                    text="".join(r.text for r in before) + text_res + "".join(r.text for r in after),
+                    wrap_tag=DocLangToken.GROUP.value,
+                )
+
         # Prepend ldiv element for ListItems (it's a delimiter, not a wrapper)
         if ldiv_element:
             text_res = ldiv_element + text_res
@@ -1254,19 +1432,21 @@ class DocLangPictureSerializer(BasePictureSerializer):
         picture_open += ">"
         picture_text = f"{picture_open}{inner}</{DocLangToken.PICTURE.value}>"
 
-        footnote_text = ""
-        if params.add_referenced_footnote:
-            ftn_res = doc_serializer.serialize_footnotes(item=item, **kwargs)
-            if ftn_res.text:
-                footnote_text = ftn_res.text
-                res_parts.append(ftn_res)
+        before, after = _serialize_floating_satellites(
+            item=item, doc_serializer=doc_serializer, doc=doc, params=params, **kwargs
+        )
+        res_parts.extend(before + after)
 
-        if not inner and not footnote_text:
+        if not inner and not (before or after):
             if params.suppress_empty_elements:
                 return create_ser_result()
             text_res = f"<{DocLangToken.PICTURE.value}></{DocLangToken.PICTURE.value}>"
-        elif footnote_text:
-            text_res = _wrap(text=picture_text + footnote_text, wrap_tag=DocLangToken.GROUP.value)
+        elif before or after:
+            # Wrap the host with its satellites so that they can be re-attached on deserialization.
+            text_res = _wrap(
+                text="".join(r.text for r in before) + picture_text + "".join(r.text for r in after),
+                wrap_tag=DocLangToken.GROUP.value,
+            )
         else:
             text_res = picture_text
 
@@ -1488,19 +1668,24 @@ class DocLangTableSerializer(BaseTableSerializer):
         table_text = _wrap(text=head + "".join(inner_parts), wrap_tag=host_token.value)
         res_parts.append(create_ser_result(text=head + "".join(inner_parts), span_source=item))
 
-        footnote_text = ""
-        if include_caption_head and params.add_referenced_footnote:
-            ftn_res = doc_serializer.serialize_footnotes(item=item, **kwargs)
-            if ftn_res.text:
-                footnote_text = ftn_res.text
-                res_parts.append(ftn_res)
+        before: list[SerializationResult] = []
+        after: list[SerializationResult] = []
+        if include_caption_head:
+            before, after = _serialize_floating_satellites(
+                item=item, doc_serializer=doc_serializer, doc=doc, params=params, **kwargs
+            )
+            res_parts.extend(before + after)
 
-        if not (head or inner_parts) and not footnote_text:
+        if not (head or inner_parts) and not (before or after):
             if params.suppress_empty_elements:
                 return create_ser_result()
             text_res = f"<{host_token.value}></{host_token.value}>"
-        elif footnote_text:
-            text_res = _wrap(text=table_text + footnote_text, wrap_tag=DocLangToken.GROUP.value)
+        elif before or after:
+            # Wrap the host with its satellites so that they can be re-attached on deserialization.
+            text_res = _wrap(
+                text="".join(r.text for r in before) + table_text + "".join(r.text for r in after),
+                wrap_tag=DocLangToken.GROUP.value,
+            )
         else:
             text_res = table_text
 
@@ -1863,19 +2048,16 @@ class DocLangDocSerializer(DocSerializer):
         """Serialize the item's footnotes with DocLang location tokens."""
         params = DocLangParams(**kwargs)
         results: list[SerializationResult] = []
-        for footnote in item.footnotes:
-            if footnote.cref not in self.get_excluded_refs(**kwargs):
-                if isinstance(ftn := footnote.resolve(self.doc), TextItem):
-                    head = _element_head_prefix(item=ftn, doc=self.doc, params=params)
-
-                    content = ""
-                    if ftn.text and ContentType.REF_FOOTNOTE in params.content_types:
-                        content = _escape_text(ftn.text, params)
-
-                    text_res = f"{head}{content}"
-                    if text_res:
-                        text_res = _wrap(text_res, wrap_tag=DocLangToken.FOOTNOTE.value)
-                        results.append(create_ser_result(text=text_res))
+        for ftn in _resolve_satellites(refs=item.footnotes, doc_serializer=self, doc=self.doc, **kwargs):
+            text_res = _serialize_satellite(
+                item=ftn,
+                tag=DocLangToken.FOOTNOTE,
+                content_type=ContentType.REF_FOOTNOTE,
+                doc=self.doc,
+                params=params,
+            )
+            if text_res:
+                results.append(create_ser_result(text=text_res))
 
         text_res = "".join([r.text for r in results])