markdown-to-confluence 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

md2conf/converter.py

@@ -8,26 +8,27 @@ Copyright 2022-2025, Levente Hunyadi
 
 # mypy: disable-error-code="dict-item"
 
+import dataclasses
 import hashlib
 import importlib.resources as resources
 import logging
 import os.path
 import re
 import uuid
-import xml.etree.ElementTree
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Literal, Optional, Union
 from urllib.parse import ParseResult, quote_plus, urlparse, urlunparse
 
 import lxml.etree as ET
-import markdown
 from lxml.builder import ElementMaker
 from strong_typing.core import JsonType
 
+from . import drawio, mermaid
 from .collection import ConfluencePageCollection
+from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .extra import path_relative_to
-from .mermaid import render_diagram
+from .markdown import markdown_to_html
 from .metadata import ConfluenceSiteMetadata
 from .properties import PageError
 from .scanner import ScannedDocument, Scanner
@@ -39,6 +40,17 @@ namespaces = {
 for key, value in namespaces.items():
     ET.register_namespace(key, value)
 
+
+def get_volatile_attributes() -> list[ET.QName]:
+    "Returns a list of volatile attributes that frequently change as a Confluence storage format XHTML document is updated."
+
+    return [
+        ET.QName(namespaces["ac"], "local-id"),
+        ET.QName(namespaces["ac"], "macro-id"),
+        ET.QName(namespaces["ri"], "version-at-save"),
+    ]
+
+
 HTML = ElementMaker()
 AC = ElementMaker(namespace=namespaces["ac"])
 RI = ElementMaker(namespace=namespaces["ri"])
@@ -88,55 +100,6 @@ def encode_title(text: str) -> str:
     return quote_plus(text.strip())
 
 
-def emoji_generator(
-    index: str,
-    shortname: str,
-    alias: Optional[str],
-    uc: Optional[str],
-    alt: str,
-    title: Optional[str],
-    category: Optional[str],
-    options: dict[str, Any],
-    md: markdown.Markdown,
-) -> xml.etree.ElementTree.Element:
-    name = (alias or shortname).strip(":")
-    span = xml.etree.ElementTree.Element("span", {"data-emoji-shortname": name})
-    if uc is not None:
-        span.attrib["data-emoji-unicode"] = uc
-
-        # convert series of Unicode code point hexadecimal values into characters
-        span.text = "".join(chr(int(item, base=16)) for item in uc.split("-"))
-    else:
-        span.text = alt
-    return span
-
-
-def markdown_to_html(content: str) -> str:
-    return markdown.markdown(
-        content,
-        extensions=[
-            "admonition",
-            "markdown.extensions.tables",
-            # "markdown.extensions.fenced_code",
-            "pymdownx.emoji",
-            "pymdownx.highlight",  # required by `pymdownx.superfences`
-            "pymdownx.magiclink",
-            "pymdownx.superfences",
-            "pymdownx.tilde",
-            "sane_lists",
-            "md_in_html",
-        ],
-        extension_configs={
-            "pymdownx.emoji": {
-                "emoji_generator": emoji_generator,
-            },
-            "pymdownx.highlight": {
-                "use_pygments": False,
-            },
-        },
-    )
-
-
 def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
     """
     Creates a fragment of several XML nodes from their string representation wrapped in a root element.
@@ -285,8 +248,8 @@ def title_to_identifier(title: str) -> str:
     "Converts a section heading title to a GitHub-style Markdown same-page anchor."
 
     s = title.strip().lower()
-    s = re.sub("[^ A-Za-z0-9]", "", s)
-    s = s.replace(" ", "-")
+    s = re.sub(r"[^\sA-Za-z0-9_\-]", "", s)
+    s = re.sub(r"\s+", "-", s)
     return s
 
 
@@ -296,6 +259,13 @@ def element_to_text(node: ET._Element) -> str:
     return "".join(node.itertext()).strip()
 
 
+@dataclass
+class ImageAttributes:
+    caption: Optional[str]
+    width: Optional[str]
+    height: Optional[str]
+
+
 @dataclass
 class TableOfContentsEntry:
     level: int
@@ -346,6 +316,8 @@ class ConfluenceConverterOptions:
         plain text; when false, raise an exception.
     :param heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
         conversion rules for the identifier.
+    :param prefer_raster: Whether to choose PNG files over SVG files when available.
+    :param render_drawio: Whether to pre-render (or use the pre-rendered version of) draw.io diagrams.
     :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
     :param diagram_output_format: Target image format for diagrams.
     :param webui_links: When true, convert relative URLs to Confluence Web UI links.
@@ -353,13 +325,15 @@ class ConfluenceConverterOptions:
 
     ignore_invalid_url: bool = False
     heading_anchors: bool = False
+    prefer_raster: bool = True
+    render_drawio: bool = False
     render_mermaid: bool = False
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False
 
 
 class ConfluenceStorageFormatConverter(NodeVisitor):
-    "Transforms a plain HTML tree into the Confluence storage format."
+    "Transforms a plain HTML tree into Confluence Storage Format."
 
     options: ConfluenceConverterOptions
     path: Path
@@ -397,6 +371,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         self.page_metadata = page_metadata
 
     def _transform_heading(self, heading: ET._Element) -> None:
+        "Adds anchors to headings in the same document (if *heading anchors* is enabled)."
+
         for e in heading:
             self.visit(e)
 
@@ -427,6 +403,14 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             raise DocumentError(msg)
 
     def _transform_link(self, anchor: ET._Element) -> Optional[ET._Element]:
+        """
+        Transforms links (HTML anchor `<a>`).
+
+        * Absolute URLs are left intact.
+        * Links to headings in the same document are transformed into `<ac:link>` (if *heading anchors* is enabled).
+        * Links to documents in the source hierarchy are mapped into full Confluence URLs.
+        """
+
         url = anchor.attrib.get("href")
         if url is None or is_absolute_url(url):
             return None
@@ -451,7 +435,6 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 link_wrapper.tail = anchor.tail
                 return link_wrapper
             else:
-                anchor.attrib["href"] = url
                 return None
 
         # convert the relative URL to absolute URL based on the base path value, then look up
@@ -474,7 +457,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 raise DocumentError(msg)
 
         relative_path = os.path.relpath(absolute_path, self.base_dir)
-        LOGGER.debug("found link to page %s with metadata: %s", relative_path, link_metadata)
+        LOGGER.debug("Found link to page %s with metadata: %s", relative_path, link_metadata)
         self.links.append(url)
 
         if self.options.webui_links:
@@ -502,32 +485,46 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         return None
 
     def _transform_image(self, image: ET._Element) -> ET._Element:
+        "Inserts an attached or external image."
+
         src = image.attrib.get("src")
 
         if not src:
             raise DocumentError("image lacks `src` attribute")
 
-        attributes: dict[str, Any] = {
-            ET.QName(namespaces["ac"], "align"): "center",
-            ET.QName(namespaces["ac"], "layout"): "center",
-        }
+        caption = image.attrib.get("alt")
         width = image.attrib.get("width")
-        if width is not None:
-            attributes.update({ET.QName(namespaces["ac"], "width"): width})
         height = image.attrib.get("height")
-        if height is not None:
-            attributes.update({ET.QName(namespaces["ac"], "height"): height})
-
-        caption = image.attrib.get("alt")
+        attrs = ImageAttributes(caption, width, height)
 
         if is_absolute_url(src):
-            return self._transform_external_image(src, caption, attributes)
+            return self._transform_external_image(src, attrs)
         else:
-            return self._transform_attached_image(Path(src), caption, attributes)
+            path = Path(src)
+
+            absolute_path = self._verify_image_path(path)
+            if absolute_path is None:
+                return self._create_missing(path, caption)
 
-    def _transform_external_image(self, url: str, caption: Optional[str], attributes: dict[str, Any]) -> ET._Element:
+            if absolute_path.name.endswith(".drawio.png") or absolute_path.name.endswith(".drawio.svg"):
+                return self._transform_drawio_image(absolute_path, attrs)
+            elif absolute_path.name.endswith(".drawio.xml") or absolute_path.name.endswith(".drawio"):
+                return self._transform_drawio(absolute_path, attrs)
+            else:
+                return self._transform_attached_image(absolute_path, attrs)
+
+    def _transform_external_image(self, url: str, attrs: ImageAttributes) -> ET._Element:
         "Emits Confluence Storage Format XHTML for an external image."
 
+        attributes: dict[str, Any] = {
+            ET.QName(namespaces["ac"], "align"): "center",
+            ET.QName(namespaces["ac"], "layout"): "center",
+        }
+        if attrs.width is not None:
+            attributes.update({ET.QName(namespaces["ac"], "width"): attrs.width})
+        if attrs.height is not None:
+            attributes.update({ET.QName(namespaces["ac"], "height"): attrs.height})
+
         elements: list[ET._Element] = []
         elements.append(
             RI(
@@ -536,33 +533,84 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 {ET.QName(namespaces["ri"], "value"): url},
             )
         )
-        if caption is not None:
-            elements.append(AC("caption", HTML.p(caption)))
+        if attrs.caption is not None:
+            elements.append(AC("caption", HTML.p(attrs.caption)))
 
         return AC("image", attributes, *elements)
 
-    def _transform_attached_image(self, path: Path, caption: Optional[str], attributes: dict[str, Any]) -> ET._Element:
-        "Emits Confluence Storage Format XHTML for an attached image."
+    def _verify_image_path(self, path: Path) -> Optional[Path]:
+        "Checks whether an image path is safe to use."
 
         # resolve relative path into absolute path w.r.t. base dir
         absolute_path = (self.base_dir / path).resolve()
 
-        if absolute_path.exists():
+        if not absolute_path.exists():
+            self._warn_or_raise(f"path to image {path} does not exist")
+            return None
+
+        if not is_directory_within(absolute_path, self.root_dir):
+            self._warn_or_raise(f"path to image {path} points to outside root path {self.root_dir}")
+            return None
+
+        return absolute_path
+
+    def _transform_attached_image(self, absolute_path: Path, attrs: ImageAttributes) -> ET._Element:
+        "Emits Confluence Storage Format XHTML for an attached raster or vector image."
+
+        if self.options.prefer_raster and absolute_path.name.endswith(".svg"):
             # prefer PNG over SVG; Confluence displays SVG in wrong size, and text labels are truncated
-            if absolute_path.suffix == ".svg":
-                png_file = absolute_path.with_suffix(".png")
-                if png_file.exists():
-                    absolute_path = png_file
-
-            if is_directory_within(absolute_path, self.root_dir):
-                self.images.append(absolute_path)
-                image_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
-            else:
-                image_name = ""
-                self._warn_or_raise(f"path to image {path} points to outside root path {self.root_dir}")
+            png_file = absolute_path.with_suffix(".png")
+            if png_file.exists():
+                absolute_path = png_file
+
+        self.images.append(absolute_path)
+        image_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
+        return self._create_attached_image(image_name, attrs)
+
+    def _transform_drawio(self, absolute_path: Path, attrs: ImageAttributes) -> ET._Element:
+        "Emits Confluence Storage Format XHTML for a draw.io diagram."
+
+        if not absolute_path.name.endswith(".drawio.xml") and not absolute_path.name.endswith(".drawio"):
+            raise DocumentError("invalid image format; expected: `*.drawio.xml` or `*.drawio`")
+
+        if self.options.render_drawio:
+            image_data = drawio.render_diagram(absolute_path, self.options.diagram_output_format)
+            image_hash = hashlib.md5(image_data).hexdigest()
+            image_filename = attachment_name(f"embedded_{image_hash}.{self.options.diagram_output_format}")
+            self.embedded_images[image_filename] = image_data
+            return self._create_attached_image(image_filename, attrs)
         else:
-            image_name = ""
-            self._warn_or_raise(f"path to image {path} does not exist")
+            self.images.append(absolute_path)
+            image_filename = attachment_name(path_relative_to(absolute_path, self.base_dir))
+            return self._create_drawio(image_filename, attrs)
+
+    def _transform_drawio_image(self, absolute_path: Path, attrs: ImageAttributes) -> ET._Element:
+        "Emits Confluence Storage Format XHTML for a draw.io diagram embedded in a PNG or SVG image."
+
+        if not absolute_path.name.endswith(".drawio.png") and not absolute_path.name.endswith(".drawio.svg"):
+            raise DocumentError("invalid image format; expected: `*.drawio.png` or `*.drawio.svg`")
+
+        if self.options.render_drawio:
+            return self._transform_attached_image(absolute_path, attrs)
+        else:
+            # extract embedded editable diagram and upload as *.drawio
+            image_data = drawio.extract_diagram(absolute_path)
+            image_filename = attachment_name(path_relative_to(absolute_path.with_suffix(".xml"), self.base_dir))
+            self.embedded_images[image_filename] = image_data
+
+            return self._create_drawio(image_filename, attrs)
+
+    def _create_attached_image(self, image_name: str, attrs: ImageAttributes) -> ET._Element:
+        "An image embedded into the page, linking to an attachment."
+
+        attributes: dict[str, Any] = {
+            ET.QName(namespaces["ac"], "align"): "center",
+            ET.QName(namespaces["ac"], "layout"): "center",
+        }
+        if attrs.width is not None:
+            attributes.update({ET.QName(namespaces["ac"], "width"): attrs.width})
+        if attrs.height is not None:
+            attributes.update({ET.QName(namespaces["ac"], "height"): attrs.height})
 
         elements: list[ET._Element] = []
         elements.append(
@@ -572,12 +620,80 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 {ET.QName(namespaces["ri"], "filename"): image_name},
             )
         )
-        if caption is not None:
-            elements.append(AC("caption", HTML.p(caption)))
+        if attrs.caption is not None:
+            elements.append(AC("caption", HTML.p(attrs.caption)))
 
         return AC("image", attributes, *elements)
 
-    def _transform_block(self, code: ET._Element) -> ET._Element:
+    def _create_drawio(self, filename: str, attrs: ImageAttributes) -> ET._Element:
+        "A draw.io diagram embedded into the page, linking to an attachment."
+
+        parameters: list[ET._Element] = [
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): "diagramName"},
+                filename,
+            ),
+        ]
+        if attrs.width is not None:
+            parameters.append(
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): "width"},
+                    attrs.width,
+                ),
+            )
+        if attrs.height is not None:
+            parameters.append(
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): "height"},
+                    attrs.height,
+                ),
+            )
+
+        local_id = str(uuid.uuid4())
+        macro_id = str(uuid.uuid4())
+        return AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "drawio",
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+                "data-layout": "default",
+                ET.QName(namespaces["ac"], "local-id"): local_id,
+                ET.QName(namespaces["ac"], "macro-id"): macro_id,
+            },
+            *parameters,
+        )
+
+    def _create_missing(self, path: Path, caption: Optional[str]) -> ET._Element:
+        "A warning panel for a missing image."
+
+        message = HTML.p("Missing image: ", HTML.code(path.as_posix()))
+        if caption is not None:
+            content = [
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): "title"},
+                    caption,
+                ),
+                AC("rich-text-body", {}, message),
+            ]
+        else:
+            content = [AC("rich-text-body", {}, message)]
+
+        return AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "warning",
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+            },
+            *content,
+        )
+
+    def _transform_code_block(self, code: ET._Element) -> ET._Element:
+        "Transforms a code block."
+
         language = code.attrib.get("class")
         if language:
             m = re.match("^language-(.*)$", language)
@@ -616,21 +732,11 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         "Transforms a Mermaid diagram code block."
 
         if self.options.render_mermaid:
-            image_data = render_diagram(content, self.options.diagram_output_format)
+            image_data = mermaid.render_diagram(content, self.options.diagram_output_format)
             image_hash = hashlib.md5(image_data).hexdigest()
             image_filename = attachment_name(f"embedded_{image_hash}.{self.options.diagram_output_format}")
             self.embedded_images[image_filename] = image_data
-            return AC(
-                "image",
-                {
-                    ET.QName(namespaces["ac"], "align"): "center",
-                    ET.QName(namespaces["ac"], "layout"): "center",
-                },
-                RI(
-                    "attachment",
-                    {ET.QName(namespaces["ri"], "filename"): image_filename},
-                ),
-            )
+            return self._create_attached_image(image_filename, ImageAttributes(None, None, None))
         else:
             local_id = str(uuid.uuid4())
             macro_id = str(uuid.uuid4())
@@ -639,7 +745,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 {
                     ET.QName(namespaces["ac"], "name"): "macro-diagram",
                     ET.QName(namespaces["ac"], "schema-version"): "1",
-                    ET.QName(namespaces["ac"], "data-layout"): "default",
+                    "data-layout": "default",
                     ET.QName(namespaces["ac"], "local-id"): local_id,
                     ET.QName(namespaces["ac"], "macro-id"): macro_id,
                 },
@@ -666,6 +772,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             )
 
     def _transform_toc(self, code: ET._Element) -> ET._Element:
+        "Creates a table of contents, constructed from headings in the document."
+
         return AC(
             "structured-macro",
             {
@@ -676,6 +784,19 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             AC("parameter", {ET.QName(namespaces["ac"], "name"): "style"}, "default"),
         )
 
+    def _transform_listing(self, code: ET._Element) -> ET._Element:
+        "Creates a list of child pages."
+
+        return AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "children",
+                ET.QName(namespaces["ac"], "schema-version"): "2",
+                "data-layout": "default",
+            },
+            AC("parameter", {ET.QName(namespaces["ac"], "name"): "allChildren"}, "true"),
+        )
+
     def _transform_admonition(self, elem: ET._Element) -> ET._Element:
         """
         Creates an info, tip, note or warning panel from a Markdown admonition.
@@ -725,6 +846,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         )
 
     def _transform_github_alert(self, elem: ET._Element) -> ET._Element:
+        """
+        Creates a GitHub-style panel, normally triggered with a block-quote starting with a capitalized string such as `[!TIP]`.
+        """
+
         content = elem[0]
         if content.text is None:
             raise DocumentError("empty content")
@@ -753,6 +878,13 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         return self._transform_alert(elem, class_name, skip)
 
     def _transform_gitlab_alert(self, elem: ET._Element) -> ET._Element:
+        """
+        Creates a classic GitLab-style panel.
+
+        Classic panels are defined with a block-quote and text starting with a capitalized string such as `DISCLAIMER:`.
+        This syntax does not use Hugo shortcode.
+        """
+
         content = elem[0]
         if content.text is None:
             raise DocumentError("empty content")
@@ -842,6 +974,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         )
 
     def _transform_emoji(self, elem: ET._Element) -> ET._Element:
+        """
+        Inserts an inline emoji character.
+        """
+
         shortname = elem.attrib.get("data-emoji-shortname", "")
         unicode = elem.attrib.get("data-emoji-unicode", None)
         alt = elem.text or ""
@@ -852,7 +988,6 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         return AC(
             "emoticon",
             {
-                # use "blue-star" as a placeholder name to ensure wiki page loads in timely manner
                 ET.QName(namespaces["ac"], "name"): shortname,
                 ET.QName(namespaces["ac"], "emoji-shortname"): f":{shortname}:",
                 ET.QName(namespaces["ac"], "emoji-id"): unicode,
@@ -860,7 +995,196 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             },
         )
 
+    def _transform_inline_math(self, elem: ET._Element) -> ET._Element:
+        """
+        Creates an inline LaTeX formula using the Confluence extension "LaTeX Math for Confluence - Math Formula & Equations".
+
+        :see: https://help.narva.net/latex-math-for-confluence/
+        """
+
+        content = elem.text or ""
+        if not content:
+            raise DocumentError("empty inline LaTeX formula")
+
+        LOGGER.debug("Found inline LaTeX formula: %s", content)
+
+        local_id = str(uuid.uuid4())
+        macro_id = str(uuid.uuid4())
+        macro = AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "eazy-math-inline",
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+                ET.QName(namespaces["ac"], "local-id"): local_id,
+                ET.QName(namespaces["ac"], "macro-id"): macro_id,
+            },
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): "body"},
+                content,
+            ),
+            AC("parameter", {ET.QName(namespaces["ac"], "name"): "align"}, "center"),
+        )
+        macro.tail = elem.tail  # chain sibling text node that immediately follows original element
+        return macro
+
+    def _transform_block_math(self, elem: ET._Element) -> ET._Element:
+        """
+        Creates a block-level LaTeX formula using the Confluence extension "LaTeX Math for Confluence - Math Formula & Equations".
+
+        :see: https://help.narva.net/latex-math-for-confluence/
+        """
+
+        content = elem.text or ""
+        if not content:
+            raise DocumentError("empty block-level LaTeX formula")
+
+        LOGGER.debug("Found block-level LaTeX formula: %s", content)
+
+        local_id = str(uuid.uuid4())
+        macro_id = str(uuid.uuid4())
+
+        return AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "easy-math-block",
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+                "data-layout": "default",
+                ET.QName(namespaces["ac"], "local-id"): local_id,
+                ET.QName(namespaces["ac"], "macro-id"): macro_id,
+            },
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): "body"},
+                content,
+            ),
+            AC("parameter", {ET.QName(namespaces["ac"], "name"): "align"}, "center"),
+        )
+
+    def _transform_footnote_ref(self, elem: ET._Element) -> None:
+        """
+        Transforms a footnote reference.
+
+        ```
+        <sup id="fnref:NAME"><a class="footnote-ref" href="#fn:NAME">1</a></sup>
+        ```
+        """
+
+        if elem.tag != "sup":
+            raise DocumentError("expected: `<sup>` as the HTML element for a footnote reference")
+
+        ref_id = elem.attrib.pop("id", "")
+        if not ref_id.startswith("fnref:"):
+            raise DocumentError("expected: attribute `id` of format `fnref:NAME` applied on `<sup>` for a footnote reference")
+        footnote_ref = ref_id.removeprefix("fnref:")
+
+        link = elem[0]
+        def_href = link.attrib.pop("href", "")
+        if not def_href.startswith("#fn:"):
+            raise DocumentError("expected: attribute `href` of format `#fn:NAME` applied on `<a>` for a footnote reference")
+        footnote_def = def_href.removeprefix("#fn:")
+
+        text = link.text or ""
+
+        # remove link generated by Python-Markdown
+        elem.remove(link)
+
+        # build new anchor for footnote reference
+        ref_anchor = AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "anchor",
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+            },
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): ""},
+                f"footnote-ref-{footnote_ref}",
+            ),
+        )
+
+        # build new link to footnote definition at the end of page
+        def_link = AC(
+            "link",
+            {
+                ET.QName(namespaces["ac"], "anchor"): f"footnote-def-{footnote_def}",
+            },
+            AC("link-body", ET.CDATA(text)),
+        )
+
+        # append children synthesized for Confluence
+        elem.append(ref_anchor)
+        elem.append(def_link)
+
+    def _transform_footnote_def(self, elem: ET._Element) -> None:
+        """
+        Transforms the footnote definition block.
+
+        ```
+        <div class="footnote">
+            <hr/>
+            <ol>
+                <li id="fn:NAME">
+                    <p>TEXT <a class="footnote-backref" href="#fnref:NAME">↩</a></p>
+                </li>
+            </ol>
+        </div>
+        ```
+        """
+
+        for list_item in elem[1]:
+            def_id = list_item.attrib.pop("id", "")
+            if not def_id.startswith("fn:"):
+                raise DocumentError("expected: attribute `id` of format `fn:NAME` applied on `<li>` for a footnote definition")
+            footnote_def = def_id.removeprefix("fn:")
+
+            paragraph = list_item[0]
+            ref_anchor = paragraph[-1]
+            if ref_anchor.tag != "a":
+                raise DocumentError("expected: `<a>` as the last HTML element in a footnote definition")
+
+            ref_href = ref_anchor.attrib.get("href", "")
+            if not ref_href.startswith("#fnref:"):
+                raise DocumentError("expected: attribute `href` of format `#fnref:NAME` applied on last element `<a>` for a footnote definition")
+            footnote_ref = ref_href.removeprefix("#fnref:")
+
+            # remove back-link generated by Python-Markdown
+            paragraph.remove(ref_anchor)
+
+            # build new anchor for footnote definition
+            def_anchor = AC(
+                "structured-macro",
+                {
+                    ET.QName(namespaces["ac"], "name"): "anchor",
+                    ET.QName(namespaces["ac"], "schema-version"): "1",
+                },
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): ""},
+                    f"footnote-def-{footnote_def}",
+                ),
+            )
+
+            # build new link to footnote reference in page body
+            ref_link = AC(
+                "link",
+                {
+                    ET.QName(namespaces["ac"], "anchor"): f"footnote-ref-{footnote_ref}",
+                },
+                AC("link-body", ET.CDATA("↩")),
+            )
+
+            # append children synthesized for Confluence
+            paragraph.insert(0, def_anchor)
+            def_anchor.tail = paragraph.text
+            paragraph.text = None
+            paragraph.append(ref_link)
+
     def transform(self, child: ET._Element) -> Optional[ET._Element]:
+        """
+        Transforms an HTML element tree obtained from a Markdown document into a Confluence Storage Format element tree.
+        """
+
         # normalize line breaks to regular space in element text
         if child.text:
             text: str = child.text
@@ -893,6 +1217,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         elif child.tag == "p" and "".join(child.itertext()) in ["[[TOC]]", "[TOC]"]:
             return self._transform_toc(child)
 
+        # <p>[[_LISTING_]]</p>
+        elif child.tag == "p" and "".join(child.itertext()) in ["[[LISTING]]", "[LISTING]"]:
+            return self._transform_listing(child)
+
         # <div class="admonition note">
         # <p class="admonition-title">Note</p>
         # <p>...</p>
@@ -943,20 +1271,35 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         # <pre><code class="language-java"> ... </code></pre>
         elif child.tag == "pre" and len(child) == 1 and child[0].tag == "code":
-            return self._transform_block(child[0])
+            return self._transform_code_block(child[0])
 
+        # <span data-emoji-shortname="..." data-emoji-unicode="...">...</span>
         elif child.tag == "span" and child.attrib.has_key("data-emoji-shortname"):
             return self._transform_emoji(child)
 
-        return None
+        # <div class="arithmatex">...</div>
+        elif child.tag == "div" and "arithmatex" in child.attrib.get("class", "").split(" "):
+            return self._transform_block_math(child)
 
+        # <span class="arithmatex">...</span>
+        elif child.tag == "span" and "arithmatex" in child.attrib.get("class", "").split(" "):
+            return self._transform_inline_math(child)
 
-class ConfluenceStorageFormatCleaner(NodeVisitor):
-    "Removes volatile attributes from a Confluence storage format XHTML document."
+        # <sup id="fnref:NAME"><a class="footnote-ref" href="#fn:NAME">1</a></sup>
+        elif child.tag == "sup" and child.attrib.get("id", "").startswith("fnref:"):
+            self._transform_footnote_ref(child)
+            return None
+
+        # <div class="footnote">
+        #   <hr/>
+        #   <ol>
+        #     <li id="fn:NAME"><p>TEXT <a class="footnote-backref" href="#fnref:NAME">↩</a></p></li>
+        #   </ol>
+        # </div>
+        elif child.tag == "div" and "footnote" in child.attrib.get("class", "").split(" "):
+            self._transform_footnote_def(child)
+            return None
 
-    def transform(self, child: ET._Element) -> Optional[ET._Element]:
-        child.attrib.pop(ET.QName(namespaces["ac"], "macro-id"), None)
-        child.attrib.pop(ET.QName(namespaces["ri"], "version-at-save"), None)
         return None
 
 
@@ -964,44 +1307,6 @@ class DocumentError(RuntimeError):
     "Raised when a converted Markdown document has an unexpected element or attribute."
 
 
-@dataclass
-class ConfluencePageID:
-    page_id: str
-
-
-@dataclass
-class ConfluenceQualifiedID:
-    page_id: str
-    space_key: str
-
-
-@dataclass
-class ConfluenceDocumentOptions:
-    """
-    Options that control the generated page content.
-
-    :param ignore_invalid_url: When true, ignore invalid URLs in input, emit a warning and replace the anchor with
-        plain text; when false, raise an exception.
-    :param heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
-        conversion rules for the identifier.
-    :param generated_by: Text to use as the generated-by prompt (or `None` to omit a prompt).
-    :param root_page_id: Confluence page to assume root page role for publishing a directory of Markdown files.
-    :param keep_hierarchy: Whether to maintain source directory structure when exporting to Confluence.
-    :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
-    :param diagram_output_format: Target image format for diagrams.
-    :param webui_links: When true, convert relative URLs to Confluence Web UI links.
-    """
-
-    ignore_invalid_url: bool = False
-    heading_anchors: bool = False
-    generated_by: Optional[str] = "This page has been generated with a tool."
-    root_page_id: Optional[ConfluencePageID] = None
-    keep_hierarchy: bool = False
-    render_mermaid: bool = False
-    diagram_output_format: Literal["png", "svg"] = "png"
-    webui_links: bool = False
-
-
 class ConversionError(RuntimeError):
     "Raised when a Markdown document cannot be converted to Confluence Storage Format."
 
@@ -1079,13 +1384,7 @@ class ConfluenceDocument:
             raise ConversionError(path) from ex
 
         converter = ConfluenceStorageFormatConverter(
-            ConfluenceConverterOptions(
-                ignore_invalid_url=self.options.ignore_invalid_url,
-                heading_anchors=self.options.heading_anchors,
-                render_mermaid=self.options.render_mermaid,
-                diagram_output_format=self.options.diagram_output_format,
-                webui_links=self.options.webui_links,
-            ),
+            ConfluenceConverterOptions(**{field.name: getattr(self.options, field.name) for field in dataclasses.fields(ConfluenceConverterOptions)}),
             path,
             root_dir,
             site_metadata,
@@ -1136,17 +1435,6 @@ def attachment_name(ref: Union[Path, str]) -> str:
     return Path(*parts).as_posix().replace("/", "_")
 
 
-def sanitize_confluence(html: str) -> str:
-    "Generates a sanitized version of a Confluence storage format XHTML document with no volatile attributes."
-
-    if not html:
-        return ""
-
-    root = elements_from_strings([html])
-    ConfluenceStorageFormatCleaner().visit(root)
-    return elements_to_string(root)
-
-
 def elements_to_string(root: ET._Element) -> str:
     xml = ET.tostring(root, encoding="utf8", method="xml").decode("utf8")
     m = re.match(r"^<root\s+[^>]*>(.*)</root>\s*$", xml, re.DOTALL)