markdown-to-confluence 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

md2conf/domain.py

@@ -0,0 +1,46 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+
+@dataclass
+class ConfluencePageID:
+    page_id: str
+
+
+@dataclass
+class ConfluenceDocumentOptions:
+    """
+    Options that control the generated page content.
+
+    :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 heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
+        conversion rules for the identifier.
+    :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 diagram_output_format: Target image format for diagrams.
+    :param webui_links: When true, convert relative URLs to Confluence Web UI links.
+    """
+
+    ignore_invalid_url: bool = False
+    heading_anchors: bool = False
+    generated_by: Optional[str] = "This page has been generated with a tool."
+    root_page_id: Optional[ConfluencePageID] = None
+    keep_hierarchy: bool = False
+    prefer_raster: bool = True
+    render_drawio: bool = False
+    render_mermaid: bool = False
+    diagram_output_format: Literal["png", "svg"] = "png"
+    webui_links: bool = False

md2conf/drawio.py

@@ -0,0 +1,271 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import base64
+import logging
+import os
+import os.path
+import shutil
+import subprocess
+import typing
+import zlib
+from pathlib import Path
+from struct import unpack
+from urllib.parse import unquote_to_bytes
+
+import lxml.etree as ET
+
+LOGGER = logging.getLogger(__name__)
+
+
+class DrawioError(ValueError):
+    """
+    Raised when the input does not adhere to the draw.io document format, or processing the input into a draw.io diagram fails.
+
+    Examples include:
+
+    * invalid or corrupt PNG file
+    * PNG chunk with embedded diagram data not found
+    * the structure of the outer XML does not match the expected format
+    * URL decoding error
+    * decompression error during INFLATE
+    """
+
+
+def inflate(data: bytes) -> bytes:
+    """
+    Decompresses (inflates) data compressed using the raw DEFLATE algorithm.
+
+    :param data: Compressed data using raw DEFLATE format.
+    :returns: Uncompressed data.
+    """
+
+    # -zlib.MAX_WBITS indicates raw DEFLATE stream (no zlib/gzip headers)
+    return zlib.decompress(data, -zlib.MAX_WBITS)
+
+
+def decompress_diagram(xml_data: typing.Union[bytes, str]) -> ET._Element:
+    """
+    Decompresses the text content of the `<diagram>` element in a draw.io XML document.
+
+    If the data is not compressed, the de-serialized XML element tree is returned.
+
+    Expected input (as `bytes` or `str`):
+    ```
+    <mxfile>
+        <diagram>... ENCODED_COMPRESSED_DATA ...</diagram>
+    </mxfile>
+    ```
+
+    Output (as XML element tree):
+    ```
+    <mxfile>
+        <diagram>
+            <mxGraphModel>
+                <root>
+                    ...
+                </root>
+            </mxGraphModel>
+        </diagram>
+    </mxfile>
+    ```
+
+    :param xml_data: The serialized XML document.
+    :returns: XML element tree with the text contained within the `<diagram>` element expanded into a sub-tree.
+    """
+
+    try:
+        root = ET.fromstring(xml_data)
+    except ET.ParseError as e:
+        raise DrawioError("invalid outer XML") from e
+
+    if root.tag != "mxfile":
+        raise DrawioError("root element is not `<mxfile>`")
+
+    diagram_elem = root.find("diagram")
+    if diagram_elem is None:
+        raise DrawioError("`<diagram>` element not found")
+
+    if len(diagram_elem) > 0:
+        # already decompressed
+        return root
+
+    if diagram_elem.text is None:
+        raise DrawioError("`<diagram>` element has no data")
+
+    # reverse base64-encoding of inner data
+    try:
+        base64_decoded = base64.b64decode(diagram_elem.text, validate=True)
+    except ValueError as e:
+        raise DrawioError("raw text data in `<diagram>` element is not properly Base64-encoded") from e
+
+    # decompress inner data
+    try:
+        embedded_data = inflate(base64_decoded)
+    except zlib.error as e:
+        raise DrawioError("`<diagram>` element text data cannot be decompressed using INFLATE") from e
+
+    # reverse URL-encoding of inner data
+    try:
+        url_decoded = unquote_to_bytes(embedded_data)
+    except ValueError as e:
+        raise DrawioError("decompressed data in `<diagram>` element is not properly URL-encoded") from e
+
+    # create sub-tree from decompressed data
+    try:
+        tree = ET.fromstring(url_decoded)
+    except ET.ParseError as e:
+        raise DrawioError("invalid inner XML extracted from `<diagram>` element") from e
+
+    # update document
+    diagram_elem.text = None
+    diagram_elem.append(tree)
+
+    return root
+
+
+def extract_xml_from_png(png_data: bytes) -> ET._Element:
+    """
+    Extracts an editable draw.io diagram from a PNG file.
+
+    :param png_data: PNG binary data, with an embedded draw.io diagram.
+    :returns: XML element tree of a draw.io diagram.
+    """
+
+    # PNG signature is always the first 8 bytes
+    png_signature = b"\x89PNG\r\n\x1a\n"
+    if not png_data.startswith(png_signature):
+        raise DrawioError("not a valid PNG file")
+
+    offset = len(png_signature)
+    while offset < len(png_data):
+        if offset + 8 > len(png_data):
+            raise DrawioError("corrupted PNG: incomplete chunk header")
+
+        # read chunk length (4 bytes) and type (4 bytes)
+        (length,) = unpack(">I", png_data[offset : offset + 4])
+        chunk_type = png_data[offset + 4 : offset + 8]
+        offset += 8
+
+        if offset + length + 4 > len(png_data):
+            raise DrawioError(f"corrupted PNG: incomplete data for chunk {chunk_type.decode('ascii')}")
+
+        # read chunk data
+        chunk_data = png_data[offset : offset + length]
+        offset += length
+
+        # skip CRC (4 bytes)
+        offset += 4
+
+        # extracts draw.io diagram data from a `tEXt` chunk with the keyword `mxfile` embedded in a PNG
+        if chunk_type != b"tEXt":
+            continue
+
+        # format: keyword\0text
+        null_pos = chunk_data.find(b"\x00")
+        if null_pos < 0:
+            raise DrawioError("corrupted PNG: tEXt chunk missing keyword")
+
+        keyword = chunk_data[:null_pos].decode("latin1")
+        if keyword != "mxfile":
+            continue
+
+        textual_data = chunk_data[null_pos + 1 :]
+
+        try:
+            url_decoded = unquote_to_bytes(textual_data)
+        except ValueError as e:
+            raise DrawioError("data in `tEXt` chunk is not properly URL-encoded") from e
+
+        # decompress data embedded in the outer XML wrapper
+        return decompress_diagram(url_decoded)
+
+    # matching `tEXt` chunk not found
+    raise DrawioError("not a PNG file made with draw.io")
+
+
+def extract_xml_from_svg(svg_data: bytes) -> ET._Element:
+    """
+    Extracts an editable draw.io diagram from an SVG file.
+
+    :param svg_data: SVG XML data, with an embedded draw.io diagram.
+    :returns: XML element tree of a draw.io diagram.
+    """
+
+    try:
+        root = ET.fromstring(svg_data)
+    except ET.ParseError as e:
+        raise DrawioError("invalid SVG XML") from e
+
+    content = root.attrib.get("content")
+    if content is None:
+        raise DrawioError("SVG root element has no attribute `content`")
+
+    return decompress_diagram(content)
+
+
+def extract_diagram(path: Path) -> bytes:
+    """
+    Extracts an editable draw.io diagram from a PNG file.
+
+    :param path: Path to a PNG or SVG file with an embedded draw.io diagram.
+    :returns: XML data of a draw.io diagram as bytes.
+    """
+
+    if path.name.endswith(".drawio.png"):
+        with open(path, "rb") as png_file:
+            root = extract_xml_from_png(png_file.read())
+    elif path.name.endswith(".drawio.svg"):
+        with open(path, "rb") as svg_file:
+            root = extract_xml_from_svg(svg_file.read())
+    else:
+        raise DrawioError(f"unrecognized file type for {path.name}")
+
+    return ET.tostring(root, encoding="utf8", method="xml")
+
+
+def render_diagram(source: Path, output_format: typing.Literal["png", "svg"] = "png") -> bytes:
+    "Generates a PNG or SVG image from a draw.io diagram source."
+
+    executable = shutil.which("draw.io")
+    if executable is None:
+        raise DrawioError("draw.io executable not found")
+
+    target = f"tmp_drawio.{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:
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=False,
+        )
+        stdout, stderr = proc.communicate()
+        if proc.returncode:
+            messages = [f"failed to convert draw.io 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 DrawioError("\n".join(messages))
+        with open(target, "rb") as f:
+            return f.read()
+
+    finally:
+        if os.path.exists(target):
+            os.remove(target)

md2conf/local.py

@@ -11,7 +11,8 @@ import os
 from pathlib import Path
 from typing import Optional
 
-from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
+from .converter import ConfluenceDocument
+from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .extra import override
 from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
@@ -66,6 +67,7 @@ class LocalProcessor(Processor):
                     page_id=page_id,
                     space_key=node.space_key or self.site.space_key or "HOME",
                     title=node.title or "",
+                    synchronized=node.synchronized,
                 ),
             )
 
@@ -76,10 +78,14 @@ class LocalProcessor(Processor):
         """
 
         content = document.xhtml()
-        out_path = self.out_dir / path.relative_to(self.root_dir).with_suffix(".csf")
-        os.makedirs(out_path.parent, exist_ok=True)
-        with open(out_path, "w", encoding="utf-8") as f:
+        csf_path = self.out_dir / path.relative_to(self.root_dir).with_suffix(".csf")
+        csf_dir = csf_path.parent
+        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_images.items():
+            with open(csf_dir / name, "wb") as f:
+                f.write(data)
 
 
 class LocalProcessorFactory(ProcessorFactory):

md2conf/markdown.py

@@ -0,0 +1,108 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import xml.etree.ElementTree
+from typing import Any, Optional
+
+import markdown
+
+
+def _emoji_generator(
+    index: str,
+    shortname: str,
+    alias: Optional[str],
+    uc: Optional[str],
+    alt: str,
+    title: Optional[str],
+    category: Optional[str],
+    options: dict[str, Any],
+    md: markdown.Markdown,
+) -> xml.etree.ElementTree.Element:
+    """
+    Custom generator for `pymdownx.emoji`.
+    """
+
+    name = (alias or shortname).strip(":")
+    span = xml.etree.ElementTree.Element("span", {"data-emoji-shortname": name})
+    if uc is not None:
+        span.attrib["data-emoji-unicode"] = uc
+
+        # convert series of Unicode code point hexadecimal values into characters
+        span.text = "".join(chr(int(item, base=16)) for item in uc.split("-"))
+    else:
+        span.text = alt
+    return span
+
+
+def _math_formatter(
+    source: str,
+    language: str,
+    css_class: str,
+    options: dict[str, Any],
+    md: markdown.Markdown,
+    classes: Optional[list[str]] = None,
+    id_value: str = "",
+    attrs: Optional[dict[str, str]] = None,
+    **kwargs: Any,
+) -> str:
+    """
+    Custom formatter for language `math` in `pymdownx.superfences`.
+    """
+
+    if classes is None:
+        classes = [css_class]
+    else:
+        classes.insert(0, css_class)
+
+    html_id = f' id="{id_value}"' if id_value else ""
+    html_class = ' class="{}"'.format(" ".join(classes))
+    html_attrs = " " + " ".join(f'{k}="{v}"' for k, v in attrs.items()) if attrs else ""
+
+    return f"<div{html_id}{html_class}{html_attrs}>{source}</div>"
+
+
+_CONVERTER = markdown.Markdown(
+    extensions=[
+        "admonition",
+        "footnotes",
+        "markdown.extensions.tables",
+        "md_in_html",
+        "pymdownx.arithmatex",
+        "pymdownx.emoji",
+        "pymdownx.highlight",  # required by `pymdownx.superfences`
+        "pymdownx.magiclink",
+        "pymdownx.superfences",
+        "pymdownx.tilde",
+        "sane_lists",
+    ],
+    extension_configs={
+        "footnotes": {"BACKLINK_TITLE": ""},
+        "pymdownx.arithmatex": {"generic": True, "preview": False, "tex_inline_wrap": ["", ""], "tex_block_wrap": ["", ""]},
+        "pymdownx.emoji": {
+            "emoji_generator": _emoji_generator,
+        },
+        "pymdownx.highlight": {
+            "use_pygments": False,
+        },
+        "pymdownx.superfences": {"custom_fences": [{"name": "math", "class": "arithmatex", "format": _math_formatter}]},
+    },
+)
+
+
+def markdown_to_html(content: str) -> str:
+    """
+    Converts a Markdown document into XHTML with Python-Markdown.
+
+    :param content: Markdown input as a string.
+    :returns: XHTML output as a string.
+    :see: https://python-markdown.github.io/
+    """
+
+    _CONVERTER.reset()
+    html = _CONVERTER.convert(content)
+    return html

md2conf/matcher.py

@@ -10,14 +10,57 @@ import os.path
 from dataclasses import dataclass
 from fnmatch import fnmatch
 from pathlib import Path
-from typing import Iterable, Optional, Union, overload
+from typing import Iterable, Optional, Union, final, overload
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, eq=True)
+class _BaseEntry:
+    """
+    Represents a file or directory entry.
+
+    Entries are primarily sorted alphabetically case-insensitive.
+    When two items are equal case-insensitive, conflicting items are put in case-sensitive order.
+
+    :param name: Name of the file-system entry.
+    """
+
+    name: str
+
+    @property
+    def lower_name(self) -> str:
+        return self.name.lower()
+
+    def __lt__(self, other: "_BaseEntry") -> bool:
+        return (self.lower_name, self.name) < (other.lower_name, other.name)
+
+    def __le__(self, other: "_BaseEntry") -> bool:
+        return (self.lower_name, self.name) <= (other.lower_name, other.name)
+
+    def __ge__(self, other: "_BaseEntry") -> bool:
+        return (self.lower_name, self.name) >= (other.lower_name, other.name)
+
+    def __gt__(self, other: "_BaseEntry") -> bool:
+        return (self.lower_name, self.name) > (other.lower_name, other.name)
+
+
+@final
+class FileEntry(_BaseEntry):
+    pass
+
+
+@final
+class DirectoryEntry(_BaseEntry):
+    pass
+
+
+@dataclass(frozen=True, eq=True)
 class Entry:
     """
     Represents a file or directory entry.
 
+    When sorted, directories come before files and items are primarily arranged in alphabetical order case-insensitive.
+    When two items are equal case-insensitive, conflicting items are put in case-sensitive order.
+
     :param name: Name of the file-system entry to match against the rule-set.
     :param is_dir: True if the entry is a directory.
     """
@@ -25,6 +68,22 @@ class Entry:
     name: str
     is_dir: bool
 
+    @property
+    def lower_name(self) -> str:
+        return self.name.lower()
+
+    def __lt__(self, other: "Entry") -> bool:
+        return (not self.is_dir, self.lower_name, self.name) < (not other.is_dir, other.lower_name, other.name)
+
+    def __le__(self, other: "Entry") -> bool:
+        return (not self.is_dir, self.lower_name, self.name) <= (not other.is_dir, other.lower_name, other.name)
+
+    def __ge__(self, other: "Entry") -> bool:
+        return (not self.is_dir, self.lower_name, self.name) >= (not other.is_dir, other.lower_name, other.name)
+
+    def __gt__(self, other: "Entry") -> bool:
+        return (not self.is_dir, self.lower_name, self.name) > (not other.is_dir, other.lower_name, other.name)
+
 
 @dataclass
 class MatcherOptions:
@@ -146,9 +205,9 @@ class Matcher:
         :returns: A filtered list of names that didn't match any of the exclusion rules.
         """
 
-        return [entry for entry in entries if self.is_included(entry)]
+        return sorted(entry for entry in entries if self.is_included(entry))
 
-    def scandir(self, path: Path) -> list[Entry]:
+    def listing(self, path: Path) -> list[Entry]:
         """
         Returns only those entries in a directory whose name doesn't match any of the exclusion rules.
 

md2conf/metadata.py

@@ -33,8 +33,10 @@ class ConfluencePageMetadata:
     :param page_id: Confluence page ID.
     :param space_key: Confluence space key.
     :param title: Document title.
+    :param synchronized: True if the document content is parsed and synchronized with Confluence.
     """
 
     page_id: str
     space_key: str
     title: str
+    synchronized: bool