markdown-to-confluence 0.3.3__tar.gz → 0.3.4__tar.gz

{markdown_to_confluence-0.3.3 → markdown_to_confluence-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.3.3
+Version: 0.3.4
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -62,13 +62,13 @@ Whenever possible, the implementation uses [Confluence REST API v2](https://deve
 
 ## Installation
 
-Install the core package from PyPI:
+**Required.** Install the core package from [PyPI](https://pypi.org/project/markdown-to-confluence/):
 
 ```sh
 pip install markdown-to-confluence
 ```
 
-Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
+**Optional.** Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -222,6 +222,13 @@ Files that don't have the extension `*.md` are skipped automatically. Hidden dir
 
 If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
 
+### Converting diagrams
+
+You can include [Mermaid diagrams](https://mermaid.js.org/) in your Markdown documents to create visual representations of systems, processes, and relationships. When a Markdown document contains a code block with the language specifier `mermaid`, *md2conf* offers two options to publish the diagram:
+
+1. Pre-render into an image. The code block is interpreted by and converted into a PNG or SVG image with the Mermaid diagram utility [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). The generated image is then uploaded to Confluence as an attachment to the page. This is the approach we use and support.
+2. Render on demand. The code block is transformed into a [diagram macro](https://atlasauthority.atlassian.net/wiki/spaces/MARKDOWNCLOUD/pages/2946826241/Diagram+Macro), which is processed by Confluence. You need a [Confluence plugin](https://marketplace.atlassian.com/apps/1211438/markdown-html-plantuml-latex-diagrams-open-api-mermaid) to turn macro definitions into images when a Confluence page is visited. This is a contributed feature. As authors of *md2conf*, we don't endorse or support any particular Confluence plugin.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:

{markdown_to_confluence-0.3.3 → markdown_to_confluence-0.3.4}/README.md

@@ -28,13 +28,13 @@ Whenever possible, the implementation uses [Confluence REST API v2](https://deve
 
 ## Installation
 
-Install the core package from PyPI:
+**Required.** Install the core package from [PyPI](https://pypi.org/project/markdown-to-confluence/):
 
 ```sh
 pip install markdown-to-confluence
 ```
 
-Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
+**Optional.** Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -188,6 +188,13 @@ Files that don't have the extension `*.md` are skipped automatically. Hidden dir
 
 If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
 
+### Converting diagrams
+
+You can include [Mermaid diagrams](https://mermaid.js.org/) in your Markdown documents to create visual representations of systems, processes, and relationships. When a Markdown document contains a code block with the language specifier `mermaid`, *md2conf* offers two options to publish the diagram:
+
+1. Pre-render into an image. The code block is interpreted by and converted into a PNG or SVG image with the Mermaid diagram utility [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). The generated image is then uploaded to Confluence as an attachment to the page. This is the approach we use and support.
+2. Render on demand. The code block is transformed into a [diagram macro](https://atlasauthority.atlassian.net/wiki/spaces/MARKDOWNCLOUD/pages/2946826241/Diagram+Macro), which is processed by Confluence. You need a [Confluence plugin](https://marketplace.atlassian.com/apps/1211438/markdown-html-plantuml-latex-diagrams-open-api-mermaid) to turn macro definitions into images when a Confluence page is visited. This is a contributed feature. As authors of *md2conf*, we don't endorse or support any particular Confluence plugin.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:

{markdown_to_confluence-0.3.3 → markdown_to_confluence-0.3.4}/markdown_to_confluence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.3.3
+Version: 0.3.4
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -62,13 +62,13 @@ Whenever possible, the implementation uses [Confluence REST API v2](https://deve
 
 ## Installation
 
-Install the core package from PyPI:
+**Required.** Install the core package from [PyPI](https://pypi.org/project/markdown-to-confluence/):
 
 ```sh
 pip install markdown-to-confluence
 ```
 
-Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
+**Optional.** Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -222,6 +222,13 @@ Files that don't have the extension `*.md` are skipped automatically. Hidden dir
 
 If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
 
+### Converting diagrams
+
+You can include [Mermaid diagrams](https://mermaid.js.org/) in your Markdown documents to create visual representations of systems, processes, and relationships. When a Markdown document contains a code block with the language specifier `mermaid`, *md2conf* offers two options to publish the diagram:
+
+1. Pre-render into an image. The code block is interpreted by and converted into a PNG or SVG image with the Mermaid diagram utility [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). The generated image is then uploaded to Confluence as an attachment to the page. This is the approach we use and support.
+2. Render on demand. The code block is transformed into a [diagram macro](https://atlasauthority.atlassian.net/wiki/spaces/MARKDOWNCLOUD/pages/2946826241/Diagram+Macro), which is processed by Confluence. You need a [Confluence plugin](https://marketplace.atlassian.com/apps/1211438/markdown-html-plantuml-latex-diagrams-open-api-mermaid) to turn macro definitions into images when a Confluence page is visited. This is a contributed feature. As authors of *md2conf*, we don't endorse or support any particular Confluence plugin.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:

{markdown_to_confluence-0.3.3 → markdown_to_confluence-0.3.4}/markdown_to_confluence.egg-info/SOURCES.txt

@@ -17,8 +17,10 @@ md2conf/application.py
 md2conf/converter.py
 md2conf/emoji.py
 md2conf/entities.dtd
+md2conf/local.py
 md2conf/matcher.py
 md2conf/mermaid.py
+md2conf/metadata.py
 md2conf/processor.py
 md2conf/properties.py
 md2conf/puppeteer-config.json

{markdown_to_confluence-0.3.3 → markdown_to_confluence-0.3.4}/md2conf/__init__.py

@@ -5,7 +5,7 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

{markdown_to_confluence-0.3.3 → markdown_to_confluence-0.3.4}/md2conf/__main__.py

@@ -22,8 +22,9 @@ import requests
 from . import __version__
 from .api import ConfluenceAPI
 from .application import Application
-from .converter import ConfluenceDocumentOptions, ConfluenceSiteMetadata
-from .processor import Processor
+from .converter import ConfluenceDocumentOptions, ConfluencePageID
+from .local import LocalConverter
+from .metadata import ConfluenceSiteMetadata
 from .properties import (
     ArgumentError,
     ConfluenceConnectionProperties,
@@ -199,7 +200,7 @@ def main() -> None:
         heading_anchors=args.heading_anchors,
         ignore_invalid_url=args.ignore_invalid_url,
         generated_by=args.generated_by,
-        root_page_id=args.root_page,
+        root_page_id=ConfluencePageID(args.root_page) if args.root_page else None,
         keep_hierarchy=args.keep_hierarchy,
         render_mermaid=args.render_mermaid,
         diagram_output_format=args.diagram_output_format,
@@ -219,7 +220,7 @@ def main() -> None:
             base_path=site_properties.base_path,
             space_key=site_properties.space_key,
         )
-        Processor(options, site_metadata).process(args.mdpath)
+        LocalConverter(options, site_metadata).process(args.mdpath)
     else:
         try:
             properties = ConfluenceConnectionProperties(
@@ -237,7 +238,7 @@ def main() -> None:
                 Application(
                     api,
                     options,
-                ).synchronize(args.mdpath)
+                ).process(args.mdpath)
         except requests.exceptions.HTTPError as err:
             logging.error(err)
 

{markdown_to_confluence-0.3.3 → markdown_to_confluence-0.3.4}/md2conf/api.py

@@ -7,6 +7,7 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 import enum
+import functools
 import io
 import json
 import logging
@@ -21,6 +22,7 @@ from urllib.parse import urlencode, urlparse, urlunparse
 import requests
 
 from .converter import ParseError, sanitize_confluence
+from .metadata import ConfluenceSiteMetadata
 from .properties import (
     ArgumentError,
     ConfluenceConnectionProperties,
@@ -76,7 +78,7 @@ def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
 LOGGER = logging.getLogger(__name__)
 
 
-@dataclass
+@dataclass(frozen=True)
 class ConfluenceAttachment:
     id: str
     media_type: str
@@ -84,14 +86,18 @@ class ConfluenceAttachment:
     comment: str
 
 
-@dataclass
-class ConfluencePage:
+@dataclass(frozen=True)
+class ConfluencePageMetadata:
     id: str
     space_id: str
     parent_id: str
     parent_type: Optional[ConfluencePageParentContentType]
     title: str
     version: int
+
+
+@dataclass(frozen=True)
+class ConfluencePage(ConfluencePageMetadata):
     content: str
 
 
@@ -136,10 +142,12 @@ class ConfluenceAPI:
 
 
 class ConfluenceSession:
+    """
+    Information about an open session to a Confluence server.
+    """
+
     session: requests.Session
-    domain: str
-    base_path: str
-    space_key: Optional[str]
+    site: ConfluenceSiteMetadata
 
     _space_id_to_key: dict[str, str]
     _space_key_to_id: dict[str, str]
@@ -152,9 +160,7 @@ class ConfluenceSession:
         space_key: Optional[str] = None,
     ) -> None:
         self.session = session
-        self.domain = domain
-        self.base_path = base_path
-        self.space_key = space_key
+        self.site = ConfluenceSiteMetadata(domain, base_path, space_key)
 
         self._space_id_to_key = {}
         self._space_key_to_id = {}
@@ -178,7 +184,9 @@ class ConfluenceSession:
         :returns: A full URL.
         """
 
-        base_url = f"https://{self.domain}{self.base_path}{version.value}{path}"
+        base_url = (
+            f"https://{self.site.domain}{self.site.base_path}{version.value}{path}"
+        )
         return build_url(base_url, query)
 
     def _invoke(
@@ -251,6 +259,29 @@ class ConfluenceSession:
 
         return id
 
+    def get_space_id(
+        self, *, space_id: Optional[str] = None, space_key: Optional[str] = None
+    ) -> Optional[str]:
+        """
+        Coalesce a space ID or space key into a space ID, accounting for site default.
+
+        :param space_id: A Confluence space ID.
+        :param space_key: A Confluence space key.
+        """
+
+        if space_id is not None and space_key is not None:
+            raise ConfluenceError("either space ID or space key is required; not both")
+
+        if space_id is not None:
+            return space_id
+
+        space_key = space_key or self.site.space_key
+        if space_key is not None:
+            return self.space_key_to_id(space_key)
+
+        # space ID and key are unset, and no default space is configured
+        return None
+
     def get_attachment_by_name(
         self, page_id: str, filename: str
     ) -> ConfluenceAttachment:
@@ -393,6 +424,7 @@ class ConfluenceSession:
         self,
         title: str,
         *,
+        space_id: Optional[str] = None,
         space_key: Optional[str] = None,
     ) -> str:
         """
@@ -408,9 +440,9 @@ class ConfluenceSession:
         query = {
             "title": title,
         }
-        coalesced_space_key = space_key or self.space_key
-        if coalesced_space_key is not None:
-            query["space-id"] = self.space_key_to_id(coalesced_space_key)
+        space_id = self.get_space_id(space_id=space_id, space_key=space_key)
+        if space_id is not None:
+            query["space-id"] = space_id
 
         payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
         payload = typing.cast(dict[str, JsonType], payload)
@@ -425,10 +457,10 @@ class ConfluenceSession:
 
     def get_page(self, page_id: str) -> ConfluencePage:
         """
-        Retrieve Confluence wiki page details.
+        Retrieve Confluence wiki page details and content.
 
         :param page_id: The Confluence page ID.
-        :returns: Confluence page info.
+        :returns: Confluence page info and content.
         """
 
         path = f"/pages/{page_id}"
@@ -453,6 +485,33 @@ class ConfluenceSession:
             content=typing.cast(str, storage["value"]),
         )
 
+    @functools.cache
+    def get_page_metadata(self, page_id: str) -> ConfluencePageMetadata:
+        """
+        Retrieve Confluence wiki page details.
+
+        :param page_id: The Confluence page ID.
+        :returns: Confluence page info.
+        """
+
+        path = f"/pages/{page_id}"
+        payload = self._invoke(ConfluenceVersion.VERSION_2, path)
+        data = typing.cast(dict[str, JsonType], payload)
+        version = typing.cast(dict[str, JsonType], data["version"])
+
+        return ConfluencePageMetadata(
+            id=page_id,
+            space_id=typing.cast(str, data["spaceId"]),
+            parent_id=typing.cast(str, data["parentId"]),
+            parent_type=(
+                ConfluencePageParentContentType(typing.cast(str, data["parentType"]))
+                if data["parentType"] is not None
+                else None
+            ),
+            title=typing.cast(str, data["title"]),
+            version=typing.cast(int, version["number"]),
+        )
+
     def get_page_version(self, page_id: str) -> int:
         """
         Retrieve a Confluence wiki page version.
@@ -507,26 +566,21 @@ class ConfluenceSession:
 
     def create_page(
         self,
-        parent_page_id: str,
+        parent_id: str,
         title: str,
         new_content: str,
-        *,
-        space_key: Optional[str] = None,
     ) -> ConfluencePage:
         """
         Create a new page via Confluence API.
         """
 
-        coalesced_space_key = space_key or self.space_key
-        if coalesced_space_key is None:
-            raise ArgumentError("Confluence space key required for creating a new page")
-
+        parent_page = self.get_page_metadata(parent_id)
         path = "/pages/"
         query = {
-            "spaceId": self.space_key_to_id(coalesced_space_key),
+            "spaceId": parent_page.space_id,
             "status": "current",
             "title": title,
-            "parentId": parent_page_id,
+            "parentId": parent_id,
             "body": {"storage": {"value": new_content, "representation": "storage"}},
         }
 
@@ -584,13 +638,24 @@ class ConfluenceSession:
             response.raise_for_status()
 
     def page_exists(
-        self, title: str, *, space_key: Optional[str] = None
+        self,
+        title: str,
+        *,
+        space_id: Optional[str] = None,
+        space_key: Optional[str] = None,
     ) -> Optional[str]:
+        """
+        Check if a Confluence page exists with the given title.
+
+        :param title: Page title. Pages in the same Confluence space must have a unique title.
+        :param space_key: Identifies the Confluence space.
+        """
+
+        space_id = self.get_space_id(space_id=space_id, space_key=space_key)
         path = "/pages"
-        coalesced_space_key = space_key or self.space_key
         query = {"title": title}
-        if coalesced_space_key is not None:
-            query["space-id"] = self.space_key_to_id(coalesced_space_key)
+        if space_id is not None:
+            query["space-id"] = space_id
 
         LOGGER.info("Checking if page exists with title: %s", title)
 
@@ -609,14 +674,20 @@ class ConfluenceSession:
         else:
             return None
 
-    def get_or_create_page(
-        self, title: str, parent_id: str, *, space_key: Optional[str] = None
-    ) -> ConfluencePage:
-        page_id = self.page_exists(title)
+    def get_or_create_page(self, title: str, parent_id: str) -> ConfluencePage:
+        """
+        Find a page with the given title, or create a new page if no such page exists.
+
+        :param title: Page title. Pages in the same Confluence space must have a unique title.
+        :param parent_id: Identifies the parent page for a new child page.
+        """
+
+        parent_page = self.get_page_metadata(parent_id)
+        page_id = self.page_exists(title, space_id=parent_page.space_id)
 
         if page_id is not None:
             LOGGER.debug("Retrieving existing page: %s", page_id)
             return self.get_page(page_id)
         else:
             LOGGER.debug("Creating new page with title: %s", title)
-            return self.create_page(parent_id, title, "", space_key=space_key)
+            return self.create_page(parent_id, title, "")

markdown_to_confluence-0.3.4/md2conf/application.py

@@ -0,0 +1,208 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+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 .converter import (
+    ConfluenceDocument,
+    ConfluenceDocumentOptions,
+    ConfluencePageID,
+    attachment_name,
+    extract_frontmatter_title,
+    extract_qualified_id,
+)
+from .metadata import ConfluencePageMetadata
+from .processor import Converter, Processor, ProcessorFactory
+from .properties import PageError
+
+LOGGER = logging.getLogger(__name__)
+
+
+class SynchronizingProcessor(Processor):
+    """
+    Synchronizes a single Markdown page or a directory of Markdown pages with Confluence.
+    """
+
+    api: ConfluenceSession
+
+    def __init__(
+        self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path
+    ) -> None:
+        """
+        Initializes a new processor instance.
+
+        :param api: Holds information about an open session to a Confluence server.
+        :param options: Options that control the generated page content.
+        :param root_dir: File system directory that acts as topmost root node.
+        """
+
+        super().__init__(options, api.site, root_dir)
+        self.api = api
+
+    def _get_or_create_page(
+        self,
+        absolute_path: Path,
+        parent_id: Optional[ConfluencePageID],
+        *,
+        title: Optional[str] = None,
+    ) -> ConfluencePageMetadata:
+        """
+        Creates a new Confluence page if no page is linked in the Markdown document.
+        """
+
+        # parse file
+        with open(absolute_path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        qualified_id, text = extract_qualified_id(text)
+
+        overwrite = False
+        if qualified_id is None:
+            # create new Confluence page
+            if parent_id is None:
+                raise PageError(
+                    f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
+                )
+
+            # assign title from front-matter if present
+            if title is None:
+                title, _ = extract_frontmatter_title(text)
+
+            # use file name (without extension) and path hash if no title is supplied
+            if title is None:
+                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, text, title, parent_id)
+        else:
+            # look up existing Confluence page
+            confluence_page = self.api.get_page(qualified_id.page_id)
+
+        space_key = (
+            self.api.space_id_to_key(confluence_page.space_id)
+            if confluence_page.space_id
+            else self.site.space_key
+        )
+
+        return ConfluencePageMetadata(
+            page_id=confluence_page.id,
+            space_key=space_key,
+            title=confluence_page.title,
+            overwrite=overwrite,
+        )
+
+    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.
+        """
+
+        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),
+        )
+        return confluence_page
+
+    def _save_document(self, document: ConfluenceDocument, path: Path) -> None:
+        """
+        Saves a new version of a Confluence document.
+
+        Invokes Confluence REST API to persist the new version.
+        """
+
+        base_path = path.parent
+        for image in document.images:
+            self.api.upload_attachment(
+                document.id.page_id,
+                attachment_name(image),
+                attachment_path=base_path / image,
+            )
+
+        for name, data in document.embedded_images.items():
+            self.api.upload_attachment(
+                document.id.page_id,
+                name,
+                raw_data=data,
+            )
+
+        content = document.xhtml()
+
+        # leave title as it is for existing pages, update title for pages with randomly assigned title
+        title = document.title if self.page_metadata[path].overwrite else None
+
+        LOGGER.debug("Generated Confluence Storage Format document:\n%s", content)
+        self.api.update_page(document.id.page_id, content, title=title)
+
+    def _update_markdown(
+        self,
+        path: Path,
+        document: str,
+        page_id: str,
+        space_key: Optional[str],
+    ) -> None:
+        """
+        Writes the Confluence page ID and space key at the beginning of the Markdown file.
+        """
+
+        content: list[str] = []
+
+        # check if the file has frontmatter
+        index = 0
+        if document.startswith("---\n"):
+            index = document.find("\n---\n", 4) + 4
+
+            # insert the Confluence keys after the frontmatter
+            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(document[index:])
+
+        with open(path, "w", encoding="utf-8") as file:
+            file.write("\n".join(content))
+
+
+class SynchronizingProcessorFactory(ProcessorFactory):
+    api: ConfluenceSession
+
+    def __init__(
+        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
+    ) -> None:
+        super().__init__(options, api.site)
+        self.api = api
+
+    def create(self, root_dir: Path) -> Processor:
+        return SynchronizingProcessor(self.api, self.options, root_dir)
+
+
+class Application(Converter):
+    """
+    The entry point for Markdown to Confluence conversion.
+    """
+
+    def __init__(
+        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
+    ) -> None:
+        super().__init__(SynchronizingProcessorFactory(api, options))