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

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

@@ -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.4 → markdown_to_confluence-0.3.5}/README.md

@@ -164,20 +164,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.4 → markdown_to_confluence-0.3.5}/markdown_to_confluence.egg-info/PKG-INFO

@@ -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.4 → markdown_to_confluence-0.3.5}/markdown_to_confluence.egg-info/SOURCES.txt

@@ -25,7 +25,9 @@ md2conf/processor.py
 md2conf/properties.py
 md2conf/puppeteer-config.json
 md2conf/py.typed
+md2conf/scanner.py
 tests/test_conversion.py
 tests/test_matcher.py
 tests/test_mermaid.py
-tests/test_processor.py
+tests/test_processor.py
+tests/test_scanner.py

markdown_to_confluence-0.3.5/markdown_to_confluence.egg-info/requires.txt

@@ -0,0 +1,9 @@
+lxml>=5.4
+types-lxml>=2025.3.30
+markdown>=3.8
+types-markdown>=3.8
+pymdown-extensions>=10.15
+PyYAML>=6.0
+types-PyYAML>=6.0
+requests>=2.32
+types-requests>=2.32

{markdown_to_confluence-0.3.4 → markdown_to_confluence-0.3.5}/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"

{markdown_to_confluence-0.3.4 → markdown_to_confluence-0.3.5}/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

{markdown_to_confluence-0.3.4 → markdown_to_confluence-0.3.5}/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__(