markdown-to-confluence 0.4.4__py3-none-any.whl → 0.4.6__py3-none-any.whl

md2conf/csf.py

@@ -149,3 +149,69 @@ def elements_to_string(root: ET._Element) -> str:
         return m.group(1)
     else:
         raise ValueError("expected: Confluence content")
+
+
+def is_block_like(elem: ET._Element) -> bool:
+    return elem.tag in ["div", "li", "ol", "p", "pre", "td", "th", "ul"]
+
+
+def normalize_inline(elem: ET._Element) -> None:
+    """
+    Ensures that inline elements are direct children of an eligible block element.
+
+    The following transformations are applied:
+
+    * consecutive inline elements and text nodes that are the direct children of the parent element are wrapped into a `<p>`,
+    * block elements are left intact,
+    * leading and trailing whitespace in each block element is removed.
+
+    The above steps transform an element tree such as
+    ```
+    <li>  to <em>be</em>, <ol/> not to <em>be</em>  </li>
+    ```
+
+    into another element tree such as
+    ```
+    <li><p>to <em>be</em>,</p><ol/><p>not to <em>be</em></p></li>
+    ```
+    """
+
+    if not is_block_like(elem):
+        raise ValueError(f"expected: block element; got: {elem.tag!s}")
+
+    contents: list[ET._Element] = []
+
+    paragraph = HTML.p()
+    contents.append(paragraph)
+    if elem.text:
+        paragraph.text = elem.text
+        elem.text = None
+
+    for child in elem:
+        if is_block_like(child):
+            contents.append(child)
+            paragraph = HTML.p()
+            contents.append(paragraph)
+            if child.tail:
+                paragraph.text = child.tail
+                child.tail = None
+        else:
+            paragraph.append(child)
+
+    for item in contents:
+        # remove lead whitespace in the block element
+        if item.text:
+            item.text = item.text.lstrip()
+        if len(item) > 0:
+            # remove tail whitespace in the last child of the block element
+            last = item[-1]
+            if last.tail:
+                last.tail = last.tail.rstrip()
+        else:
+            # remove tail whitespace directly in the block element content
+            if item.text:
+                item.text = item.text.rstrip()
+
+        # ignore empty elements
+        if item.tag != "p" or len(item) > 0 or item.text:
+            elem.append(item)

md2conf/domain.py

@@ -30,6 +30,7 @@ class ConfluenceDocumentOptions:
     :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_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.
     """
@@ -42,5 +43,6 @@ class ConfluenceDocumentOptions:
     prefer_raster: bool = True
     render_drawio: bool = False
     render_mermaid: bool = False
+    render_latex: bool = False
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False

md2conf/drawio.py

@@ -9,9 +9,9 @@ Copyright 2022-2025, Levente Hunyadi
 import base64
 import logging
 import os
-import os.path
 import shutil
 import subprocess
+import tempfile
 import typing
 import zlib
 from pathlib import Path
@@ -153,7 +153,8 @@ def extract_xml_from_png(png_data: bytes) -> ET._Element:
         offset += 8
 
         if offset + length + 4 > len(png_data):
-            raise DrawioError(f"corrupted PNG: incomplete data for chunk {chunk_type.decode('ascii')}")
+            chunk_name = chunk_type.decode("ascii", errors="replace")
+            raise DrawioError(f"corrupted PNG: incomplete data for chunk {chunk_name}")
 
         # read chunk data
         chunk_data = png_data[offset : offset + length]
@@ -169,7 +170,7 @@ def extract_xml_from_png(png_data: bytes) -> ET._Element:
         # format: keyword\0text
         null_pos = chunk_data.find(b"\x00")
         if null_pos < 0:
-            raise DrawioError("corrupted PNG: tEXt chunk missing keyword")
+            raise DrawioError("corrupted PNG: `tEXt` chunk missing keyword or data")
 
         keyword = chunk_data[:null_pos].decode("latin1")
         if keyword != "mxfile":
@@ -236,17 +237,21 @@ def render_diagram(source: Path, output_format: typing.Literal["png", "svg"] = "
     if executable is None:
         raise DrawioError("draw.io executable not found")
 
-    target = f"tmp_drawio.{output_format}"
+    # create a temporary file and get its file descriptor and path
+    fd, target = tempfile.mkstemp(prefix="drawio_", suffix=f".{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:
+        # close the descriptor, just use the filename
+        os.close(fd)
+
+        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))
         proc = subprocess.Popen(
             cmd,
             stdout=subprocess.PIPE,
@@ -267,5 +272,4 @@ def render_diagram(source: Path, output_format: typing.Literal["png", "svg"] = "
             return f.read()
 
     finally:
-        if os.path.exists(target):
-            os.remove(target)
+        os.remove(target)

md2conf/emoticon.py

@@ -0,0 +1,22 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+_EMOJI_TO_EMOTICON = {
+    "grinning": "laugh",
+    "heart": "heart",
+    "slight_frown": "sad",
+    "slight_smile": "smile",
+    "stuck_out_tongue": "cheeky",
+    "thumbsdown": "thumbs-down",
+    "thumbsup": "thumbs-up",
+    "wink": "wink",
+}
+
+
+def emoji_to_emoticon(shortname: str) -> str:
+    return _EMOJI_TO_EMOTICON.get(shortname) or "blue-star"

md2conf/latex.py

@@ -0,0 +1,245 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, 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, Optional, Union, overload
+
+
+def render_latex(expression: str, *, format: Literal["png", "svg"] = "png", dpi: int = 100, font_size: int = 12) -> bytes:
+    """
+    Generates a PNG or SVG image of a LaTeX math expression using `matplotlib` for rendering.
+
+    :param expression: A LaTeX math expression, e.g., r'\frac{a}{b}'.
+    :param format: Output image format.
+    :param dpi: Output image resolution (if applicable).
+    :param font_size: Font size of the LaTeX text (if applicable).
+    """
+
+    with BytesIO() as f:
+        _render_latex(expression, f, format=format, dpi=dpi, font_size=font_size)
+        return f.getvalue()
+
+
+if importlib.util.find_spec("matplotlib") is None:
+    LATEX_ENABLED = False
+
+    def _render_latex(expression: str, f: BinaryIO, *, format: Literal["png", "svg"], dpi: int, font_size: int) -> None:
+        raise RuntimeError("matplotlib not installed; run: `pip install matplotlib`")
+
+else:
+    import matplotlib
+    import matplotlib.pyplot as plt
+
+    matplotlib.rcParams["mathtext.fontset"] = "cm"  # change font to "Computer Modern"
+
+    LATEX_ENABLED = True
+
+    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)
+
+        # transparent background
+        fig.patch.set_alpha(0)
+
+        # add LaTeX text
+        fig.text(x=0, y=0, s=f"${expression}$", fontsize=font_size)
+
+        # save the image
+        fig.savefig(
+            f,
+            transparent=True,
+            format=format,
+            bbox_inches="tight",
+            pad_inches=0.0,
+            metadata={"Title": expression} if format == "png" else None,
+        )
+
+        # 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: Union[str, Path]) -> tuple[int, int]: ...
+
+
+def get_png_dimensions(*, data: Optional[bytes] = None, path: Union[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: Union[str, Path]) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes, target_path: Union[str, Path]) -> None: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: Union[str, Path], target_path: Union[str, Path]) -> None: ...
+
+
+def remove_png_chunks(
+    names: Iterable[str], *, source_data: Optional[bytes] = None, source_path: Union[str, Path, None] = None, target_path: Union[str, Path, None] = None
+) -> Optional[bytes]:
+    """
+    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) -> Optional[_Chunk]:
+    "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)
+    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

@@ -83,9 +83,9 @@ class LocalProcessor(Processor):
         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_files.items():
+        for name, file_data in document.embedded_files.items():
             with open(csf_dir / name, "wb") as f:
-                f.write(data)
+                f.write(file_data.data)
 
 
 class LocalProcessorFactory(ProcessorFactory):

md2conf/markdown.py

@@ -76,9 +76,11 @@ _CONVERTER = markdown.Markdown(
         "markdown.extensions.tables",
         "md_in_html",
         "pymdownx.arithmatex",
+        "pymdownx.caret",
         "pymdownx.emoji",
         "pymdownx.highlight",  # required by `pymdownx.superfences`
         "pymdownx.magiclink",
+        "pymdownx.mark",
         "pymdownx.superfences",
         "pymdownx.tilde",
         "sane_lists",
@@ -86,7 +88,7 @@ _CONVERTER = markdown.Markdown(
     extension_configs={
         "footnotes": {"BACKLINK_TITLE": ""},
         "pymdownx.arithmatex": {"generic": True, "preview": False, "tex_inline_wrap": ["", ""], "tex_block_wrap": ["", ""]},
-        "pymdownx.emoji": {"emoji_generator": _emoji_generator, "strict": True},
+        "pymdownx.emoji": {"emoji_generator": _emoji_generator},
         "pymdownx.highlight": {
             "use_pygments": False,
         },

md2conf/mermaid.py

@@ -11,11 +11,23 @@ import os
 import os.path
 import shutil
 import subprocess
-from typing import Literal
+from dataclasses import dataclass
+from typing import Literal, Optional
 
 LOGGER = logging.getLogger(__name__)
 
 
+@dataclass
+class MermaidConfigProperties:
+    """
+    Configuration options for rendering Mermaid diagrams.
+
+    :param scale: Scaling factor for the rendered diagram.
+    """
+
+    scale: Optional[float] = None
+
+
 def is_docker() -> bool:
     "True if the application is running in a Docker container."
 
@@ -44,49 +56,46 @@ def has_mmdc() -> bool:
     return shutil.which(executable) is not None
 
 
-def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") -> bytes:
+def render_diagram(source: str, output_format: Literal["png", "svg"] = "png", config: Optional[MermaidConfigProperties] = None) -> bytes:
     "Generates a PNG or SVG image from a Mermaid diagram source."
 
-    filename = f"tmp_mermaid.{output_format}"
+    if config is None:
+        config = MermaidConfigProperties()
 
     cmd = [
         get_mmdc(),
         "--input",
         "-",
         "--output",
-        filename,
+        "-",
         "--outputFormat",
         output_format,
         "--backgroundColor",
         "transparent",
         "--scale",
-        "2",
+        str(config.scale or 2),
     ]
     root = os.path.dirname(__file__)
     if is_docker():
         cmd.extend(["-p", os.path.join(root, "puppeteer-config.json")])
     LOGGER.debug("Executing: %s", " ".join(cmd))
-    try:
-        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))
-        with open(filename, "rb") as image:
-            return image.read()
-
-    finally:
-        if os.path.exists(filename):
-            os.remove(filename)
+
+    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

md2conf/processor.py

@@ -16,9 +16,9 @@ from typing import Iterable, Optional
 from .collection import ConfluencePageCollection
 from .converter import ConfluenceDocument
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
+from .environment import ArgumentError
 from .matcher import DirectoryEntry, FileEntry, Matcher, MatcherOptions
 from .metadata import ConfluenceSiteMetadata
-from .properties import ArgumentError
 from .scanner import Scanner
 
 LOGGER = logging.getLogger(__name__)

md2conf/{application.py → publisher.py}

@@ -12,13 +12,13 @@ from typing import Optional
 
 from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
 from .converter import ConfluenceDocument, attachment_name, get_volatile_attributes, get_volatile_elements
-from .csf import elements_from_string
+from .csf import AC_ATTR, elements_from_string
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
+from .environment import PageError
 from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
-from .properties import PageError
-from .xml import is_xml_equal
+from .xml import is_xml_equal, unwrap_substitute
 
 LOGGER = logging.getLogger(__name__)
 
@@ -73,20 +73,23 @@ class SynchronizingProcessor(Processor):
             # verify if page exists
             page = self.api.get_page_properties(node.page_id)
             update = False
-        elif node.title is not None:
-            # look up page by title
-            page = self.api.get_or_create_page(node.title, parent_id.page_id)
+        else:
+            if node.title is not None:
+                # use title extracted from source metadata
+                title = node.title
+            else:
+                # assign an auto-generated title
+                digest = self._generate_hash(node.absolute_path)
+                title = f"{node.absolute_path.stem} [{digest}]"
+
+            # look up page by (possibly auto-generated) title
+            page = self.api.get_or_create_page(title, parent_id.page_id)
 
             if page.status is ConfluenceStatus.ARCHIVED:
+                # user has archived a page with this (auto-generated) title
                 raise PageError(f"unable to update archived page with ID {page.id}")
 
             update = True
-        else:
-            # always create a new page
-            digest = self._generate_hash(node.absolute_path)
-            title = f"{node.absolute_path.stem} [{digest}]"
-            page = self.api.create_page(parent_id.page_id, title, "")
-            update = True
 
         space_key = self.api.space_id_to_key(page.spaceId)
         if update:
@@ -116,18 +119,20 @@ class SynchronizingProcessor(Processor):
         """
 
         base_path = path.parent
-        for image_path in document.images:
+        for image_data in document.images:
             self.api.upload_attachment(
                 page_id.page_id,
-                attachment_name(path_relative_to(image_path, base_path)),
-                attachment_path=image_path,
+                attachment_name(path_relative_to(image_data.path, base_path)),
+                attachment_path=image_data.path,
+                comment=image_data.description,
             )
 
-        for name, data in document.embedded_files.items():
+        for name, file_data in document.embedded_files.items():
             self.api.upload_attachment(
                 page_id.page_id,
                 name,
-                raw_data=data,
+                raw_data=file_data.data,
+                comment=file_data.description,
             )
 
         content = document.xhtml()
@@ -152,10 +157,14 @@ class SynchronizingProcessor(Processor):
         if not title:  # empty or `None`
             title = page.title
 
+        # discard comments
+        tree = elements_from_string(page.content)
+        unwrap_substitute(AC_ATTR("inline-comment-marker"), tree)
+
         # check if page has any changes
         if page.title != title or not is_xml_equal(
             document.root,
-            elements_from_string(page.content),
+            tree,
             skip_attributes=get_volatile_attributes(),
             skip_elements=get_volatile_elements(),
         ):
@@ -209,7 +218,7 @@ class SynchronizingProcessorFactory(ProcessorFactory):
         return SynchronizingProcessor(self.api, self.options, root_dir)
 
 
-class Application(Converter):
+class Publisher(Converter):
     """
     The entry point for Markdown to Confluence conversion.