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

md2conf/application.py

@@ -10,14 +10,9 @@ import logging
 from pathlib import Path
 from typing import Optional
 
-from .api import ConfluenceLabel, ConfluenceSession
-from .converter import (
-    ConfluenceDocument,
-    ConfluenceDocumentOptions,
-    ConfluencePageID,
-    attachment_name,
-)
-from .extra import override
+from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
+from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID, attachment_name
+from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 from .properties import PageError
@@ -32,9 +27,7 @@ class SynchronizingProcessor(Processor):
 
     api: ConfluenceSession
 
-    def __init__(
-        self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path
-    ) -> None:
+    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path) -> None:
         """
         Initializes a new processor instance.
 
@@ -47,9 +40,7 @@ class SynchronizingProcessor(Processor):
         self.api = api
 
     @override
-    def _synchronize_tree(
-        self, root: DocumentNode, root_id: Optional[ConfluencePageID]
-    ) -> None:
+    def _synchronize_tree(self, root: DocumentNode, root_id: Optional[ConfluencePageID]) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 
@@ -59,14 +50,10 @@ class SynchronizingProcessor(Processor):
         """
 
         if root.page_id is None and root_id is None:
-            raise PageError(
-                f"expected: root page ID in options, or explicit page ID in {root.absolute_path}"
-            )
+            raise PageError(f"expected: root page ID in options, or explicit page ID in {root.absolute_path}")
         elif root.page_id is not None and root_id is not None:
             if root.page_id != root_id.page_id:
-                raise PageError(
-                    f"mismatched inferred page ID of {root_id.page_id} and explicit page ID in {root.absolute_path}"
-                )
+                raise PageError(f"mismatched inferred page ID of {root_id.page_id} and explicit page ID in {root.absolute_path}")
 
             real_id = root_id
         elif root_id is not None:
@@ -78,9 +65,7 @@ class SynchronizingProcessor(Processor):
 
         self._synchronize_subtree(root, real_id)
 
-    def _synchronize_subtree(
-        self, node: DocumentNode, parent_id: ConfluencePageID
-    ) -> None:
+    def _synchronize_subtree(self, node: DocumentNode, parent_id: ConfluencePageID) -> None:
         if node.page_id is not None:
             # verify if page exists
             page = self.api.get_page_properties(node.page_id)
@@ -88,6 +73,10 @@ class SynchronizingProcessor(Processor):
         elif node.title is not None:
             # look up page by title
             page = self.api.get_or_create_page(node.title, parent_id.page_id)
+
+            if page.status is ConfluenceStatus.ARCHIVED:
+                raise PageError(f"unable to update archived page with ID {page.id}")
+
             update = True
         else:
             # always create a new page
@@ -115,9 +104,7 @@ class SynchronizingProcessor(Processor):
             self._synchronize_subtree(child_node, ConfluencePageID(page.id))
 
     @override
-    def _update_page(
-        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
-    ) -> None:
+    def _update_page(self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path) -> None:
         """
         Saves a new version of a Confluence document.
 
@@ -125,11 +112,11 @@ class SynchronizingProcessor(Processor):
         """
 
         base_path = path.parent
-        for image in document.images:
+        for image_path in document.images:
             self.api.upload_attachment(
                 page_id.page_id,
-                attachment_name(image),
-                attachment_path=base_path / image,
+                attachment_name(path_relative_to(image_path, base_path)),
+                attachment_path=image_path,
             )
 
         for name, data in document.embedded_images.items():
@@ -145,14 +132,8 @@ class SynchronizingProcessor(Processor):
         title = None
         if document.title is not None:
             meta = self.page_metadata.get(path)
-            if (
-                meta is not None
-                and meta.space_key is not None
-                and meta.title != document.title
-            ):
-                conflicting_page_id = self.api.page_exists(
-                    document.title, space_id=self.api.space_key_to_id(meta.space_key)
-                )
+            if meta is not None and meta.space_key is not None and meta.title != document.title:
+                conflicting_page_id = self.api.page_exists(document.title, space_id=self.api.space_key_to_id(meta.space_key))
                 if conflicting_page_id is None:
                     title = document.title
                 else:
@@ -167,12 +148,12 @@ class SynchronizingProcessor(Processor):
         if document.labels is not None:
             self.api.update_labels(
                 page_id.page_id,
-                [
-                    ConfluenceLabel(name=label, prefix="global")
-                    for label in document.labels
-                ],
+                [ConfluenceLabel(name=label, prefix="global") for label in document.labels],
             )
 
+        if document.properties is not None:
+            self.api.update_content_properties_for_page(page_id.page_id, [ConfluenceContentProperty(key, value) for key, value in document.properties.items()])
+
     def _update_markdown(self, path: Path, *, page_id: str, space_key: str) -> None:
         """
         Writes the Confluence page ID and space key at the beginning of the Markdown file.
@@ -202,9 +183,7 @@ class SynchronizingProcessor(Processor):
 class SynchronizingProcessorFactory(ProcessorFactory):
     api: ConfluenceSession
 
-    def __init__(
-        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
-    ) -> None:
+    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions) -> None:
         super().__init__(options, api.site)
         self.api = api
 
@@ -219,7 +198,5 @@ class Application(Converter):
     This is the class instantiated by the command-line application.
     """
 
-    def __init__(
-        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
-    ) -> None:
+    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions) -> None:
         super().__init__(SynchronizingProcessorFactory(api, options))

md2conf/converter.py

@@ -23,8 +23,10 @@ from urllib.parse import ParseResult, quote_plus, urlparse, urlunparse
 import lxml.etree as ET
 import markdown
 from lxml.builder import ElementMaker
+from strong_typing.core import JsonType
 
 from .collection import ConfluencePageCollection
+from .extra import path_relative_to
 from .mermaid import render_diagram
 from .metadata import ConfluenceSiteMetadata
 from .properties import PageError
@@ -67,6 +69,12 @@ def is_relative_url(url: str) -> bool:
     return not bool(urlparts.scheme) and not bool(urlparts.netloc)
 
 
+def is_directory_within(absolute_path: Path, base_path: Path) -> bool:
+    "True if the absolute path is nested within the base path."
+
+    return absolute_path.as_posix().startswith(base_path.as_posix())
+
+
 def encode_title(text: str) -> str:
     "Converts a title string such that it is safe to embed into a Confluence URL."
 
@@ -145,14 +153,11 @@ def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
         load_dtd=True,
     )
 
-    ns_attr_list = "".join(
-        f' xmlns:{key}="{value}"' for key, value in namespaces.items()
-    )
+    ns_attr_list = "".join(f' xmlns:{key}="{value}"' for key, value in namespaces.items())
 
     data = [
         '<?xml version="1.0"?>',
-        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}">'
-        f"<root{ns_attr_list}>",
+        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}"><root{ns_attr_list}>',
     ]
     data.extend(items)
     data.append("</root>")
@@ -376,6 +381,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         page_metadata: ConfluencePageCollection,
     ) -> None:
         super().__init__()
+
+        path = path.resolve(True)
+        root_dir = root_dir.resolve(True)
+
         self.options = options
         self.path = path
         self.base_dir = path.parent
@@ -409,6 +418,14 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         anchor.tail = heading.text
         heading.text = None
 
+    def _warn_or_raise(self, msg: str) -> None:
+        "Emit a warning or raise an exception when a path points to a resource that doesn't exist."
+
+        if self.options.ignore_invalid_url:
+            LOGGER.warning(msg)
+        else:
+            raise DocumentError(msg)
+
     def _transform_link(self, anchor: ET._Element) -> Optional[ET._Element]:
         url = anchor.attrib.get("href")
         if url is None or is_absolute_url(url):
@@ -417,13 +434,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         LOGGER.debug("Found link %s relative to %s", url, self.path)
         relative_url: ParseResult = urlparse(url)
 
-        if (
-            not relative_url.scheme
-            and not relative_url.netloc
-            and not relative_url.path
-            and not relative_url.params
-            and not relative_url.query
-        ):
+        if not relative_url.scheme and not relative_url.netloc and not relative_url.path and not relative_url.params and not relative_url.query:
             LOGGER.debug("Found local URL: %s", url)
             if self.options.heading_anchors:
                 # <ac:link ac:anchor="anchor"><ac:link-body>...</ac:link-body></ac:link>
@@ -446,15 +457,11 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         # convert the relative URL to absolute URL based on the base path value, then look up
         # the absolute path in the page metadata dictionary to discover the relative path
         # within Confluence that should be used
-        absolute_path = (self.base_dir / relative_url.path).resolve(True)
-        if not str(absolute_path).startswith(str(self.root_dir)):
-            msg = f"relative URL {url} points to outside root path: {self.root_dir}"
-            if self.options.ignore_invalid_url:
-                LOGGER.warning(msg)
-                anchor.attrib.pop("href")
-                return None
-            else:
-                raise DocumentError(msg)
+        absolute_path = (self.base_dir / relative_url.path).resolve()
+        if not is_directory_within(absolute_path, self.root_dir):
+            anchor.attrib.pop("href")
+            self._warn_or_raise(f"relative URL {url} points to outside root path: {self.root_dir}")
+            return None
 
         link_metadata = self.page_metadata.get(absolute_path)
         if link_metadata is None:
@@ -467,9 +474,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 raise DocumentError(msg)
 
         relative_path = os.path.relpath(absolute_path, self.base_dir)
-        LOGGER.debug(
-            "found link to page %s with metadata: %s", relative_path, link_metadata
-        )
+        LOGGER.debug("found link to page %s with metadata: %s", relative_path, link_metadata)
         self.links.append(url)
 
         if self.options.webui_links:
@@ -478,9 +483,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             space_key = link_metadata.space_key or self.site_metadata.space_key
 
             if space_key is None:
-                raise DocumentError(
-                    "Confluence space key required for building full web URLs"
-                )
+                raise DocumentError("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}/{encode_title(link_metadata.title)}"
 
@@ -522,9 +525,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         else:
             return self._transform_attached_image(Path(src), caption, attributes)
 
-    def _transform_external_image(
-        self, url: str, caption: Optional[str], attributes: dict[str, Any]
-    ) -> ET._Element:
+    def _transform_external_image(self, url: str, caption: Optional[str], attributes: dict[str, Any]) -> ET._Element:
         "Emits Confluence Storage Format XHTML for an external image."
 
         elements: list[ET._Element] = []
@@ -540,18 +541,28 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         return AC("image", attributes, *elements)
 
-    def _transform_attached_image(
-        self, path: Path, caption: Optional[str], attributes: dict[str, Any]
-    ) -> ET._Element:
+    def _transform_attached_image(self, path: Path, caption: Optional[str], attributes: dict[str, Any]) -> ET._Element:
         "Emits Confluence Storage Format XHTML for an attached image."
 
-        # prefer PNG over SVG; Confluence displays SVG in wrong size, and text labels are truncated
-        png_file = path.with_suffix(".png")
-        if path.suffix == ".svg" and (self.base_dir / png_file).exists():
-            path = png_file
+        # resolve relative path into absolute path w.r.t. base dir
+        absolute_path = (self.base_dir / path).resolve()
+
+        if absolute_path.exists():
+            # prefer PNG over SVG; Confluence displays SVG in wrong size, and text labels are truncated
+            if absolute_path.suffix == ".svg":
+                png_file = absolute_path.with_suffix(".png")
+                if png_file.exists():
+                    absolute_path = png_file
 
-        self.images.append(path)
-        image_name = attachment_name(path)
+            if is_directory_within(absolute_path, self.root_dir):
+                self.images.append(absolute_path)
+                image_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
+            else:
+                image_name = ""
+                self._warn_or_raise(f"path to image {path} points to outside root path {self.root_dir}")
+        else:
+            image_name = ""
+            self._warn_or_raise(f"path to image {path} does not exist")
 
         elements: list[ET._Element] = []
         elements.append(
@@ -607,9 +618,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if self.options.render_mermaid:
             image_data = render_diagram(content, self.options.diagram_output_format)
             image_hash = hashlib.md5(image_data).hexdigest()
-            image_filename = attachment_name(
-                f"embedded_{image_hash}.{self.options.diagram_output_format}"
-            )
+            image_filename = attachment_name(f"embedded_{image_hash}.{self.options.diagram_output_format}")
             self.embedded_images[image_filename] = image_data
             return AC(
                 "image",
@@ -769,9 +778,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         return self._transform_alert(elem, class_name, skip)
 
-    def _transform_alert(
-        self, elem: ET._Element, class_name: Optional[str], skip: int
-    ) -> ET._Element:
+    def _transform_alert(self, elem: ET._Element, class_name: Optional[str], skip: int) -> ET._Element:
         """
         Creates an info, tip, note or warning panel from a GitHub or GitLab alert.
 
@@ -806,14 +813,12 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         Creates a collapsed section.
 
         Transforms
-        [GitHub collapsed section](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)  # noqa: E501 # no way to make this link shorter
+        [GitHub collapsed section](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
         syntax into the Confluence structured macro *expand*.
         """
 
         if elem[0].tag != "summary":
-            raise DocumentError(
-                "expected: `<summary>` as first direct child of `<details>`"
-            )
+            raise DocumentError("expected: `<summary>` as first direct child of `<details>`")
         if elem[0].tail is not None:
             raise DocumentError('expected: attribute `markdown="1"` on `<details>`')
 
@@ -905,13 +910,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         # <blockquote>
         #   <p>[!TIP] ...</p>
         # </blockquote>
-        elif (
-            child.tag == "blockquote"
-            and len(child) > 0
-            and child[0].tag == "p"
-            and child[0].text is not None
-            and child[0].text.startswith("[!")
-        ):
+        elif child.tag == "blockquote" and len(child) > 0 and child[0].tag == "p" and child[0].text is not None and child[0].text.startswith("[!"):
             return self._transform_github_alert(child)
 
         # Alerts in GitLab
@@ -923,9 +922,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             and len(child) > 0
             and child[0].tag == "p"
             and child[0].text is not None
-            and starts_with_any(
-                child[0].text, ["FLAG:", "NOTE:", "WARNING:", "DISCLAIMER:"]
-            )
+            and starts_with_any(child[0].text, ["FLAG:", "NOTE:", "WARNING:", "DISCLAIMER:"])
         ):
             return self._transform_gitlab_alert(child)
 
@@ -1012,6 +1009,7 @@ class ConversionError(RuntimeError):
 class ConfluenceDocument:
     title: Optional[str]
     labels: Optional[list[str]]
+    properties: Optional[dict[str, JsonType]]
     links: list[str]
     images: list[Path]
 
@@ -1041,9 +1039,7 @@ class ConfluenceDocument:
             else:
                 raise PageError("missing Confluence page ID")
 
-        return page_id, ConfluenceDocument(
-            path, document, options, root_dir, site_metadata, page_metadata
-        )
+        return page_id, ConfluenceDocument(path, document, options, root_dir, site_metadata, page_metadata)
 
     def __init__(
         self,
@@ -1102,21 +1098,42 @@ class ConfluenceDocument:
 
         self.title = document.title or converter.toc.get_title()
         self.labels = document.tags
+        self.properties = document.properties
 
     def xhtml(self) -> str:
         return elements_to_string(self.root)
 
 
-def attachment_name(name: Union[Path, str]) -> str:
+def attachment_name(ref: Union[Path, str]) -> str:
     """
     Safe name for use with attachment uploads.
 
+    Mutates a relative path such that it meets Confluence's attachment naming requirements.
+
     Allowed characters:
+
     * Alphanumeric characters: 0-9, a-z, A-Z
     * Special characters: hyphen (-), underscore (_), period (.)
     """
 
-    return re.sub(r"[^\-0-9A-Za-z_.]", "_", str(name))
+    if isinstance(ref, Path):
+        path = ref
+    else:
+        path = Path(ref)
+
+    if path.drive or path.root:
+        raise ValueError(f"required: relative path; got: {ref}")
+
+    regexp = re.compile(r"[^\-0-9A-Za-z_.]", re.UNICODE)
+
+    def replace_part(part: str) -> str:
+        if part == "..":
+            return "PAR"
+        else:
+            return regexp.sub("_", part)
+
+    parts = [replace_part(p) for p in path.parts]
+    return Path(*parts).as_posix().replace("/", "_")
 
 
 def sanitize_confluence(html: str) -> str:
@@ -1147,14 +1164,11 @@ def _content_to_string(dtd_path: Path, content: str) -> str:
         load_dtd=True,
     )
 
-    ns_attr_list = "".join(
-        f' xmlns:{key}="{value}"' for key, value in namespaces.items()
-    )
+    ns_attr_list = "".join(f' xmlns:{key}="{value}"' for key, value in namespaces.items())
 
     data = [
         '<?xml version="1.0"?>',
-        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}">'
-        f"<root{ns_attr_list}>",
+        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}"><root{ns_attr_list}>',
     ]
     data.append(content)
     data.append("</root>")

md2conf/extra.py

@@ -12,3 +12,16 @@ if sys.version_info >= (3, 12):
     from typing import override as override  # noqa: F401
 else:
     from typing_extensions import override as override  # noqa: F401
+
+if sys.version_info >= (3, 12):
+    from pathlib import Path
+
+    def path_relative_to(destination: Path, origin: Path) -> Path:
+        return destination.relative_to(origin, walk_up=True)
+
+else:
+    import os.path
+    from pathlib import Path
+
+    def path_relative_to(destination: Path, origin: Path) -> Path:
+        return Path(os.path.relpath(destination, start=origin))

md2conf/local.py

@@ -45,9 +45,7 @@ class LocalProcessor(Processor):
         self.out_dir = out_dir or root_dir
 
     @override
-    def _synchronize_tree(
-        self, root: DocumentNode, root_id: Optional[ConfluencePageID]
-    ) -> None:
+    def _synchronize_tree(self, root: DocumentNode, root_id: Optional[ConfluencePageID]) -> None:
         """
         Creates the cross-reference index.
 
@@ -59,9 +57,7 @@ class LocalProcessor(Processor):
                 page_id = node.page_id
             else:
                 digest = self._generate_hash(node.absolute_path)
-                LOGGER.info(
-                    "Identifier %s assigned to page: %s", digest, node.absolute_path
-                )
+                LOGGER.info("Identifier %s assigned to page: %s", digest, node.absolute_path)
                 page_id = digest
 
             self.page_metadata.add(
@@ -74,9 +70,7 @@ class LocalProcessor(Processor):
             )
 
     @override
-    def _update_page(
-        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
-    ) -> None:
+    def _update_page(self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path) -> None:
         """
         Saves the document as Confluence Storage Format XHTML to the local disk.
         """
@@ -101,9 +95,7 @@ class LocalProcessorFactory(ProcessorFactory):
         self.out_dir = out_dir
 
     def create(self, root_dir: Path) -> Processor:
-        return LocalProcessor(
-            self.options, self.site, out_dir=self.out_dir, root_dir=root_dir
-        )
+        return LocalProcessor(self.options, self.site, out_dir=self.out_dir, root_dir=root_dir)
 
 
 class LocalConverter(Converter):

md2conf/matcher.py

@@ -156,6 +156,4 @@ class Matcher:
         :returns: A filtered list of entries whose name didn't match any of the exclusion rules.
         """
 
-        return self.filter(
-            Entry(entry.name, entry.is_dir()) for entry in os.scandir(path)
-        )
+        return self.filter(Entry(entry.name, entry.is_dir()) for entry in os.scandir(path))

md2conf/mermaid.py

@@ -19,10 +19,7 @@ LOGGER = logging.getLogger(__name__)
 def is_docker() -> bool:
     "True if the application is running in a Docker container."
 
-    return (
-        os.environ.get("CHROME_BIN") == "/usr/bin/chromium-browser"
-        and os.environ.get("PUPPETEER_SKIP_DOWNLOAD") == "true"
-    )
+    return os.environ.get("CHROME_BIN") == "/usr/bin/chromium-browser" and os.environ.get("PUPPETEER_SKIP_DOWNLOAD") == "true"
 
 
 def get_mmdc() -> str:
@@ -79,9 +76,7 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") ->
         )
         stdout, stderr = proc.communicate(input=source.encode("utf-8"))
         if proc.returncode:
-            messages = [
-                f"failed to convert Mermaid diagram; exit code: {proc.returncode}"
-            ]
+            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}")

md2conf/processor.py

@@ -131,15 +131,11 @@ class Processor:
         Synchronizes a single Markdown document with its corresponding Confluence page.
         """
 
-        page_id, document = ConfluenceDocument.create(
-            path, self.options, self.root_dir, self.site, self.page_metadata
-        )
+        page_id, document = ConfluenceDocument.create(path, self.options, self.root_dir, self.site, self.page_metadata)
         self._update_page(page_id, document, path)
 
     @abstractmethod
-    def _synchronize_tree(
-        self, node: DocumentNode, page_id: Optional[ConfluencePageID]
-    ) -> None:
+    def _synchronize_tree(self, node: DocumentNode, page_id: Optional[ConfluencePageID]) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 
@@ -150,17 +146,13 @@ class Processor:
         ...
 
     @abstractmethod
-    def _update_page(
-        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
-    ) -> None:
+    def _update_page(self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path) -> None:
         """
         Saves the document as Confluence Storage Format XHTML.
         """
         ...
 
-    def _index_directory(
-        self, local_dir: Path, parent: Optional[DocumentNode]
-    ) -> DocumentNode:
+    def _index_directory(self, local_dir: Path, parent: Optional[DocumentNode]) -> DocumentNode:
         """
         Indexes Markdown files in a directory hierarchy recursively.
         """
@@ -176,21 +168,21 @@ class Processor:
                 continue
 
             if entry.is_file():
-                files.append(Path(local_dir) / entry.name)
+                files.append(local_dir / entry.name)
             elif entry.is_dir():
-                directories.append(Path(local_dir) / entry.name)
+                directories.append(local_dir / entry.name)
 
         # make page act as parent node
         parent_doc: Optional[Path] = None
-        if (Path(local_dir) / "index.md") in files:
-            parent_doc = Path(local_dir) / "index.md"
-        elif (Path(local_dir) / "README.md") in files:
-            parent_doc = Path(local_dir) / "README.md"
-        elif (Path(local_dir) / f"{local_dir.name}.md") in files:
-            parent_doc = Path(local_dir) / f"{local_dir.name}.md"
+        if (local_dir / "index.md") in files:
+            parent_doc = local_dir / "index.md"
+        elif (local_dir / "README.md") in files:
+            parent_doc = local_dir / "README.md"
+        elif (local_dir / f"{local_dir.name}.md") in files:
+            parent_doc = local_dir / f"{local_dir.name}.md"
 
         if parent_doc is None and self.options.keep_hierarchy:
-            parent_doc = Path(local_dir) / "index.md"
+            parent_doc = local_dir / "index.md"
 
             # create a blank page for directory entry
             with open(parent_doc, "w"):
@@ -206,13 +198,7 @@ class Processor:
                 parent.add_child(node)
             parent = node
         elif parent is None:
-            # create new top-level node
-            if self.options.root_page_id is not None:
-                page_id = self.options.root_page_id.page_id
-                parent = DocumentNode(local_dir, page_id=page_id)
-            else:
-                # local use only, raises error with remote synchronization
-                parent = DocumentNode(local_dir, page_id=None)
+            raise ArgumentError(f"root page requires corresponding top-level Markdown document in {local_dir}")
 
         for file in files:
             node = self._index_file(file)
@@ -254,9 +240,7 @@ class ProcessorFactory:
     options: ConfluenceDocumentOptions
     site: ConfluenceSiteMetadata
 
-    def __init__(
-        self, options: ConfluenceDocumentOptions, site: ConfluenceSiteMetadata
-    ) -> None:
+    def __init__(self, options: ConfluenceDocumentOptions, site: ConfluenceSiteMetadata) -> None:
         self.options = options
         self.site = site
 
@@ -283,9 +267,7 @@ class Converter:
         else:
             raise ArgumentError(f"expected: valid file or directory path; got: {path}")
 
-    def process_directory(
-        self, local_dir: Path, root_dir: Optional[Path] = None
-    ) -> None:
+    def process_directory(self, local_dir: Path, root_dir: Optional[Path] = None) -> None:
         """
         Recursively scans a directory hierarchy for Markdown files, and processes each, resolving cross-references.
         """