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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.3.1
+Version: 0.3.3
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -30,6 +30,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: types-requests>=2.32
+Dynamic: license-file
 
 # Publish Markdown files to Confluence wiki
 
@@ -166,7 +167,7 @@ The concepts above are illustrated in the following sections.
 
 #### File-system directory hierarchy
 
-The title of each Markdown file (either the text of the first heading (`#`), or the title specified in front-matter) is shown next to the file name.
+The title of each Markdown file (either the text of the topmost unique heading (`#`), or the title specified in front-matter) is shown next to the file name.
 
 ```
 .
@@ -197,12 +198,30 @@ root
         └── Mean vs. median
 ```
 
+### 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.
+
+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.
 
 Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
 
+### 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:
+
+1. The `title` attribute set in the [front-matter](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/). Front-matter is a block delimited by `---` at the beginning of a Markdown document. Currently, only YAML syntax is supported.
+2. The text of the topmost unique Markdown heading (`#`). For example, if a document has a single first-level heading (e.g. `# My document`), its text is used. However, if there are multiple first-level headings, this step is skipped.
+3. The file name (without the extension `.md`).
+
+If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
@@ -215,10 +234,8 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
-               [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY] [--no-generated-by]
-               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors]
-               [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
+usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--keep-hierarchy] [--generated-by GENERATED_BY] [--no-generated-by]
+               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
                mdpath
 
 positional arguments:
@@ -239,6 +256,7 @@ options:
   -l {debug,info,warning,error,critical}, --loglevel {debug,info,warning,error,critical}
                         Use this option to set the log verbosity.
   -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
+  --keep-hierarchy      Maintain source directory structure when exporting to Confluence.
   --generated-by GENERATED_BY
                         Add prompt to pages (default: 'This page has been generated with a tool.').
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.

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

@@ -133,7 +133,7 @@ The concepts above are illustrated in the following sections.
 
 #### File-system directory hierarchy
 
-The title of each Markdown file (either the text of the first heading (`#`), or the title specified in front-matter) is shown next to the file name.
+The title of each Markdown file (either the text of the topmost unique heading (`#`), or the title specified in front-matter) is shown next to the file name.
 
 ```
 .
@@ -164,12 +164,30 @@ root
         └── Mean vs. median
 ```
 
+### 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.
+
+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.
 
 Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
 
+### 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:
+
+1. The `title` attribute set in the [front-matter](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/). Front-matter is a block delimited by `---` at the beginning of a Markdown document. Currently, only YAML syntax is supported.
+2. The text of the topmost unique Markdown heading (`#`). For example, if a document has a single first-level heading (e.g. `# My document`), its text is used. However, if there are multiple first-level headings, this step is skipped.
+3. The file name (without the extension `.md`).
+
+If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
@@ -182,10 +200,8 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
-               [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY] [--no-generated-by]
-               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors]
-               [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
+usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--keep-hierarchy] [--generated-by GENERATED_BY] [--no-generated-by]
+               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
                mdpath
 
 positional arguments:
@@ -206,6 +222,7 @@ options:
   -l {debug,info,warning,error,critical}, --loglevel {debug,info,warning,error,critical}
                         Use this option to set the log verbosity.
   -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
+  --keep-hierarchy      Maintain source directory structure when exporting to Confluence.
   --generated-by GENERATED_BY
                         Add prompt to pages (default: 'This page has been generated with a tool.').
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.3.1
+Version: 0.3.3
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -30,6 +30,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: types-requests>=2.32
+Dynamic: license-file
 
 # Publish Markdown files to Confluence wiki
 
@@ -166,7 +167,7 @@ The concepts above are illustrated in the following sections.
 
 #### File-system directory hierarchy
 
-The title of each Markdown file (either the text of the first heading (`#`), or the title specified in front-matter) is shown next to the file name.
+The title of each Markdown file (either the text of the topmost unique heading (`#`), or the title specified in front-matter) is shown next to the file name.
 
 ```
 .
@@ -197,12 +198,30 @@ root
         └── Mean vs. median
 ```
 
+### 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.
+
+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.
 
 Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
 
+### 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:
+
+1. The `title` attribute set in the [front-matter](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/). Front-matter is a block delimited by `---` at the beginning of a Markdown document. Currently, only YAML syntax is supported.
+2. The text of the topmost unique Markdown heading (`#`). For example, if a document has a single first-level heading (e.g. `# My document`), its text is used. However, if there are multiple first-level headings, this step is skipped.
+3. The file name (without the extension `.md`).
+
+If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
@@ -215,10 +234,8 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
-               [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY] [--no-generated-by]
-               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors]
-               [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
+usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--keep-hierarchy] [--generated-by GENERATED_BY] [--no-generated-by]
+               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
                mdpath
 
 positional arguments:
@@ -239,6 +256,7 @@ options:
   -l {debug,info,warning,error,critical}, --loglevel {debug,info,warning,error,critical}
                         Use this option to set the log verbosity.
   -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
+  --keep-hierarchy      Maintain source directory structure when exporting to Confluence.
   --generated-by GENERATED_BY
                         Add prompt to pages (default: 'This page has been generated with a tool.').
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.

{markdown_to_confluence-0.3.1 → markdown_to_confluence-0.3.3}/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.1"
+__version__ = "0.3.3"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

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

@@ -22,18 +22,22 @@ import requests
 from . import __version__
 from .api import ConfluenceAPI
 from .application import Application
-from .converter import ConfluenceDocumentOptions
+from .converter import ConfluenceDocumentOptions, ConfluenceSiteMetadata
 from .processor import Processor
-from .properties import ConfluenceProperties
+from .properties import (
+    ArgumentError,
+    ConfluenceConnectionProperties,
+    ConfluenceSiteProperties,
+)
 
 
 class Arguments(argparse.Namespace):
     mdpath: Path
-    domain: str
-    path: str
-    username: str
-    apikey: str
-    space: str
+    domain: Optional[str]
+    path: Optional[str]
+    username: Optional[str]
+    apikey: Optional[str]
+    space: Optional[str]
     loglevel: str
     ignore_invalid_url: bool
     heading_anchors: bool
@@ -201,12 +205,33 @@ def main() -> None:
         diagram_output_format=args.diagram_output_format,
         webui_links=args.webui_links,
     )
-    properties = ConfluenceProperties(
-        args.domain, args.path, args.username, args.apikey, args.space, args.headers
-    )
     if args.local:
-        Processor(options, properties).process(args.mdpath)
+        try:
+            site_properties = ConfluenceSiteProperties(
+                domain=args.domain,
+                base_path=args.path,
+                space_key=args.space,
+            )
+        except ArgumentError as e:
+            parser.error(str(e))
+        site_metadata = ConfluenceSiteMetadata(
+            domain=site_properties.domain,
+            base_path=site_properties.base_path,
+            space_key=site_properties.space_key,
+        )
+        Processor(options, site_metadata).process(args.mdpath)
     else:
+        try:
+            properties = ConfluenceConnectionProperties(
+                args.domain,
+                args.path,
+                args.username,
+                args.apikey,
+                args.space,
+                args.headers,
+            )
+        except ArgumentError as e:
+            parser.error(str(e))
         try:
             with ConfluenceAPI(properties) as api:
                 Application(

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

@@ -21,7 +21,12 @@ from urllib.parse import urlencode, urlparse, urlunparse
 import requests
 
 from .converter import ParseError, sanitize_confluence
-from .properties import ConfluenceError, ConfluenceProperties
+from .properties import (
+    ArgumentError,
+    ConfluenceConnectionProperties,
+    ConfluenceError,
+    PageError,
+)
 
 # a JSON type with possible `null` values
 JsonType = Union[
@@ -40,6 +45,18 @@ class ConfluenceVersion(enum.Enum):
     VERSION_2 = "api/v2"
 
 
+class ConfluencePageParentContentType(enum.Enum):
+    """
+    Content types that can be a parent to a Confluence page
+    """
+
+    PAGE = "page"
+    WHITEBOARD = "whiteboard"
+    DATABASE = "database"
+    EMBED = "embed"
+    FOLDER = "folder"
+
+
 def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
     "Builds a URL with scheme, host, port, path and query string parameters."
 
@@ -71,17 +88,21 @@ class ConfluenceAttachment:
 class ConfluencePage:
     id: str
     space_id: str
+    parent_id: str
+    parent_type: Optional[ConfluencePageParentContentType]
     title: str
     version: int
     content: str
 
 
 class ConfluenceAPI:
-    properties: ConfluenceProperties
+    properties: ConfluenceConnectionProperties
     session: Optional["ConfluenceSession"] = None
 
-    def __init__(self, properties: Optional[ConfluenceProperties] = None) -> None:
-        self.properties = properties or ConfluenceProperties()
+    def __init__(
+        self, properties: Optional[ConfluenceConnectionProperties] = None
+    ) -> None:
+        self.properties = properties or ConfluenceConnectionProperties()
 
     def __enter__(self) -> "ConfluenceSession":
         session = requests.Session()
@@ -128,7 +149,7 @@ class ConfluenceSession:
         session: requests.Session,
         domain: str,
         base_path: str,
-        space_key: Optional[str],
+        space_key: Optional[str] = None,
     ) -> None:
         self.session = session
         self.domain = domain
@@ -170,11 +191,9 @@ class ConfluenceSession:
 
         url = self._build_url(version, path, query)
         response = self.session.get(url)
-        response.raise_for_status()
-        if len(response.text) > 240:
-            LOGGER.debug("Received HTTP payload (truncated):\n%.240s...", response.text)
-        else:
+        if response.text:
             LOGGER.debug("Received HTTP payload:\n%s", response.text)
+        response.raise_for_status()
         return response.json()
 
     def _save(self, version: ConfluenceVersion, path: str, data: dict) -> None:
@@ -184,6 +203,8 @@ class ConfluenceSession:
             data=json.dumps(data),
             headers={"Content-Type": "application/json"},
         )
+        if response.text:
+            LOGGER.debug("Received HTTP payload:\n%s", response.text)
         response.raise_for_status()
 
     def space_id_to_key(self, id: str) -> str:
@@ -194,7 +215,7 @@ class ConfluenceSession:
             payload = self._invoke(
                 ConfluenceVersion.VERSION_2,
                 "/spaces",
-                {"ids": id, "type": "global", "status": "current"},
+                {"ids": id, "status": "current"},
             )
             payload = typing.cast(dict[str, JsonType], payload)
             results = typing.cast(list[JsonType], payload["results"])
@@ -216,7 +237,7 @@ class ConfluenceSession:
             payload = self._invoke(
                 ConfluenceVersion.VERSION_2,
                 "/spaces",
-                {"keys": key, "type": "global", "status": "current"},
+                {"keys": key, "status": "current"},
             )
             payload = typing.cast(dict[str, JsonType], payload)
             results = typing.cast(list[JsonType], payload["results"])
@@ -261,12 +282,11 @@ class ConfluenceSession:
         comment: Optional[str] = None,
         force: bool = False,
     ) -> None:
-
         if attachment_path is None and raw_data is None:
-            raise ConfluenceError("required: `attachment_path` or `raw_data`")
+            raise ArgumentError("required: `attachment_path` or `raw_data`")
 
         if attachment_path is not None and raw_data is not None:
-            raise ConfluenceError("expected: either `attachment_path` or `raw_data`")
+            raise ArgumentError("expected: either `attachment_path` or `raw_data`")
 
         if content_type is None:
             if attachment_path is not None:
@@ -276,7 +296,7 @@ class ConfluenceSession:
             content_type, _ = mimetypes.guess_type(name, strict=True)
 
         if attachment_path is not None and not attachment_path.is_file():
-            raise ConfluenceError(f"file not found: {attachment_path}")
+            raise PageError(f"file not found: {attachment_path}")
 
         try:
             attachment = self.get_attachment_by_name(page_id, attachment_name)
@@ -422,6 +442,12 @@ class ConfluenceSession:
         return ConfluencePage(
             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"]),
             content=typing.cast(str, storage["value"]),
@@ -493,9 +519,7 @@ class ConfluenceSession:
 
         coalesced_space_key = space_key or self.space_key
         if coalesced_space_key is None:
-            raise ConfluenceError(
-                "Confluence space key required for creating a new page"
-            )
+            raise ArgumentError("Confluence space key required for creating a new page")
 
         path = "/pages/"
         query = {
@@ -524,6 +548,12 @@ class ConfluenceSession:
         return ConfluencePage(
             id=typing.cast(str, data["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"]),
             content=typing.cast(str, storage["value"]),

{markdown_to_confluence-0.3.1 → markdown_to_confluence-0.3.3}/md2conf/application.py

@@ -6,8 +6,9 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
+import hashlib
 import logging
-import os.path
+import os
 from pathlib import Path
 from typing import Optional
 
@@ -17,12 +18,14 @@ from .converter import (
     ConfluenceDocumentOptions,
     ConfluencePageMetadata,
     ConfluenceQualifiedID,
+    ConfluenceSiteMetadata,
     attachment_name,
     extract_frontmatter_title,
     extract_qualified_id,
     read_qualified_id,
 )
 from .matcher import Matcher, MatcherOptions
+from .properties import ArgumentError, PageError
 
 LOGGER = logging.getLogger(__name__)
 
@@ -48,7 +51,7 @@ class Application:
         elif path.is_file():
             self.synchronize_page(path)
         else:
-            raise ValueError(f"expected: valid file or directory path; got: {path}")
+            raise ArgumentError(f"expected: valid file or directory path; got: {path}")
 
     def synchronize_page(
         self, page_path: Path, root_dir: Optional[Path] = None
@@ -83,7 +86,7 @@ class Application:
             if self.options.root_page_id
             else None
         )
-        self._index_directory(local_dir, root_id, page_metadata)
+        self._index_directory(local_dir, root_dir, root_id, page_metadata)
         LOGGER.info("Indexed %d page(s)", len(page_metadata))
 
         # Step 2: convert each page
@@ -99,12 +102,21 @@ class Application:
         base_path = page_path.parent
 
         LOGGER.info("Synchronizing page: %s", page_path)
-        document = ConfluenceDocument(page_path, self.options, root_dir, page_metadata)
+        site_metadata = ConfluenceSiteMetadata(
+            domain=self.api.domain,
+            base_path=self.api.base_path,
+            space_key=self.api.space_key,
+        )
+
+        document = ConfluenceDocument.create(
+            page_path, self.options, root_dir, site_metadata, page_metadata
+        )
         self._update_document(document, base_path)
 
     def _index_directory(
         self,
         local_dir: Path,
+        root_dir: Path,
         root_id: Optional[ConfluenceQualifiedID],
         page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
@@ -144,7 +156,7 @@ class Application:
         if parent_doc is not None:
             files.remove(parent_doc)
 
-            metadata = self._get_or_create_page(parent_doc, root_id)
+            metadata = self._get_or_create_page(parent_doc, root_dir, root_id)
             LOGGER.debug("Indexed parent %s with metadata: %s", parent_doc, metadata)
             page_metadata[parent_doc] = metadata
 
@@ -153,16 +165,17 @@ class Application:
             parent_id = root_id
 
         for doc in files:
-            metadata = self._get_or_create_page(doc, parent_id)
+            metadata = self._get_or_create_page(doc, root_dir, parent_id)
             LOGGER.debug("Indexed %s with metadata: %s", doc, metadata)
             page_metadata[doc] = metadata
 
         for directory in directories:
-            self._index_directory(directory, parent_id, page_metadata)
+            self._index_directory(directory, root_dir, parent_id, page_metadata)
 
     def _get_or_create_page(
         self,
         absolute_path: Path,
+        root_dir: Path,
         parent_id: Optional[ConfluenceQualifiedID],
         *,
         title: Optional[str] = None,
@@ -176,19 +189,28 @@ class Application:
             document = f.read()
 
         qualified_id, document = extract_qualified_id(document)
-        frontmatter_title, _ = extract_frontmatter_title(document)
 
         if qualified_id is not None:
             confluence_page = self.api.get_page(qualified_id.page_id)
         else:
             if parent_id is None:
-                raise ValueError(
+                raise PageError(
                     f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
                 )
 
-            # assign title from frontmatter if present
+            # assign title from front-matter if present
+            if title is None:
+                title, _ = extract_frontmatter_title(document)
+
+            # use file name (without extension) and path hash if no title is supplied
+            if title is None:
+                relative_path = absolute_path.relative_to(root_dir)
+                hash = hashlib.md5(relative_path.as_posix().encode("utf-8"))
+                digest = "".join(f"{c:x}" for c in hash.digest())
+                title = f"{absolute_path.stem} [{digest}]"
+
             confluence_page = self._create_page(
-                absolute_path, document, title or frontmatter_title, parent_id
+                absolute_path, document, title, parent_id
             )
 
         space_key = (
@@ -198,8 +220,6 @@ class Application:
         )
 
         return ConfluencePageMetadata(
-            domain=self.api.domain,
-            base_path=self.api.base_path,
             page_id=confluence_page.id,
             space_key=space_key,
             title=confluence_page.title or "",
@@ -209,15 +229,11 @@ class Application:
         self,
         absolute_path: Path,
         document: str,
-        title: Optional[str],
+        title: str,
         parent_id: ConfluenceQualifiedID,
     ) -> ConfluencePage:
         "Creates a new Confluence page when Markdown file doesn't have an embedded page ID yet."
 
-        # use file name without extension if no title is supplied
-        if title is None:
-            title = absolute_path.stem
-
         confluence_page = self.api.get_or_create_page(
             title, parent_id.page_id, space_key=parent_id.space_key
         )