mkdocs2confluence 0.7.9__tar.gz → 0.7.11__tar.gz

{mkdocs2confluence-0.7.9/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.7.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.7.9
+Version: 0.7.11
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -355,7 +355,7 @@ If `repo_url` + `edit_uri` are set in `mkdocs.yml`, an **Edit Source** row links
 
 ### Abbreviation expansion
 
-MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — Confluence has no native `<abbr>` tooltip. The **first occurrence** in body text is expanded as `IAM (Identity and Access Management)`; subsequent occurrences are left as-is. Abbreviations that only appear in headings or code are collected into an auto-appended **Glossary** section.
+MkDocs abbreviation definitions (`*[ABBR]: Full term`) are rendered as inline Confluence **footnotes**. The **first occurrence** of each abbreviation in body text is annotated with a footnote macro — Confluence renders it as a superscript number and collects all definitions at the bottom of the page. Subsequent occurrences are left as plain text. Abbreviations that only appear in headings or other non-expandable contexts are collected into an auto-appended **Glossary** section as a fallback.
 
 ---
 
@@ -364,7 +364,7 @@ MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — C
 | Feature | Behaviour |
 |---|---|
 | **Admonition styling** | `tip`, `info`, `warning`, `note` use Confluence's fixed native macro colours. `danger`, `error`, `bug` use a custom red `panel` macro with 🚨 prefix. All other types are mapped to the nearest native macro. |
-| **Abbreviation tooltips** | No native tooltip support. First occurrence expanded inline; remainder left as-is. |
+| **Abbreviation tooltips** | No native tooltip support. First occurrence annotated with an inline Confluence footnote; definition collected at the bottom of the page. |
 | **Page ordering** | Confluence sorts child pages alphabetically; the v2 REST API has no write endpoint for ordering. |
 | **Code language aliases** | Short aliases (`py`, `js`, `yml`, `ts`, `sh`) are passed through as-is; Confluence requires full language names for syntax highlighting. |
 | **Unrecognised blocks** | Preserved as a visible `warning` macro — no content is silently lost. |

{mkdocs2confluence-0.7.9 → mkdocs2confluence-0.7.11}/README.md

@@ -315,7 +315,7 @@ If `repo_url` + `edit_uri` are set in `mkdocs.yml`, an **Edit Source** row links
 
 ### Abbreviation expansion
 
-MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — Confluence has no native `<abbr>` tooltip. The **first occurrence** in body text is expanded as `IAM (Identity and Access Management)`; subsequent occurrences are left as-is. Abbreviations that only appear in headings or code are collected into an auto-appended **Glossary** section.
+MkDocs abbreviation definitions (`*[ABBR]: Full term`) are rendered as inline Confluence **footnotes**. The **first occurrence** of each abbreviation in body text is annotated with a footnote macro — Confluence renders it as a superscript number and collects all definitions at the bottom of the page. Subsequent occurrences are left as plain text. Abbreviations that only appear in headings or other non-expandable contexts are collected into an auto-appended **Glossary** section as a fallback.
 
 ---
 
@@ -324,7 +324,7 @@ MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — C
 | Feature | Behaviour |
 |---|---|
 | **Admonition styling** | `tip`, `info`, `warning`, `note` use Confluence's fixed native macro colours. `danger`, `error`, `bug` use a custom red `panel` macro with 🚨 prefix. All other types are mapped to the nearest native macro. |
-| **Abbreviation tooltips** | No native tooltip support. First occurrence expanded inline; remainder left as-is. |
+| **Abbreviation tooltips** | No native tooltip support. First occurrence annotated with an inline Confluence footnote; definition collected at the bottom of the page. |
 | **Page ordering** | Confluence sorts child pages alphabetically; the v2 REST API has no write endpoint for ordering. |
 | **Code language aliases** | Short aliases (`py`, `js`, `yml`, `ts`, `sh`) are passed through as-is; Confluence requires full language names for syntax highlighting. |
 | **Unrecognised blocks** | Preserved as a visible `warning` macro — no content is silently lost. |

{mkdocs2confluence-0.7.9 → mkdocs2confluence-0.7.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.7.9"
+version = "0.7.11"
 description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }

{mkdocs2confluence-0.7.9 → mkdocs2confluence-0.7.11/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.7.9
+Version: 0.7.11
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -355,7 +355,7 @@ If `repo_url` + `edit_uri` are set in `mkdocs.yml`, an **Edit Source** row links
 
 ### Abbreviation expansion
 
-MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — Confluence has no native `<abbr>` tooltip. The **first occurrence** in body text is expanded as `IAM (Identity and Access Management)`; subsequent occurrences are left as-is. Abbreviations that only appear in headings or code are collected into an auto-appended **Glossary** section.
+MkDocs abbreviation definitions (`*[ABBR]: Full term`) are rendered as inline Confluence **footnotes**. The **first occurrence** of each abbreviation in body text is annotated with a footnote macro — Confluence renders it as a superscript number and collects all definitions at the bottom of the page. Subsequent occurrences are left as plain text. Abbreviations that only appear in headings or other non-expandable contexts are collected into an auto-appended **Glossary** section as a fallback.
 
 ---
 
@@ -364,7 +364,7 @@ MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — C
 | Feature | Behaviour |
 |---|---|
 | **Admonition styling** | `tip`, `info`, `warning`, `note` use Confluence's fixed native macro colours. `danger`, `error`, `bug` use a custom red `panel` macro with 🚨 prefix. All other types are mapped to the nearest native macro. |
-| **Abbreviation tooltips** | No native tooltip support. First occurrence expanded inline; remainder left as-is. |
+| **Abbreviation tooltips** | No native tooltip support. First occurrence annotated with an inline Confluence footnote; definition collected at the bottom of the page. |
 | **Page ordering** | Confluence sorts child pages alphabetically; the v2 REST API has no write endpoint for ordering. |
 | **Code language aliases** | Short aliases (`py`, `js`, `yml`, `ts`, `sh`) are passed through as-is; Confluence requires full language names for syntax highlighting. |
 | **Unrecognised blocks** | Preserved as a visible `warning` macro — no content is silently lost. |

{mkdocs2confluence-0.7.9 → mkdocs2confluence-0.7.11}/src/mkdocs_to_confluence/emitter/xhtml.py

@@ -22,6 +22,8 @@ from typing import Sequence
 from urllib.parse import urlparse
 
 from mkdocs_to_confluence.ir.nodes import (
+    AbbrevFootnoteNode,
+    AbbrevGlossaryBlock,
     Admonition,
     BlockQuote,
     BoldNode,
@@ -190,6 +192,8 @@ def _emit_node(node: IRNode) -> str:
         return _emit_front_matter(node)
     if isinstance(node, FootnoteBlock):
         return _emit_footnote_block(node)
+    if isinstance(node, AbbrevGlossaryBlock):
+        return _emit_abbrev_glossary_block(node)
     if isinstance(node, GridCards):
         return _emit_grid_cards(node)
     if isinstance(node, UnsupportedBlock):
@@ -555,6 +559,45 @@ def _emit_footnote_ref(node: FootnoteRef) -> str:
     )
 
 
+def _emit_abbrev_footnote(node: AbbrevFootnoteNode) -> str:
+    """Inline: ABBR + superscript anchor-link to the glossary entry."""
+    anchor = html.escape(f"abbr-{node.number}")
+    num = html.escape(str(node.number))
+    term = html.escape(node.abbr)
+    return (
+        f"{term}"
+        f"<sup>"
+        f'<ac:link ac:anchor="{anchor}">'
+        f"<ac:plain-text-link-body><![CDATA[{num}]]></ac:plain-text-link-body>"
+        f"</ac:link>"
+        f"</sup>"
+    )
+
+
+def _emit_abbrev_glossary_block(node: AbbrevGlossaryBlock) -> str:
+    """End-of-page abbreviations list with Confluence anchor targets."""
+    parts: list[str] = ["<hr />\n<h6>Abbreviations</h6>\n"]
+    if node.footnoted:
+        parts.append("<ol>\n")
+        for fn in node.footnoted:
+            anchor = html.escape(f"abbr-{fn.number}")
+            anchor_macro = (
+                f'<ac:structured-macro ac:name="anchor">'
+                f'<ac:parameter ac:name=""><![CDATA[{anchor}]]></ac:parameter>'
+                f"</ac:structured-macro>"
+            )
+            abbr = html.escape(fn.abbr)
+            defn = html.escape(fn.definition)
+            parts.append(f"<li>{anchor_macro}<strong>{abbr}</strong> — {defn}</li>\n")
+        parts.append("</ol>\n")
+    if node.extras:
+        parts.append("<ul>\n")
+        for abbr, defn in node.extras:
+            parts.append(f"<li><strong>{html.escape(abbr)}</strong> — {html.escape(defn)}</li>\n")
+        parts.append("</ul>\n")
+    return "".join(parts)
+
+
 def _emit_footnote_block(node: FootnoteBlock) -> str:
     """Footnotes section: heading + ordered list with anchor targets."""
     items: list[str] = []
@@ -613,6 +656,8 @@ def _emit_inline(node: IRNode) -> str:
         return _emit_image(node)
     if isinstance(node, FootnoteRef):
         return _emit_footnote_ref(node)
+    if isinstance(node, AbbrevFootnoteNode):
+        return _emit_abbrev_footnote(node)
     if isinstance(node, LineBreakNode):
         return "<br />"
     if isinstance(node, InlineHtmlNode):

{mkdocs2confluence-0.7.9 → mkdocs2confluence-0.7.11}/src/mkdocs_to_confluence/ir/nodes.py

@@ -428,6 +428,40 @@ class FrontMatter(IRNode):
     site_url: str | None = None
 
 
+# ── Abbreviation footnotes ────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class AbbrevFootnoteNode(IRNode):
+    """Inline: abbreviated term with a superscript anchor-link to the glossary.
+
+    The emitter renders ``ABBR<sup>[N]</sup>`` where ``[N]`` links to the
+    corresponding entry in the end-of-page :class:`AbbrevGlossaryBlock`.
+    """
+
+    abbr: str
+    definition: str
+    number: int  # 1-based, assigned by the transform in order of first encounter
+
+
+@dataclass(frozen=True)
+class AbbrevGlossaryBlock(IRNode):
+    """End-of-page abbreviations reference block.
+
+    Rendered as a numbered list (with Confluence anchor targets for the
+    back-links) followed by an optional bullet list of abbreviations that
+    only appeared in headings or other non-expandable contexts.
+
+    Attributes:
+        footnoted: Abbreviations annotated inline, ordered by first encounter.
+        extras:    ``(abbr, definition)`` pairs for abbreviations that could
+                   not be annotated inline, sorted alphabetically.
+    """
+
+    footnoted: tuple[AbbrevFootnoteNode, ...]
+    extras: tuple[tuple[str, str], ...]
+
+
 # ── Footnotes ────────────────────────────────────────────────────────────────
 
 

{mkdocs2confluence-0.7.9 → mkdocs2confluence-0.7.11}/src/mkdocs_to_confluence/transforms/abbrevs.py

@@ -3,17 +3,19 @@
 Collects ``*[ABBR]: definition`` pairs (extracted by
 :mod:`mkdocs_to_confluence.preprocess.abbrevs`) and walks the IR tree to:
 
-1. **Expand** the first occurrence of each abbreviation in *safe* body nodes —
-   paragraphs, list items, table body cells, blockquotes — by rewriting it to
-   ``ABBR (definition)``.
+1. **Annotate** the first occurrence of each abbreviation in *safe* body nodes —
+   paragraphs, list items, table body cells, blockquotes — by inserting an
+   inline Confluence ``footnote`` macro immediately after the term.  Confluence
+   renders this as a superscript number and collects all definitions at the
+   bottom of the page.
 
 2. **Skip** structural/title nodes where expansion would look odd:
    section headings, table header cells, admonition/panel titles, code spans,
    and link text.
 
 3. **Append a Glossary section** at the end of the page for any abbreviation
-   that was detected in the page text but could not be expanded inline because
-   it only appeared in skipped contexts.
+   that was detected in the page text but could not be footnoted because it
+   only appeared in skipped contexts (headings, table headers, etc.).
 
 Entry point
 -----------
@@ -27,13 +29,14 @@ import re
 from dataclasses import replace
 
 from mkdocs_to_confluence.ir.nodes import (
+    AbbrevFootnoteNode,
+    AbbrevGlossaryBlock,
     Admonition,
     BlockQuote,
     BoldNode,
     BulletList,
     ContentTabs,
     Expandable,
-    HorizontalRule,
     IRNode,
     ItalicNode,
     LinkNode,
@@ -57,28 +60,45 @@ class _State:
 
     def __init__(self, abbrevs: dict[str, str]) -> None:
         self.abbrevs = abbrevs
-        self.expanded: set[str] = set()
+        self._expanded_list: list[str] = []  # ordered by first encounter
+        self._expanded_set: set[str] = set()  # fast membership test
         # Pre-compile word-boundary patterns once.
         self._patterns: dict[str, re.Pattern[str]] = {
             abbr: re.compile(r"\b" + re.escape(abbr) + r"\b")
             for abbr in abbrevs
         }
 
-    def expand_text(self, text: str) -> str:
-        """Return *text* with first-occurrence abbreviations expanded.
+    @property
+    def expanded(self) -> set[str]:
+        return self._expanded_set
 
-        Each abbreviation is expanded at most once across the entire page.
-        Once an abbreviation has been expanded, subsequent occurrences are left
-        as plain text.
+    def expand_to_nodes(self, text: str) -> tuple[IRNode, ...]:
+        """Split *text* around the first unexpanded abbreviation.
+
+        Returns a mix of :class:`TextNode` and :class:`AbbrevFootnoteNode`.
+        Each abbreviation is footnoted at most once per page.
         """
-        for abbr, defn in self.abbrevs.items():
-            if abbr in self.expanded:
+        best: tuple[int, int, str] | None = None
+        for abbr in self.abbrevs:
+            if abbr in self._expanded_set:
                 continue
-            pattern = self._patterns[abbr]
-            if pattern.search(text):
-                text = pattern.sub(f"{abbr} ({defn})", text, count=1)
-                self.expanded.add(abbr)
-        return text
+            m = self._patterns[abbr].search(text)
+            if m and (best is None or m.start() < best[0]):
+                best = (m.start(), m.end(), abbr)
+
+        if best is None:
+            return (TextNode(text),) if text else ()
+
+        start, end, abbr = best
+        self._expanded_list.append(abbr)
+        self._expanded_set.add(abbr)
+        number = len(self._expanded_list)  # 1-based
+        nodes: list[IRNode] = []
+        if text[:start]:
+            nodes.append(TextNode(text[:start]))
+        nodes.append(AbbrevFootnoteNode(abbr=abbr, definition=self.abbrevs[abbr], number=number))
+        nodes.extend(self.expand_to_nodes(text[end:]))
+        return tuple(nodes)
 
 
 # ── Block-level transform ─────────────────────────────────────────────────────
@@ -151,22 +171,25 @@ def _transform_table_cell(cell: TableCell, state: _State) -> TableCell:
 
 
 def _inline(nodes: tuple[IRNode, ...], state: _State, safe: bool) -> tuple[IRNode, ...]:
-    return tuple(_transform_inline(n, state, safe) for n in nodes)
+    result: list[IRNode] = []
+    for n in nodes:
+        result.extend(_transform_inline(n, state, safe))
+    return tuple(result)
 
 
-def _transform_inline(node: IRNode, state: _State, safe: bool) -> IRNode:
+def _transform_inline(node: IRNode, state: _State, safe: bool) -> tuple[IRNode, ...]:
     if isinstance(node, TextNode):
-        return TextNode(state.expand_text(node.text)) if safe else node
+        return state.expand_to_nodes(node.text) if safe else (node,)
 
     if isinstance(node, (BoldNode, ItalicNode, StrikethroughNode)):
-        return replace(node, children=_inline(node.children, state, safe))
+        return (replace(node, children=_inline(node.children, state, safe)),)
 
     if isinstance(node, LinkNode):
         # Expanding inside link text could break the anchor label — skip.
-        return replace(node, children=_inline(node.children, state, safe=False))
+        return (replace(node, children=_inline(node.children, state, safe=False)),)
 
     # CodeInlineNode, ImageNode — never expand.
-    return node
+    return (node,)
 
 
 # ── Glossary builder ──────────────────────────────────────────────────────────
@@ -181,21 +204,6 @@ def _find_mentioned(text: str, abbrevs: dict[str, str]) -> set[str]:
     }
 
 
-def _build_glossary_section(terms: dict[str, str]) -> tuple[IRNode, ...]:
-    """Return an HR + h6 ``Section`` listing abbreviations that could not be expanded inline."""
-    items = tuple(
-        ListItem(children=(Paragraph(children=(TextNode(f"{abbr} — {defn}"),)),))
-        for abbr, defn in sorted(terms.items())
-    )
-    section = Section(
-        level=6,
-        anchor="glossary",
-        title=(TextNode("Glossary"),),
-        children=(BulletList(items=items),),
-    )
-    return (HorizontalRule(), section)
-
-
 # ── Public API ────────────────────────────────────────────────────────────────
 
 
@@ -213,13 +221,15 @@ def apply_abbreviations(
                     :func:`~mkdocs_to_confluence.preprocess.abbrevs.extract_abbreviations`.
         page_text:  The preprocessed page text (after stripping abbreviation
                     definition lines) used to detect which abbreviations are
-                    actually present on the page.  Used to determine which
-                    abbreviations need a glossary entry.
+                    actually present on the page.
 
     Returns:
-        Modified node tuple.  A ``Glossary`` section is appended if any
-        abbreviation was detected in *page_text* but could not be expanded
-        inline (e.g. it only appeared in headings or table headers).
+        Modified node tuple.  Abbreviations in body text receive an inline
+        superscript anchor-link (:class:`AbbrevFootnoteNode`).  An
+        :class:`AbbrevGlossaryBlock` is appended when any abbreviation was
+        mentioned on the page, listing all footnoted entries (with anchor
+        targets for the back-links) plus any abbreviations that only appeared
+        in headings or other non-expandable contexts.
     """
     if not abbrevs:
         return nodes
@@ -228,12 +238,17 @@ def apply_abbreviations(
     transformed = tuple(_transform_block(n, state) for n in nodes)
 
     mentioned = _find_mentioned(page_text, abbrevs)
-    glossary_needed = {
-        abbr: abbrevs[abbr]
-        for abbr in mentioned
-    }
+    footnoted = tuple(
+        AbbrevFootnoteNode(abbr=abbr, definition=abbrevs[abbr], number=i + 1)
+        for i, abbr in enumerate(state._expanded_list)
+    )
+    extras = tuple(
+        (abbr, abbrevs[abbr])
+        for abbr in sorted(mentioned - state._expanded_set)
+    )
 
-    if glossary_needed:
-        transformed = transformed + _build_glossary_section(glossary_needed)
+    if footnoted or extras:
+        transformed = transformed + (AbbrevGlossaryBlock(footnoted=footnoted, extras=extras),)
 
     return transformed
+

{mkdocs2confluence-0.7.9 → mkdocs2confluence-0.7.11}/tests/test_abbrevs.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 from mkdocs_to_confluence.ir.nodes import (
+    AbbrevFootnoteNode,
+    AbbrevGlossaryBlock,
     Admonition,
     BoldNode,
-    BulletList,
     CodeBlock,
-    HorizontalRule,
     LinkNode,
     Paragraph,
     Section,
@@ -81,26 +81,42 @@ def _para(text: str) -> Paragraph:
     return Paragraph(children=(TextNode(text),))
 
 
-def test_expands_first_occurrence_in_paragraph():
+def test_expands_first_occurrence_as_footnote():
     abbrevs = {"IAM": "Identity and Access Management"}
     nodes = (_para("The IAM platform handles IAM requests."),)
     result = apply_abbreviations(nodes, abbrevs, page_text="The IAM platform handles IAM requests.")
     para = result[0]
     assert isinstance(para, Paragraph)
-    text = para.children[0].text  # type: ignore[union-attr]
-    assert "IAM (Identity and Access Management)" in text
-    # Second occurrence not expanded
-    assert text.count("IAM (Identity and Access Management)") == 1
-    assert text.endswith("IAM requests.")
+    children = para.children
+    # TextNode("The ") + AbbrevFootnoteNode + TextNode(" platform handles IAM requests.")
+    assert len(children) == 3
+    assert isinstance(children[0], TextNode) and children[0].text == "The "
+    fn = children[1]
+    assert isinstance(fn, AbbrevFootnoteNode)
+    assert fn.abbr == "IAM"
+    assert fn.definition == "Identity and Access Management"
+    assert fn.number == 1
+    # Second occurrence left as plain text
+    assert isinstance(children[2], TextNode)
+    assert "IAM requests." in children[2].text
+    # Glossary block appended
+    glossary = result[1]
+    assert isinstance(glossary, AbbrevGlossaryBlock)
+    assert glossary.footnoted[0].abbr == "IAM"
+    assert glossary.footnoted[0].number == 1
 
 
 def test_expands_multiple_different_abbrevs():
     abbrevs = {"IAM": "Identity and Access Management", "RBAC": "Role-Based Access Control"}
     nodes = (_para("Use IAM and RBAC for access control."),)
     result = apply_abbreviations(nodes, abbrevs, page_text="Use IAM and RBAC for access control.")
-    text = result[0].children[0].text  # type: ignore[union-attr]
-    assert "IAM (Identity and Access Management)" in text
-    assert "RBAC (Role-Based Access Control)" in text
+    para = result[0]
+    footnotes = [c for c in para.children if isinstance(c, AbbrevFootnoteNode)]
+    abbrs = {fn.abbr for fn in footnotes}
+    assert "IAM" in abbrs
+    assert "RBAC" in abbrs
+    numbers = sorted(fn.number for fn in footnotes)
+    assert numbers == [1, 2]
 
 
 def test_no_expand_when_no_abbrevs():
@@ -111,173 +127,110 @@ def test_no_expand_when_no_abbrevs():
 
 def test_no_expand_in_section_heading():
     abbrevs = {"IAM": "Identity and Access Management"}
-    section = Section(
-        level=2,
-        anchor="iam",
-        title=(TextNode("IAM Platform"),),
-        children=(),
-    )
+    section = Section(level=2, anchor="iam", title=(TextNode("IAM Platform"),), children=())
     result = apply_abbreviations((section,), abbrevs, page_text="IAM Platform")
     heading_text = result[0].title[0].text  # type: ignore[union-attr]
-    assert heading_text == "IAM Platform"  # not expanded
+    assert heading_text == "IAM Platform"  # not annotated
 
 
-def test_glossary_appended_for_heading_only_abbrev():
+def test_glossary_block_appended_for_heading_only_abbrev():
     abbrevs = {"IAM": "Identity and Access Management"}
-    section = Section(
-        level=2,
-        anchor="iam",
-        title=(TextNode("IAM Platform"),),
-        children=(),
-    )
+    section = Section(level=2, anchor="iam", title=(TextNode("IAM Platform"),), children=())
     result = apply_abbreviations((section,), abbrevs, page_text="IAM Platform")
-    # An HR separator and a Glossary section should be appended
-    assert len(result) == 3
-    assert isinstance(result[1], HorizontalRule)
-    glossary = result[2]
-    assert isinstance(glossary, Section)
-    assert glossary.anchor == "glossary"
-    assert glossary.level == 6
-    # Glossary should list the term
-    bullet_list = glossary.children[0]
-    assert isinstance(bullet_list, BulletList)
-    item_text = bullet_list.items[0].children[0].children[0].text  # type: ignore[union-attr]
-    assert "IAM" in item_text
-    assert "Identity and Access Management" in item_text
-
-
-def test_no_glossary_when_abbrev_expanded_inline():
+    assert len(result) == 2
+    glossary = result[1]
+    assert isinstance(glossary, AbbrevGlossaryBlock)
+    assert len(glossary.footnoted) == 0
+    assert glossary.extras == (("IAM", "Identity and Access Management"),)
+
+
+def test_no_glossary_when_abbrev_footnoted_inline():
     abbrevs = {"IAM": "Identity and Access Management"}
     nodes = (_para("The IAM platform."),)
     result = apply_abbreviations(nodes, abbrevs, page_text="The IAM platform.")
-    # Expanded inline, but also added to glossary for bottom-of-page reference
-    assert len(result) == 3
-    assert isinstance(result[1], HorizontalRule)
-    glossary = result[-1]
-    assert isinstance(glossary, Section)
-    assert glossary.anchor == "glossary"
+    assert len(result) == 2
+    assert isinstance(result[1], AbbrevGlossaryBlock)
+    assert len(result[1].extras) == 0
 
 
 def test_no_expand_in_table_header_cell():
     abbrevs = {"API": "Application Programming Interface"}
-    header = TableRow(cells=(
-        TableCell(children=(TextNode("API Endpoint"),), is_header=True),
-    ))
-    body = TableRow(cells=(
-        TableCell(children=(TextNode("The API docs"),), is_header=False),
-    ))
+    header = TableRow(cells=(TableCell(children=(TextNode("API Endpoint"),), is_header=True),))
+    body = TableRow(cells=(TableCell(children=(TextNode("The API docs"),), is_header=False),))
     table = Table(header=header, rows=(body,))
     result = apply_abbreviations((table,), abbrevs, page_text="API Endpoint The API docs")
-
-    # Header cell: not expanded
     header_text = result[0].header.cells[0].children[0].text  # type: ignore[union-attr]
     assert header_text == "API Endpoint"
-
-    # Body cell: first occurrence expanded
-    body_text = result[0].rows[0].cells[0].children[0].text  # type: ignore[union-attr]
-    assert "API (Application Programming Interface)" in body_text
+    body_children = result[0].rows[0].cells[0].children  # type: ignore[union-attr]
+    assert any(isinstance(c, AbbrevFootnoteNode) and c.abbr == "API" for c in body_children)
 
 
 def test_no_expand_in_admonition_title():
     abbrevs = {"TLS": "Transport Layer Security"}
     admonition = Admonition(
-        kind="note",
-        title="TLS Configuration",
+        kind="note", title="TLS Configuration",
         children=(_para("Use TLS for encryption."),),
     )
     result = apply_abbreviations((admonition,), abbrevs, page_text="TLS Configuration Use TLS for encryption.")
-    # Title is str, unchanged
     assert result[0].title == "TLS Configuration"  # type: ignore[union-attr]
-    # Body paragraph: expanded
-    body_text = result[0].children[0].children[0].text  # type: ignore[union-attr]
-    assert "TLS (Transport Layer Security)" in body_text
+    body_children = result[0].children[0].children  # type: ignore[union-attr]
+    assert any(isinstance(c, AbbrevFootnoteNode) and c.abbr == "TLS" for c in body_children)
 
 
 def test_no_expand_in_code_block():
     abbrevs = {"SQL": "Structured Query Language"}
     code = CodeBlock(code="SELECT * FROM SQL_table", language="sql")
-    nodes = (code,)
-    result = apply_abbreviations(nodes, abbrevs, page_text="SELECT * FROM SQL_table")
-    assert result[0].code == "SELECT * FROM SQL_table"
+    result = apply_abbreviations((code,), abbrevs, page_text="SELECT * FROM SQL_table")
+    assert result[0].code == "SELECT * FROM SQL_table"  # type: ignore[union-attr]
 
 
 def test_no_expand_in_link_text():
     abbrevs = {"CLI": "Command Line Interface"}
-    link = LinkNode(
-        href="https://example.com",
-        children=(TextNode("CLI tools"),),
-    )
-    para = Paragraph(children=(link,))
-    result = apply_abbreviations((para,), abbrevs, page_text="CLI tools")
-    link_text = result[0].children[0].children[0].text  # type: ignore[union-attr]
-    assert link_text == "CLI tools"  # not expanded inside link
+    link = LinkNode(href="https://example.com", children=(TextNode("CLI tools"),))
+    result = apply_abbreviations((Paragraph(children=(link,)),), abbrevs, page_text="CLI tools")
+    assert result[0].children[0].children[0].text == "CLI tools"  # type: ignore[union-attr]
 
 
 def test_expands_inside_bold():
     abbrevs = {"CI": "Continuous Integration"}
     bold = BoldNode(children=(TextNode("CI pipeline"),))
-    para = Paragraph(children=(bold,))
-    result = apply_abbreviations((para,), abbrevs, page_text="CI pipeline")
-    bold_text = result[0].children[0].children[0].text  # type: ignore[union-attr]
-    assert "CI (Continuous Integration)" in bold_text
+    result = apply_abbreviations((Paragraph(children=(bold,)),), abbrevs, page_text="CI pipeline")
+    bold_children = result[0].children[0].children  # type: ignore[union-attr]
+    assert any(isinstance(c, AbbrevFootnoteNode) and c.abbr == "CI" for c in bold_children)
 
 
 def test_word_boundary_not_partial_match():
     abbrevs = {"API": "Application Programming Interface"}
     nodes = (_para("The RAPID response via API."),)
     result = apply_abbreviations(nodes, abbrevs, page_text="The RAPID response via API.")
-    text = result[0].children[0].text  # type: ignore[union-attr]
-    # RAPID should not be touched; API should be expanded
-    assert "RAPID" in text
-    assert "API (Application Programming Interface)" in text
+    para = result[0]
+    all_text = "".join(c.text for c in para.children if isinstance(c, TextNode))
+    assert "RAPID" in all_text
+    assert any(isinstance(c, AbbrevFootnoteNode) and c.abbr == "API" for c in para.children)
 
 
-def test_glossary_includes_inline_expanded_abbrevs():
-    # Abbreviations expanded inline should ALSO appear in the glossary,
-    # so readers who jump directly to the bottom have a full reference.
+def test_footnoted_abbrevs_not_in_extras():
     abbrevs = {"API": "Application Programming Interface", "IAM": "Identity and Access Management"}
     nodes = (_para("Use the API and IAM to authenticate."),)
-    result = apply_abbreviations(
-        nodes, abbrevs,
-        page_text="Use the API and IAM to authenticate."
-    )
-    # Both should be expanded inline...
-    body_text = result[0].children[0].text  # type: ignore[union-attr]
-    assert "API (Application Programming Interface)" in body_text
-    assert "IAM (Identity and Access Management)" in body_text
-    # ...AND both should appear in the glossary at the bottom.
-    assert len(result) == 3
-    assert isinstance(result[1], HorizontalRule)
-    glossary = result[-1]
-    assert isinstance(glossary, Section)
-    items = glossary.children[0].items  # type: ignore[union-attr]
-    labels = " ".join(item.children[0].children[0].text for item in items)  # type: ignore[union-attr]
-    assert "API" in labels
-    assert "IAM" in labels
+    result = apply_abbreviations(nodes, abbrevs, page_text="Use the API and IAM to authenticate.")
+    assert len(result) == 2
+    glossary = result[1]
+    assert isinstance(glossary, AbbrevGlossaryBlock)
+    assert {fn.abbr for fn in glossary.footnoted} == {"API", "IAM"}
+    assert len(glossary.extras) == 0
 
 
 def test_abbrev_not_in_text_produces_no_glossary():
     abbrevs = {"XYZ": "Some Definition"}
-    nodes = (_para("Nothing relevant here."),)
-    result = apply_abbreviations(nodes, abbrevs, page_text="Nothing relevant here.")
-    # XYZ never mentioned → no glossary
+    result = apply_abbreviations((_para("Nothing relevant here."),), abbrevs, page_text="Nothing relevant here.")
     assert len(result) == 1
 
 
-def test_glossary_entries_sorted_alphabetically():
+def test_extras_sorted_alphabetically():
     abbrevs = {"RBAC": "Role-Based Access Control", "IAM": "Identity and Access Management"}
-    # Both only in heading (unsafe), so both go to glossary
-    section = Section(
-        level=1,
-        anchor="overview",
-        title=(TextNode("IAM and RBAC Overview"),),
-        children=(),
-    )
-    result = apply_abbreviations(
-        (section,), abbrevs, page_text="IAM and RBAC Overview"
-    )
+    section = Section(level=1, anchor="overview", title=(TextNode("IAM and RBAC Overview"),), children=())
+    result = apply_abbreviations((section,), abbrevs, page_text="IAM and RBAC Overview")
     glossary = result[-1]
-    assert isinstance(glossary, Section)
-    items = glossary.children[0].items  # type: ignore[union-attr]
-    labels = [item.children[0].children[0].text for item in items]  # type: ignore[union-attr]
-    assert labels == sorted(labels)
+    assert isinstance(glossary, AbbrevGlossaryBlock)
+    extra_abbrs = [abbr for abbr, _ in glossary.extras]
+    assert extra_abbrs == sorted(extra_abbrs)