markdown-to-confluence 0.5.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

md2conf/csf.py

@@ -1,15 +1,16 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
 import importlib.resources as resources
 import re
+from collections.abc import Generator
+from contextlib import contextmanager
 from pathlib import Path
-from typing import Callable, TypeVar
 
 import lxml.etree as ET
 from lxml.builder import ElementMaker
@@ -45,15 +46,14 @@ def RI_ATTR(name: str) -> str:
     return _qname(_namespaces["ri"], name)
 
 
-R = TypeVar("R")
-
-
-def with_entities(func: Callable[[Path], R]) -> R:
+@contextmanager
+def entities() -> Generator[Path, None, None]:
     "Invokes a callable in the context of an entity definition file."
 
-    resource_path = resources.files(__package__).joinpath("entities.dtd")
-    with resources.as_file(resource_path) as dtd_path:
-        return func(dtd_path)
+    if __package__ is not None:  # always true at run time
+        resource_path = resources.files(__package__).joinpath("entities.dtd")
+        with resources.as_file(resource_path) as dtd_path:
+            yield dtd_path
 
 
 def _elements_from_strings(dtd_path: Path, items: list[str]) -> ElementType:
@@ -102,7 +102,8 @@ def elements_from_strings(items: list[str]) -> ElementType:
     :returns: An XML document as an element tree.
     """
 
-    return with_entities(lambda dtd_path: _elements_from_strings(dtd_path, items))
+    with entities() as dtd_path:
+        return _elements_from_strings(dtd_path, items)
 
 
 def elements_from_string(content: str) -> ElementType:
@@ -134,7 +135,8 @@ def content_to_string(content: str) -> str:
     :returns: XML as a string.
     """
 
-    return with_entities(lambda dtd_path: _content_to_string(dtd_path, content))
+    with entities() as dtd_path:
+        return _content_to_string(dtd_path, content)
 
 
 def elements_to_string(root: ElementType) -> str:

md2conf/drawio/extension.py

@@ -0,0 +1,116 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import uuid
+from pathlib import Path
+
+import lxml.etree as ET
+
+from md2conf.attachment import EmbeddedFileData, ImageData, attachment_name
+from md2conf.compatibility import override, path_relative_to
+from md2conf.csf import AC_ATTR, AC_ELEM
+from md2conf.extension import MarketplaceExtension
+from md2conf.formatting import ImageAlignment, ImageAttributes
+
+from .render import extract_diagram, render_diagram
+
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+
+
+class DrawioExtension(MarketplaceExtension):
+    @override
+    def matches_image(self, absolute_path: Path) -> bool:
+        return absolute_path.name.endswith((".drawio", ".drawio.png", ".drawio.svg", ".drawio.xml"))
+
+    @override
+    def matches_fenced(self, language: str, content: str) -> bool:
+        return False
+
+    @override
+    def transform_image(self, absolute_path: Path, attrs: ImageAttributes) -> ElementType:
+        if absolute_path.name.endswith((".drawio.png", ".drawio.svg")):
+            return self._transform_drawio_image(absolute_path, attrs)
+        elif absolute_path.name.endswith((".drawio", ".drawio.xml")):
+            return self._transform_drawio(absolute_path, attrs)
+        else:
+            raise RuntimeError(f"unrecognized image format: {absolute_path.suffix}")
+
+    @override
+    def transform_fenced(self, content: str) -> ElementType:
+        raise RuntimeError("draw.io diagrams cannot be defined in fenced code blocks")
+
+    def _transform_drawio(self, absolute_path: Path, attrs: ImageAttributes) -> ElementType:
+        relative_path = path_relative_to(absolute_path, self.base_dir)
+        if self.options.render:
+            image_data = render_diagram(absolute_path, self.generator.options.output_format)
+            return self.generator.transform_attached_data(image_data, attrs, relative_path)
+        else:
+            self.attachments.add_image(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) -> ElementType:
+        if self.options.render:
+            # already a PNG or SVG file (with embedded draw.io content)
+            return self.generator.transform_attached_image(absolute_path, attrs)
+        else:
+            # extract embedded editable diagram and upload as *.drawio
+            image_data = extract_diagram(absolute_path)
+            image_filename = attachment_name(path_relative_to(absolute_path.with_suffix(".xml"), self.base_dir))
+            self.attachments.add_embed(image_filename, EmbeddedFileData(image_data, attrs.alt))
+
+            return self._create_drawio(image_filename, attrs)
+
+    def _create_drawio(self, filename: str, attrs: ImageAttributes) -> ElementType:
+        "A draw.io diagram embedded into the page, linking to an attachment."
+
+        parameters: list[ElementType] = [
+            AC_ELEM(
+                "parameter",
+                {AC_ATTR("name"): "diagramName"},
+                filename,
+            ),
+        ]
+        if attrs.width is not None:
+            parameters.append(
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "width"},
+                    str(attrs.width),
+                ),
+            )
+        if attrs.height is not None:
+            parameters.append(
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "height"},
+                    str(attrs.height),
+                ),
+            )
+        if attrs.alignment is ImageAlignment.CENTER:
+            parameters.append(
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "pCenter"},
+                    str(1),
+                ),
+            )
+
+        local_id = str(uuid.uuid4())
+        macro_id = str(uuid.uuid4())
+        return AC_ELEM(
+            "structured-macro",
+            {
+                AC_ATTR("name"): "drawio",
+                AC_ATTR("schema-version"): "1",
+                "data-layout": "default",
+                AC_ATTR("local-id"): local_id,
+                AC_ATTR("macro-id"): macro_id,
+            },
+            *parameters,
+        )

md2conf/{drawio.py → drawio/render.py}

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """

md2conf/emoticon.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -12,8 +12,8 @@ _EMOJI_TO_EMOTICON = {
     "slight_frown": "sad",
     "slight_smile": "smile",
     "stuck_out_tongue": "cheeky",
-    "thumbsdown": "thumbs-down",
-    "thumbsup": "thumbs-up",
+    "thumbsdown": "thumbs-down",  # spellchecker:disable-line
+    "thumbsup": "thumbs-up",  # spellchecker:disable-line
     "wink": "wink",
 }
 

md2conf/environment.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -83,7 +83,7 @@ class ConfluenceSiteProperties:
         self.space_key = opt_space_key
 
 
-class ConfluenceConnectionProperties:
+class ConnectionProperties:
     """
     Properties related to connecting to Confluence.
 

md2conf/extension.py

@@ -0,0 +1,78 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from abc import abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+import lxml.etree as ET
+
+from .attachment import AttachmentCatalog
+from .formatting import ImageAttributes
+from .image import ImageGenerator
+
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+
+
+@dataclass
+class ExtensionOptions:
+    """
+    Customizes how Confluence content is generated for a drawing or diagram.
+
+    :param render: Whether to pre-render the drawing or diagram into a PNG/SVG image.
+    """
+
+    render: bool
+
+
+class MarketplaceExtension:
+    """
+    Base class for integrating third-party Atlassian Marketplace extensions.
+
+    Derive from this class to generate custom Confluence Storage Format output for Markdown image references and fenced code blocks.
+    """
+
+    generator: ImageGenerator
+    options: ExtensionOptions
+
+    def __init__(self, generator: ImageGenerator, options: ExtensionOptions) -> None:
+        self.generator = generator
+        self.options = options
+
+    @property
+    def base_dir(self) -> Path:
+        "Base directory for resolving relative links."
+
+        return self.generator.base_dir
+
+    @property
+    def attachments(self) -> AttachmentCatalog:
+        "Maintains a list of files and binary data to be uploaded to Confluence as attachments."
+
+        return self.generator.attachments
+
+    @abstractmethod
+    def matches_image(self, absolute_path: Path) -> bool:
+        "True if the extension is able to process the external file."
+        ...
+
+    @abstractmethod
+    def matches_fenced(self, language: str, content: str) -> bool:
+        "True if the extension can process the fenced code block."
+        ...
+
+    @abstractmethod
+    def transform_image(self, absolute_path: Path, attrs: ImageAttributes) -> ElementType:
+        "Emits Confluence Storage Format XHTML for a drawing or diagram linked as an image."
+        ...
+
+    @abstractmethod
+    def transform_fenced(self, content: str) -> ElementType:
+        "Emits Confluence Storage Format XHTML for a drawing or diagram defined in a fenced code block."
+
+        ...

md2conf/external.py

@@ -0,0 +1,49 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import logging
+import subprocess
+from typing import Sequence
+
+LOGGER = logging.getLogger(__name__)
+
+
+def execute_subprocess(command: Sequence[str], data: bytes, *, application: str | None = None) -> bytes:
+    """
+    Executes a subprocess, feeding input to stdin, and capturing output from stdout.
+
+    This function handles the common pattern of:
+
+    1. executing a command with stdin/stdout/stderr pipes,
+    2. passing input data as binary (e.g. UTF-8 encoded),
+    3. capturing binary output,
+    4. error handling with exit codes and stderr.
+
+    :param command: Full command with arguments to execute.
+    :param data: Application input as `bytes`.
+    :param application: Human-readable application name for error messages (e.g., "Mermaid", "PlantUML").
+    :returns: Application output as `bytes`.
+    :raises RuntimeError: If the subprocess fails with non-zero exit code.
+    """
+
+    LOGGER.debug("Executing: %s", " ".join(command))
+
+    proc = subprocess.Popen(command, stdout=subprocess.PIPE, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+    stdout, stderr = proc.communicate(input=data)
+
+    if proc.returncode:
+        messages = [f"failed to execute {application or 'application'}; 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 RuntimeError("\n".join(messages))
+
+    return stdout

md2conf/formatting.py

@@ -0,0 +1,135 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import enum
+from dataclasses import dataclass
+from typing import ClassVar
+
+from .csf import AC_ATTR
+
+
+@enum.unique
+class FormattingContext(enum.Enum):
+    "Identifies the formatting context for the element."
+
+    BLOCK = "block"
+    INLINE = "inline"
+
+
+@enum.unique
+class ImageAlignment(enum.Enum):
+    "Determines whether to align block-level images to center, left or right."
+
+    CENTER = "center"
+    LEFT = "left"
+    RIGHT = "right"
+
+
+def display_width(*, width: int | None, max_width: int | None) -> int | None:
+    """
+    Calculate the display width for an image, applying the maximum image width constraint if set.
+
+    :returns: The constrained display width, or None if no constraint is needed.
+    """
+
+    if width is None or max_width is None:
+        return None
+    if width <= max_width:
+        return None  # no constraint needed, image is already within limits
+    return max_width
+
+
+@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).
+    :param alignment: Alignment for block-level images.
+    """
+
+    context: FormattingContext
+    width: int | None
+    height: int | None
+    alt: str | None
+    title: str | None
+    caption: str | None
+    alignment: ImageAlignment = ImageAlignment.CENTER
+
+    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, *, max_width: int | None) -> dict[str, str]:
+        """
+        Produces a key-value store of element attributes.
+
+        :param max_width: The desired maximum width of the image in pixels.
+        """
+
+        attributes: dict[str, str] = {}
+        match self.context:
+            case FormattingContext.BLOCK:
+                match self.alignment:
+                    case ImageAlignment.LEFT:
+                        align = "left"
+                        layout = "align-start"
+                    case ImageAlignment.RIGHT:
+                        align = "right"
+                        layout = "align-end"
+                    case ImageAlignment.CENTER:
+                        align = "center"
+                        layout = "center"
+                attributes[AC_ATTR("align")] = align
+                attributes[AC_ATTR("layout")] = layout
+
+                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"
+                    # Use display_width if set, otherwise use natural width
+                    effective_width = display_width(width=self.width, max_width=max_width) or self.width
+                    attributes[AC_ATTR("width")] = str(effective_width)
+
+            case 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)
+
+        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
+
+    EMPTY_BLOCK: ClassVar["ImageAttributes"]
+    EMPTY_INLINE: ClassVar["ImageAttributes"]
+
+    @classmethod
+    def empty(cls, context: FormattingContext) -> "ImageAttributes":
+        match context:
+            case FormattingContext.BLOCK:
+                return cls.EMPTY_BLOCK
+            case FormattingContext.INLINE:
+                return cls.EMPTY_INLINE
+
+
+ImageAttributes.EMPTY_BLOCK = ImageAttributes(
+    FormattingContext.BLOCK, width=None, height=None, alt=None, title=None, caption=None, alignment=ImageAlignment.CENTER
+)
+ImageAttributes.EMPTY_INLINE = ImageAttributes(
+    FormattingContext.INLINE, width=None, height=None, alt=None, title=None, caption=None, alignment=ImageAlignment.CENTER
+)

md2conf/frontmatter.py

@@ -0,0 +1,70 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import re
+import typing
+from typing import Any, TypeVar
+
+import yaml
+
+from .serializer import JsonType, json_to_object
+
+D = TypeVar("D")
+
+
+def extract_value(pattern: str, text: str) -> tuple[str | None, str]:
+    """
+    Extracts the value captured by the first group in a regular expression.
+
+    :returns: A tuple of (1) the value extracted and (2) remaining text without the captured text.
+    """
+
+    expr = re.compile(pattern)
+    if expr.groups != 1:
+        raise ValueError("expected: a single group whose value to extract")
+
+    class _Matcher:
+        value: str | None = None
+
+        def __call__(self, match: re.Match[str]) -> str:
+            self.value = match.group(1)
+            return ""
+
+    matcher = _Matcher()
+    text = expr.sub(matcher, text, count=1)
+    return matcher.value, text
+
+
+def extract_frontmatter_block(text: str) -> tuple[str | None, str]:
+    "Extracts the front-matter from a Markdown document as a blob of unparsed text."
+
+    return extract_value(r"(?ms)\A---$(.+?)^---$", text)
+
+
+def extract_frontmatter_json(text: str) -> tuple[dict[str, JsonType] | None, str]:
+    "Extracts the front-matter from a Markdown document as a dictionary."
+
+    block, text = extract_frontmatter_block(text)
+
+    properties: dict[str, Any] | None = None
+    if block is not None:
+        data = yaml.safe_load(block)
+        if isinstance(data, dict):
+            properties = typing.cast(dict[str, JsonType], data)
+
+    return properties, text
+
+
+def extract_frontmatter_object(tp: type[D], text: str) -> tuple[D | None, str]:
+    properties, text = extract_frontmatter_json(text)
+
+    value_object: D | None = None
+    if properties is not None:
+        value_object = json_to_object(tp, properties)
+
+    return value_object, text

md2conf/image.py

@@ -0,0 +1,127 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import lxml.etree as ET
+
+from .attachment import AttachmentCatalog, EmbeddedFileData, ImageData, attachment_name
+from .compatibility import path_relative_to
+from .csf import AC_ELEM, RI_ATTR, RI_ELEM
+from .formatting import ImageAttributes
+from .png import extract_png_dimensions
+from .svg import fix_svg_get_dimensions, get_svg_dimensions
+
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+
+
+@dataclass
+class ImageGeneratorOptions:
+    """
+    Configures how images are pre-rendered and what Confluence Storage Format output they produce.
+
+    :param output_format: Target image format for diagrams.
+    :param prefer_raster: Whether to choose PNG files over SVG files when available.
+    :param max_width: Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.
+    """
+
+    output_format: Literal["png", "svg"]
+    prefer_raster: bool
+    max_width: int | None
+
+
+class ImageGenerator:
+    base_dir: Path
+    attachments: AttachmentCatalog
+
+    def __init__(self, base_dir: Path, attachments: AttachmentCatalog, options: ImageGeneratorOptions) -> None:
+        self.base_dir = base_dir
+        self.attachments = attachments
+        self.options = options
+
+    def transform_attached_image(self, absolute_path: Path, attrs: ImageAttributes) -> ElementType:
+        "Emits Confluence Storage Format XHTML for an attached raster or vector image."
+
+        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
+
+        # infer SVG dimensions if not already specified
+        if absolute_path.suffix == ".svg" and attrs.width is None and attrs.height is None:
+            svg_width, svg_height = get_svg_dimensions(absolute_path)
+            if svg_width is not None:
+                attrs = ImageAttributes(
+                    context=attrs.context,
+                    width=svg_width,
+                    height=svg_height,
+                    alt=attrs.alt,
+                    title=attrs.title,
+                    caption=attrs.caption,
+                    alignment=attrs.alignment,
+                )
+
+        self.attachments.add_image(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)
+
+    def transform_attached_data(self, image_data: bytes, attrs: ImageAttributes, relative_path: Path | None = None) -> ElementType:
+        "Emits Confluence Storage Format XHTML for an attached raster or vector image."
+
+        # extract dimensions and update attributes based on format
+        width: int | None
+        height: int | None
+        match self.options.output_format:
+            case "svg":
+                image_data, width, height = fix_svg_get_dimensions(image_data)
+            case "png":
+                width, height = extract_png_dimensions(data=image_data)
+
+        # only update attributes if we successfully extracted dimensions and the base attributes don't already have explicit dimensions
+        if (width is not None or height is not None) and (attrs.width is None and attrs.height is None):
+            # create updated image attributes with extracted dimensions
+            attrs = ImageAttributes(
+                context=attrs.context,
+                width=width,
+                height=height,
+                alt=attrs.alt,
+                title=attrs.title,
+                caption=attrs.caption,
+                alignment=attrs.alignment,
+            )
+
+        # generate filename and add as attachment
+        if relative_path is not None:
+            image_filename = attachment_name(relative_path.with_suffix(f".{self.options.output_format}"))
+            self.attachments.add_embed(image_filename, EmbeddedFileData(image_data, attrs.alt))
+        else:
+            image_hash = hashlib.md5(image_data).hexdigest()
+            image_filename = attachment_name(f"embedded_{image_hash}.{self.options.output_format}")
+            self.attachments.add_embed(image_filename, EmbeddedFileData(image_data))
+
+        return self.create_attached_image(image_filename, attrs)
+
+    def create_attached_image(self, image_name: str, attrs: ImageAttributes) -> ElementType:
+        "Emits Confluence Storage Format XHTML for an image embedded into the page, linking to an attachment."
+
+        elements: list[ElementType] = []
+        elements.append(
+            RI_ELEM(
+                "attachment",
+                # refers to an attachment uploaded alongside the page
+                {RI_ATTR("filename"): image_name},
+            )
+        )
+        if attrs.caption:
+            elements.append(AC_ELEM("caption", attrs.caption))
+
+        return AC_ELEM("image", attrs.as_dict(max_width=self.options.max_width), *elements)