markdown-to-confluence 0.3.5__py3-none-any.whl → 0.4.0__py3-none-any.whl

md2conf/application.py

@@ -6,22 +6,21 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
-import hashlib
 import logging
 from pathlib import Path
 from typing import Optional
 
-from .api import ConfluencePage, ConfluenceSession
+from .api import ConfluenceLabel, ConfluenceSession
 from .converter import (
     ConfluenceDocument,
     ConfluenceDocumentOptions,
     ConfluencePageID,
     attachment_name,
 )
+from .extra import override
 from .metadata import ConfluencePageMetadata
-from .processor import Converter, Processor, ProcessorFactory
+from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 from .properties import PageError
-from .scanner import Scanner
 
 LOGGER = logging.getLogger(__name__)
 
@@ -47,69 +46,76 @@ class SynchronizingProcessor(Processor):
         super().__init__(options, api.site, root_dir)
         self.api = api
 
-    def _get_or_create_page(
-        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
-    ) -> ConfluencePageMetadata:
-        """
-        Creates a new Confluence page if no page is linked in the Markdown document.
+    @override
+    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.
+
+        Creates new Confluence pages as necessary, e.g. if no page is linked in the Markdown document, or no page is found with lookup by page title.
 
-        # parse file
-        document = Scanner().read(absolute_path)
+        Updates the original Markdown document to add tags to associate the document with its corresponding Confluence page.
+        """
 
-        overwrite = False
-        if document.page_id is None:
-            # create new Confluence page
-            if parent_id is None:
+        if root.page_id is None and root_id is None:
+            raise PageError(
+                f"expected: root page ID in options, or explicit page ID in {root.absolute_path}"
+            )
+        elif root.page_id is not None and root_id is not None:
+            if root.page_id != root_id.page_id:
                 raise PageError(
-                    f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
+                    f"mismatched inferred page ID of {root_id.page_id} and explicit page ID in {root.absolute_path}"
                 )
 
-            # use file name (without extension) and path hash if no title is supplied
-            if document.title is not None:
-                title = document.title
-            else:
-                overwrite = True
-                relative_path = absolute_path.relative_to(self.root_dir)
-                hash = hashlib.md5(relative_path.as_posix().encode("utf-8"))
-                digest = "".join(f"{c:x}" for c in hash.digest())
-                title = f"{absolute_path.stem} [{digest}]"
-
-            confluence_page = self._create_page(
-                absolute_path, document.text, title, parent_id
-            )
+            real_id = root_id
+        elif root_id is not None:
+            real_id = root_id
+        elif root.page_id is not None:
+            real_id = ConfluencePageID(root.page_id)
         else:
-            # look up existing Confluence page
-            confluence_page = self.api.get_page(document.page_id)
-
-        return ConfluencePageMetadata(
-            page_id=confluence_page.id,
-            space_key=self.api.space_id_to_key(confluence_page.space_id),
-            title=confluence_page.title,
-            overwrite=overwrite,
-        )
+            raise NotImplementedError("condition not exhaustive")
 
-    def _create_page(
-        self,
-        absolute_path: Path,
-        document: str,
-        title: str,
-        parent_id: ConfluencePageID,
-    ) -> ConfluencePage:
-        """
-        Creates a new Confluence page when Markdown file doesn't have an embedded page ID yet.
-        """
+        self._synchronize_subtree(root, real_id)
 
-        confluence_page = self.api.get_or_create_page(title, parent_id.page_id)
-        self._update_markdown(
-            absolute_path,
-            document,
-            confluence_page.id,
-            self.api.space_id_to_key(confluence_page.space_id),
+    def _synchronize_subtree(
+        self, node: DocumentNode, parent_id: ConfluencePageID
+    ) -> None:
+        if node.page_id is not None:
+            # 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)
+            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:
+            self._update_markdown(
+                node.absolute_path,
+                page_id=page.id,
+                space_key=space_key,
+            )
+
+        data = ConfluencePageMetadata(
+            page_id=page.id,
+            space_key=space_key,
+            title=page.title,
         )
-        return confluence_page
+        self.page_metadata.add(node.absolute_path, data)
+
+        for child_node in node.children():
+            self._synchronize_subtree(child_node, ConfluencePageID(page.id))
 
-    def _save_document(
+    @override
+    def _update_page(
         self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
     ) -> None:
         """
@@ -138,10 +144,12 @@ class SynchronizingProcessor(Processor):
 
         title = None
         if document.title is not None:
-            meta = self.page_metadata[path]
-
-            # update title only for pages with randomly assigned title
-            if meta.overwrite:
+            meta = self.page_metadata.get(path)
+            if (
+                meta is not None
+                and meta.space_key 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)
                 )
@@ -156,17 +164,23 @@ class SynchronizingProcessor(Processor):
 
         self.api.update_page(page_id.page_id, content, title=title)
 
-    def _update_markdown(
-        self,
-        path: Path,
-        document: str,
-        page_id: str,
-        space_key: Optional[str],
-    ) -> None:
+        if document.labels is not None:
+            self.api.update_labels(
+                page_id.page_id,
+                [
+                    ConfluenceLabel(name=label, prefix="global")
+                    for label in document.labels
+                ],
+            )
+
+    def _update_markdown(self, path: Path, *, page_id: str, space_key: str) -> None:
         """
         Writes the Confluence page ID and space key at the beginning of the Markdown file.
         """
 
+        with open(path, "r", encoding="utf-8") as file:
+            document = file.read()
+
         content: list[str] = []
 
         # check if the file has frontmatter
@@ -178,9 +192,7 @@ class SynchronizingProcessor(Processor):
             content.append(document[:index])
 
         content.append(f"<!-- confluence-page-id: {page_id} -->")
-        if space_key:
-            content.append(f"<!-- confluence-space-key: {space_key} -->")
-
+        content.append(f"<!-- confluence-space-key: {space_key} -->")
         content.append(document[index:])
 
         with open(path, "w", encoding="utf-8") as file:

md2conf/collection.py

@@ -0,0 +1,31 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from pathlib import Path
+from typing import Iterable, Optional
+
+from .metadata import ConfluencePageMetadata
+
+
+class ConfluencePageCollection:
+    _metadata: dict[Path, ConfluencePageMetadata]
+
+    def __init__(self) -> None:
+        self._metadata = {}
+
+    def __len__(self) -> int:
+        return len(self._metadata)
+
+    def add(self, path: Path, data: ConfluencePageMetadata) -> None:
+        self._metadata[path] = data
+
+    def get(self, path: Path) -> Optional[ConfluencePageMetadata]:
+        return self._metadata.get(path)
+
+    def items(self) -> Iterable[tuple[Path, ConfluencePageMetadata]]:
+        return self._metadata.items()

md2conf/converter.py

@@ -24,8 +24,9 @@ import lxml.etree as ET
 import markdown
 from lxml.builder import ElementMaker
 
+from .collection import ConfluencePageCollection
 from .mermaid import render_diagram
-from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
+from .metadata import ConfluenceSiteMetadata
 from .properties import PageError
 from .scanner import ScannedDocument, Scanner
 
@@ -91,8 +92,10 @@ def emoji_generator(
     md: markdown.Markdown,
 ) -> xml.etree.ElementTree.Element:
     name = (alias or shortname).strip(":")
-    span = xml.etree.ElementTree.Element("span", {"data-emoji": name})
+    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:
@@ -362,7 +365,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     images: list[Path]
     embedded_images: dict[str, bytes]
     site_metadata: ConfluenceSiteMetadata
-    page_metadata: dict[Path, ConfluencePageMetadata]
+    page_metadata: ConfluencePageCollection
 
     def __init__(
         self,
@@ -370,7 +373,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         path: Path,
         root_dir: Path,
         site_metadata: ConfluenceSiteMetadata,
-        page_metadata: dict[Path, ConfluencePageMetadata],
+        page_metadata: ConfluencePageCollection,
     ) -> None:
         super().__init__()
         self.options = options
@@ -834,7 +837,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         )
 
     def _transform_emoji(self, elem: ET._Element) -> ET._Element:
-        shortname = elem.attrib.get("data-emoji", "")
+        shortname = elem.attrib.get("data-emoji-shortname", "")
+        unicode = elem.attrib.get("data-emoji-unicode", None)
         alt = elem.text or ""
 
         # <ac:emoticon ac:name="wink" ac:emoji-shortname=":wink:" ac:emoji-id="1f609" ac:emoji-fallback="&#128521;"/>
@@ -844,8 +848,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             "emoticon",
             {
                 # use "blue-star" as a placeholder name to ensure wiki page loads in timely manner
-                ET.QName(namespaces["ac"], "name"): "blue-star",
+                ET.QName(namespaces["ac"], "name"): shortname,
                 ET.QName(namespaces["ac"], "emoji-shortname"): f":{shortname}:",
+                ET.QName(namespaces["ac"], "emoji-id"): unicode,
                 ET.QName(namespaces["ac"], "emoji-fallback"): alt,
             },
         )
@@ -943,7 +948,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         elif child.tag == "pre" and len(child) == 1 and child[0].tag == "code":
             return self._transform_block(child[0])
 
-        elif child.tag == "span" and child.attrib.has_key("data-emoji"):
+        elif child.tag == "span" and child.attrib.has_key("data-emoji-shortname"):
             return self._transform_emoji(child)
 
         return None
@@ -1006,6 +1011,7 @@ class ConversionError(RuntimeError):
 
 class ConfluenceDocument:
     title: Optional[str]
+    labels: Optional[list[str]]
     links: list[str]
     images: list[Path]
 
@@ -1019,7 +1025,7 @@ class ConfluenceDocument:
         options: ConfluenceDocumentOptions,
         root_dir: Path,
         site_metadata: ConfluenceSiteMetadata,
-        page_metadata: dict[Path, ConfluencePageMetadata],
+        page_metadata: ConfluencePageCollection,
     ) -> tuple[ConfluencePageID, "ConfluenceDocument"]:
         path = path.resolve(True)
 
@@ -1046,7 +1052,7 @@ class ConfluenceDocument:
         options: ConfluenceDocumentOptions,
         root_dir: Path,
         site_metadata: ConfluenceSiteMetadata,
-        page_metadata: dict[Path, ConfluencePageMetadata],
+        page_metadata: ConfluencePageCollection,
     ) -> None:
         self.options = options
 
@@ -1095,6 +1101,7 @@ class ConfluenceDocument:
         self.embedded_images = converter.embedded_images
 
         self.title = document.title or converter.toc.get_title()
+        self.labels = document.tags
 
     def xhtml(self) -> str:
         return elements_to_string(self.root)
@@ -1146,7 +1153,7 @@ def _content_to_string(dtd_path: Path, content: str) -> str:
 
     data = [
         '<?xml version="1.0"?>',
-        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path}">'
+        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}">'
         f"<root{ns_attr_list}>",
     ]
     data.append(content)

md2conf/emoji.py

@@ -10,7 +10,24 @@ import pathlib
 
 import pymdownx.emoji1_db as emoji_db
 
-EMOJI_PAGE_ID = "86918529216"
+EMOJI_PAGE_ID = "13500452"
+
+
+def to_html(cp: int) -> str:
+    """
+    Returns the safe HTML representation for a Unicode code point.
+
+    Converts non-ASCII and non-printable characters into HTML entities with decimal notation.
+
+    :param cp: Unicode code point.
+    :returns: An HTML representation of the Unicode character.
+    """
+
+    ch = chr(cp)
+    if ch.isascii() and ch.isalnum():
+        return ch
+    else:
+        return f"&#{cp};"
 
 
 def generate_source(path: pathlib.Path) -> None:
@@ -47,11 +64,19 @@ def generate_target(path: pathlib.Path) -> None:
         print("<thead><tr><th>Icon</th><th>Emoji code</th></tr></thead>", file=f)
         print("<tbody>", file=f)
         for key, data in emojis.items():
+            unicode = data["unicode"]
             key = key.strip(":")
-            unicode = "".join(f"&#x{item};" for item in data["unicode"].split("-"))
+            html = "".join(to_html(int(item, base=16)) for item in unicode.split("-"))
 
             print(
-                f'<tr><td><ac:emoticon ac:name="blue-star" ac:emoji-shortname=":{key}:" ac:emoji-fallback="{unicode}"/></td><td><code>:{key}:</code></td></tr>',
+                f"<tr>\n"
+                f"  <td>\n"
+                f'    <ac:emoticon ac:name="{key}" ac:emoji-shortname=":{key}:" ac:emoji-id="{unicode}" ac:emoji-fallback="{html}"/>\n'
+                f"  </td>\n"
+                f"  <td>\n"
+                f"    <code>:{key}:</code>\n"
+                f"  </td>\n"
+                f"</tr>",
                 file=f,
             )
         print("</tbody>", file=f)

md2conf/extra.py

@@ -0,0 +1,14 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import override as override  # noqa: F401
+else:
+    from typing_extensions import override as override  # noqa: F401

md2conf/local.py

@@ -6,17 +6,15 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
-import hashlib
 import logging
 import os
 from pathlib import Path
 from typing import Optional
 
 from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
+from .extra import override
 from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
-from .processor import Converter, Processor, ProcessorFactory
-from .properties import PageError
-from .scanner import Scanner
+from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 
 LOGGER = logging.getLogger(__name__)
 
@@ -46,44 +44,41 @@ class LocalProcessor(Processor):
         super().__init__(options, site, root_dir)
         self.out_dir = out_dir or root_dir
 
-    def _get_or_create_page(
-        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
-    ) -> ConfluencePageMetadata:
+    @override
+    def _synchronize_tree(
+        self, root: DocumentNode, root_id: Optional[ConfluencePageID]
+    ) -> None:
         """
-        Extracts metadata from a Markdown file.
+        Creates the cross-reference index.
+
+        Does not change Markdown files.
         """
 
-        # parse file
-        document = Scanner().read(absolute_path)
-        if document.page_id is not None:
-            page_id = document.page_id
-            space_key = document.space_key or self.site.space_key or "HOME"
-        else:
-            if parent_id is None:
-                raise PageError(
-                    f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
+        for node in root.all():
+            if node.page_id is not None:
+                page_id = node.page_id
+            else:
+                digest = self._generate_hash(node.absolute_path)
+                LOGGER.info(
+                    "Identifier %s assigned to page: %s", digest, node.absolute_path
                 )
-
-            hash = hashlib.md5(document.text.encode("utf-8"))
-            digest = "".join(f"{c:x}" for c in hash.digest())
-            LOGGER.info("Identifier %s assigned to page: %s", digest, absolute_path)
-            page_id = digest
-            space_key = self.site.space_key or "HOME"
-
-        return ConfluencePageMetadata(
-            page_id=page_id,
-            space_key=space_key,
-            title="",
-            overwrite=True,
-        )
-
-    def _save_document(
+                page_id = digest
+
+            self.page_metadata.add(
+                node.absolute_path,
+                ConfluencePageMetadata(
+                    page_id=page_id,
+                    space_key=node.space_key or self.site.space_key or "HOME",
+                    title=node.title or "",
+                ),
+            )
+
+    @override
+    def _update_page(
         self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
     ) -> None:
         """
-        Saves a new version of a Confluence document.
-
-        A derived class may invoke Confluence REST API to persist the new version.
+        Saves the document as Confluence Storage Format XHTML to the local disk.
         """
 
         content = document.xhtml()

md2conf/metadata.py

@@ -33,10 +33,8 @@ class ConfluencePageMetadata:
     :param page_id: Confluence page ID.
     :param space_key: Confluence space key.
     :param title: Document title.
-    :param overwrite: True if operations are allowed to update document properties (e.g. title).
     """
 
     page_id: str
     space_key: str
     title: str
-    overwrite: bool