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

md2conf/options.py

@@ -0,0 +1,116 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import dataclasses
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class ConfluencePageID:
+    page_id: str
+
+
+@dataclass
+class ImageLayoutOptions:
+    """
+    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 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 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
+    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
+    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 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."
+    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_bytes
+
+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
+                width, height = get_svg_dimensions_from_bytes(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, width, height)
+            else:
+                return self._create_plantuml_macro(content)
+
+    def _create_plantuml_macro(self, source: str, filename: str | None = None, width: int | None = None, height: 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 width is not None:
+            parameters.append(
+                AC_ELEM(
+                    "parameter",
+                    {AC_ATTR("name"): "originalWidth"},
+                    str(width),
+                )
+            )
+        if height is not None:
+            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,139 @@
+"""
+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()
+
+    # Build command for PlantUML with pipe mode
+    # -pipe: read from stdin and write to stdout
+    # -t<format>: output format (png or svg)
+    # -charset utf-8: ensure UTF-8 encoding
+    cmd = _get_plantuml_command()
+    cmd.extend(
+        [
+            "-pipe",
+            f"-t{output_format}",
+            "-charset",
+            "utf-8",
+        ]
+    )
+
+    # 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()

md2conf/png.py

@@ -0,0 +1,202 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from io import BytesIO
+from pathlib import Path
+from struct import unpack
+from typing import BinaryIO, Iterable, overload
+
+
+class _Chunk:
+    "Data chunk in binary data as per the PNG image format."
+
+    __slots__ = ("length", "name", "data", "crc")
+
+    length: int
+    name: bytes
+    data: bytes
+    crc: bytes
+
+    def __init__(self, length: int, name: bytes, data: bytes, crc: bytes):
+        self.length = length
+        self.name = name
+        self.data = data
+        self.crc = crc
+
+
+def _read_signature(f: BinaryIO) -> None:
+    "Reads and checks PNG signature (first 8 bytes)."
+
+    signature = f.read(8)
+    if signature != b"\x89PNG\r\n\x1a\n":
+        raise ValueError("not a valid PNG file")
+
+
+def _read_chunk(f: BinaryIO) -> _Chunk | None:
+    "Reads and parses a PNG chunk such as `IHDR` or `tEXt`."
+
+    length_bytes = f.read(4)
+    if not length_bytes:
+        return None
+
+    if len(length_bytes) != 4:
+        raise ValueError("expected: 4 bytes storing chunk length")
+
+    length = int.from_bytes(length_bytes, "big")
+
+    data_length = 4 + length + 4
+    data_bytes = f.read(data_length)
+    actual_length = len(data_bytes)
+    if actual_length != data_length:
+        raise ValueError(f"expected: {length} bytes storing chunk data; got: {actual_length}")
+
+    chunk_type = data_bytes[0:4]
+    chunk_data = data_bytes[4:-4]
+    crc = data_bytes[-4:]
+
+    return _Chunk(length, chunk_type, chunk_data, crc)
+
+
+def _extract_png_dimensions(source_file: BinaryIO) -> tuple[int, int]:
+    """
+    Returns the width and height of a PNG image inspecting its header.
+
+    :param source_file: A binary file opened for reading that contains PNG image data.
+    :returns: A tuple of the image's width and height in pixels.
+    """
+
+    _read_signature(source_file)
+
+    # validate IHDR (Image Header) chunk
+    ihdr = _read_chunk(source_file)
+    if ihdr is None:
+        raise ValueError("missing IHDR chunk")
+
+    if ihdr.length != 13:
+        raise ValueError("invalid chunk length")
+    if ihdr.name != b"IHDR":
+        raise ValueError(f"expected: IHDR chunk; got: {ihdr.name!r}")
+
+    (
+        width,
+        height,
+        bit_depth,  # pyright: ignore[reportUnusedVariable]
+        color_type,  # pyright: ignore[reportUnusedVariable]
+        compression,  # pyright: ignore[reportUnusedVariable]
+        filter,  # pyright: ignore[reportUnusedVariable]
+        interlace,  # pyright: ignore[reportUnusedVariable]
+    ) = unpack(">IIBBBBB", ihdr.data)  # spellchecker:disable-line
+    return width, height
+
+
+@overload
+def extract_png_dimensions(*, data: bytes) -> tuple[int, int]: ...
+
+
+@overload
+def extract_png_dimensions(*, path: str | Path) -> tuple[int, int]: ...
+
+
+def extract_png_dimensions(*, data: bytes | None = None, path: str | Path | None = None) -> tuple[int, int]:
+    """
+    Returns the width and height of a PNG image inspecting its header.
+
+    :param data: PNG image data.
+    :param path: Path to the PNG image file.
+    :returns: A tuple of the image's width and height in pixels.
+    """
+
+    if data is not None and path is not None:
+        raise TypeError("expected: either `data` or `path`; got: both")
+    elif data is not None:
+        with BytesIO(data) as f:
+            return _extract_png_dimensions(f)
+    elif path is not None:
+        with open(path, "rb") as f:
+            return _extract_png_dimensions(f)
+    else:
+        raise TypeError("expected: either `data` or `path`; got: neither")
+
+
+def _write_chunk(f: BinaryIO, chunk: _Chunk) -> None:
+    f.write(chunk.length.to_bytes(4, "big"))
+    f.write(chunk.name)
+    f.write(chunk.data)
+    f.write(chunk.crc)
+
+
+def _remove_png_chunks(names: Iterable[str], source_file: BinaryIO, target_file: BinaryIO) -> None:
+    """
+    Rewrites a PNG file by removing chunks with the specified names.
+
+    :param source_file: A binary file opened for reading that contains PNG image data.
+    :param target_file: A binary file opened for writing to receive PNG image data.
+    """
+
+    exclude_set = set(name.encode("ascii") for name in names)
+
+    _read_signature(source_file)
+    target_file.write(b"\x89PNG\r\n\x1a\n")
+
+    while True:
+        chunk = _read_chunk(source_file)
+        if chunk is None:
+            break
+
+        if chunk.name not in exclude_set:
+            _write_chunk(target_file, chunk)
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: str | Path) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes, target_path: str | Path) -> None: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: str | Path, target_path: str | Path) -> None: ...
+
+
+def remove_png_chunks(
+    names: Iterable[str], *, source_data: bytes | None = None, source_path: str | Path | None = None, target_path: str | Path | None = None
+) -> bytes | None:
+    """
+    Rewrites a PNG file by removing chunks with the specified names.
+
+    :param source_data: PNG image data.
+    :param source_path: Path to the file to read from.
+    :param target_path: Path to the file to write to.
+    """
+
+    if source_data is not None and source_path is not None:
+        raise TypeError("expected: either `source_data` or `source_path`; got: both")
+    elif source_data is not None:
+
+        def source_reader() -> BinaryIO:
+            return BytesIO(source_data)
+    elif source_path is not None:
+
+        def source_reader() -> BinaryIO:
+            return open(source_path, "rb")
+    else:
+        raise TypeError("expected: either `source_data` or `source_path`; got: neither")
+
+    if target_path is None:
+        with source_reader() as source_file, BytesIO() as memory_file:
+            _remove_png_chunks(names, source_file, memory_file)
+            return memory_file.getvalue()
+    else:
+        with source_reader() as source_file, open(target_path, "wb") as target_file:
+            _remove_png_chunks(names, source_file, target_file)
+            return None