markdown-to-confluence 0.4.5__py3-none-any.whl → 0.4.7__py3-none-any.whl

md2conf/csf.py

@@ -14,6 +14,8 @@ from typing import Callable, TypeVar
 import lxml.etree as ET
 from lxml.builder import ElementMaker
 
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+
 # XML namespaces typically associated with Confluence Storage Format documents
 _namespaces = {
     "ac": "http://atlassian.com/content",
@@ -54,7 +56,7 @@ def with_entities(func: Callable[[Path], R]) -> R:
         return func(dtd_path)
 
 
-def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
+def _elements_from_strings(dtd_path: Path, items: list[str]) -> ElementType:
     """
     Creates an XML document tree from XML fragment strings.
 
@@ -90,7 +92,7 @@ def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
         raise ParseError() from ex
 
 
-def elements_from_strings(items: list[str]) -> ET._Element:
+def elements_from_strings(items: list[str]) -> ElementType:
     """
     Creates a Confluence Storage Format XML document tree from XML fragment strings.
 
@@ -103,7 +105,7 @@ def elements_from_strings(items: list[str]) -> ET._Element:
     return with_entities(lambda dtd_path: _elements_from_strings(dtd_path, items))
 
 
-def elements_from_string(content: str) -> ET._Element:
+def elements_from_string(content: str) -> ElementType:
     """
     Creates a Confluence Storage Format XML document tree from an XML string.
 
@@ -135,7 +137,7 @@ def content_to_string(content: str) -> str:
     return with_entities(lambda dtd_path: _content_to_string(dtd_path, content))
 
 
-def elements_to_string(root: ET._Element) -> str:
+def elements_to_string(root: ElementType) -> str:
     """
     Converts a Confluence Storage Format element tree into an XML string to push to Confluence REST API.
 
@@ -151,11 +153,11 @@ def elements_to_string(root: ET._Element) -> str:
         raise ValueError("expected: Confluence content")
 
 
-def is_block_like(elem: ET._Element) -> bool:
-    return elem.tag in ["div", "li", "ol", "p", "pre", "ul"]
+def is_block_like(elem: ElementType) -> bool:
+    return elem.tag in ["div", "li", "ol", "p", "pre", "td", "th", "ul"]
 
 
-def normalize_inline(elem: ET._Element) -> None:
+def normalize_inline(elem: ElementType) -> None:
     """
     Ensures that inline elements are direct children of an eligible block element.
 
@@ -179,7 +181,7 @@ def normalize_inline(elem: ET._Element) -> None:
     if not is_block_like(elem):
         raise ValueError(f"expected: block element; got: {elem.tag!s}")
 
-    contents: list[ET._Element] = []
+    contents: list[ElementType] = []
 
     paragraph = HTML.p()
     contents.append(paragraph)

md2conf/domain.py

@@ -33,6 +33,8 @@ class ConfluenceDocumentOptions:
     :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 use_panel: Whether to transform admonitions and alerts into a Confluence custom panel.
     """
 
     ignore_invalid_url: bool = False
@@ -46,3 +48,5 @@ class ConfluenceDocumentOptions:
     render_latex: bool = False
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False
+    alignment: Literal["center", "left", "right"] = "center"
+    use_panel: bool = False

md2conf/drawio.py

@@ -20,6 +20,8 @@ from urllib.parse import unquote_to_bytes
 
 import lxml.etree as ET
 
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+
 LOGGER = logging.getLogger(__name__)
 
 
@@ -49,7 +51,7 @@ def inflate(data: bytes) -> bytes:
     return zlib.decompress(data, -zlib.MAX_WBITS)
 
 
-def decompress_diagram(xml_data: typing.Union[bytes, str]) -> ET._Element:
+def decompress_diagram(xml_data: typing.Union[bytes, str]) -> ElementType:
     """
     Decompresses the text content of the `<diagram>` element in a draw.io XML document.
 
@@ -129,7 +131,7 @@ def decompress_diagram(xml_data: typing.Union[bytes, str]) -> ET._Element:
     return root
 
 
-def extract_xml_from_png(png_data: bytes) -> ET._Element:
+def extract_xml_from_png(png_data: bytes) -> ElementType:
     """
     Extracts an editable draw.io diagram from a PNG file.
 
@@ -190,7 +192,7 @@ def extract_xml_from_png(png_data: bytes) -> ET._Element:
     raise DrawioError("not a PNG file made with draw.io")
 
 
-def extract_xml_from_svg(svg_data: bytes) -> ET._Element:
+def extract_xml_from_svg(svg_data: bytes) -> ElementType:
     """
     Extracts an editable draw.io diagram from an SVG file.
 

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

@@ -40,7 +40,7 @@ else:
 
     matplotlib.rcParams["mathtext.fontset"] = "cm"  # change font to "Computer Modern"
 
-    LATEX_ENABLED = True
+    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
@@ -219,7 +219,7 @@ def _get_png_dimensions(source_file: BinaryIO) -> tuple[int, int]:
     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)
+    (width, height, bit_depth, color_type, compression, filter, interlace) = unpack(">IIBBBBB", ihdr.data)  # pyright: ignore[reportUnusedVariable]
     return width, height
 
 

md2conf/matcher.py

@@ -105,10 +105,8 @@ class MatcherOptions:
 def _entry_name_dir(entry: Union[Entry, os.DirEntry[str]]) -> tuple[str, bool]:
     if isinstance(entry, Entry):
         return entry.name, entry.is_dir
-    elif isinstance(entry, os.DirEntry):
-        return entry.name, entry.is_dir()
     else:
-        raise NotImplementedError("type match not exhaustive")
+        return entry.name, entry.is_dir()
 
 
 class Matcher:

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,9 +56,12 @@ 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."
 
+    if config is None:
+        config = MermaidConfigProperties()
+
     cmd = [
         get_mmdc(),
         "--input",
@@ -58,7 +73,7 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") ->
         "--backgroundColor",
         "transparent",
         "--scale",
-        "2",
+        str(config.scale or 2),
     ]
     root = os.path.dirname(__file__)
     if is_docker():

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__)
@@ -140,7 +140,7 @@ class Processor:
         self._update_page(page_id, document, path)
 
     @abstractmethod
-    def _synchronize_tree(self, node: DocumentNode, page_id: Optional[ConfluencePageID]) -> None:
+    def _synchronize_tree(self, root: DocumentNode, root_id: Optional[ConfluencePageID]) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 

md2conf/{application.py → publisher.py}

@@ -14,10 +14,10 @@ from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession,
 from .converter import ConfluenceDocument, attachment_name, get_volatile_attributes, get_volatile_elements
 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, 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:
@@ -138,7 +141,7 @@ class SynchronizingProcessor(Processor):
         title = None
         if document.title is not None:
             meta = self.page_metadata.get(path)
-            if meta is not None and meta.space_key is not None and meta.title != document.title:
+            if meta is not None and meta.title != document.title:
                 conflicting_page_id = self.api.page_exists(document.title, space_id=self.api.space_key_to_id(meta.space_key))
                 if conflicting_page_id is None:
                     title = document.title
@@ -215,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.
 

md2conf/scanner.py

@@ -7,14 +7,17 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 import re
+import typing
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Optional, TypeVar
+from typing import Any, Literal, Optional, TypeVar
 
 import yaml
 from strong_typing.core import JsonType
 from strong_typing.serialization import DeserializerOptions, json_to_object
 
+from .mermaid import MermaidConfigProperties
+
 T = TypeVar("T")
 
 
@@ -43,7 +46,7 @@ def extract_frontmatter_block(text: str) -> tuple[Optional[str], str]:
     return extract_value(r"(?ms)\A---$(.+?)^---$", text)
 
 
-def extract_frontmatter_properties(text: str) -> tuple[Optional[dict[str, Any]], str]:
+def extract_frontmatter_properties(text: str) -> tuple[Optional[dict[str, JsonType]], str]:
     "Extracts the front-matter from a Markdown document as a dictionary."
 
     block, text = extract_frontmatter_block(text)
@@ -52,7 +55,7 @@ def extract_frontmatter_properties(text: str) -> tuple[Optional[dict[str, Any]],
     if block is not None:
         data = yaml.safe_load(block)
         if isinstance(data, dict):
-            properties = data
+            properties = typing.cast(dict[str, JsonType], data)
 
     return properties, text
 
@@ -71,6 +74,7 @@ class DocumentProperties:
     :param tags: A list of tags (content labels) extracted from front-matter.
     :param synchronized: True if the document content is parsed and synchronized with Confluence.
     :param properties: A dictionary of key-value pairs extracted from front-matter to apply as page properties.
+    :param alignment: Alignment for block-level images and formulas.
     """
 
     page_id: Optional[str]
@@ -82,6 +86,7 @@ class DocumentProperties:
     tags: Optional[list[str]]
     synchronized: Optional[bool]
     properties: Optional[dict[str, JsonType]]
+    alignment: Optional[Literal["center", "left", "right"]]
 
 
 @dataclass
@@ -96,6 +101,7 @@ class ScannedDocument:
     :param tags: A list of tags (content labels) extracted from front-matter.
     :param synchronized: True if the document content is parsed and synchronized with Confluence.
     :param properties: A dictionary of key-value pairs extracted from front-matter to apply as page properties.
+    :param alignment: Alignment for block-level images and formulas.
     :param text: Text that remains after front-matter and inline properties have been extracted.
     """
 
@@ -106,6 +112,7 @@ class ScannedDocument:
     tags: Optional[list[str]]
     synchronized: Optional[bool]
     properties: Optional[dict[str, JsonType]]
+    alignment: Optional[Literal["center", "left", "right"]]
     text: str
 
 
@@ -132,6 +139,7 @@ class Scanner:
         tags: Optional[list[str]] = None
         synchronized: Optional[bool] = None
         properties: Optional[dict[str, JsonType]] = None
+        alignment: Optional[Literal["center", "left", "right"]] = None
 
         # extract front-matter
         data, text = extract_frontmatter_properties(text)
@@ -144,6 +152,7 @@ class Scanner:
             tags = p.tags
             synchronized = p.synchronized
             properties = p.properties
+            alignment = p.alignment
 
         return ScannedDocument(
             page_id=page_id,
@@ -153,5 +162,50 @@ class Scanner:
             tags=tags,
             synchronized=synchronized,
             properties=properties,
+            alignment=alignment,
             text=text,
         )
+
+
+@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: Optional[str] = None
+    config: Optional[MermaidConfigProperties] = 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_properties(content)
+        if properties is not None:
+            front_matter = _json_to_object(MermaidProperties, properties)
+            config = front_matter.config or MermaidConfigProperties()
+
+            return MermaidProperties(title=front_matter.title, config=config)
+
+        return MermaidProperties()

md2conf/xml.py

@@ -10,8 +10,11 @@ from typing import Iterable, Optional
 
 import lxml.etree as ET
 
+ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
+AttribType = ET._Attrib  # pyright: ignore[reportPrivateUsage]
 
-def _attrs_equal_excluding(attrs1: ET._Attrib, attrs2: ET._Attrib, exclude: set[str]) -> bool:
+
+def _attrs_equal_excluding(attrs1: AttribType, attrs2: AttribType, exclude: set[str]) -> bool:
     """
     Compares two dictionary objects, excluding keys in the skip set.
 
@@ -47,7 +50,7 @@ class ElementComparator:
         self.skip_attributes = set(skip_attributes) if skip_attributes else set()
         self.skip_elements = set(skip_elements) if skip_elements else set()
 
-    def is_equal(self, e1: ET._Element, e2: ET._Element) -> bool:
+    def is_equal(self, e1: ElementType, e2: ElementType) -> bool:
         """
         Recursively check if two XML elements are equal.
         """
@@ -82,7 +85,7 @@ class ElementComparator:
 
 
 def is_xml_equal(
-    tree1: ET._Element, tree2: ET._Element, *, skip_attributes: Optional[Iterable[str]] = None, skip_elements: Optional[Iterable[str]] = None
+    tree1: ElementType, tree2: ElementType, *, skip_attributes: Optional[Iterable[str]] = None, skip_elements: Optional[Iterable[str]] = None
 ) -> bool:
     """
     Compare two XML documents for equivalence, ignoring leading/trailing whitespace differences and attribute definition order.
@@ -99,13 +102,13 @@ def is_xml_equal(
     return ElementComparator(skip_attributes=skip_attributes, skip_elements=skip_elements).is_equal(tree1, tree2)
 
 
-def element_to_text(node: ET._Element) -> str:
+def element_to_text(node: ElementType) -> str:
     "Returns all text contained in an element as a concatenated string."
 
     return "".join(node.itertext()).strip()
 
 
-def unwrap_substitute(name: str, root: ET._Element) -> None:
+def unwrap_substitute(name: str, root: ElementType) -> None:
     """
     Substitutes all occurrences of an element with its contents.
 

markdown_to_confluence-0.4.5.dist-info/RECORD

@@ -1,33 +0,0 @@
-markdown_to_confluence-0.4.5.dist-info/licenses/LICENSE,sha256=56L-Y0dyZwyVlINRJRz3PNw-ka-oLVaAq-7d8zo6qlc,1077
-md2conf/__init__.py,sha256=uvviya0xS1aCIW7IU3EfeI_QkC_d9T_PiVsLEMXo9S4,402
-md2conf/__main__.py,sha256=gQncJ-mkhRyQyhrZg-uJ1RnN8aGw-sr0c83ydunFNj0,11661
-md2conf/api.py,sha256=VjXD0da4de5YtPCbUCjK0k1oD6vl59IQLItEapj0pyM,37861
-md2conf/application.py,sha256=PZDPUpoKjKBPTHwgVO20pGzTwER3paZuQbI-2_TWBgE,8563
-md2conf/collection.py,sha256=EobgMRJgkYloWlY03NZJ52MRC_SGLpTVCHkltDbQyt0,837
-md2conf/converter.py,sha256=hWqbXYSFymMkvobh-f3uUO6JG28EWHU_7s0QYPI6NKM,61400
-md2conf/csf.py,sha256=WIzGrX-RXAkr4XsgLIUT11WM1qwhjgcXZHI_cALXpyM,6397
-md2conf/domain.py,sha256=NpeGl-I9_rgKYCKKZT1Ygg3nl5U0-jJHYYrzDVpMSGQ,1965
-md2conf/drawio.py,sha256=3RJFFzlp5a7SNVNCnwO_HCDfMy0DqYQeXfHWRPInOVE,8527
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/extra.py,sha256=VuMxuOnnC2Qwy6y52ukIxsaYhrZArRqMmRHRE4QZl8g,687
-md2conf/latex.py,sha256=yAClNclguPv-xWBMVWbqvYWLbyUHBVufc2aUzwyKHew,7586
-md2conf/local.py,sha256=mvp2kA_eo6JUQ_rlM7zDdEFgBPVxMr3VKP_X1nsLjHE,3747
-md2conf/markdown.py,sha256=czabU17tUfhSX1JQGiI_TrMrTmtoVThOwFu_To_Oi_w,3176
-md2conf/matcher.py,sha256=m5rZjYZSjhKfdeKS8JdPq7cG861Mc6rVZBkrIOZTHGE,6916
-md2conf/mermaid.py,sha256=7iziRC1Li3D85psR5NlnZ6BOePsOfFELgkNCAxahbZU,2240
-md2conf/metadata.py,sha256=LzZM-oPNnzCULmLhF516tPlV5zZBknccwMHt8Nan-xg,1007
-md2conf/processor.py,sha256=z2d2KMPEYWaxflOtH2UTwrjzpPU8TtLSEUvor85ez1Q,9732
-md2conf/properties.py,sha256=RC1jY_TKVbOv2bJxXn27Fj4fNWzyoNUQt6ltgUyVQAQ,3987
-md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-md2conf/scanner.py,sha256=Cyvjab8tBvKgubttQvNagS8nailuTvFBqUGoiX5MNp8,5351
-md2conf/text.py,sha256=fHOrUaPXAjE4iRhHqFq-CiI-knpo4wvyHCWp0crewqA,1736
-md2conf/toc.py,sha256=hpqqDbFgNJg5-ul8qWjOglI3Am0sbwR-TLwGN5G9Qo0,2447
-md2conf/uri.py,sha256=KbLBdRFtZTQTZd8b4j0LtE8Pb68Ly0WkemF4iW-EAB4,1158
-md2conf/xml.py,sha256=Ybf3Ctt6EurVvel0eb1KezF33_e_cDpMwlUqHi4kNLE,5411
-markdown_to_confluence-0.4.5.dist-info/METADATA,sha256=zhCjkqQkp71Z28iRzGH-vLMczWaELkd-2FU_kiNv61k,33724
-markdown_to_confluence-0.4.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-markdown_to_confluence-0.4.5.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.4.5.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.4.5.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.4.5.dist-info/RECORD,,