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

{markdown_to_confluence-0.4.2.dist-info → markdown_to_confluence-0.4.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.4.2
+Version: 0.4.3
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -58,7 +58,7 @@ This Python package
 * Text with **bold**, *italic*, `monospace`, <ins>underline</ins> and ~~strikethrough~~
 * Link to [sections on the same page](#getting-started) or [external locations](http://example.com/)
 * Subscript and superscript (with HTML tags `<sub>` and `<sup>`)
-* Math formulas with LaTeX notation [^math]
+* Math formulas with LaTeX notation
 * Emoji
 * Ordered and unordered lists
 * Block quotes
@@ -69,8 +69,8 @@ This Python package
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
 * [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
-* draw\.io diagrams [^drawio]
-* [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images) [^mermaid]
+* draw\.io diagrams
+* [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images)
 
 Whenever possible, the implementation uses [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/) to fetch space properties, and get, create or update page content.
 
@@ -84,9 +84,9 @@ pip install markdown-to-confluence
 
 ### Command-line utilities
 
-**Optional.** Converting `*.drawio` diagrams into PNG or SVG images requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
+**Optional.** Converting `*.drawio` diagrams to PNG or SVG images before uploading to Confluence as attachments requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
 
-**Optional.** Converting code blocks of Mermaid diagrams into PNG or SVG images requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
+**Optional.** Converting code blocks of Mermaid diagrams to PNG or SVG images before uploading to Confluence as attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -98,9 +98,9 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Editable draw\.io diagrams require [draw.io Diagrams marketplace app](https://marketplace.atlassian.com/apps/1210933/draw-io-diagrams-uml-bpmn-aws-erd-flowcharts). (Refer to `--no-render-drawio`.)
 
-**Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering requires a marketplace app. (Refer to `--no-render-mermaid`.)
+**Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering in the synchronization phase requires a marketplace app. (Refer to `--no-render-mermaid`.)
 
-**Optional.** Displaying formulas and equations requires [LaTeX Math marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations).
+**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
 
 ## Getting started
 
@@ -523,7 +523,3 @@ FROM leventehunyadi/md2conf:latest
 
 CMD ["-d", "example.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "SPACE", "./"]
 ```
-
-[^math]: Requires installing Confluence plugin [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
-[^drawio]: Converting draw\.io diagrams to images before uploading to Confluence requires an installation of [draw.io](https://www.drawio.com/). Editable draw\.io diagrams require separate marketplace app.
-[^mermaid]: Converting Mermaid diagrams to images before uploading to Confluence requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). Displaying Mermaid diagrams on the fly requires separate marketplace app.

{markdown_to_confluence-0.4.2.dist-info → markdown_to_confluence-0.4.3.dist-info}/RECORD

@@ -1,27 +1,29 @@
-markdown_to_confluence-0.4.2.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-md2conf/__init__.py,sha256=XAJAgUDrYS3PdOzoo2BQ-rM3PbQWOrOW2kPt5iJ8xY0,402
-md2conf/__main__.py,sha256=qyboDihyVTm0EZa_c3AFWF1AojhL8-bww_kISAa5nHQ,10130
+markdown_to_confluence-0.4.3.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+md2conf/__init__.py,sha256=ZEoZwOt29zT2OnQNpbYW9lO3zJEJ6soXwwjYX9PwNNo,402
+md2conf/__main__.py,sha256=RImfFrO2m9C5iebmBrHKlLjosy_A8AY4O7PK9CmiWSw,11120
 md2conf/api.py,sha256=DbG1udDb9ti4OjqgSW3DSuHwxKNFPVDTkhjnaB1GNMI,37193
-md2conf/application.py,sha256=X_V4KdFACHwl5Nt4BIHQyhtecOqNOzknrPyPTW0d4Z0,8185
+md2conf/application.py,sha256=MsumqUFw1WPo6-57r06Poq4wg2DPd3hQ4jA5qC4Oios,8212
 md2conf/collection.py,sha256=EobgMRJgkYloWlY03NZJ52MRC_SGLpTVCHkltDbQyt0,837
-md2conf/converter.py,sha256=Eg6emS77GQAkhbXutaRjHxcBFgmXp_4z_zOAmBfqxUY,54360
-md2conf/drawio.py,sha256=G_pD2nafl7dXuFK_4MBiEUl0ZZGNuagnHw6GFOrev94,6717
+md2conf/converter.py,sha256=mr5UvEhOnM7ZYRIGsgrW85PpxmlpXFjsKYsa8uGFxp0,50475
+md2conf/domain.py,sha256=tA9V0vb5Vo9Nt0eQvwAFARaM9TX88LBVQ73nVvdcaqA,1851
+md2conf/drawio.py,sha256=P_t7Wp7Tg9XkZM2ZchWCWWEdBaU1KgZ_YX9ZlkZo4Dk,8293
 md2conf/emoji.py,sha256=UzDrxqFo59wHmbbJmMNdn0rYFDXbZE4qirOM-_egzXc,2603
 md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
 md2conf/extra.py,sha256=VuMxuOnnC2Qwy6y52ukIxsaYhrZArRqMmRHRE4QZl8g,687
-md2conf/local.py,sha256=Ph-cGc_JQ1SkvuZ_Jxn37dlpaKZYKLVPBnsk5CGSVnk,3548
+md2conf/local.py,sha256=Cicfp9SJDJuX0aUWZPWCfWKPfQQWxEbifUsmqwxFjDU,3733
+md2conf/markdown.py,sha256=9BQbYD4GfpBYmx-3N1M36u2nVWY0VJ9UWKye2Jtnmnk,2901
 md2conf/matcher.py,sha256=m5rZjYZSjhKfdeKS8JdPq7cG861Mc6rVZBkrIOZTHGE,6916
 md2conf/mermaid.py,sha256=f0x7ISj-41ZMh4zTAFPhIWwr94SDcsVZUc1NWqmH_G4,2508
 md2conf/metadata.py,sha256=LzZM-oPNnzCULmLhF516tPlV5zZBknccwMHt8Nan-xg,1007
-md2conf/processor.py,sha256=59XDWKgTvJwEZ1y52VfRkM67K2-Ivh7kGD6Eg2tfG9c,9713
+md2conf/processor.py,sha256=z2d2KMPEYWaxflOtH2UTwrjzpPU8TtLSEUvor85ez1Q,9732
 md2conf/properties.py,sha256=RC1jY_TKVbOv2bJxXn27Fj4fNWzyoNUQt6ltgUyVQAQ,3987
 md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
 md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 md2conf/scanner.py,sha256=Cyvjab8tBvKgubttQvNagS8nailuTvFBqUGoiX5MNp8,5351
 md2conf/xml.py,sha256=HoKJfF1yRZ3Gk8jTS-kRpOqVs0nQJZyr56l0Fo3y9fs,2193
-markdown_to_confluence-0.4.2.dist-info/METADATA,sha256=ggIrg30RRTvk3ax2LKC_wKjMhOEhrXOYVrSwvb2dDbw,29495
-markdown_to_confluence-0.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-markdown_to_confluence-0.4.2.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.4.2.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.4.2.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.4.2.dist-info/RECORD,,
+markdown_to_confluence-0.4.3.dist-info/METADATA,sha256=sU45yX796M_cZ0ssGMaDtuxb0xwtKaPTktNAy2rczMg,29119
+markdown_to_confluence-0.4.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.4.3.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.4.3.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.4.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.4.3.dist-info/RECORD,,

md2conf/__init__.py

@@ -5,7 +5,7 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -17,14 +17,9 @@ import typing
 from pathlib import Path
 from typing import Any, Iterable, Literal, Optional, Sequence, Union
 
-import requests
-
 from . import __version__
-from .api import ConfluenceAPI
-from .application import Application
-from .converter import ConfluenceDocumentOptions, ConfluencePageID
+from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .extra import override
-from .local import LocalConverter
 from .metadata import ConfluenceSiteMetadata
 from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceSiteProperties
 
@@ -52,7 +47,7 @@ class Arguments(argparse.Namespace):
 
 
 class KwargsAppendAction(argparse.Action):
-    """Append key-value pairs to a dictionary"""
+    """Append key-value pairs to a dictionary."""
 
     @override
     def __call__(
@@ -72,6 +67,30 @@ class KwargsAppendAction(argparse.Action):
         setattr(namespace, self.dest, d)
 
 
+def unsupported(prefer: str) -> type[argparse.Action]:
+    class UnsupportedAction(argparse.Action):
+        """Display an error for unsupported command-line options."""
+
+        @override
+        def __call__(
+            self,
+            parser: argparse.ArgumentParser,
+            namespace: argparse.Namespace,
+            values: Union[None, str, Sequence[Any]],
+            option_string: Optional[str] = None,
+        ) -> None:
+            raise argparse.ArgumentError(
+                self,
+                f"this command-line option is no longer supported, use `--{prefer}`",
+            )
+
+        @override
+        def __repr__(self) -> str:
+            return f"{unsupported.__name__}({repr(prefer)})"
+
+    return UnsupportedAction
+
+
 class PositionalOnlyHelpFormatter(argparse.HelpFormatter):
     def _format_usage(
         self,
@@ -189,12 +208,18 @@ def main() -> None:
         help="Inline Mermaid diagram in Confluence page. (Marketplace app required.)",
     )
     parser.add_argument(
-        "--render-mermaid-format",
+        "--diagram-output-format",
         dest="diagram_output_format",
         choices=["png", "svg"],
         default="png",
         help="Format for rendering Mermaid and draw.io diagrams (default: 'png').",
     )
+    parser.add_argument(
+        "--render-mermaid-format",
+        action=unsupported("diagram-output-format"),
+        metavar="FORMAT",
+        help="Format for rendering Mermaid diagrams (default: 'png').",
+    )
     parser.add_argument(
         "--heading-anchors",
         action="store_true",
@@ -256,6 +281,8 @@ def main() -> None:
         webui_links=args.webui_links,
     )
     if args.local:
+        from .local import LocalConverter
+
         try:
             site_properties = ConfluenceSiteProperties(
                 domain=args.domain,
@@ -271,6 +298,11 @@ def main() -> None:
         )
         LocalConverter(options, site_metadata).process(args.mdpath)
     else:
+        from requests import HTTPError, JSONDecodeError
+
+        from .api import ConfluenceAPI
+        from .application import Application
+
         try:
             properties = ConfluenceConnectionProperties(
                 api_url=args.api_url,
@@ -289,14 +321,14 @@ def main() -> None:
                     api,
                     options,
                 ).process(args.mdpath)
-        except requests.exceptions.HTTPError as err:
+        except HTTPError as err:
             logging.error(err)
 
             # print details for a response with JSON body
             if err.response is not None:
                 try:
                     logging.error(err.response.json())
-                except requests.exceptions.JSONDecodeError:
+                except JSONDecodeError:
                     pass
 
             sys.exit(1)

md2conf/application.py

@@ -11,7 +11,8 @@ from pathlib import Path
 from typing import Optional
 
 from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
-from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID, attachment_name, elements_from_string, get_volatile_attributes
+from .converter import ConfluenceDocument, attachment_name, elements_from_string, get_volatile_attributes
+from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
@@ -158,7 +159,7 @@ class SynchronizingProcessor(Processor):
         ):
             self.api.update_page(page_id.page_id, content, title=title, version=page.version.number + 1)
         else:
-            LOGGER.info("Up-to-date page: %s", page_id)
+            LOGGER.info("Up-to-date page: %s", page_id.page_id)
 
         if document.labels is not None:
             self.api.update_labels(

md2conf/converter.py

@@ -8,28 +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 md2conf.drawio import extract_diagram
-
+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
@@ -101,90 +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:
-    """
-    Custom generator for `pymdownx.emoji`.
-    """
-
-    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 math_formatter(
-    source: str,
-    language: str,
-    css_class: str,
-    options: dict[str, Any],
-    md: markdown.Markdown,
-    classes: Optional[list[str]] = None,
-    id_value: str = "",
-    attrs: Optional[dict[str, str]] = None,
-    **kwargs: Any,
-) -> str:
-    """
-    Custom formatter for language `math` in `pymdownx.superfences`.
-    """
-
-    if classes is None:
-        classes = [css_class]
-    else:
-        classes.insert(0, css_class)
-
-    html_id = f' id="{id_value}"' if id_value else ""
-    html_class = ' class="{}"'.format(" ".join(classes))
-    html_attrs = " " + " ".join(f'{k}="{v}"' for k, v in attrs.items()) if attrs else ""
-
-    return f"<div{html_id}{html_class}{html_attrs}>{source}</div>"
-
-
-def markdown_to_html(content: str) -> str:
-    return markdown.markdown(
-        content,
-        extensions=[
-            "admonition",
-            "footnotes",
-            "markdown.extensions.tables",
-            "md_in_html",
-            "pymdownx.arithmatex",
-            "pymdownx.emoji",
-            "pymdownx.highlight",  # required by `pymdownx.superfences`
-            "pymdownx.magiclink",
-            "pymdownx.superfences",
-            "pymdownx.tilde",
-            "sane_lists",
-        ],
-        extension_configs={
-            "footnotes": {"BACKLINK_TITLE": ""},
-            "pymdownx.arithmatex": {"generic": True, "preview": False, "tex_inline_wrap": ["", ""], "tex_block_wrap": ["", ""]},
-            "pymdownx.emoji": {
-                "emoji_generator": emoji_generator,
-            },
-            "pymdownx.highlight": {
-                "use_pygments": False,
-            },
-            "pymdownx.superfences": {"custom_fences": [{"name": "math", "class": "arithmatex", "format": math_formatter}]},
-        },
-    )
-
-
 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.
@@ -333,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
 
 
@@ -594,9 +509,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             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"):
-                self.images.append(absolute_path)
-                image_filename = attachment_name(path_relative_to(absolute_path, self.base_dir))
-                return self._create_drawio(image_filename, attrs)
+                return self._transform_drawio(absolute_path, attrs)
             else:
                 return self._transform_attached_image(absolute_path, attrs)
 
@@ -651,10 +564,28 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 absolute_path = png_file
 
         self.images.append(absolute_path)
-        return self._create_image(absolute_path, attrs)
+        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:
+            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 image."
+        "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`")
@@ -663,17 +594,15 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             return self._transform_attached_image(absolute_path, attrs)
         else:
             # extract embedded editable diagram and upload as *.drawio
-            image_data = extract_diagram(absolute_path)
+            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_image(self, absolute_path: Path, attrs: ImageAttributes) -> ET._Element:
+    def _create_attached_image(self, image_name: str, attrs: ImageAttributes) -> ET._Element:
         "An image embedded into the page, linking to an attachment."
 
-        image_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
-
         attributes: dict[str, Any] = {
             ET.QName(namespaces["ac"], "align"): "center",
             ET.QName(namespaces["ac"], "layout"): "center",
@@ -803,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())
@@ -1388,48 +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 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.
-    """
-
-    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
-    prefer_raster: bool = True
-    render_drawio: 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."
 
@@ -1507,15 +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,
-                prefer_raster=self.options.prefer_raster,
-                render_drawio=self.options.render_drawio,
-                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,

md2conf/domain.py

@@ -0,0 +1,46 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+
+@dataclass
+class ConfluencePageID:
+    page_id: 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 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.
+    """
+
+    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
+    prefer_raster: bool = True
+    render_drawio: bool = False
+    render_mermaid: bool = False
+    diagram_output_format: Literal["png", "svg"] = "png"
+    webui_links: bool = False

md2conf/drawio.py

@@ -7,6 +7,11 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 import base64
+import logging
+import os
+import os.path
+import shutil
+import subprocess
 import typing
 import zlib
 from pathlib import Path
@@ -15,6 +20,8 @@ from urllib.parse import unquote_to_bytes
 
 import lxml.etree as ET
 
+LOGGER = logging.getLogger(__name__)
+
 
 class DrawioError(ValueError):
     """
@@ -220,3 +227,45 @@ def extract_diagram(path: Path) -> bytes:
         raise DrawioError(f"unrecognized file type for {path.name}")
 
     return ET.tostring(root, encoding="utf8", method="xml")
+
+
+def render_diagram(source: Path, output_format: typing.Literal["png", "svg"] = "png") -> bytes:
+    "Generates a PNG or SVG image from a draw.io diagram source."
+
+    executable = shutil.which("draw.io")
+    if executable is None:
+        raise DrawioError("draw.io executable not found")
+
+    target = f"tmp_drawio.{output_format}"
+
+    cmd = [executable, "--export", "--format", output_format, "--output", target]
+    if output_format == "png":
+        cmd.extend(["--scale", "2", "--transparent"])
+    elif output_format == "svg":
+        cmd.append("--embed-svg-images")
+    cmd.append(str(source))
+
+    LOGGER.debug("Executing: %s", " ".join(cmd))
+    try:
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=False,
+        )
+        stdout, stderr = proc.communicate()
+        if proc.returncode:
+            messages = [f"failed to convert draw.io diagram; exit code: {proc.returncode}"]
+            console_output = stdout.decode("utf-8")
+            if console_output:
+                messages.append(f"output:\n{console_output}")
+            console_error = stderr.decode("utf-8")
+            if console_error:
+                messages.append(f"error:\n{console_error}")
+            raise DrawioError("\n".join(messages))
+        with open(target, "rb") as f:
+            return f.read()
+
+    finally:
+        if os.path.exists(target):
+            os.remove(target)

md2conf/local.py

@@ -11,7 +11,8 @@ import os
 from pathlib import Path
 from typing import Optional
 
-from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
+from .converter import ConfluenceDocument
+from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .extra import override
 from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
@@ -77,10 +78,14 @@ class LocalProcessor(Processor):
         """
 
         content = document.xhtml()
-        out_path = self.out_dir / path.relative_to(self.root_dir).with_suffix(".csf")
-        os.makedirs(out_path.parent, exist_ok=True)
-        with open(out_path, "w", encoding="utf-8") as f:
+        csf_path = self.out_dir / path.relative_to(self.root_dir).with_suffix(".csf")
+        csf_dir = csf_path.parent
+        os.makedirs(csf_dir, exist_ok=True)
+        with open(csf_path, "w", encoding="utf-8") as f:
             f.write(content)
+        for name, data in document.embedded_images.items():
+            with open(csf_dir / name, "wb") as f:
+                f.write(data)
 
 
 class LocalProcessorFactory(ProcessorFactory):

md2conf/markdown.py

@@ -0,0 +1,108 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import xml.etree.ElementTree
+from typing import Any, Optional
+
+import markdown
+
+
+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:
+    """
+    Custom generator for `pymdownx.emoji`.
+    """
+
+    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 _math_formatter(
+    source: str,
+    language: str,
+    css_class: str,
+    options: dict[str, Any],
+    md: markdown.Markdown,
+    classes: Optional[list[str]] = None,
+    id_value: str = "",
+    attrs: Optional[dict[str, str]] = None,
+    **kwargs: Any,
+) -> str:
+    """
+    Custom formatter for language `math` in `pymdownx.superfences`.
+    """
+
+    if classes is None:
+        classes = [css_class]
+    else:
+        classes.insert(0, css_class)
+
+    html_id = f' id="{id_value}"' if id_value else ""
+    html_class = ' class="{}"'.format(" ".join(classes))
+    html_attrs = " " + " ".join(f'{k}="{v}"' for k, v in attrs.items()) if attrs else ""
+
+    return f"<div{html_id}{html_class}{html_attrs}>{source}</div>"
+
+
+_CONVERTER = markdown.Markdown(
+    extensions=[
+        "admonition",
+        "footnotes",
+        "markdown.extensions.tables",
+        "md_in_html",
+        "pymdownx.arithmatex",
+        "pymdownx.emoji",
+        "pymdownx.highlight",  # required by `pymdownx.superfences`
+        "pymdownx.magiclink",
+        "pymdownx.superfences",
+        "pymdownx.tilde",
+        "sane_lists",
+    ],
+    extension_configs={
+        "footnotes": {"BACKLINK_TITLE": ""},
+        "pymdownx.arithmatex": {"generic": True, "preview": False, "tex_inline_wrap": ["", ""], "tex_block_wrap": ["", ""]},
+        "pymdownx.emoji": {
+            "emoji_generator": _emoji_generator,
+        },
+        "pymdownx.highlight": {
+            "use_pygments": False,
+        },
+        "pymdownx.superfences": {"custom_fences": [{"name": "math", "class": "arithmatex", "format": _math_formatter}]},
+    },
+)
+
+
+def markdown_to_html(content: str) -> str:
+    """
+    Converts a Markdown document into XHTML with Python-Markdown.
+
+    :param content: Markdown input as a string.
+    :returns: XHTML output as a string.
+    :see: https://python-markdown.github.io/
+    """
+
+    _CONVERTER.reset()
+    html = _CONVERTER.convert(content)
+    return html

md2conf/processor.py

@@ -14,7 +14,8 @@ from pathlib import Path
 from typing import Iterable, Optional
 
 from .collection import ConfluencePageCollection
-from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
+from .converter import ConfluenceDocument
+from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .matcher import DirectoryEntry, FileEntry, Matcher, MatcherOptions
 from .metadata import ConfluenceSiteMetadata
 from .properties import ArgumentError