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

md2conf/metadata.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/{domain.py → options.py}

@@ -1,11 +1,12 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
+import dataclasses
 from dataclasses import dataclass
 from typing import Literal
 
@@ -16,44 +17,102 @@ class ConfluencePageID:
 
 
 @dataclass
-class ConfluenceDocumentOptions:
+class ImageLayoutOptions:
     """
-    Options that control the generated page content.
+    Image layout options on a Confluence page.
+
+    :param alignment: Alignment for block-level images and formulas.
+    :param max_width: Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.
+    """
+
+    alignment: Literal["center", "left", "right"] | None = None
+    max_width: int | None = None
+
+
+@dataclass
+class TableLayoutOptions:
+    """
+    Table layout options on a Confluence page.
+
+    :param width: Maximum table width in pixels.
+    :param display_mode: Whether to use fixed or responsive column widths.
+    """
+
+    width: int | None = None
+    display_mode: Literal["fixed", "responsive"] | None = None
+
+
+@dataclass
+class LayoutOptions:
+    """
+    Layout options for content on a Confluence page.
+
+    Layout options can be overridden in Markdown front-matter.
+
+    :param image: Image layout options.
+    :param table: Table layout options.
+    :param alignment: Default alignment (unless overridden with more specific setting).
+    """
+
+    image: ImageLayoutOptions = dataclasses.field(default_factory=ImageLayoutOptions)
+    table: TableLayoutOptions = dataclasses.field(default_factory=TableLayoutOptions)
+    alignment: Literal["center", "left", "right"] | None = None
+
+    def get_image_alignment(self) -> Literal["center", "left", "right"]:
+        return self.image.alignment or self.alignment or "center"
+
+
+@dataclass
+class ConverterOptions:
+    """
+    Options for converting an HTML tree into Confluence Storage Format.
 
     :param heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
         conversion rules for the identifier.
     :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 skip_title_heading: Whether to remove the first heading from document body when used as page title.
-    :param title_prefix: String to prepend to Confluence page title for each published page.
-    :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 render_plantuml: Whether to pre-render PlantUML 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.
-    :param alignment: Alignment for block-level images and formulas.
-    :param max_image_width: Maximum display width for images [px]. Wider images are scaled down for page display.
-        Original size kept for full-size viewing.
     :param use_panel: Whether to transform admonitions and alerts into a Confluence custom panel.
+    :param layout: Layout options for content on a Confluence page.
     """
 
     heading_anchors: bool = False
     ignore_invalid_url: bool = False
     skip_title_heading: bool = False
-    title_prefix: str | None = None
-    generated_by: str | None = "This page has been generated with a tool."
-    root_page_id: ConfluencePageID | None = None
-    keep_hierarchy: bool = False
     prefer_raster: bool = True
     render_drawio: bool = False
     render_mermaid: bool = False
+    render_plantuml: bool = False
     render_latex: bool = False
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False
-    alignment: Literal["center", "left", "right"] = "center"
-    max_image_width: int | None = None
     use_panel: bool = False
+    layout: LayoutOptions = dataclasses.field(default_factory=LayoutOptions)
+
+
+@dataclass
+class DocumentOptions:
+    """
+    Options that control the generated page content.
+
+    :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 title_prefix: String to prepend to Confluence page title for each published page.
+    :param generated_by: Text to use as the generated-by prompt (or `None` to omit a prompt).
+    :param skip_update: Whether to skip saving Confluence page ID in Markdown files.
+    :param converter: Options for converting an HTML tree into Confluence Storage Format.
+    """
+
+    root_page_id: ConfluencePageID | None = None
+    keep_hierarchy: bool = False
+    title_prefix: str | None = None
+    generated_by: str | None = "This page has been generated with a tool."
+    skip_update: bool = False
+    converter: ConverterOptions = dataclasses.field(default_factory=ConverterOptions)

md2conf/plantuml/config.py

@@ -0,0 +1,20 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PlantUMLConfigProperties:
+    """
+    Configuration options for rendering PlantUML diagrams.
+
+    :param scale: Scaling factor for the rendered diagram.
+    """
+
+    scale: float | None = None

md2conf/plantuml/extension.py

@@ -0,0 +1,158 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import hashlib
+import logging
+import uuid
+from pathlib import Path
+
+import lxml.etree as ET
+from cattrs import BaseValidationError
+
+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 ImageAttributes
+from md2conf.svg import get_svg_dimensions
+
+from .config import PlantUMLConfigProperties
+from .render import compress_plantuml_data, has_plantuml, render_diagram
+from .scanner import PlantUMLScanner
+
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+
+LOGGER = logging.getLogger(__name__)
+
+
+class PlantUMLExtension(MarketplaceExtension):
+    @override
+    def matches_image(self, absolute_path: Path) -> bool:
+        return absolute_path.name.endswith((".puml", ".plantuml"))
+
+    @override
+    def matches_fenced(self, language: str, content: str) -> bool:
+        return language == "plantuml"
+
+    def _extract_plantuml_config(self, content: str) -> PlantUMLConfigProperties | None:
+        "Extract config from PlantUML YAML front matter configuration."
+
+        try:
+            properties = PlantUMLScanner().read(content)
+            return properties.config
+        except BaseValidationError as ex:
+            LOGGER.warning("Failed to extract PlantUML properties: %s", ex)
+            return None
+
+    @override
+    def transform_image(self, absolute_path: Path, attrs: ImageAttributes) -> ElementType:
+        relative_path = path_relative_to(absolute_path, self.base_dir)
+
+        # read PlantUML source
+        with open(absolute_path, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        return self._transform_plantuml(content, attrs, relative_path)
+
+    @override
+    def transform_fenced(self, content: str) -> ElementType:
+        return self._transform_plantuml(content, ImageAttributes.EMPTY_BLOCK)
+
+    def _transform_plantuml(self, content: str, attrs: ImageAttributes, relative_path: Path | None = None) -> ElementType:
+        """
+        Emits Confluence Storage Format XHTML for a PlantUML diagram read from an external file or defined in a fenced code block.
+
+        When `render_plantuml` is enabled, renders as an image attachment. Otherwise, uses a structured macro with embedded SVG and compressed source.
+        """
+
+        if self.options.render:
+            # render diagram as image file (PNG or SVG based on diagram output format)
+            config = self._extract_plantuml_config(content)
+            image_data = render_diagram(content, self.generator.options.output_format, config=config)
+            return self.generator.transform_attached_data(image_data, attrs, relative_path)
+        else:
+            if relative_path is not None:
+                absolute_path = self.base_dir / relative_path
+                self.attachments.add_image(ImageData(absolute_path, attrs.alt))
+
+            # use `structured-macro` with SVG attachment
+            if has_plantuml():
+                # render to SVG for structured macro (macro requires SVG)
+                config = self._extract_plantuml_config(content)
+                image_data = render_diagram(content, "svg", config=config)
+
+                # extract dimensions from SVG
+                dimensions = get_svg_dimensions(image_data)
+
+                # generate SVG filename and add as attachment
+                if relative_path is not None:
+                    svg_filename = attachment_name(relative_path.with_suffix(".svg"))
+                    self.attachments.add_embed(svg_filename, EmbeddedFileData(image_data, attrs.alt))
+                else:
+                    plantuml_hash = hashlib.md5(content.encode("utf-8")).hexdigest()
+                    svg_filename = attachment_name(f"embedded_{plantuml_hash}.svg")
+                    self.attachments.add_embed(svg_filename, EmbeddedFileData(image_data))
+
+                return self._create_plantuml_macro(content, svg_filename, dimensions)
+            else:
+                return self._create_plantuml_macro(content)
+
+    def _create_plantuml_macro(self, source: str, filename: str | None = None, dimensions: tuple[int, int] | None = None) -> ElementType:
+        """
+        A PlantUML diagram using a `structured-macro` with embedded data.
+
+        Generates a macro compatible with "PlantUML Diagrams for Confluence" app.
+
+        :see: https://stratus-addons.atlassian.net/wiki/spaces/PDFC/pages/1839333377
+        """
+
+        local_id = str(uuid.uuid4())
+        macro_id = str(uuid.uuid4())
+
+        # Compress PlantUML source for embedding
+        compressed_data = compress_plantuml_data(source)
+
+        # Build mandatory parameters
+        parameters: list[ElementType] = [
+            AC_ELEM("parameter", {AC_ATTR("name"): "data"}, compressed_data),
+            AC_ELEM("parameter", {AC_ATTR("name"): "compressed"}, "true"),
+            AC_ELEM("parameter", {AC_ATTR("name"): "revision"}, "1"),
+            AC_ELEM("parameter", {AC_ATTR("name"): "toolbar"}, "bottom"),
+        ]
+        if filename is not None:
+            parameters.append(AC_ELEM("parameter", {AC_ATTR("name"): "filename"}, filename))
+
+        # add optional dimension parameters if available
+        if dimensions is not None:
+            width, height = dimensions
+            parameters.append(
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "originalWidth"},
+                    str(width),
+                )
+            )
+            parameters.append(
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "originalHeight"},
+                    str(height),
+                )
+            )
+
+        return AC_ELEM(
+            "structured-macro",
+            {
+                AC_ATTR("name"): "plantumlcloud",
+                AC_ATTR("schema-version"): "1",
+                "data-layout": "default",
+                AC_ATTR("local-id"): local_id,
+                AC_ATTR("macro-id"): macro_id,
+            },
+            *parameters,
+        )

md2conf/plantuml/render.py

@@ -0,0 +1,138 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import base64
+import logging
+import os
+import shlex
+import shutil
+import zlib
+from pathlib import Path
+from typing import Literal
+from urllib.parse import quote
+
+import md2conf
+from md2conf.external import execute_subprocess
+
+from .config import PlantUMLConfigProperties
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _get_plantuml_jar_path() -> Path:
+    """
+    Returns the expected path to `plantuml.jar`.
+
+    Priority:
+
+    1. value of environment variable `PLANTUML_JAR`
+    2. path to `plantuml.jar` if found in parent directory of module `md2conf`
+    3. path to `plantuml.jar` if found in current directory
+    """
+
+    # check environment variable
+    env_jar = os.environ.get("PLANTUML_JAR")
+    if env_jar:
+        return Path(env_jar)
+
+    # check parent directory of module `md2conf`
+    base_path = Path(md2conf.__file__).parent.parent
+    jar_path = base_path / "plantuml.jar"
+    if jar_path.exists():
+        return jar_path
+
+    # check current directory
+    return Path("plantuml.jar")
+
+
+def _get_plantuml_command() -> list[str]:
+    """
+    Returns the command to invoke PlantUML.
+
+    :raises RuntimeError: Raised when `plantuml.jar` is not found.
+    """
+
+    env_cmd = os.environ.get("PLANTUML_CMD")
+    if env_cmd:
+        LOGGER.debug(f"Using PlantUML command: {env_cmd}")
+        return shlex.split(env_cmd)
+
+    jar_path = _get_plantuml_jar_path()
+    if jar_path.is_file():
+        LOGGER.debug(f"Using PlantUML JAR at: {jar_path}")
+        return ["java", "-jar", str(jar_path)]
+
+    # JAR not found - fail with helpful message
+    raise RuntimeError(
+        "PlantUML JAR not found. Download `plantuml.jar` from https://github.com/plantuml/plantuml/releases and set the PLANTUML_JAR environment variable."
+    )
+
+
+def has_plantuml() -> bool:
+    """True if PlantUML JAR is available and Java is installed."""
+
+    jar_path = _get_plantuml_jar_path()
+
+    # Check if we have JAR file and Java is available
+    return jar_path.is_file() and shutil.which("java") is not None
+
+
+def render_diagram(
+    source: str,
+    output_format: Literal["png", "svg"] = "png",
+    config: PlantUMLConfigProperties | None = None,
+) -> bytes:
+    "Generates a PNG or SVG image from a PlantUML diagram source."
+
+    if config is None:
+        config = PlantUMLConfigProperties()
+
+    # command for PlantUML with pipe mode
+    cmd = _get_plantuml_command()
+    cmd.extend(
+        [
+            "--charset",
+            "utf-8",
+            "--format",
+            output_format,
+            "--no-error-image",
+            "--pipe",
+        ]
+    )
+
+    # Add scale if specified
+    if config.scale is not None:
+        cmd.extend(["-scale", str(config.scale)])
+
+    return execute_subprocess(cmd, source.encode("utf-8"), application="PlantUML")
+
+
+def compress_plantuml_data(source: str) -> str:
+    """
+    Compress PlantUML source for embedding in plantumlcloud macro.
+
+    Implements the encoding used by PlantUML Diagrams for Confluence:
+
+    1. URI encode the source
+    2. Deflate with raw deflate (zlib)
+    3. Base64 encode
+
+    :param source: PlantUML diagram source code.
+    :returns: Compressed and encoded data suitable for macro data parameter.
+    :see: https://stratus-addons.atlassian.net/wiki/spaces/PDFC/pages/1839333377
+    """
+
+    # Step 1: URI encode
+    encoded = quote(source, safe="")
+
+    # Step 2: Deflate with raw deflate (remove zlib header/trailer)
+    # zlib.compress() adds 2-byte header and 4-byte trailer
+    deflated = zlib.compress(encoded.encode("utf-8"))[2:-4]
+
+    # Step 3: Base64 encode
+    return base64.b64encode(deflated).decode("ascii")

md2conf/plantuml/scanner.py

@@ -0,0 +1,56 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from dataclasses import dataclass
+
+from md2conf.frontmatter import extract_frontmatter_object
+
+from .config import PlantUMLConfigProperties
+
+
+@dataclass
+class PlantUMLProperties:
+    """
+    An object that holds the front-matter properties structure
+    for PlantUML diagrams.
+
+    :param title: The title of the diagram.
+    :param config: Configuration options for rendering.
+    """
+
+    title: str | None = None
+    config: PlantUMLConfigProperties | None = None
+
+
+class PlantUMLScanner:
+    """
+    Extracts properties from the JSON/YAML front-matter of a PlantUML diagram.
+    """
+
+    def read(self, content: str) -> PlantUMLProperties:
+        """
+        Extracts rendering preferences from a PlantUML front-matter content.
+
+        ```
+        ---
+        title: Class diagram
+        config:
+            scale: 1
+        ---
+        @startuml
+        class Example
+        @enduml
+        ```
+        """
+
+        properties, _ = extract_frontmatter_object(PlantUMLProperties, content)
+        if properties is not None:
+            config = properties.config or PlantUMLConfigProperties()
+            return PlantUMLProperties(title=properties.title, config=config)
+
+        return PlantUMLProperties()