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

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

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

@@ -0,0 +1,22 @@
+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,,

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

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.0)
+Generator: setuptools (80.8.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.2"
+__version__ = "0.3.4"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -22,18 +22,23 @@ import requests
 from . import __version__
 from .api import ConfluenceAPI
 from .application import Application
-from .converter import ConfluenceDocumentOptions
-from .processor import Processor
-from .properties import ConfluenceProperties
+from .converter import ConfluenceDocumentOptions, ConfluencePageID
+from .local import LocalConverter
+from .metadata import ConfluenceSiteMetadata
+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
@@ -195,24 +200,45 @@ def main() -> None:
         heading_anchors=args.heading_anchors,
         ignore_invalid_url=args.ignore_invalid_url,
         generated_by=args.generated_by,
-        root_page_id=args.root_page,
+        root_page_id=ConfluencePageID(args.root_page) if args.root_page else None,
         keep_hierarchy=args.keep_hierarchy,
         render_mermaid=args.render_mermaid,
         diagram_output_format=args.diagram_output_format,
         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,
+        )
+        LocalConverter(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(
                     api,
                     options,
-                ).synchronize(args.mdpath)
+                ).process(args.mdpath)
         except requests.exceptions.HTTPError as err:
             logging.error(err)
 

md2conf/api.py

@@ -7,6 +7,7 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 import enum
+import functools
 import io
 import json
 import logging
@@ -21,7 +22,13 @@ from urllib.parse import urlencode, urlparse, urlunparse
 import requests
 
 from .converter import ParseError, sanitize_confluence
-from .properties import ConfluenceError, ConfluenceProperties
+from .metadata import ConfluenceSiteMetadata
+from .properties import (
+    ArgumentError,
+    ConfluenceConnectionProperties,
+    ConfluenceError,
+    PageError,
+)
 
 # a JSON type with possible `null` values
 JsonType = Union[
@@ -44,6 +51,7 @@ class ConfluencePageParentContentType(enum.Enum):
     """
     Content types that can be a parent to a Confluence page
     """
+
     PAGE = "page"
     WHITEBOARD = "whiteboard"
     DATABASE = "database"
@@ -70,7 +78,7 @@ def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
 LOGGER = logging.getLogger(__name__)
 
 
-@dataclass
+@dataclass(frozen=True)
 class ConfluenceAttachment:
     id: str
     media_type: str
@@ -78,23 +86,29 @@ class ConfluenceAttachment:
     comment: str
 
 
-@dataclass
-class ConfluencePage:
+@dataclass(frozen=True)
+class ConfluencePageMetadata:
     id: str
     space_id: str
     parent_id: str
-    parent_type: ConfluencePageParentContentType
+    parent_type: Optional[ConfluencePageParentContentType]
     title: str
     version: int
+
+
+@dataclass(frozen=True)
+class ConfluencePage(ConfluencePageMetadata):
     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,10 +142,12 @@ class ConfluenceAPI:
 
 
 class ConfluenceSession:
+    """
+    Information about an open session to a Confluence server.
+    """
+
     session: requests.Session
-    domain: str
-    base_path: str
-    space_key: Optional[str]
+    site: ConfluenceSiteMetadata
 
     _space_id_to_key: dict[str, str]
     _space_key_to_id: dict[str, str]
@@ -141,12 +157,10 @@ 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
-        self.base_path = base_path
-        self.space_key = space_key
+        self.site = ConfluenceSiteMetadata(domain, base_path, space_key)
 
         self._space_id_to_key = {}
         self._space_key_to_id = {}
@@ -170,7 +184,9 @@ class ConfluenceSession:
         :returns: A full URL.
         """
 
-        base_url = f"https://{self.domain}{self.base_path}{version.value}{path}"
+        base_url = (
+            f"https://{self.site.domain}{self.site.base_path}{version.value}{path}"
+        )
         return build_url(base_url, query)
 
     def _invoke(
@@ -183,11 +199,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:
@@ -197,6 +211,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:
@@ -243,6 +259,29 @@ class ConfluenceSession:
 
         return id
 
+    def get_space_id(
+        self, *, space_id: Optional[str] = None, space_key: Optional[str] = None
+    ) -> Optional[str]:
+        """
+        Coalesce a space ID or space key into a space ID, accounting for site default.
+
+        :param space_id: A Confluence space ID.
+        :param space_key: A Confluence space key.
+        """
+
+        if space_id is not None and space_key is not None:
+            raise ConfluenceError("either space ID or space key is required; not both")
+
+        if space_id is not None:
+            return space_id
+
+        space_key = space_key or self.site.space_key
+        if space_key is not None:
+            return self.space_key_to_id(space_key)
+
+        # space ID and key are unset, and no default space is configured
+        return None
+
     def get_attachment_by_name(
         self, page_id: str, filename: str
     ) -> ConfluenceAttachment:
@@ -275,10 +314,10 @@ class ConfluenceSession:
         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:
@@ -288,7 +327,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)
@@ -385,6 +424,7 @@ class ConfluenceSession:
         self,
         title: str,
         *,
+        space_id: Optional[str] = None,
         space_key: Optional[str] = None,
     ) -> str:
         """
@@ -400,9 +440,9 @@ class ConfluenceSession:
         query = {
             "title": title,
         }
-        coalesced_space_key = space_key or self.space_key
-        if coalesced_space_key is not None:
-            query["space-id"] = self.space_key_to_id(coalesced_space_key)
+        space_id = self.get_space_id(space_id=space_id, space_key=space_key)
+        if space_id is not None:
+            query["space-id"] = space_id
 
         payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
         payload = typing.cast(dict[str, JsonType], payload)
@@ -417,10 +457,10 @@ class ConfluenceSession:
 
     def get_page(self, page_id: str) -> ConfluencePage:
         """
-        Retrieve Confluence wiki page details.
+        Retrieve Confluence wiki page details and content.
 
         :param page_id: The Confluence page ID.
-        :returns: Confluence page info.
+        :returns: Confluence page info and content.
         """
 
         path = f"/pages/{page_id}"
@@ -435,12 +475,43 @@ class ConfluenceSession:
             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"])),
+            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"]),
         )
 
+    @functools.cache
+    def get_page_metadata(self, page_id: str) -> ConfluencePageMetadata:
+        """
+        Retrieve Confluence wiki page details.
+
+        :param page_id: The Confluence page ID.
+        :returns: Confluence page info.
+        """
+
+        path = f"/pages/{page_id}"
+        payload = self._invoke(ConfluenceVersion.VERSION_2, path)
+        data = typing.cast(dict[str, JsonType], payload)
+        version = typing.cast(dict[str, JsonType], data["version"])
+
+        return ConfluencePageMetadata(
+            id=page_id,
+            space_id=typing.cast(str, data["spaceId"]),
+            parent_id=typing.cast(str, data["parentId"]),
+            parent_type=(
+                ConfluencePageParentContentType(typing.cast(str, data["parentType"]))
+                if data["parentType"] is not None
+                else None
+            ),
+            title=typing.cast(str, data["title"]),
+            version=typing.cast(int, version["number"]),
+        )
+
     def get_page_version(self, page_id: str) -> int:
         """
         Retrieve a Confluence wiki page version.
@@ -495,28 +566,21 @@ class ConfluenceSession:
 
     def create_page(
         self,
-        parent_page_id: str,
+        parent_id: str,
         title: str,
         new_content: str,
-        *,
-        space_key: Optional[str] = None,
     ) -> ConfluencePage:
         """
         Create a new page via Confluence API.
         """
 
-        coalesced_space_key = space_key or self.space_key
-        if coalesced_space_key is None:
-            raise ConfluenceError(
-                "Confluence space key required for creating a new page"
-            )
-
+        parent_page = self.get_page_metadata(parent_id)
         path = "/pages/"
         query = {
-            "spaceId": self.space_key_to_id(coalesced_space_key),
+            "spaceId": parent_page.space_id,
             "status": "current",
             "title": title,
-            "parentId": parent_page_id,
+            "parentId": parent_id,
             "body": {"storage": {"value": new_content, "representation": "storage"}},
         }
 
@@ -539,7 +603,11 @@ class ConfluenceSession:
             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"])),
+            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"]),
@@ -570,13 +638,24 @@ class ConfluenceSession:
             response.raise_for_status()
 
     def page_exists(
-        self, title: str, *, space_key: Optional[str] = None
+        self,
+        title: str,
+        *,
+        space_id: Optional[str] = None,
+        space_key: Optional[str] = None,
     ) -> Optional[str]:
+        """
+        Check if a Confluence page exists with the given title.
+
+        :param title: Page title. Pages in the same Confluence space must have a unique title.
+        :param space_key: Identifies the Confluence space.
+        """
+
+        space_id = self.get_space_id(space_id=space_id, space_key=space_key)
         path = "/pages"
-        coalesced_space_key = space_key or self.space_key
         query = {"title": title}
-        if coalesced_space_key is not None:
-            query["space-id"] = self.space_key_to_id(coalesced_space_key)
+        if space_id is not None:
+            query["space-id"] = space_id
 
         LOGGER.info("Checking if page exists with title: %s", title)
 
@@ -595,14 +674,20 @@ class ConfluenceSession:
         else:
             return None
 
-    def get_or_create_page(
-        self, title: str, parent_id: str, *, space_key: Optional[str] = None
-    ) -> ConfluencePage:
-        page_id = self.page_exists(title)
+    def get_or_create_page(self, title: str, parent_id: str) -> ConfluencePage:
+        """
+        Find a page with the given title, or create a new page if no such page exists.
+
+        :param title: Page title. Pages in the same Confluence space must have a unique title.
+        :param parent_id: Identifies the parent page for a new child page.
+        """
+
+        parent_page = self.get_page_metadata(parent_id)
+        page_id = self.page_exists(title, space_id=parent_page.space_id)
 
         if page_id is not None:
             LOGGER.debug("Retrieving existing page: %s", page_id)
             return self.get_page(page_id)
         else:
             LOGGER.debug("Creating new page with title: %s", title)
-            return self.create_page(parent_id, title, "", space_key=space_key)
+            return self.create_page(parent_id, title, "")