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

md2conf/latex.py

@@ -1,16 +1,14 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
 import importlib.util
 from io import BytesIO
-from pathlib import Path
-from struct import unpack
-from typing import BinaryIO, Iterable, Literal, overload
+from typing import BinaryIO, Literal
 
 
 def render_latex(expression: str, *, format: Literal["png", "svg"] = "png", dpi: int = 100, font_size: int = 12) -> bytes:
@@ -38,22 +36,24 @@ else:
     import matplotlib
     import matplotlib.pyplot as plt
 
+    # spellchecker:disable-next-line
     matplotlib.rcParams["mathtext.fontset"] = "cm"  # change font to "Computer Modern"
 
     LATEX_ENABLED = True  # pyright: ignore[reportConstantRedefinition]
 
     def _render_latex(expression: str, f: BinaryIO, *, format: Literal["png", "svg"], dpi: int, font_size: int) -> None:
         # create a figure with no axis
-        fig = plt.figure(dpi=dpi)
+        fig = plt.figure(dpi=dpi)  # pyright: ignore[reportUnknownMemberType]
 
         # transparent background
         fig.patch.set_alpha(0)
 
         # add LaTeX text
-        fig.text(x=0, y=0, s=f"${expression}$", fontsize=font_size)
+        # spellchecker:disable-next-line
+        fig.text(x=0, y=0, s=f"${expression}$", fontsize=font_size)  # pyright: ignore[reportUnknownMemberType]
 
         # save the image
-        fig.savefig(
+        fig.savefig(  # pyright: ignore[reportUnknownMemberType]
             f,
             transparent=True,
             format=format,
@@ -64,182 +64,3 @@ else:
 
         # close the figure to free memory
         plt.close(fig)
-
-
-@overload
-def get_png_dimensions(*, data: bytes) -> tuple[int, int]: ...
-
-
-@overload
-def get_png_dimensions(*, path: str | Path) -> tuple[int, int]: ...
-
-
-def get_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 _get_png_dimensions(f)
-    elif path is not None:
-        with open(path, "rb") as f:
-            return _get_png_dimensions(f)
-    else:
-        raise TypeError("expected: either `data` or `path`; got: neither")
-
-
-@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
-
-
-class _Chunk:
-    __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("insufficient bytes to read chunk length")
-
-    length = int.from_bytes(length_bytes, "big")
-
-    data_length = 4 + length + 4
-    data_bytes = f.read(data_length)
-    if len(data_bytes) != data_length:
-        raise ValueError(f"insufficient bytes to read chunk data of length {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 _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 _get_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 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, color_type, compression, filter, interlace) = unpack(">IIBBBBB", ihdr.data)  # pyright: ignore[reportUnusedVariable]
-    return width, height
-
-
-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)

md2conf/local.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
 """
@@ -10,10 +10,10 @@ import logging
 import os
 from pathlib import Path
 
+from .compatibility import override
 from .converter import ConfluenceDocument
-from .domain import ConfluenceDocumentOptions, ConfluencePageID
-from .extra import override
 from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
+from .options import ConfluencePageID, DocumentOptions
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 
 LOGGER = logging.getLogger(__name__)
@@ -26,7 +26,7 @@ class LocalProcessor(Processor):
 
     def __init__(
         self,
-        options: ConfluenceDocumentOptions,
+        options: DocumentOptions,
         site: ConfluenceSiteMetadata,
         *,
         out_dir: Path | None,
@@ -45,14 +45,14 @@ class LocalProcessor(Processor):
         self.out_dir = out_dir or root_dir
 
     @override
-    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
+    def _synchronize_tree(self, tree: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index.
 
         Does not change Markdown files.
         """
 
-        for node in root.all():
+        for node in tree.all():
             if node.page_id is not None:
                 page_id = node.page_id
             else:
@@ -92,7 +92,7 @@ class LocalProcessorFactory(ProcessorFactory):
 
     def __init__(
         self,
-        options: ConfluenceDocumentOptions,
+        options: DocumentOptions,
         site: ConfluenceSiteMetadata,
         out_dir: Path | None = None,
     ) -> None:
@@ -110,7 +110,7 @@ class LocalConverter(Converter):
 
     def __init__(
         self,
-        options: ConfluenceDocumentOptions,
+        options: DocumentOptions,
         site: ConfluenceSiteMetadata,
         out_dir: Path | None = None,
     ) -> None:

md2conf/markdown.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/matcher.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/mermaid/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 MermaidConfigProperties:
+    """
+    Configuration options for rendering Mermaid diagrams.
+
+    :param scale: Scaling factor for the rendered diagram.
+    """
+
+    scale: float | None = None

md2conf/mermaid/extension.py

@@ -0,0 +1,109 @@
+"""
+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 .config import MermaidConfigProperties
+from .render import render_diagram
+from .scanner import MermaidScanner
+
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+
+LOGGER = logging.getLogger(__name__)
+
+
+class MermaidExtension(MarketplaceExtension):
+    @override
+    def matches_image(self, absolute_path: Path) -> bool:
+        return absolute_path.name.endswith((".mmd", ".mermaid"))
+
+    @override
+    def matches_fenced(self, language: str, content: str) -> bool:
+        return language == "mermaid"
+
+    def _extract_mermaid_config(self, content: str) -> MermaidConfigProperties | None:
+        """Extract scale from Mermaid YAML front matter configuration."""
+
+        try:
+            properties = MermaidScanner().read(content)
+            return properties.config
+        except BaseValidationError as ex:
+            LOGGER.warning("Failed to extract Mermaid 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)
+        if self.options.render:
+            with open(absolute_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            config = self._extract_mermaid_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:
+            self.attachments.add_image(ImageData(absolute_path, attrs.alt))
+            mermaid_filename = attachment_name(relative_path)
+            return self._create_mermaid_embed(mermaid_filename)
+
+    @override
+    def transform_fenced(self, content: str) -> ElementType:
+        if self.options.render:
+            config = self._extract_mermaid_config(content)
+            image_data = render_diagram(content, self.generator.options.output_format, config=config)
+            return self.generator.transform_attached_data(image_data, ImageAttributes.EMPTY_BLOCK)
+        else:
+            mermaid_data = content.encode("utf-8")
+            mermaid_hash = hashlib.md5(mermaid_data).hexdigest()
+            mermaid_filename = attachment_name(f"embedded_{mermaid_hash}.mmd")
+            self.attachments.add_embed(mermaid_filename, EmbeddedFileData(mermaid_data))
+            return self._create_mermaid_embed(mermaid_filename)
+
+    def _create_mermaid_embed(self, filename: str) -> ElementType:
+        "A Mermaid diagram, linking to an attachment that captures the Mermaid source."
+
+        local_id = str(uuid.uuid4())
+        macro_id = str(uuid.uuid4())
+        return AC_ELEM(
+            "structured-macro",
+            {
+                AC_ATTR("name"): "mermaid-cloud",
+                AC_ATTR("schema-version"): "1",
+                "data-layout": "default",
+                AC_ATTR("local-id"): local_id,
+                AC_ATTR("macro-id"): macro_id,
+            },
+            AC_ELEM(
+                "parameter",
+                {AC_ATTR("name"): "filename"},
+                filename,
+            ),
+            AC_ELEM(
+                "parameter",
+                {AC_ATTR("name"): "toolbar"},
+                "bottom",
+            ),
+            AC_ELEM(
+                "parameter",
+                {AC_ATTR("name"): "zoom"},
+                "fit",
+            ),
+            AC_ELEM("parameter", {AC_ATTR("name"): "revision"}, "1"),
+        )

md2conf/{mermaid.py → mermaid/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
 """
@@ -10,25 +10,16 @@ import logging
 import os
 import os.path
 import shutil
-import subprocess
-from dataclasses import dataclass
 from typing import Literal
 
-LOGGER = logging.getLogger(__name__)
-
-
-@dataclass
-class MermaidConfigProperties:
-    """
-    Configuration options for rendering Mermaid diagrams.
+from md2conf.external import execute_subprocess
 
-    :param scale: Scaling factor for the rendered diagram.
-    """
+from .config import MermaidConfigProperties
 
-    scale: float | None = None
+LOGGER = logging.getLogger(__name__)
 
 
-def is_docker() -> bool:
+def _is_docker() -> bool:
     "True if the application is running in a Docker container."
 
     return os.environ.get("CHROME_BIN") == "/usr/bin/chromium-browser" and os.environ.get("PUPPETEER_SKIP_DOWNLOAD") == "true"
@@ -37,7 +28,7 @@ def is_docker() -> bool:
 def get_mmdc() -> str:
     "Path to the Mermaid diagram converter."
 
-    if is_docker():
+    if _is_docker():
         full_path = "/home/md2conf/node_modules/.bin/mmdc"
         if os.path.exists(full_path):
             return full_path
@@ -75,27 +66,8 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png", co
         "--scale",
         str(config.scale or 2),
     ]
-    root = os.path.dirname(__file__)
-    if is_docker():
+    if _is_docker():
+        root = os.path.dirname(os.path.dirname(__file__))
         cmd.extend(["-p", os.path.join(root, "puppeteer-config.json")])
-    LOGGER.debug("Executing: %s", " ".join(cmd))
-
-    proc = subprocess.Popen(
-        cmd,
-        stdout=subprocess.PIPE,
-        stdin=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        text=False,
-    )
-    stdout, stderr = proc.communicate(input=source.encode("utf-8"))
-    if proc.returncode:
-        messages = [f"failed to convert Mermaid 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 RuntimeError("\n".join(messages))
-
-    return stdout
+
+    return execute_subprocess(cmd, source.encode("utf-8"), application="Mermaid")

md2conf/mermaid/scanner.py

@@ -0,0 +1,55 @@
+"""
+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 MermaidConfigProperties
+
+
+@dataclass
+class MermaidProperties:
+    """
+    An object that holds the front-matter properties structure for Mermaid diagrams.
+
+    :param title: The title of the diagram.
+    :param config: Configuration options for rendering.
+    """
+
+    title: str | None = None
+    config: MermaidConfigProperties | None = None
+
+
+class MermaidScanner:
+    """
+    Extracts properties from the JSON/YAML front-matter of a Mermaid diagram.
+    """
+
+    def read(self, content: str) -> MermaidProperties:
+        """
+        Extracts rendering preferences from a Mermaid front-matter content.
+
+        ```
+        ---
+        title: Tiny flow diagram
+        config:
+            scale: 1
+        ---
+        flowchart LR
+            A[Component A] --> B[Component B]
+            B --> C[Component C]
+        ```
+        """
+
+        properties, _ = extract_frontmatter_object(MermaidProperties, content)
+        if properties is not None:
+            config = properties.config or MermaidConfigProperties()
+            return MermaidProperties(title=properties.title, config=config)
+
+        return MermaidProperties()

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
 """