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

md2conf/converter.py

@@ -6,60 +6,59 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
-# mypy: disable-error-code="dict-item"
-
 import dataclasses
+import enum
 import hashlib
-import importlib.resources as resources
 import logging
 import os.path
 import re
 import uuid
+from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal, Optional, Union
-from urllib.parse import ParseResult, quote_plus, urlparse, urlunparse
+from typing import ClassVar, Literal, Optional, Union
+from urllib.parse import ParseResult, quote_plus, urlparse
 
 import lxml.etree as ET
-from lxml.builder import ElementMaker
 from strong_typing.core import JsonType
 
 from . import drawio, mermaid
 from .collection import ConfluencePageCollection
+from .csf import AC_ATTR, AC_ELEM, HTML, RI_ATTR, RI_ELEM, ParseError, elements_from_strings, elements_to_string, normalize_inline
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
-from .extra import path_relative_to
+from .extra import override, path_relative_to
+from .latex import get_png_dimensions, remove_png_chunks, render_latex
 from .markdown import markdown_to_html
 from .metadata import ConfluenceSiteMetadata
 from .properties import PageError
 from .scanner import ScannedDocument, Scanner
-
-namespaces = {
-    "ac": "http://atlassian.com/content",
-    "ri": "http://atlassian.com/resource/identifier",
-}
-for key, value in namespaces.items():
-    ET.register_namespace(key, value)
+from .toc import TableOfContentsBuilder
+from .uri import is_absolute_url, to_uuid_urn
+from .xml import element_to_text
 
 
-def get_volatile_attributes() -> list[ET.QName]:
+def get_volatile_attributes() -> list[str]:
     "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"),
+        AC_ATTR("local-id"),
+        AC_ATTR("macro-id"),
+        RI_ATTR("version-at-save"),
     ]
 
 
-HTML = ElementMaker()
-AC = ElementMaker(namespace=namespaces["ac"])
-RI = ElementMaker(namespace=namespaces["ri"])
+def get_volatile_elements() -> list[str]:
+    "Returns a list of volatile elements whose content frequently changes as a Confluence storage format XHTML document is updated."
 
-LOGGER = logging.getLogger(__name__)
+    return [AC_ATTR("task-uuid")]
 
 
-class ParseError(RuntimeError):
-    pass
+status_images: dict[str, str] = {
+    to_uuid_urn(f'<svg height="10" width="10" xmlns="http://www.w3.org/2000/svg"><circle r="5" cx="5" cy="5" fill="{color}" /></svg>'): color
+    for color in ["gray", "purple", "blue", "red", "yellow", "green"]
+}
+
+LOGGER = logging.getLogger(__name__)
 
 
 def starts_with_any(text: str, prefixes: list[str]) -> bool:
@@ -71,16 +70,6 @@ def starts_with_any(text: str, prefixes: list[str]) -> bool:
     return False
 
 
-def is_absolute_url(url: str) -> bool:
-    urlparts = urlparse(url)
-    return bool(urlparts.scheme) or bool(urlparts.netloc)
-
-
-def is_relative_url(url: str) -> bool:
-    urlparts = urlparse(url)
-    return not bool(urlparts.scheme) and not bool(urlparts.netloc)
-
-
 def is_directory_within(absolute_path: Path, base_path: Path) -> bool:
     "True if the absolute path is nested within the base path."
 
@@ -100,132 +89,94 @@ def encode_title(text: str) -> str:
     return quote_plus(text.strip())
 
 
-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.
-
-    :param dtd_path: Path to a DTD document that defines entities like &cent; or &copy;.
-    :param items: Strings to parse into XML fragments.
-    :returns: An XML document as an element tree.
-    """
-
-    parser = ET.XMLParser(
-        remove_blank_text=True,
-        remove_comments=True,
-        strip_cdata=False,
-        load_dtd=True,
-    )
+# supported code block languages, for which syntax highlighting is available
+_LANGUAGES = {
+    "abap": "abap",
+    "actionscript3": "actionscript3",
+    "ada": "ada",
+    "applescript": "applescript",
+    "arduino": "arduino",
+    "autoit": "autoit",
+    "bash": "bash",
+    "c": "c",
+    "c#": "c#",
+    "clojure": "clojure",
+    "coffeescript": "coffeescript",
+    "coldfusion": "coldfusion",
+    "cpp": "cpp",
+    "csharp": "c#",
+    "css": "css",
+    "cuda": "cuda",
+    "d": "d",
+    "dart": "dart",
+    "delphi": "delphi",
+    "diff": "diff",
+    "elixir": "elixir",
+    "erl": "erl",
+    "erlang": "erl",
+    "fortran": "fortran",
+    "foxpro": "foxpro",
+    "go": "go",
+    "graphql": "graphql",
+    "groovy": "groovy",
+    "haskell": "haskell",
+    "haxe": "haxe",
+    "html": "html",
+    "java": "java",
+    "javafx": "javafx",
+    "javascript": "js",
+    "js": "js",
+    "json": "json",
+    "jsx": "jsx",
+    "julia": "julia",
+    "kotlin": "kotlin",
+    "livescript": "livescript",
+    "lua": "lua",
+    "mermaid": "mermaid",
+    "mathematica": "mathematica",
+    "matlab": "matlab",
+    "objectivec": "objectivec",
+    "objectivej": "objectivej",
+    "ocaml": "ocaml",
+    "octave": "octave",
+    "pascal": "pascal",
+    "perl": "perl",
+    "php": "php",
+    "powershell": "powershell",
+    "prolog": "prolog",
+    "puppet": "puppet",
+    "py": "py",
+    "python": "py",
+    "qml": "qml",
+    "r": "r",
+    "racket": "racket",
+    "rst": "rst",
+    "ruby": "ruby",
+    "rust": "rust",
+    "sass": "sass",
+    "scala": "scala",
+    "scheme": "scheme",
+    "shell": "shell",
+    "smalltalk": "smalltalk",
+    "splunk": "splunk",
+    "sql": "sql",
+    "standardml": "standardml",
+    "swift": "swift",
+    "tcl": "tcl",
+    "tex": "tex",
+    "tsx": "tsx",
+    "typescript": "typescript",
+    "vala": "vala",
+    "vb": "vb",
+    "verilog": "verilog",
+    "vhdl": "vhdl",
+    "xml": "xml",
+    "xquery": "xquery",
+    "yaml": "yaml",
+}
 
-    ns_attr_list = "".join(f' xmlns:{key}="{value}"' for key, value in namespaces.items())
 
-    data = [
-        '<?xml version="1.0"?>',
-        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}"><root{ns_attr_list}>',
-    ]
-    data.extend(items)
-    data.append("</root>")
-
-    try:
-        return ET.fromstringlist(data, parser=parser)
-    except ET.XMLSyntaxError as ex:
-        raise ParseError() from ex
-
-
-def elements_from_strings(items: list[str]) -> ET._Element:
-    "Creates a fragment of several XML nodes from their string representation wrapped in a root element."
-
-    resource_path = resources.files(__package__).joinpath("entities.dtd")
-    with resources.as_file(resource_path) as dtd_path:
-        return _elements_from_strings(dtd_path, items)
-
-
-def elements_from_string(content: str) -> ET._Element:
-    return elements_from_strings([content])
-
-
-_languages = [
-    "abap",
-    "actionscript3",
-    "ada",
-    "applescript",
-    "arduino",
-    "autoit",
-    "bash",
-    "c",
-    "clojure",
-    "coffeescript",
-    "coldfusion",
-    "cpp",
-    "csharp",
-    "css",
-    "cuda",
-    "d",
-    "dart",
-    "delphi",
-    "diff",
-    "elixir",
-    "erlang",
-    "fortran",
-    "foxpro",
-    "go",
-    "graphql",
-    "groovy",
-    "haskell",
-    "haxe",
-    "html",
-    "java",
-    "javafx",
-    "javascript",
-    "json",
-    "jsx",
-    "julia",
-    "kotlin",
-    "livescript",
-    "lua",
-    "mermaid",
-    "mathematica",
-    "matlab",
-    "objectivec",
-    "objectivej",
-    "ocaml",
-    "octave",
-    "pascal",
-    "perl",
-    "php",
-    "powershell",
-    "prolog",
-    "puppet",
-    "python",
-    "qml",
-    "r",
-    "racket",
-    "rst",
-    "ruby",
-    "rust",
-    "sass",
-    "scala",
-    "scheme",
-    "shell",
-    "smalltalk",
-    "splunk",
-    "sql",
-    "standardml",
-    "swift",
-    "tcl",
-    "tex",
-    "tsx",
-    "typescript",
-    "vala",
-    "vb",
-    "verilog",
-    "vhdl",
-    "xml",
-    "xquery",
-    "yaml",
-]
-
-
-class NodeVisitor:
+class NodeVisitor(ABC):
     def visit(self, node: ET._Element) -> None:
         "Recursively visits all descendants of this node."
 
@@ -236,12 +187,17 @@ class NodeVisitor:
             source = node[index]
             target = self.transform(source)
             if target is not None:
+                # chain sibling text node that immediately follows original element
+                target.tail = source.tail
+                source.tail = None
+
+                # replace original element with transformed element
                 node[index] = target
             else:
                 self.visit(source)
 
-    def transform(self, child: ET._Element) -> Optional[ET._Element]:
-        pass
+    @abstractmethod
+    def transform(self, child: ET._Element) -> Optional[ET._Element]: ...
 
 
 def title_to_identifier(title: str) -> str:
@@ -253,58 +209,107 @@ def title_to_identifier(title: str) -> str:
     return s
 
 
-def element_to_text(node: ET._Element) -> str:
-    "Returns all text contained in an element as a concatenated string."
+def element_text_starts_with_any(node: ET._Element, prefixes: list[str]) -> bool:
+    "True if the text contained in an element starts with any of the specified prefix strings."
 
-    return "".join(node.itertext()).strip()
+    if node.text is None:
+        return False
+    return starts_with_any(node.text, prefixes)
 
 
-@dataclass
-class ImageAttributes:
-    caption: Optional[str]
-    width: Optional[str]
-    height: Optional[str]
+def is_placeholder_for(node: ET._Element, name: str) -> bool:
+    """
+    Identifies a Confluence widget placeholder, e.g. `[[_TOC_]]` or `[[_LISTING_]]`.
 
+    :param node: The element to check.
+    :param name: The placeholder name.
+    """
 
-@dataclass
-class TableOfContentsEntry:
-    level: int
-    text: str
+    # `[[_TOC_]]` is represented in HTML as <p>[[<em>TOC</em>]]</p>
+    if node.text != "[[" or len(node) != 1:
+        return False
 
+    child = node[0]
+    if child.tag != "em" or child.text != name or child.tail != "]]":
+        return False
 
-class TableOfContents:
-    "Builds a table of contents from Markdown headings."
+    return True
 
-    headings: list[TableOfContentsEntry]
 
-    def __init__(self) -> None:
-        self.headings = []
+@enum.unique
+class FormattingContext(enum.Enum):
+    "Identifies the formatting context for the element."
 
-    def add(self, level: int, text: str) -> None:
-        """
-        Adds a heading to the table of contents.
+    BLOCK = "block"
+    INLINE = "inline"
 
-        :param level: Markdown heading level (e.g. `1` for first-level heading).
-        :param text: Markdown heading text.
-        """
 
-        self.headings.append(TableOfContentsEntry(level, text))
+@dataclass
+class ImageAttributes:
+    """
+    Attributes applied to an `<img>` element.
+
+    :param context: Identifies the formatting context for the element (block or inline).
+    :param width: Natural image width in pixels.
+    :param height: Natural image height in pixels.
+    :param alt: Alternate text.
+    :param title: Title text (a.k.a. image tooltip).
+    :param caption: Caption text (shown below figure).
+    """
 
-    def get_title(self) -> Optional[str]:
-        """
-        Returns a proposed document title (if unique).
+    context: FormattingContext
+    width: Optional[int]
+    height: Optional[int]
+    alt: Optional[str]
+    title: Optional[str]
+    caption: Optional[str]
 
-        :returns: Title text, or `None` if no unique title can be inferred.
-        """
+    def __post_init__(self) -> None:
+        if self.caption is None and self.context is FormattingContext.BLOCK:
+            self.caption = self.title or self.alt
+
+    def as_dict(self) -> dict[str, str]:
+        attributes: dict[str, str] = {}
+        if self.context is FormattingContext.BLOCK:
+            attributes[AC_ATTR("align")] = "center"
+            attributes[AC_ATTR("layout")] = "center"
+            if self.width is not None:
+                attributes[AC_ATTR("original-width")] = str(self.width)
+            if self.height is not None:
+                attributes[AC_ATTR("original-height")] = str(self.height)
+            if self.width is not None:
+                attributes[AC_ATTR("custom-width")] = "true"
+                attributes[AC_ATTR("width")] = str(self.width)
+
+        elif self.context is FormattingContext.INLINE:
+            if self.width is not None:
+                attributes[AC_ATTR("width")] = str(self.width)
+            if self.height is not None:
+                attributes[AC_ATTR("height")] = str(self.height)
+        else:
+            raise NotImplementedError("match not exhaustive for enumeration")
 
-        for level in range(1, 7):
-            try:
-                (title,) = (item.text for item in self.headings if item.level == level)
-                return title
-            except ValueError:
-                pass
+        if self.alt is not None:
+            attributes.update({AC_ATTR("alt"): self.alt})
+        if self.title is not None:
+            attributes.update({AC_ATTR("title"): self.title})
+        return attributes
 
-        return None
+    EMPTY_BLOCK: ClassVar["ImageAttributes"]
+    EMPTY_INLINE: ClassVar["ImageAttributes"]
+
+    @classmethod
+    def empty(cls, context: FormattingContext) -> "ImageAttributes":
+        if context is FormattingContext.BLOCK:
+            return cls.EMPTY_BLOCK
+        elif context is FormattingContext.INLINE:
+            return cls.EMPTY_INLINE
+        else:
+            raise NotImplementedError("match not exhaustive for enumeration")
+
+
+ImageAttributes.EMPTY_BLOCK = ImageAttributes(FormattingContext.BLOCK, None, None, None, None, None)
+ImageAttributes.EMPTY_INLINE = ImageAttributes(FormattingContext.INLINE, None, None, None, None, None)
 
 
 @dataclass
@@ -319,6 +324,7 @@ class ConfluenceConverterOptions:
     :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 render_latex: Whether to pre-render LaTeX formulas 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.
     """
@@ -328,10 +334,23 @@ class ConfluenceConverterOptions:
     prefer_raster: bool = True
     render_drawio: bool = False
     render_mermaid: bool = False
+    render_latex: bool = False
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False
 
 
+@dataclass
+class ImageData:
+    path: Path
+    description: Optional[str] = None
+
+
+@dataclass
+class EmbeddedFileData:
+    data: bytes
+    description: Optional[str] = None
+
+
 class ConfluenceStorageFormatConverter(NodeVisitor):
     "Transforms a plain HTML tree into Confluence Storage Format."
 
@@ -339,10 +358,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     path: Path
     base_dir: Path
     root_dir: Path
-    toc: TableOfContents
+    toc: TableOfContentsBuilder
     links: list[str]
-    images: list[Path]
-    embedded_images: dict[str, bytes]
+    images: list[ImageData]
+    embedded_files: dict[str, EmbeddedFileData]
     site_metadata: ConfluenceSiteMetadata
     page_metadata: ConfluencePageCollection
 
@@ -363,28 +382,40 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         self.path = path
         self.base_dir = path.parent
         self.root_dir = root_dir
-        self.toc = TableOfContents()
+        self.toc = TableOfContentsBuilder()
         self.links = []
         self.images = []
-        self.embedded_images = {}
+        self.embedded_files = {}
         self.site_metadata = site_metadata
         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)."
+        """
+        Adds anchors to headings in the same document (if *heading anchors* is enabled).
+
+        Original:
+        ```
+        <h1>Heading text</h1>
+        ```
+
+        Transformed:
+        ```
+        <h1><structured-macro name="anchor">...</structured-macro>Heading text</h1>
+        ```
+        """
 
         for e in heading:
             self.visit(e)
 
-        anchor = AC(
+        anchor = AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "anchor",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "anchor",
+                AC_ATTR("schema-version"): "1",
             },
-            AC(
+            AC_ELEM(
                 "parameter",
-                {ET.QName(namespaces["ac"], "name"): ""},
+                {AC_ATTR("name"): ""},
                 title_to_identifier(element_to_text(heading)),
             ),
         )
@@ -395,7 +426,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         heading.text = None
 
     def _warn_or_raise(self, msg: str) -> None:
-        "Emit a warning or raise an exception when a path points to a resource that doesn't exist."
+        "Emit a warning or raise an exception when a path points to a resource that doesn't exist or is outside of the permitted hierarchy."
 
         if self.options.ignore_invalid_url:
             LOGGER.warning(msg)
@@ -411,7 +442,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         * Links to documents in the source hierarchy are mapped into full Confluence URLs.
         """
 
-        url = anchor.attrib.get("href")
+        # Confluence doesn't support `title` attribute on `<a>` elements
+        anchor.attrib.pop("title", None)
+
+        url = anchor.get("href")
         if url is None or is_absolute_url(url):
             return None
 
@@ -419,46 +453,52 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         relative_url: ParseResult = urlparse(url)
 
         if not relative_url.scheme and not relative_url.netloc and not relative_url.path and not relative_url.params and not relative_url.query:
-            LOGGER.debug("Found local URL: %s", url)
+            LOGGER.debug("Found same-page URL: %s", url)
             if self.options.heading_anchors:
                 # <ac:link ac:anchor="anchor"><ac:link-body>...</ac:link-body></ac:link>
                 target = relative_url.fragment.lstrip("#")
-                link_body = AC("link-body", {}, *list(anchor))
+                link_body = AC_ELEM("link-body", {}, *list(anchor))
                 link_body.text = anchor.text
-                link_wrapper = AC(
+                link_wrapper = AC_ELEM(
                     "link",
                     {
-                        ET.QName(namespaces["ac"], "anchor"): target,
+                        AC_ATTR("anchor"): target,
                     },
                     link_body,
                 )
-                link_wrapper.tail = anchor.tail
                 return link_wrapper
             else:
                 return None
 
-        # convert the relative URL to absolute URL based on the base path value, then look up
-        # the absolute path in the page metadata dictionary to discover the relative path
-        # within Confluence that should be used
+        # discard original value: relative links always require transformation
+        anchor.attrib.pop("href")
+
+        # convert the relative URL to absolute path based on the base path value
         absolute_path = (self.base_dir / relative_url.path).resolve()
+
+        # look up the absolute path in the page metadata dictionary to discover the relative path within Confluence that should be used
         if not is_directory_within(absolute_path, self.root_dir):
-            anchor.attrib.pop("href")
             self._warn_or_raise(f"relative URL {url} points to outside root path: {self.root_dir}")
             return None
 
+        if absolute_path.suffix == ".md":
+            return self._transform_page_link(anchor, relative_url, absolute_path)
+        else:
+            return self._transform_attachment_link(anchor, absolute_path)
+
+    def _transform_page_link(self, anchor: ET._Element, relative_url: ParseResult, absolute_path: Path) -> Optional[ET._Element]:
+        """
+        Transforms links to other Markdown documents (Confluence pages).
+        """
+
         link_metadata = self.page_metadata.get(absolute_path)
         if link_metadata is None:
-            msg = f"unable to find matching page for URL: {url}"
-            if self.options.ignore_invalid_url:
-                LOGGER.warning(msg)
-                anchor.attrib.pop("href")
-                return None
-            else:
-                raise DocumentError(msg)
+            self._warn_or_raise(f"unable to find matching page for URL: {relative_url.geturl()}")
+            return None
 
         relative_path = os.path.relpath(absolute_path, self.base_dir)
         LOGGER.debug("Found link to page %s with metadata: %s", relative_path, link_metadata)
-        self.links.append(url)
+        self.links.append(relative_url.geturl())
 
         if self.options.webui_links:
             page_url = f"{self.site_metadata.base_path}pages/viewpage.action?pageId={link_metadata.page_id}"
@@ -470,7 +510,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
             page_url = f"{self.site_metadata.base_path}spaces/{space_key}/pages/{link_metadata.page_id}/{encode_title(link_metadata.title)}"
 
-        components = ParseResult(
+        transformed_url = ParseResult(
             scheme="https",
             netloc=self.site_metadata.domain,
             path=page_url,
@@ -478,24 +518,83 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             query="",
             fragment=relative_url.fragment,
         )
-        transformed_url = urlunparse(components)
 
-        LOGGER.debug("Transformed relative URL: %s to URL: %s", url, transformed_url)
-        anchor.attrib["href"] = transformed_url
+        LOGGER.debug("Transformed relative URL: %s to URL: %s", relative_url.geturl(), transformed_url.geturl())
+        anchor.set("href", transformed_url.geturl())
         return None
 
-    def _transform_image(self, image: ET._Element) -> ET._Element:
-        "Inserts an attached or external image."
+    def _transform_attachment_link(self, anchor: ET._Element, absolute_path: Path) -> Optional[ET._Element]:
+        """
+        Transforms links to document binaries such as PDF, DOCX or XLSX.
+        """
+
+        if not absolute_path.exists():
+            self._warn_or_raise(f"relative URL points to non-existing file: {absolute_path}")
+            return None
+
+        file_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
+        self.images.append(ImageData(absolute_path))
+
+        link_body = AC_ELEM("link-body", {}, *list(anchor))
+        link_body.text = anchor.text
+        link_wrapper = AC_ELEM(
+            "link",
+            {},
+            RI_ELEM("attachment", {RI_ATTR("filename"): file_name}),
+            link_body,
+        )
+        return link_wrapper
+
+    def _transform_status(self, color: str, caption: str) -> ET._Element:
+        macro_id = str(uuid.uuid4())
+        attributes = {
+            AC_ATTR("name"): "status",
+            AC_ATTR("schema-version"): "1",
+            AC_ATTR("macro-id"): macro_id,
+        }
+        if color != "gray":
+            return AC_ELEM(
+                "structured-macro",
+                attributes,
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "colour"},
+                    color.title(),
+                ),
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "title"},
+                    caption,
+                ),
+            )
+        else:
+            return AC_ELEM(
+                "structured-macro",
+                attributes,
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "title"},
+                    caption,
+                ),
+            )
 
-        src = image.attrib.get("src")
+    def _transform_image(self, context: FormattingContext, image: ET._Element) -> ET._Element:
+        "Inserts an attached or external image."
 
+        src = image.get("src")
         if not src:
             raise DocumentError("image lacks `src` attribute")
 
-        caption = image.attrib.get("alt")
-        width = image.attrib.get("width")
-        height = image.attrib.get("height")
-        attrs = ImageAttributes(caption, width, height)
+        alt = image.get("alt")
+        if alt is not None and src.startswith("urn:uuid:") and (color := status_images.get(src)) is not None:
+            return self._transform_status(color, alt)
+
+        title = image.get("title")
+        width = image.get("width")
+        height = image.get("height")
+        pixel_width = int(width) if width is not None and width.isdecimal() else None
+        pixel_height = int(height) if height is not None and height.isdecimal() else None
+        attrs = ImageAttributes(context, pixel_width, pixel_height, alt, title, None)
 
         if is_absolute_url(src):
             return self._transform_external_image(src, attrs)
@@ -504,39 +603,32 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
             absolute_path = self._verify_image_path(path)
             if absolute_path is None:
-                return self._create_missing(path, caption)
+                return self._create_missing(path, attrs.caption)
 
             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)
+            elif absolute_path.name.endswith(".mmd") or absolute_path.name.endswith(".mermaid"):
+                return self._transform_external_mermaid(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(
+            RI_ELEM(
                 "url",
                 # refers to an external image
-                {ET.QName(namespaces["ri"], "value"): url},
+                {RI_ATTR("value"): url},
             )
         )
-        if attrs.caption is not None:
-            elements.append(AC("caption", HTML.p(attrs.caption)))
+        if attrs.caption:
+            elements.append(AC_ELEM("caption", attrs.caption))
 
-        return AC("image", attributes, *elements)
+        return AC_ELEM("image", attrs.as_dict(), *elements)
 
     def _verify_image_path(self, path: Path) -> Optional[Path]:
         "Checks whether an image path is safe to use."
@@ -557,13 +649,13 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     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"):
+        if self.options.prefer_raster and absolute_path.suffix == ".svg":
             # prefer PNG over SVG; Confluence displays SVG in wrong size, and text labels are truncated
             png_file = absolute_path.with_suffix(".png")
             if png_file.exists():
                 absolute_path = png_file
 
-        self.images.append(absolute_path)
+        self.images.append(ImageData(absolute_path, attrs.alt))
         image_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
         return self._create_attached_image(image_name, attrs)
 
@@ -573,15 +665,15 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         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`")
 
+        relative_path = path_relative_to(absolute_path, self.base_dir)
         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
+            image_filename = attachment_name(relative_path.with_suffix(f".{self.options.diagram_output_format}"))
+            self.embedded_files[image_filename] = EmbeddedFileData(image_data, attrs.alt)
             return self._create_attached_image(image_filename, attrs)
         else:
-            self.images.append(absolute_path)
-            image_filename = attachment_name(path_relative_to(absolute_path, self.base_dir))
+            self.images.append(ImageData(absolute_path, attrs.alt))
+            image_filename = attachment_name(relative_path)
             return self._create_drawio(image_filename, attrs)
 
     def _transform_drawio_image(self, absolute_path: Path, attrs: ImageAttributes) -> ET._Element:
@@ -596,72 +688,63 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             # 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
+            self.embedded_files[image_filename] = EmbeddedFileData(image_data, attrs.alt)
 
             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(
-            RI(
+            RI_ELEM(
                 "attachment",
                 # refers to an attachment uploaded alongside the page
-                {ET.QName(namespaces["ri"], "filename"): image_name},
+                {RI_ATTR("filename"): image_name},
             )
         )
-        if attrs.caption is not None:
-            elements.append(AC("caption", HTML.p(attrs.caption)))
+        if attrs.caption:
+            elements.append(AC_ELEM("caption", attrs.caption))
 
-        return AC("image", attributes, *elements)
+        return AC_ELEM("image", attrs.as_dict(), *elements)
 
     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(
+            AC_ELEM(
                 "parameter",
-                {ET.QName(namespaces["ac"], "name"): "diagramName"},
+                {AC_ATTR("name"): "diagramName"},
                 filename,
             ),
         ]
         if attrs.width is not None:
             parameters.append(
-                AC(
+                AC_ELEM(
                     "parameter",
-                    {ET.QName(namespaces["ac"], "name"): "width"},
-                    attrs.width,
+                    {AC_ATTR("name"): "width"},
+                    str(attrs.width),
                 ),
             )
         if attrs.height is not None:
             parameters.append(
-                AC(
+                AC_ELEM(
                     "parameter",
-                    {ET.QName(namespaces["ac"], "name"): "height"},
-                    attrs.height,
+                    {AC_ATTR("name"): "height"},
+                    str(attrs.height),
                 ),
             )
 
         local_id = str(uuid.uuid4())
         macro_id = str(uuid.uuid4())
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "drawio",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "drawio",
+                AC_ATTR("schema-version"): "1",
                 "data-layout": "default",
-                ET.QName(namespaces["ac"], "local-id"): local_id,
-                ET.QName(namespaces["ac"], "macro-id"): macro_id,
+                AC_ATTR("local-id"): local_id,
+                AC_ATTR("macro-id"): macro_id,
             },
             *parameters,
         )
@@ -672,21 +755,21 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         message = HTML.p("Missing image: ", HTML.code(path.as_posix()))
         if caption is not None:
             content = [
-                AC(
+                AC_ELEM(
                     "parameter",
-                    {ET.QName(namespaces["ac"], "name"): "title"},
+                    {AC_ATTR("name"): "title"},
                     caption,
                 ),
-                AC("rich-text-body", {}, message),
+                AC_ELEM("rich-text-body", {}, message),
             ]
         else:
-            content = [AC("rich-text-body", {}, message)]
+            content = [AC_ELEM("rich-text-body", {}, message)]
 
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "warning",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "warning",
+                AC_ATTR("schema-version"): "1",
             },
             *content,
         )
@@ -694,107 +777,132 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     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)
-            if m:
-                language = m.group(1)
+        if language_class := code.get("class"):
+            if m := re.match("^language-(.*)$", language_class):
+                language_name = m.group(1)
             else:
-                language = "none"
-        if language not in _languages:
-            language = "none"
+                language_name = None
+        else:
+            language_name = None
+
+        # translate name to standard name for (programming) language
+        if language_name is not None:
+            language_id = _LANGUAGES.get(language_name)
+        else:
+            language_id = None
+
         content: str = code.text or ""
         content = content.rstrip()
 
-        if language == "mermaid":
-            return self._transform_mermaid(content)
+        if language_id == "mermaid":
+            return self._transform_fenced_mermaid(content)
 
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "code",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "code",
+                AC_ATTR("schema-version"): "1",
             },
-            AC(
+            AC_ELEM(
                 "parameter",
-                {ET.QName(namespaces["ac"], "name"): "theme"},
-                "Default",
+                {AC_ATTR("name"): "language"},
+                language_id or "none",
             ),
-            AC(
-                "parameter",
-                {ET.QName(namespaces["ac"], "name"): "language"},
-                language,
-            ),
-            AC("plain-text-body", ET.CDATA(content)),
+            AC_ELEM("plain-text-body", ET.CDATA(content)),
         )
 
-    def _transform_mermaid(self, content: str) -> ET._Element:
-        "Transforms a Mermaid diagram code block."
+    def _transform_external_mermaid(self, absolute_path: Path, attrs: ImageAttributes) -> ET._Element:
+        "Emits Confluence Storage Format XHTML for a Mermaid diagram read from an external file."
+
+        if not absolute_path.name.endswith(".mmd") and not absolute_path.name.endswith(".mermaid"):
+            raise DocumentError("invalid image format; expected: `*.mmd` or `*.mermaid`")
+
+        relative_path = path_relative_to(absolute_path, self.base_dir)
+        if self.options.render_mermaid:
+            with open(absolute_path, "r", encoding="utf-8") as f:
+                content = f.read()
+            image_data = mermaid.render_diagram(content, self.options.diagram_output_format)
+            image_filename = attachment_name(relative_path.with_suffix(f".{self.options.diagram_output_format}"))
+            self.embedded_files[image_filename] = EmbeddedFileData(image_data, attrs.alt)
+            return self._create_attached_image(image_filename, attrs)
+        else:
+            self.images.append(ImageData(absolute_path, attrs.alt))
+            mermaid_filename = attachment_name(relative_path)
+            return self._create_mermaid_embed(mermaid_filename)
+
+    def _transform_fenced_mermaid(self, content: str) -> ET._Element:
+        "Emits Confluence Storage Format XHTML for a Mermaid diagram defined in a fenced code block."
 
         if self.options.render_mermaid:
             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 self._create_attached_image(image_filename, ImageAttributes(None, None, None))
+            self.embedded_files[image_filename] = EmbeddedFileData(image_data)
+            return self._create_attached_image(image_filename, ImageAttributes.EMPTY_BLOCK)
         else:
-            local_id = str(uuid.uuid4())
-            macro_id = str(uuid.uuid4())
-            return AC(
-                "structured-macro",
-                {
-                    ET.QName(namespaces["ac"], "name"): "macro-diagram",
-                    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"): "sourceType"},
-                    "MacroBody",
-                ),
-                AC(
-                    "parameter",
-                    {ET.QName(namespaces["ac"], "name"): "attachmentPageId"},
-                ),
-                AC(
-                    "parameter",
-                    {ET.QName(namespaces["ac"], "name"): "syntax"},
-                    "Mermaid",
-                ),
-                AC(
-                    "parameter",
-                    {ET.QName(namespaces["ac"], "name"): "attachmentId"},
-                ),
-                AC("parameter", {ET.QName(namespaces["ac"], "name"): "url"}),
-                AC("plain-text-body", ET.CDATA(content)),
-            )
+            mermaid_data = content.encode("utf-8")
+            mermaid_hash = hashlib.md5(mermaid_data).hexdigest()
+            mermaid_filename = attachment_name(f"embedded_{mermaid_hash}.mmd")
+            self.embedded_files[mermaid_filename] = EmbeddedFileData(mermaid_data)
+            return self._create_mermaid_embed(mermaid_filename)
+
+    def _create_mermaid_embed(self, filename: str) -> ET._Element:
+        "A Mermaid diagram, linking to an attachment that captures the Mermaid source."
+
+        local_id = str(uuid.uuid4())
+        macro_id = str(uuid.uuid4())
+        return AC_ELEM(
+            "structured-macro",
+            {
+                AC_ATTR("name"): "mermaid-cloud",
+                AC_ATTR("schema-version"): "1",
+                "data-layout": "default",
+                AC_ATTR("local-id"): local_id,
+                AC_ATTR("macro-id"): macro_id,
+            },
+            AC_ELEM(
+                "parameter",
+                {AC_ATTR("name"): "filename"},
+                filename,
+            ),
+            AC_ELEM(
+                "parameter",
+                {AC_ATTR("name"): "toolbar"},
+                "bottom",
+            ),
+            AC_ELEM(
+                "parameter",
+                {AC_ATTR("name"): "zoom"},
+                "fit",
+            ),
+            AC_ELEM("parameter", {AC_ATTR("name"): "revision"}, "1"),
+        )
 
     def _transform_toc(self, code: ET._Element) -> ET._Element:
         "Creates a table of contents, constructed from headings in the document."
 
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "toc",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "toc",
+                AC_ATTR("schema-version"): "1",
+                "data-layout": "default",
             },
-            AC("parameter", {ET.QName(namespaces["ac"], "name"): "outline"}, "clear"),
-            AC("parameter", {ET.QName(namespaces["ac"], "name"): "style"}, "default"),
+            AC_ELEM("parameter", {AC_ATTR("name"): "outline"}, "clear"),
+            AC_ELEM("parameter", {AC_ATTR("name"): "style"}, "default"),
         )
 
     def _transform_listing(self, code: ET._Element) -> ET._Element:
         "Creates a list of child pages."
 
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "children",
-                ET.QName(namespaces["ac"], "schema-version"): "2",
+                AC_ATTR("name"): "children",
+                AC_ATTR("schema-version"): "2",
                 "data-layout": "default",
             },
-            AC("parameter", {ET.QName(namespaces["ac"], "name"): "allChildren"}, "true"),
+            AC_ELEM("parameter", {AC_ATTR("name"): "allChildren"}, "true"),
         )
 
     def _transform_admonition(self, elem: ET._Element) -> ET._Element:
@@ -805,8 +913,11 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         syntax into one of the Confluence structured macros *info*, *tip*, *note*, or *warning*.
         """
 
+        if len(elem) < 1:
+            raise DocumentError("empty admonition")
+
         # <div class="admonition note">
-        class_list = elem.attrib.get("class", "").split(" ")
+        class_list = elem.get("class", "").split(" ")
         class_name: Optional[str] = None
         if "info" in class_list:
             class_name = "info"
@@ -824,33 +935,36 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             self.visit(e)
 
         # <p class="admonition-title">Note</p>
-        if "admonition-title" in elem[0].attrib.get("class", "").split(" "):
+        if "admonition-title" in elem[0].get("class", "").split(" "):
             content = [
-                AC(
+                AC_ELEM(
                     "parameter",
-                    {ET.QName(namespaces["ac"], "name"): "title"},
+                    {AC_ATTR("name"): "title"},
                     elem[0].text or "",
                 ),
-                AC("rich-text-body", {}, *list(elem[1:])),
+                AC_ELEM("rich-text-body", {}, *list(elem[1:])),
             ]
         else:
-            content = [AC("rich-text-body", {}, *list(elem))]
+            content = [AC_ELEM("rich-text-body", {}, *list(elem))]
 
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): class_name,
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): class_name,
+                AC_ATTR("schema-version"): "1",
             },
             *content,
         )
 
-    def _transform_github_alert(self, elem: ET._Element) -> ET._Element:
+    def _transform_github_alert(self, blockquote: 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 len(blockquote) < 1:
+            raise DocumentError("empty GitHub alert")
+
+        content = blockquote[0]
         if content.text is None:
             raise DocumentError("empty content")
 
@@ -875,9 +989,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             else:
                 raise DocumentError(f"unsupported GitHub alert: {alert}")
 
-        return self._transform_alert(elem, class_name, skip)
+        return self._transform_alert(blockquote, class_name, skip)
 
-    def _transform_gitlab_alert(self, elem: ET._Element) -> ET._Element:
+    def _transform_gitlab_alert(self, blockquote: ET._Element) -> ET._Element:
         """
         Creates a classic GitLab-style panel.
 
@@ -885,7 +999,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         This syntax does not use Hugo shortcode.
         """
 
-        content = elem[0]
+        if len(blockquote) < 1:
+            raise DocumentError("empty GitLab alert")
+
+        content = blockquote[0]
         if content.text is None:
             raise DocumentError("empty content")
 
@@ -908,69 +1025,85 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             else:
                 raise DocumentError(f"unsupported GitLab alert: {alert}")
 
-        return self._transform_alert(elem, class_name, skip)
+        return self._transform_alert(blockquote, class_name, skip)
 
-    def _transform_alert(self, elem: ET._Element, class_name: Optional[str], skip: int) -> ET._Element:
+    def _transform_alert(self, blockquote: ET._Element, class_name: Optional[str], skip: int) -> ET._Element:
         """
         Creates an info, tip, note or warning panel from a GitHub or GitLab alert.
 
-        Transforms
-        [GitHub alert](https://docs.github.com/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
-        or [GitLab alert](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
-        syntax into one of the Confluence structured macros *info*, *tip*, *note*, or *warning*.
+        Transforms GitHub alert or GitLab alert syntax into one of the Confluence structured macros *info*, *tip*, *note*, or *warning*.
+
+        :see: https://docs.github.com/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
+        :see: https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes
         """
 
-        content = elem[0]
+        content = blockquote[0]
         if content.text is None:
             raise DocumentError("empty content")
 
         if class_name is None:
             raise DocumentError("not an alert")
 
-        for e in elem:
+        for e in blockquote:
             self.visit(e)
 
         content.text = content.text[skip:]
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): class_name,
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): class_name,
+                AC_ATTR("schema-version"): "1",
             },
-            AC("rich-text-body", {}, *list(elem)),
+            AC_ELEM("rich-text-body", {}, *list(blockquote)),
         )
 
-    def _transform_section(self, elem: ET._Element) -> ET._Element:
+    def _transform_section(self, details: ET._Element) -> ET._Element:
         """
         Creates a collapsed section.
 
-        Transforms
-        [GitHub collapsed section](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
-        syntax into the Confluence structured macro *expand*.
+        Transforms a GitHub collapsed section syntax into the Confluence structured macro *expand*.
+
+        :see: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections
         """
 
-        if elem[0].tag != "summary":
+        summary = details[0]
+        if summary.tag != "summary":
             raise DocumentError("expected: `<summary>` as first direct child of `<details>`")
-        if elem[0].tail is not None:
+        if details.text is not None or summary.tail is not None:
+            # when `<details>` has attribute `markdown=1`, content is parsed as Markdown:
+            # ```
+            # <details>
+            #   <summary>...</summary>
+            #   <p>Text with <em>emphasis</em>.</p>
+            # </details>
+            # ```
+            #
+            # when `<details>` lacks attribute `markdown=1`, content is passed down as raw HTML, partly as `text` of `<detail>` or `tail` of `<summary>`:
+            # ```
+            # <details>
+            #   <summary>...</summary>
+            #   Text with *emphasis*.
+            # </details>
             raise DocumentError('expected: attribute `markdown="1"` on `<details>`')
 
-        summary = "".join(elem[0].itertext()).strip()
-        elem.remove(elem[0])
+        summary_text = element_to_text(summary)
+        details.remove(summary)
 
-        self.visit(elem)
+        # transform Markdown to Confluence within collapsed section content
+        self.visit(details)
 
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "expand",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "expand",
+                AC_ATTR("schema-version"): "1",
             },
-            AC(
+            AC_ELEM(
                 "parameter",
-                {ET.QName(namespaces["ac"], "name"): "title"},
-                summary,
+                {AC_ATTR("name"): "title"},
+                summary_text,
             ),
-            AC("rich-text-body", {}, *list(elem)),
+            AC_ELEM("rich-text-body", {}, *list(details)),
         )
 
     def _transform_emoji(self, elem: ET._Element) -> ET._Element:
@@ -978,23 +1111,59 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         Inserts an inline emoji character.
         """
 
-        shortname = elem.attrib.get("data-emoji-shortname", "")
-        unicode = elem.attrib.get("data-emoji-unicode", None)
+        shortname = elem.get("data-shortname", "")
+        unicode = elem.get("data-unicode", None)
         alt = elem.text or ""
 
         # <ac:emoticon ac:name="wink" ac:emoji-shortname=":wink:" ac:emoji-id="1f609" ac:emoji-fallback="&#128521;"/>
-        # <ac:emoticon ac:name="blue-star" ac:emoji-shortname=":heavy_plus_sign:" ac:emoji-id="2795" ac:emoji-fallback="&#10133;"/>
-        # <ac:emoticon ac:name="blue-star" ac:emoji-shortname=":heavy_minus_sign:" ac:emoji-id="2796" ac:emoji-fallback="&#10134;"/>
-        return AC(
+        return AC_ELEM(
             "emoticon",
             {
-                ET.QName(namespaces["ac"], "name"): shortname,
-                ET.QName(namespaces["ac"], "emoji-shortname"): f":{shortname}:",
-                ET.QName(namespaces["ac"], "emoji-id"): unicode,
-                ET.QName(namespaces["ac"], "emoji-fallback"): alt,
+                AC_ATTR("name"): shortname,
+                AC_ATTR("emoji-shortname"): f":{shortname}:",
+                AC_ATTR("emoji-id"): unicode,
+                AC_ATTR("emoji-fallback"): alt,
             },
         )
 
+    def _transform_mark(self, mark: ET._Element) -> ET._Element:
+        """
+        Adds inline highlighting to text.
+        """
+
+        attrs = dict(mark.items())
+        old_style = attrs.get("style")
+        new_style = "background-color: rgb(254,222,200);"
+        if old_style is not None:
+            new_style += f" {old_style}"
+        attrs["style"] = new_style
+        span = HTML("span", attrs, *list(mark))
+        span.text = mark.text
+        return span
+
+    def _transform_latex(self, elem: ET._Element, context: FormattingContext) -> ET._Element:
+        """
+        Creates an image rendering of a LaTeX formula with Matplotlib.
+        """
+
+        content = elem.text
+        if not content:
+            raise DocumentError("empty LaTeX formula")
+
+        image_data = render_latex(content, format=self.options.diagram_output_format)
+        if self.options.diagram_output_format == "png":
+            width, height = get_png_dimensions(data=image_data)
+            image_data = remove_png_chunks(["pHYs"], source_data=image_data)
+            attrs = ImageAttributes(context, width, height, content, None, "")
+        else:
+            attrs = ImageAttributes.empty(context)
+
+        image_hash = hashlib.md5(image_data).hexdigest()
+        image_filename = attachment_name(f"formula_{image_hash}.{self.options.diagram_output_format}")
+        self.embedded_files[image_filename] = EmbeddedFileData(image_data, content)
+        image = self._create_attached_image(image_filename, attrs)
+        return image
+
     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".
@@ -1002,30 +1171,32 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         :see: https://help.narva.net/latex-math-for-confluence/
         """
 
-        content = elem.text or ""
+        content = elem.text
         if not content:
             raise DocumentError("empty inline LaTeX formula")
 
         LOGGER.debug("Found inline LaTeX formula: %s", content)
 
+        if self.options.render_latex:
+            return self._transform_latex(elem, FormattingContext.INLINE)
+
         local_id = str(uuid.uuid4())
         macro_id = str(uuid.uuid4())
-        macro = AC(
+        macro = AC_ELEM(
             "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_ATTR("name"): "eazy-math-inline",
+                AC_ATTR("schema-version"): "1",
+                AC_ATTR("local-id"): local_id,
+                AC_ATTR("macro-id"): macro_id,
             },
-            AC(
+            AC_ELEM(
                 "parameter",
-                {ET.QName(namespaces["ac"], "name"): "body"},
+                {AC_ATTR("name"): "body"},
                 content,
             ),
-            AC("parameter", {ET.QName(namespaces["ac"], "name"): "align"}, "center"),
+            AC_ELEM("parameter", {AC_ATTR("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:
@@ -1035,30 +1206,33 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         :see: https://help.narva.net/latex-math-for-confluence/
         """
 
-        content = elem.text or ""
+        content = elem.text
         if not content:
             raise DocumentError("empty block-level LaTeX formula")
 
         LOGGER.debug("Found block-level LaTeX formula: %s", content)
 
+        if self.options.render_latex:
+            return self._transform_latex(elem, FormattingContext.BLOCK)
+
         local_id = str(uuid.uuid4())
         macro_id = str(uuid.uuid4())
 
-        return AC(
+        return AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "easy-math-block",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "easy-math-block",
+                AC_ATTR("schema-version"): "1",
                 "data-layout": "default",
-                ET.QName(namespaces["ac"], "local-id"): local_id,
-                ET.QName(namespaces["ac"], "macro-id"): macro_id,
+                AC_ATTR("local-id"): local_id,
+                AC_ATTR("macro-id"): macro_id,
             },
-            AC(
+            AC_ELEM(
                 "parameter",
-                {ET.QName(namespaces["ac"], "name"): "body"},
+                {AC_ATTR("name"): "body"},
                 content,
             ),
-            AC("parameter", {ET.QName(namespaces["ac"], "name"): "align"}, "center"),
+            AC_ELEM("parameter", {AC_ATTR("name"): "align"}, "center"),
         )
 
     def _transform_footnote_ref(self, elem: ET._Element) -> None:
@@ -1078,7 +1252,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             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]
+        link = next((elem.iterchildren(tag="a")), None)
+        if link is None:
+            raise DocumentError("expected: `<a>` as the first HTML element in a footnote reference")
         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")
@@ -1090,26 +1266,26 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         elem.remove(link)
 
         # build new anchor for footnote reference
-        ref_anchor = AC(
+        ref_anchor = AC_ELEM(
             "structured-macro",
             {
-                ET.QName(namespaces["ac"], "name"): "anchor",
-                ET.QName(namespaces["ac"], "schema-version"): "1",
+                AC_ATTR("name"): "anchor",
+                AC_ATTR("schema-version"): "1",
             },
-            AC(
+            AC_ELEM(
                 "parameter",
-                {ET.QName(namespaces["ac"], "name"): ""},
+                {AC_ATTR("name"): ""},
                 f"footnote-ref-{footnote_ref}",
             ),
         )
 
         # build new link to footnote definition at the end of page
-        def_link = AC(
+        def_link = AC_ELEM(
             "link",
             {
-                ET.QName(namespaces["ac"], "anchor"): f"footnote-def-{footnote_def}",
+                AC_ATTR("anchor"): f"footnote-def-{footnote_def}",
             },
-            AC("link-body", ET.CDATA(text)),
+            AC_ELEM("link-body", ET.CDATA(text)),
         )
 
         # append children synthesized for Confluence
@@ -1132,18 +1308,28 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         ```
         """
 
-        for list_item in elem[1]:
+        ordered_list = next((elem.iterchildren(tag="ol")), None)
+        if ordered_list is None:
+            raise DocumentError("expected: `<ol>` as direct child of footnote definition block")
+
+        for list_item in ordered_list:
+            if list_item.tag != "li":
+                raise DocumentError("expected: `<li>` as children of `<ol>` in footnote definition block")
+
             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":
+            paragraph = next((list_item.iterchildren(tag="p")), None)
+            if paragraph is None:
+                raise DocumentError("expected: `<p>` as a child of `<li>` in a footnote definition")
+
+            ref_anchor = next((paragraph.iterchildren(tag="a", reversed=True)), None)
+            if ref_anchor is None:
                 raise DocumentError("expected: `<a>` as the last HTML element in a footnote definition")
 
-            ref_href = ref_anchor.attrib.get("href", "")
+            ref_href = ref_anchor.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:")
@@ -1152,26 +1338,26 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             paragraph.remove(ref_anchor)
 
             # build new anchor for footnote definition
-            def_anchor = AC(
+            def_anchor = AC_ELEM(
                 "structured-macro",
                 {
-                    ET.QName(namespaces["ac"], "name"): "anchor",
-                    ET.QName(namespaces["ac"], "schema-version"): "1",
+                    AC_ATTR("name"): "anchor",
+                    AC_ATTR("schema-version"): "1",
                 },
-                AC(
+                AC_ELEM(
                     "parameter",
-                    {ET.QName(namespaces["ac"], "name"): ""},
+                    {AC_ATTR("name"): ""},
                     f"footnote-def-{footnote_def}",
                 ),
             )
 
             # build new link to footnote reference in page body
-            ref_link = AC(
+            ref_link = AC_ELEM(
                 "link",
                 {
-                    ET.QName(namespaces["ac"], "anchor"): f"footnote-ref-{footnote_ref}",
+                    AC_ATTR("anchor"): f"footnote-ref-{footnote_ref}",
                 },
-                AC("link-body", ET.CDATA("↩")),
+                AC_ELEM("link-body", ET.CDATA("↩")),
             )
 
             # append children synthesized for Confluence
@@ -1180,79 +1366,132 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             paragraph.text = None
             paragraph.append(ref_link)
 
+    def _transform_tasklist(self, elem: ET._Element) -> ET._Element:
+        """
+        Transforms a list of tasks into an action widget.
+
+        :see: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-tasklists
+        """
+
+        if elem.tag != "ul":
+            raise DocumentError("expected: `<ul>` as the HTML element for a tasklist")
+
+        for item in elem:
+            if item.tag != "li":
+                raise DocumentError("expected: `<li>` as the HTML element for a task")
+            if not element_text_starts_with_any(item, ["[ ]", "[x]", "[X]"]):
+                raise DocumentError("expected: each `<li>` in a task list starting with [ ] or [x]")
+
+        tasks: list[ET._Element] = []
+        for index, item in enumerate(elem, start=1):
+            if item.text is None:
+                raise NotImplementedError("pre-condition check not exhaustive")
+            match = re.match(r"^\[([x X])\]", item.text)
+            if match is None:
+                raise NotImplementedError("pre-condition check not exhaustive")
+
+            status = "incomplete" if match.group(1).isspace() else "complete"
+            item.text = item.text[3:]
+
+            # transform Markdown to Confluence within tasklist content
+            self.visit(item)
+
+            body = AC_ELEM("task-body", *list(item))
+            body.text = item.text
+            tasks.append(
+                AC_ELEM(
+                    "task",
+                    {},
+                    AC_ELEM("task-id", str(index)),
+                    AC_ELEM("task-uuid", str(uuid.uuid4())),
+                    AC_ELEM("task-status", status),
+                    body,
+                ),
+            )
+        return AC_ELEM("task-list", {}, *tasks)
+
+    @override
     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
+        # replace line breaks with regular space in element text to minimize phantom changes
         if child.text:
-            text: str = child.text
-            child.text = text.replace("\n", " ")
+            child.text = child.text.replace("\n", " ")
         if child.tail:
-            tail: str = child.tail
-            child.tail = tail.replace("\n", " ")
+            child.tail = child.tail.replace("\n", " ")
 
         if not isinstance(child.tag, str):
             return None
 
-        # <h1>...</h1>
-        # <h2>...</h2> ...
-        m = re.match(r"^h([1-6])$", child.tag, flags=re.IGNORECASE)
-        if m is not None:
-            level = int(m.group(1))
-            title = element_to_text(child)
-            self.toc.add(level, title)
-
-            if self.options.heading_anchors:
-                self._transform_heading(child)
+        # <p>...</p>
+        if child.tag == "p":
+            # <p><img src="..." /></p>
+            if len(child) == 1 and not child.text and child[0].tag == "img" and not child[0].tail:
+                return self._transform_image(FormattingContext.BLOCK, child[0])
+
+            # <p>[[<em>TOC</em>]]</p> (represented in Markdown as `[[_TOC_]]`)
+            elif is_placeholder_for(child, "TOC"):
+                return self._transform_toc(child)
+
+            # <p>[[<em>LISTING</em>]]</p> (represented in Markdown as `[[_LISTING_]]`)
+            elif is_placeholder_for(child, "LISTING"):
+                return self._transform_listing(child)
+
+        # <div>...</div>
+        elif child.tag == "div":
+            classes = child.get("class", "").split(" ")
+
+            # <div class="arithmatex">...</div>
+            if "arithmatex" in classes:
+                return self._transform_block_math(child)
+
+            # <div><ac:structured-macro ...>...</ac:structured-macro></div>
+            elif "csf" in classes:
+                if len(child) != 1:
+                    raise DocumentError("expected: single child in Confluence Storage Format block")
+
+                return child[0]
+
+            # <div class="footnote">
+            #   <hr/>
+            #   <ol>
+            #     <li id="fn:NAME"><p>TEXT <a class="footnote-backref" href="#fnref:NAME">↩</a></p></li>
+            #   </ol>
+            # </div>
+            elif "footnote" in classes:
+                self._transform_footnote_def(child)
                 return None
 
-        # <p><img src="..." /></p>
-        if child.tag == "p" and len(child) == 1 and child[0].tag == "img":
-            return self._transform_image(child[0])
-
-        # <p>[[_TOC_]]</p>
-        # <p>[TOC]</p>
-        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>
-        # </div>
-        #
-        # --- OR ---
-        #
-        # <div class="admonition note">
-        # <p>...</p>
-        # </div>
-        elif child.tag == "div" and "admonition" in child.attrib.get("class", ""):
-            return self._transform_admonition(child)
-
-        # Alerts in GitHub
-        # <blockquote>
-        #   <p>[!TIP] ...</p>
-        # </blockquote>
-        elif child.tag == "blockquote" and len(child) > 0 and child[0].tag == "p" and child[0].text is not None and child[0].text.startswith("[!"):
-            return self._transform_github_alert(child)
-
-        # Alerts in GitLab
-        # <blockquote>
-        #   <p>DISCLAIMER: ...</p>
-        # </blockquote>
-        elif (
-            child.tag == "blockquote"
-            and len(child) > 0
-            and child[0].tag == "p"
-            and child[0].text is not None
-            and starts_with_any(child[0].text, ["FLAG:", "NOTE:", "WARNING:", "DISCLAIMER:"])
-        ):
-            return self._transform_gitlab_alert(child)
+            # <div class="admonition note">
+            # <p class="admonition-title">Note</p>
+            # <p>...</p>
+            # </div>
+            #
+            # --- OR ---
+            #
+            # <div class="admonition note">
+            # <p>...</p>
+            # </div>
+            elif "admonition" in classes:
+                return self._transform_admonition(child)
+
+        # <blockquote>...</blockquote>
+        elif child.tag == "blockquote":
+            # Alerts in GitHub
+            # <blockquote>
+            #   <p>[!TIP] ...</p>
+            # </blockquote>
+            if len(child) > 0 and child[0].tag == "p" and child[0].text is not None and child[0].text.startswith("[!"):
+                return self._transform_github_alert(child)
+
+            # Alerts in GitLab
+            # <blockquote>
+            #   <p>DISCLAIMER: ...</p>
+            # </blockquote>
+            elif len(child) > 0 and child[0].tag == "p" and element_text_starts_with_any(child[0], ["FLAG:", "NOTE:", "WARNING:", "DISCLAIMER:"]):
+                return self._transform_gitlab_alert(child)
 
         # <details markdown="1">
         # <summary>...</summary>
@@ -1261,44 +1500,84 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         elif child.tag == "details" and len(child) > 1 and child[0].tag == "summary":
             return self._transform_section(child)
 
+        # <ol>...</ol>
+        elif child.tag == "ol":
+            # Confluence adds the attribute `start` for every ordered list
+            child.set("start", "1")
+            return None
+
+        # <ul>
+        #   <li>[ ] ...</li>
+        #   <li>[x] ...</li>
+        # </ul>
+        elif child.tag == "ul":
+            if len(child) > 0 and element_text_starts_with_any(child[0], ["[ ]", "[x]", "[X]"]):
+                return self._transform_tasklist(child)
+
+            return None
+
+        elif child.tag == "li":
+            normalize_inline(child)
+            return None
+
+        # <pre><code class="language-java"> ... </code></pre>
+        elif child.tag == "pre" and len(child) == 1 and child[0].tag == "code":
+            return self._transform_code_block(child[0])
+
+        # <table>...</table>
+        elif child.tag == "table":
+            child.set("data-layout", "default")
+            return None
+
         # <img src="..." alt="..." />
         elif child.tag == "img":
-            return self._transform_image(child)
+            return self._transform_image(FormattingContext.INLINE, child)
 
         # <a href="..."> ... </a>
         elif child.tag == "a":
             return self._transform_link(child)
 
-        # <pre><code class="language-java"> ... </code></pre>
-        elif child.tag == "pre" and len(child) == 1 and child[0].tag == "code":
-            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)
+        # <mark>...</mark>
+        elif child.tag == "mark":
+            return self._transform_mark(child)
 
-        # <div class="arithmatex">...</div>
-        elif child.tag == "div" and "arithmatex" in child.attrib.get("class", "").split(" "):
-            return self._transform_block_math(child)
+        # <span>...</span>
+        elif child.tag == "span":
+            classes = child.get("class", "").split(" ")
 
-        # <span class="arithmatex">...</span>
-        elif child.tag == "span" and "arithmatex" in child.attrib.get("class", "").split(" "):
-            return self._transform_inline_math(child)
+            # <span class="arithmatex">...</span>
+            if "arithmatex" in classes:
+                return self._transform_inline_math(child)
 
         # <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:"):
+        elif child.tag == "sup" and child.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
+        # <input type="date" value="1984-01-01" />
+        elif child.tag == "input" and child.get("type", "") == "date":
+            return HTML("time", {"datetime": child.get("value", "")})
+
+        # <ins>...</ins>
+        elif child.tag == "ins":
+            # Confluence prefers <u> over <ins> for underline, and replaces <ins> with <u>
+            child.tag = "u"
+
+        # <x-emoji data-shortname="wink" data-unicode="1f609">😉</x-emoji>
+        elif child.tag == "x-emoji":
+            return self._transform_emoji(child)
+
+        # <h1>...</h1>
+        # <h2>...</h2> ...
+        m = re.match(r"^h([1-6])$", child.tag, flags=re.IGNORECASE)
+        if m is not None:
+            level = int(m.group(1))
+            title = element_to_text(child)
+            self.toc.add(level, title)
+
+            if self.options.heading_anchors:
+                self._transform_heading(child)
+                return None
 
         return None
 
@@ -1312,11 +1591,15 @@ class ConversionError(RuntimeError):
 
 
 class ConfluenceDocument:
+    "Encapsulates an element tree for a Confluence document created by parsing a Markdown document."
+
     title: Optional[str]
     labels: Optional[list[str]]
     properties: Optional[dict[str, JsonType]]
+
     links: list[str]
-    images: list[Path]
+    images: list[ImageData]
+    embedded_files: dict[str, EmbeddedFileData]
 
     options: ConfluenceDocumentOptions
     root: ET._Element
@@ -1355,10 +1638,18 @@ class ConfluenceDocument:
         site_metadata: ConfluenceSiteMetadata,
         page_metadata: ConfluencePageCollection,
     ) -> None:
+        "Converts a single Markdown document to Confluence Storage Format."
+
         self.options = options
 
+        # register auxiliary URL substitutions
+        lines: list[str] = []
+        for data_uri, color in status_images.items():
+            lines.append(f"[STATUS-{color.upper()}]: {data_uri}")
+        lines.append(document.text)
+
         # convert to HTML
-        html = markdown_to_html(document.text)
+        html = markdown_to_html("\n".join(lines))
 
         # parse Markdown document
         if self.options.generated_by is not None:
@@ -1390,10 +1681,13 @@ class ConfluenceDocument:
             site_metadata,
             page_metadata,
         )
-        converter.visit(self.root)
+        try:
+            converter.visit(self.root)
+        except DocumentError as ex:
+            raise ConversionError(path) from ex
         self.links = converter.links
         self.images = converter.images
-        self.embedded_images = converter.embedded_images
+        self.embedded_files = converter.embedded_files
 
         self.title = document.title or converter.toc.get_title()
         self.labels = document.tags
@@ -1433,41 +1727,3 @@ def attachment_name(ref: Union[Path, str]) -> str:
 
     parts = [replace_part(p) for p in path.parts]
     return Path(*parts).as_posix().replace("/", "_")
-
-
-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)
-    if m:
-        return m.group(1)
-    else:
-        raise ValueError("expected: Confluence content")
-
-
-def _content_to_string(dtd_path: Path, content: str) -> str:
-    parser = ET.XMLParser(
-        remove_blank_text=True,
-        remove_comments=True,
-        strip_cdata=False,
-        load_dtd=True,
-    )
-
-    ns_attr_list = "".join(f' xmlns:{key}="{value}"' for key, value in namespaces.items())
-
-    data = [
-        '<?xml version="1.0"?>',
-        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}"><root{ns_attr_list}>',
-    ]
-    data.append(content)
-    data.append("</root>")
-
-    tree = ET.fromstringlist(data, parser=parser)
-    return ET.tostring(tree, pretty_print=True).decode("utf-8")
-
-
-def content_to_string(content: str) -> str:
-    "Converts a Confluence Storage Format document returned by the API into a readable XML document."
-
-    resource_path = resources.files(__package__).joinpath("entities.dtd")
-    with resources.as_file(resource_path) as dtd_path:
-        return _content_to_string(dtd_path, content)