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

{markdown_to_confluence-0.3.4.dist-info → markdown_to_confluence-0.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.3.4
+Version: 0.3.5
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -21,12 +21,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lxml>=5.3
-Requires-Dist: types-lxml>=2024.12.13
-Requires-Dist: markdown>=3.7
-Requires-Dist: types-markdown>=3.7
-Requires-Dist: pymdown-extensions>=10.14
-Requires-Dist: pyyaml>=6.0
+Requires-Dist: lxml>=5.4
+Requires-Dist: types-lxml>=2025.3.30
+Requires-Dist: markdown>=3.8
+Requires-Dist: types-markdown>=3.8
+Requires-Dist: pymdown-extensions>=10.15
+Requires-Dist: PyYAML>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: types-requests>=2.32
@@ -198,20 +198,26 @@ root
         └── Mean vs. median
 ```
 
+### Lists and tables
+
+If your Markdown lists or tables don't appear in Confluence as expected, verify that the list or table is delimited by a blank line both before and after, as per strict Markdown syntax. While some previewers accept a more lenient syntax (e.g. an itemized list immediately following a paragraph), *md2conf* uses [Python-Markdown](https://python-markdown.github.io/) internally to convert Markdown into XHTML, which expects the Markdown document to adhere to the stricter syntax.
+
 ### Publishing images
 
 Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
 
-Unfortunately, Confluence struggles with SVG images, e.g. they may only show in *edit* mode, display in a wrong size or text labels in the image may be truncated. In order to mitigate the issue, whenever *md2conf* encounters a reference to an SVG image in a Markdown file, it checks whether a corresponding PNG image also exists in the same directory, and if a PNG image is found, it is published instead.
+Unfortunately, Confluence struggles with SVG images, e.g. they may only show in *edit* mode, display in a wrong size or text labels in the image may be truncated. (This seems to be a known issue in Confluence.) In order to mitigate the issue, whenever *md2conf* encounters a reference to an SVG image in a Markdown file, it checks whether a corresponding PNG image also exists in the same directory, and if a PNG image is found, it is published instead.
 
 External images referenced with an absolute URL retain the original URL.
 
 ### Ignoring files
 
-Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
+Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax (and constraints) of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
 
 Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
 
+Relative paths to items in a nested directory are not supported. You must put `.mdignore` in the same directory where the items to be skipped reside.
+
 ### Page title
 
 *md2conf* makes a best-effort attempt at setting the Confluence wiki page title when it publishes a Markdown document the first time. The following are probed in this order:

markdown_to_confluence-0.3.5.dist-info/RECORD

@@ -0,0 +1,23 @@
+markdown_to_confluence-0.3.5.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+md2conf/__init__.py,sha256=Uaqb3maQScpYs3FiH8kuM6pUh5JzE4Vy52MgU9pvMTw,402
+md2conf/__main__.py,sha256=bFcfmSnTWeuhmDm7bJ3jJabZ2S8W9biuAP6_R-Cc9As,8034
+md2conf/api.py,sha256=VxrAJ4yCsdGFVAEQQWw5aONwsMz0b6KvN4EMLXCKOwE,26905
+md2conf/application.py,sha256=SIM4yLHaLnvG7wRJLbRvptrkc0q4JMuAhDnanqsuYzA,6697
+md2conf/converter.py,sha256=ASXhs7g79dOU4x1QhfvKL8mtwth508GTGcb3AUHigC4,37286
+md2conf/emoji.py,sha256=48QJtOD0F3Be1laYLvAOwe0GxrJS-vcfjtCdiBsNcAc,1960
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/local.py,sha256=998bBRpDAOywA-L0KD4_VyuL2Xftflv0ler-uNPQZn4,3866
+md2conf/matcher.py,sha256=y5WEZNklTpUoJtMJlulTvfhl_v-UMU6wySJAKit91ig,4940
+md2conf/mermaid.py,sha256=ZETocFDKi_fSYyVR1pJ7fo207YYFSuT44MSYFQ8-cZ0,2562
+md2conf/metadata.py,sha256=Xozg2PjJnis7VQYQT_edIvTb8u0cs_ZizPOAxc1N8vg,1003
+md2conf/processor.py,sha256=jSLFy8hqZJXf3b79jp31Fn9-cm4j9xq4HDChp9pyhP0,6706
+md2conf/properties.py,sha256=TOCXLdTfYkKjRwZaMgvXw0mNCI4opEUwpBXro2Kv2B4,2467
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/scanner.py,sha256=iF8NCQAFO6Yut5aAQr7uxfWzVMMt9j3T5ADoVVSJWKQ,3543
+markdown_to_confluence-0.3.5.dist-info/METADATA,sha256=NiXwBXtQ5WhHce_JX7TBUSefQSR5jk5fERe46BL4vwE,18462
+markdown_to_confluence-0.3.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.3.5.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.3.5.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.3.5.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.3.5.dist-info/RECORD,,

{markdown_to_confluence-0.3.4.dist-info → markdown_to_confluence-0.3.5.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

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.4"
+__version__ = "0.3.5"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/api.py

@@ -43,13 +43,23 @@ JsonType = Union[
 
 
 class ConfluenceVersion(enum.Enum):
+    """
+    Confluence REST API version an HTTP request corresponds to.
+
+    For some operations, Confluence Cloud supports v2 endpoints exclusively. However, for other operations, only v1 endpoints are available via REST API.
+    Some versions of Confluence Server and Data Center, unfortunately, don't support v2 endpoints at all.
+
+    The principal use case for *md2conf* is Confluence Cloud. As such, *md2conf* uses v2 endpoints when available, and resorts to v1 endpoints only when
+    necessary.
+    """
+
     VERSION_1 = "rest/api"
     VERSION_2 = "api/v2"
 
 
 class ConfluencePageParentContentType(enum.Enum):
     """
-    Content types that can be a parent to a Confluence page
+    Content types that can be a parent to a Confluence page.
     """
 
     PAGE = "page"
@@ -80,6 +90,15 @@ LOGGER = logging.getLogger(__name__)
 
 @dataclass(frozen=True)
 class ConfluenceAttachment:
+    """
+    Holds data for an object uploaded to Confluence as a page attachment.
+
+    :param id: Unique ID for the attachment.
+    :param media_type: MIME type for the attachment.
+    :param file_size: Size in bytes.
+    :param comment: Description for the attachment.
+    """
+
     id: str
     media_type: str
     file_size: int
@@ -87,7 +106,18 @@ class ConfluenceAttachment:
 
 
 @dataclass(frozen=True)
-class ConfluencePageMetadata:
+class ConfluencePageProperties:
+    """
+    Holds Confluence page properties used for page synchronization.
+
+    :param id: Confluence page ID.
+    :param space_id: Confluence space ID.
+    :param parent_id: Confluence page ID of the immediate parent.
+    :param parent_type: Identifies the content type of the parent.
+    :param title: Page title.
+    :param version: Page version. Incremented when the page is updated.
+    """
+
     id: str
     space_id: str
     parent_id: str
@@ -97,11 +127,36 @@ class ConfluencePageMetadata:
 
 
 @dataclass(frozen=True)
-class ConfluencePage(ConfluencePageMetadata):
+class ConfluencePage(ConfluencePageProperties):
+    """
+    Holds Confluence page data used for page synchronization.
+
+    :param content: Page content in Confluence Storage Format.
+    """
+
     content: str
 
 
+@dataclass(frozen=True)
+class ConfluenceLabel:
+    """
+    Holds information about a single label.
+
+    :param id: ID of the label.
+    :param name: Name of the label.
+    :param prefix: Prefix of the label.
+    """
+
+    id: str
+    name: str
+    prefix: str
+
+
 class ConfluenceAPI:
+    """
+    Represents an active connection to a Confluence server.
+    """
+
     properties: ConfluenceConnectionProperties
     session: Optional["ConfluenceSession"] = None
 
@@ -195,7 +250,7 @@ class ConfluenceSession:
         path: str,
         query: Optional[dict[str, str]] = None,
     ) -> JsonType:
-        "Execute an HTTP request via Confluence API."
+        "Executes an HTTP request via Confluence API."
 
         url = self._build_url(version, path, query)
         response = self.session.get(url)
@@ -204,7 +259,33 @@ class ConfluenceSession:
         response.raise_for_status()
         return response.json()
 
-    def _save(self, version: ConfluenceVersion, path: str, data: dict) -> None:
+    def _fetch(
+        self, path: str, query: Optional[dict[str, str]] = None
+    ) -> list[JsonType]:
+        "Retrieves all results of a REST API v2 paginated result-set."
+
+        items: list[JsonType] = []
+        url = self._build_url(ConfluenceVersion.VERSION_2, path, query)
+        while True:
+            response = self.session.get(url)
+            response.raise_for_status()
+
+            payload = typing.cast(dict[str, JsonType], response.json())
+            results = typing.cast(list[JsonType], payload["results"])
+            items.extend(results)
+
+            links = typing.cast(dict[str, JsonType], payload.get("_links", {}))
+            link = typing.cast(str, links.get("next", ""))
+            if link:
+                url = f"https://{self.site.domain}{link}"
+            else:
+                break
+
+        return items
+
+    def _save(self, version: ConfluenceVersion, path: str, data: JsonType) -> None:
+        "Persists data via Confluence REST API."
+
         url = self._build_url(version, path)
         response = self.session.put(
             url,
@@ -263,7 +344,7 @@ class ConfluenceSession:
         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.
+        Coalesces 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.
@@ -285,6 +366,10 @@ class ConfluenceSession:
     def get_attachment_by_name(
         self, page_id: str, filename: str
     ) -> ConfluenceAttachment:
+        """
+        Retrieves a Confluence page attachment by an unprefixed file name.
+        """
+
         path = f"/pages/{page_id}/attachments"
         query = {"filename": filename}
         data = typing.cast(
@@ -313,6 +398,18 @@ class ConfluenceSession:
         comment: Optional[str] = None,
         force: bool = False,
     ) -> None:
+        """
+        Uploads a new attachment to a Confluence page.
+
+        :param page_id: Confluence page ID.
+        :param attachment_name: Unprefixed name unique to the page.
+        :param attachment_path: Path to the file to upload as an attachment.
+        :param raw_data: Raw data to upload as an attachment.
+        :param content_type: Attachment MIME type.
+        :param comment: Attachment description.
+        :param force: Overwrite an existing attachment even if there seem to be no changes.
+        """
+
         if attachment_path is None and raw_data is None:
             raise ArgumentError("required: `attachment_path` or `raw_data`")
 
@@ -409,7 +506,7 @@ class ConfluenceSession:
     ) -> None:
         id = attachment_id.removeprefix("att")
         path = f"/content/{page_id}/child/attachment/{id}"
-        data = {
+        data: JsonType = {
             "id": attachment_id,
             "type": "attachment",
             "status": "current",
@@ -428,10 +525,11 @@ class ConfluenceSession:
         space_key: Optional[str] = None,
     ) -> str:
         """
-        Look up a Confluence wiki page ID by title.
+        Looks up a Confluence wiki page ID by title.
 
         :param title: The page title.
-        :param space_key: The Confluence space key (unless the default space is to be used).
+        :param space_id: The Confluence space ID (unless the default space is to be used). Exclusive with space key.
+        :param space_key: The Confluence space key (unless the default space is to be used). Exclusive with space ID.
         :returns: Confluence page ID.
         """
 
@@ -457,7 +555,7 @@ class ConfluenceSession:
 
     def get_page(self, page_id: str) -> ConfluencePage:
         """
-        Retrieve Confluence wiki page details and content.
+        Retrieves Confluence wiki page details and content.
 
         :param page_id: The Confluence page ID.
         :returns: Confluence page info and content.
@@ -486,9 +584,9 @@ class ConfluenceSession:
         )
 
     @functools.cache
-    def get_page_metadata(self, page_id: str) -> ConfluencePageMetadata:
+    def get_page_properties(self, page_id: str) -> ConfluencePageProperties:
         """
-        Retrieve Confluence wiki page details.
+        Retrieves Confluence wiki page details.
 
         :param page_id: The Confluence page ID.
         :returns: Confluence page info.
@@ -499,7 +597,7 @@ class ConfluenceSession:
         data = typing.cast(dict[str, JsonType], payload)
         version = typing.cast(dict[str, JsonType], data["version"])
 
-        return ConfluencePageMetadata(
+        return ConfluencePageProperties(
             id=page_id,
             space_id=typing.cast(str, data["spaceId"]),
             parent_id=typing.cast(str, data["parentId"]),
@@ -514,7 +612,7 @@ class ConfluenceSession:
 
     def get_page_version(self, page_id: str) -> int:
         """
-        Retrieve a Confluence wiki page version.
+        Retrieves a Confluence wiki page version.
 
         :param page_id: The Confluence page ID.
         :returns: Confluence page version.
@@ -534,7 +632,7 @@ class ConfluenceSession:
         title: Optional[str] = None,
     ) -> None:
         """
-        Update a page via the Confluence API.
+        Updates a page via the Confluence API.
 
         :param page_id: The Confluence page ID.
         :param new_content: Confluence Storage Format XHTML.
@@ -553,7 +651,7 @@ class ConfluenceSession:
             LOGGER.warning(exc)
 
         path = f"/pages/{page_id}"
-        data = {
+        data: JsonType = {
             "id": page_id,
             "status": "current",
             "title": new_title,
@@ -571,10 +669,10 @@ class ConfluenceSession:
         new_content: str,
     ) -> ConfluencePage:
         """
-        Create a new page via Confluence API.
+        Creates a new page via Confluence API.
         """
 
-        parent_page = self.get_page_metadata(parent_id)
+        parent_page = self.get_page_properties(parent_id)
         path = "/pages/"
         query = {
             "spaceId": parent_page.space_id,
@@ -615,10 +713,10 @@ class ConfluenceSession:
 
     def delete_page(self, page_id: str, *, purge: bool = False) -> None:
         """
-        Delete a page via Confluence API.
+        Deletes a page via Confluence API.
 
         :param page_id: The Confluence page ID.
-        :param purge: True to completely purge the page, False to move to trash only.
+        :param purge: `True` to completely purge the page, `False` to move to trash only.
         """
 
         path = f"/pages/{page_id}"
@@ -645,10 +743,12 @@ class ConfluenceSession:
         space_key: Optional[str] = None,
     ) -> Optional[str]:
         """
-        Check if a Confluence page exists with the given title.
+        Checks 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.
+
+        :returns: Confluence page ID of a matching page (if found), or `None`.
         """
 
         space_id = self.get_space_id(space_id=space_id, space_key=space_key)
@@ -676,13 +776,13 @@ class ConfluenceSession:
 
     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.
+        Finds a page with the given title, or creates 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)
+        parent_page = self.get_page_properties(parent_id)
         page_id = self.page_exists(title, space_id=parent_page.space_id)
 
         if page_id is not None:
@@ -691,3 +791,22 @@ class ConfluenceSession:
         else:
             LOGGER.debug("Creating new page with title: %s", title)
             return self.create_page(parent_id, title, "")
+
+    def get_labels(self, page_id: str) -> list[ConfluenceLabel]:
+        """
+        Retrieves labels for a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :returns: A list of page labels.
+        """
+
+        items: list[ConfluenceLabel] = []
+        path = f"/pages/{page_id}/labels"
+        results = self._fetch(path)
+        for r in results:
+            result = typing.cast(dict[str, JsonType], r)
+            id = typing.cast(str, result["id"])
+            name = typing.cast(str, result["name"])
+            prefix = typing.cast(str, result["prefix"])
+            items.append(ConfluenceLabel(id, name, prefix))
+        return items

md2conf/application.py

@@ -17,12 +17,11 @@ from .converter import (
     ConfluenceDocumentOptions,
     ConfluencePageID,
     attachment_name,
-    extract_frontmatter_title,
-    extract_qualified_id,
 )
 from .metadata import ConfluencePageMetadata
 from .processor import Converter, Processor, ProcessorFactory
 from .properties import PageError
+from .scanner import Scanner
 
 LOGGER = logging.getLogger(__name__)
 
@@ -49,56 +48,43 @@ class SynchronizingProcessor(Processor):
         self.api = api
 
     def _get_or_create_page(
-        self,
-        absolute_path: Path,
-        parent_id: Optional[ConfluencePageID],
-        *,
-        title: Optional[str] = None,
+        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
     ) -> 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)
+        document = Scanner().read(absolute_path)
 
         overwrite = False
-        if qualified_id is None:
+        if document.page_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:
+            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, text, title, parent_id)
+            confluence_page = self._create_page(
+                absolute_path, document.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
-        )
+            confluence_page = self.api.get_page(document.page_id)
 
         return ConfluencePageMetadata(
             page_id=confluence_page.id,
-            space_key=space_key,
+            space_key=self.api.space_id_to_key(confluence_page.space_id),
             title=confluence_page.title,
             overwrite=overwrite,
         )
@@ -123,7 +109,9 @@ class SynchronizingProcessor(Processor):
         )
         return confluence_page
 
-    def _save_document(self, document: ConfluenceDocument, path: Path) -> None:
+    def _save_document(
+        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
+    ) -> None:
         """
         Saves a new version of a Confluence document.
 
@@ -133,25 +121,40 @@ class SynchronizingProcessor(Processor):
         base_path = path.parent
         for image in document.images:
             self.api.upload_attachment(
-                document.id.page_id,
+                page_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,
+                page_id.page_id,
                 name,
                 raw_data=data,
             )
 
         content = document.xhtml()
+        LOGGER.debug("Generated Confluence Storage Format document:\n%s", content)
 
-        # 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
+        title = None
+        if document.title is not None:
+            meta = self.page_metadata[path]
 
-        LOGGER.debug("Generated Confluence Storage Format document:\n%s", content)
-        self.api.update_page(document.id.page_id, content, title=title)
+            # update title only for pages with randomly assigned title
+            if meta.overwrite:
+                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
+                else:
+                    LOGGER.info(
+                        "Document title of %s conflicts with Confluence page title of %s",
+                        path,
+                        conflicting_page_id,
+                    )
+
+        self.api.update_page(page_id.page_id, content, title=title)
 
     def _update_markdown(
         self,
@@ -200,6 +203,8 @@ class SynchronizingProcessorFactory(ProcessorFactory):
 class Application(Converter):
     """
     The entry point for Markdown to Confluence conversion.
+
+    This is the class instantiated by the command-line application.
     """
 
     def __init__(

md2conf/converter.py

@@ -18,16 +18,16 @@ import xml.etree.ElementTree
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Literal, Optional, Union
-from urllib.parse import ParseResult, urlparse, urlunparse
+from urllib.parse import ParseResult, quote_plus, urlparse, urlunparse
 
 import lxml.etree as ET
 import markdown
-import yaml
 from lxml.builder import ElementMaker
 
 from .mermaid import render_diagram
 from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
 from .properties import PageError
+from .scanner import ScannedDocument, Scanner
 
 namespaces = {
     "ac": "http://atlassian.com/content",
@@ -66,6 +66,19 @@ def is_relative_url(url: str) -> bool:
     return not bool(urlparts.scheme) and not bool(urlparts.netloc)
 
 
+def encode_title(text: str) -> str:
+    "Converts a title string such that it is safe to embed into a Confluence URL."
+
+    # replace unsafe characters with space
+    text = re.sub(r"[^A-Za-z0-9._~()'!*:@,;+?-]+", " ", text)
+
+    # replace multiple consecutive spaces with single space
+    text = re.sub(r"\s\s+", " ", text)
+
+    # URL-encode
+    return quote_plus(text.strip())
+
+
 def emoji_generator(
     index: str,
     shortname: str,
@@ -466,7 +479,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                     "Confluence space key required for building full web URLs"
                 )
 
-            page_url = f"{self.site_metadata.base_path}spaces/{space_key}/pages/{link_metadata.page_id}/{link_metadata.title}"
+            page_url = f"{self.site_metadata.base_path}spaces/{space_key}/pages/{link_metadata.page_id}/{encode_title(link_metadata.title)}"
 
         components = ParseResult(
             scheme="https",
@@ -949,78 +962,15 @@ class DocumentError(RuntimeError):
     "Raised when a converted Markdown document has an unexpected element or attribute."
 
 
-def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
-    values: list[str] = []
-
-    def _repl_func(matchobj: re.Match) -> str:
-        values.append(matchobj.group(1))
-        return ""
-
-    text = re.sub(pattern, _repl_func, text, 1, re.ASCII)
-    value = values[0] if values else None
-    return value, text
-
-
 @dataclass
 class ConfluencePageID:
     page_id: str
 
-    def __init__(self, page_id: str):
-        self.page_id = page_id
-
 
 @dataclass
 class ConfluenceQualifiedID:
     page_id: str
-    space_key: Optional[str] = None
-
-    def __init__(self, page_id: str, space_key: Optional[str] = None):
-        self.page_id = page_id
-        self.space_key = space_key
-
-
-def extract_qualified_id(text: str) -> tuple[Optional[ConfluenceQualifiedID], str]:
-    "Extracts the Confluence page ID and space key from a Markdown document."
-
-    page_id, text = extract_value(r"<!--\s+confluence-page-id:\s*(\d+)\s+-->", text)
-
-    if page_id is None:
-        return None, text
-
-    # extract Confluence space key
-    space_key, text = extract_value(r"<!--\s+confluence-space-key:\s*(\S+)\s+-->", text)
-
-    return ConfluenceQualifiedID(page_id, space_key), text
-
-
-def extract_frontmatter(text: str) -> tuple[Optional[str], str]:
-    "Extracts the front matter from a Markdown document."
-
-    return extract_value(r"(?ms)\A---$(.+?)^---$", text)
-
-
-def extract_frontmatter_title(text: str) -> tuple[Optional[str], str]:
-    frontmatter, text = extract_frontmatter(text)
-
-    title: Optional[str] = None
-    if frontmatter is not None:
-        properties = yaml.safe_load(frontmatter)
-        if isinstance(properties, dict):
-            property_title = properties.get("title")
-            if isinstance(property_title, str):
-                title = property_title
-
-    return title, text
-
-
-def read_qualified_id(absolute_path: Path) -> Optional[ConfluenceQualifiedID]:
-    "Reads the Confluence page ID and space key from a Markdown document."
-
-    with open(absolute_path, "r", encoding="utf-8") as f:
-        document = f.read()
-
-    qualified_id, _ = extract_qualified_id(document)
-    return qualified_id
+    space_key: str
 
 
 @dataclass
@@ -1055,7 +1005,6 @@ class ConversionError(RuntimeError):
 
 
 class ConfluenceDocument:
-    id: ConfluenceQualifiedID
     title: Optional[str]
     links: list[str]
     images: list[Path]
@@ -1071,63 +1020,47 @@ class ConfluenceDocument:
         root_dir: Path,
         site_metadata: ConfluenceSiteMetadata,
         page_metadata: dict[Path, ConfluencePageMetadata],
-    ) -> "ConfluenceDocument":
+    ) -> tuple[ConfluencePageID, "ConfluenceDocument"]:
         path = path.resolve(True)
 
-        with open(path, "r", encoding="utf-8") as f:
-            text = f.read()
+        document = Scanner().read(path)
 
-        # extract Confluence page ID
-        qualified_id, text = extract_qualified_id(text)
-        if qualified_id is None:
+        if document.page_id is not None:
+            page_id = ConfluencePageID(document.page_id)
+        else:
             # look up Confluence page ID in metadata
             metadata = page_metadata.get(path)
             if metadata is not None:
-                qualified_id = ConfluenceQualifiedID(
-                    metadata.page_id, metadata.space_key
-                )
-        if qualified_id is None:
-            raise PageError("missing Confluence page ID")
+                page_id = ConfluencePageID(metadata.page_id)
+            else:
+                raise PageError("missing Confluence page ID")
 
-        return ConfluenceDocument(
-            path, text, qualified_id, options, root_dir, site_metadata, page_metadata
+        return page_id, ConfluenceDocument(
+            path, document, options, root_dir, site_metadata, page_metadata
         )
 
     def __init__(
         self,
         path: Path,
-        text: str,
-        qualified_id: ConfluenceQualifiedID,
+        document: ScannedDocument,
         options: ConfluenceDocumentOptions,
         root_dir: Path,
         site_metadata: ConfluenceSiteMetadata,
         page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         self.options = options
-        self.id = qualified_id
-
-        # extract frontmatter
-        self.title, text = extract_frontmatter_title(text)
-
-        # extract 'generated-by' tag text
-        generated_by_tag, text = extract_value(
-            r"<!--\s+generated-by:\s*(.*)\s+-->", text
-        )
 
         # convert to HTML
-        html = markdown_to_html(text)
+        html = markdown_to_html(document.text)
 
         # parse Markdown document
         if self.options.generated_by is not None:
-            if generated_by_tag is not None:
-                generated_by_text = generated_by_tag
-            else:
-                generated_by_text = self.options.generated_by
+            generated_by = document.generated_by or self.options.generated_by
         else:
-            generated_by_text = None
+            generated_by = None
 
-        if generated_by_text is not None:
-            generated_by_html = markdown_to_html(generated_by_text)
+        if generated_by is not None:
+            generated_by_html = markdown_to_html(generated_by)
 
             content = [
                 '<ac:structured-macro ac:name="info" ac:schema-version="1">',
@@ -1161,8 +1094,7 @@ class ConfluenceDocument:
         self.images = converter.images
         self.embedded_images = converter.embedded_images
 
-        if self.title is None:
-            self.title = converter.toc.get_title()
+        self.title = document.title or converter.toc.get_title()
 
     def xhtml(self) -> str:
         return elements_to_string(self.root)

md2conf/local.py

@@ -12,16 +12,11 @@ import os
 from pathlib import Path
 from typing import Optional
 
-from .converter import (
-    ConfluenceDocument,
-    ConfluenceDocumentOptions,
-    ConfluencePageID,
-    ConfluenceQualifiedID,
-    extract_qualified_id,
-)
+from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
 from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
 from .processor import Converter, Processor, ProcessorFactory
 from .properties import PageError
+from .scanner import Scanner
 
 LOGGER = logging.getLogger(__name__)
 
@@ -52,41 +47,39 @@ class LocalProcessor(Processor):
         self.out_dir = out_dir or root_dir
 
     def _get_or_create_page(
-        self,
-        absolute_path: Path,
-        parent_id: Optional[ConfluencePageID],
-        *,
-        title: Optional[str] = None,
+        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
     ) -> ConfluencePageMetadata:
         """
         Extracts metadata from a Markdown file.
         """
 
         # parse file
-        with open(absolute_path, "r", encoding="utf-8") as f:
-            text = f.read()
-
-        qualified_id, text = extract_qualified_id(text)
-
-        if qualified_id is None:
+        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}"
                 )
 
-            hash = hashlib.md5(text.encode("utf-8"))
+            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)
-            qualified_id = ConfluenceQualifiedID(digest)
+            page_id = digest
+            space_key = self.site.space_key or "HOME"
 
         return ConfluencePageMetadata(
-            page_id=qualified_id.page_id,
-            space_key=qualified_id.space_key,
+            page_id=page_id,
+            space_key=space_key,
             title="",
             overwrite=True,
         )
 
-    def _save_document(self, document: ConfluenceDocument, path: Path) -> None:
+    def _save_document(
+        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
+    ) -> None:
         """
         Saves a new version of a Confluence document.
 

md2conf/matcher.py

@@ -10,15 +10,15 @@ import os.path
 from dataclasses import dataclass
 from fnmatch import fnmatch
 from pathlib import Path
-from typing import Iterable, Optional
+from typing import Iterable, Optional, Union, overload
 
 
-@dataclass
+@dataclass(frozen=True)
 class Entry:
     """
     Represents a file or directory entry.
 
-    :param name: Name of the file-system entry.
+    :param name: Name of the file-system entry to match against the rule-set.
     :param is_dir: True if the entry is a directory.
     """
 
@@ -43,6 +43,15 @@ class MatcherOptions:
             self.extension = f".{self.extension}"
 
 
+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")
+
+
 class Matcher:
     "Compares file and directory names against a list of exclude/include patterns."
 
@@ -58,20 +67,40 @@ class Matcher:
         else:
             self.rules = []
 
+        for rule in self.rules:
+            if "/" in rule or os.path.sep in rule:
+                raise ValueError(f"nested matching not supported: {rule}")
+
     def extension_matches(self, name: str) -> bool:
         "True if the file name has the expected extension."
 
         return self.options.extension is None or name.endswith(self.options.extension)
 
-    def is_excluded(self, name: str, is_dir: bool) -> bool:
+    @overload
+    def is_excluded(self, entry: Entry) -> bool:
+        """
+        True if the file or directory name matches any of the exclusion patterns.
+
+        :param entry: A data-class object.
+        :returns: True if the name matches at least one of the exclusion patterns.
+        """
+
+        ...
+
+    @overload
+    def is_excluded(self, entry: os.DirEntry[str]) -> bool:
         """
         True if the file or directory name matches any of the exclusion patterns.
 
-        :param name: Name to match against the rule-set.
-        :param is_dir: Whether the name identifies a directory.
+        :param entry: An object returned by `scandir`.
         :returns: True if the name matches at least one of the exclusion patterns.
         """
 
+        ...
+
+    def is_excluded(self, entry: Union[Entry, os.DirEntry[str]]) -> bool:
+        name, is_dir = _entry_name_dir(entry)
+
         # skip hidden files and directories
         if name.startswith("."):
             return True
@@ -86,26 +115,38 @@ class Matcher:
         else:
             return False
 
-    def is_included(self, name: str, is_dir: bool) -> bool:
+    @overload
+    def is_included(self, entry: Entry) -> bool:
+        """
+        True if the file or directory name matches none of the exclusion patterns.
+
+        :param entry: A data-class object.
+        :returns: True if the name doesn't match any of the exclusion patterns.
+        """
+        ...
+
+    @overload
+    def is_included(self, entry: os.DirEntry[str]) -> bool:
         """
         True if the file or directory name matches none of the exclusion patterns.
 
-        :param name: Name to match against the rule-set.
-        :param is_dir: Whether the name identifies a directory.
+        :param entry: An object returned by `scandir`.
         :returns: True if the name doesn't match any of the exclusion patterns.
         """
+        ...
 
-        return not self.is_excluded(name, is_dir)
+    def is_included(self, entry: Union[Entry, os.DirEntry[str]]) -> bool:
+        return not self.is_excluded(entry)
 
-    def filter(self, items: Iterable[Entry]) -> list[Entry]:
+    def filter(self, entries: Iterable[Entry]) -> list[Entry]:
         """
         Returns only those elements from the input that don't match any of the exclusion rules.
 
-        :param items: A list of names to filter.
+        :param entries: A list of names to filter.
         :returns: A filtered list of names that didn't match any of the exclusion rules.
         """
 
-        return [item for item in items if self.is_included(item.name, item.is_dir)]
+        return [entry for entry in entries if self.is_included(entry)]
 
     def scandir(self, path: Path) -> list[Entry]:
         """

md2conf/mermaid.py

@@ -79,10 +79,16 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") ->
         )
         stdout, stderr = proc.communicate(input=source.encode("utf-8"))
         if proc.returncode:
-            raise RuntimeError(
-                f"failed to convert Mermaid diagram; exit code: {proc.returncode}, "
-                f"output:\n{stdout.decode('utf-8')}\n{stderr.decode('utf-8')}"
-            )
+            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()
 

md2conf/metadata.py

@@ -37,6 +37,6 @@ class ConfluencePageMetadata:
     """
 
     page_id: str
-    space_key: Optional[str]
+    space_key: str
     title: str
     overwrite: bool

md2conf/processor.py

@@ -69,18 +69,14 @@ class Processor:
         self._process_page(path)
 
     def _process_page(self, path: Path) -> None:
-        document = ConfluenceDocument.create(
+        page_id, document = ConfluenceDocument.create(
             path, self.options, self.root_dir, self.site, self.page_metadata
         )
-        self._save_document(document, path)
+        self._save_document(page_id, document, path)
 
     @abstractmethod
     def _get_or_create_page(
-        self,
-        absolute_path: Path,
-        parent_id: Optional[ConfluencePageID],
-        *,
-        title: Optional[str] = None,
+        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
     ) -> ConfluencePageMetadata:
         """
         Creates a new Confluence page if no page is linked in the Markdown document.
@@ -88,7 +84,9 @@ class Processor:
         ...
 
     @abstractmethod
-    def _save_document(self, document: ConfluenceDocument, path: Path) -> None: ...
+    def _save_document(
+        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
+    ) -> None: ...
 
     def _index_directory(
         self, local_dir: Path, parent_id: Optional[ConfluencePageID]
@@ -104,7 +102,7 @@ class Processor:
         files: list[Path] = []
         directories: list[Path] = []
         for entry in os.scandir(local_dir):
-            if matcher.is_excluded(entry.name, entry.is_dir()):
+            if matcher.is_excluded(entry):
                 continue
 
             if entry.is_file():

md2conf/scanner.py

@@ -0,0 +1,117 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+
+def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
+    values: list[str] = []
+
+    def _repl_func(matchobj: re.Match) -> str:
+        values.append(matchobj.group(1))
+        return ""
+
+    text = re.sub(pattern, _repl_func, text, count=1, flags=re.ASCII)
+    value = values[0] if values else None
+    return value, text
+
+
+def extract_frontmatter_block(text: str) -> tuple[Optional[str], str]:
+    "Extracts the front-matter from a Markdown document as a blob of unparsed text."
+
+    return extract_value(r"(?ms)\A---$(.+?)^---$", text)
+
+
+def extract_frontmatter_properties(text: str) -> tuple[Optional[dict[str, Any]], str]:
+    "Extracts the front-matter from a Markdown document as a dictionary."
+
+    block, text = extract_frontmatter_block(text)
+
+    properties: Optional[dict[str, Any]] = None
+    if block is not None:
+        data = yaml.safe_load(block)
+        if isinstance(data, dict):
+            properties = data
+
+    return properties, text
+
+
+def get_string(properties: dict[str, Any], key: str) -> Optional[str]:
+    value = properties.get(key)
+    if value is None:
+        return None
+    elif not isinstance(value, str):
+        raise ValueError(
+            f"expected dictionary value type of `str` for key `{key}`; got value of type `{type(value).__name__}`"
+        )
+    else:
+        return value
+
+
+@dataclass
+class ScannedDocument:
+    """
+    An object that holds properties extracted from a Markdown document, including remaining source text.
+
+    :param page_id: Confluence page ID.
+    :param space_key: Confluence space key.
+    :param generated_by: Text identifying the tool that generated the document.
+    :param title: The title extracted from front-matter.
+    :param text: Text that remains after front-matter and inline properties have been extracted.
+    """
+
+    page_id: Optional[str]
+    space_key: Optional[str]
+    generated_by: Optional[str]
+    title: Optional[str]
+    text: str
+
+
+class Scanner:
+    def read(self, absolute_path: Path) -> ScannedDocument:
+        """
+        Extracts essential properties from a Markdown document.
+        """
+
+        # parse file
+        with open(absolute_path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        # extract Confluence page ID
+        page_id, text = extract_value(r"<!--\s+confluence-page-id:\s*(\d+)\s+-->", text)
+
+        # extract Confluence space key
+        space_key, text = extract_value(
+            r"<!--\s+confluence-space-key:\s*(\S+)\s+-->", text
+        )
+
+        # extract 'generated-by' tag text
+        generated_by, text = extract_value(r"<!--\s+generated-by:\s*(.*)\s+-->", text)
+
+        title: Optional[str] = None
+
+        # extract front-matter
+        properties, text = extract_frontmatter_properties(text)
+        if properties is not None:
+            page_id = page_id or get_string(properties, "confluence-page-id")
+            space_key = space_key or get_string(properties, "confluence-space-key")
+            generated_by = generated_by or get_string(properties, "generated-by")
+            title = get_string(properties, "title")
+
+        return ScannedDocument(
+            page_id=page_id,
+            space_key=space_key,
+            generated_by=generated_by,
+            title=title,
+            text=text,
+        )

markdown_to_confluence-0.3.4.dist-info/RECORD

@@ -1,22 +0,0 @@
-markdown_to_confluence-0.3.4.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-md2conf/__init__.py,sha256=9gI6OYCv9-54FzxjNHLOH09H5quUDEMWq9pdbhnwoXM,402
-md2conf/__main__.py,sha256=bFcfmSnTWeuhmDm7bJ3jJabZ2S8W9biuAP6_R-Cc9As,8034
-md2conf/api.py,sha256=ZIYoBXclLbzrrQ_oFRllsTEnQIMbxqd9OD80-AC5qM0,22769
-md2conf/application.py,sha256=eIVeAGUzfdIq1uYLYpTg30UNSq-YcUIY-OgKKK3M4E4,6436
-md2conf/converter.py,sha256=2Sgq1WQd-dCtrdTVrBwhowPC8PmubMNCH1aAcRwntjs,39404
-md2conf/emoji.py,sha256=48QJtOD0F3Be1laYLvAOwe0GxrJS-vcfjtCdiBsNcAc,1960
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/local.py,sha256=AOuwyvPOXrRRPGOTDeoVYkMPJ9MI2zqRGAvHuY35wy4,3884
-md2conf/matcher.py,sha256=FgMFPvGiOqGezCs8OyerfsVo-iIHFoI6LRMzdcjM5UY,3693
-md2conf/mermaid.py,sha256=un_KHBDpG5Zad_QD3HN1uBwUxp4I-HVJYhNKbH7KwcA,2312
-md2conf/metadata.py,sha256=9BtNRsICbKzPTs63P70XekNARePdW1DtdKNJqXh2ZFM,1013
-md2conf/processor.py,sha256=Ko_3WqLK6jM-bEN7OD9Vc3g3vhSjRYawz3fG6uoUsXc,6733
-md2conf/properties.py,sha256=TOCXLdTfYkKjRwZaMgvXw0mNCI4opEUwpBXro2Kv2B4,2467
-md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-markdown_to_confluence-0.3.4.dist-info/METADATA,sha256=PUtJXudDooVfwOzVtohxweWHMjgDv5CIrDvyqiJ0tlg,17745
-markdown_to_confluence-0.3.4.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-markdown_to_confluence-0.3.4.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.3.4.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.3.4.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.3.4.dist-info/RECORD,,