markdown-to-confluence 0.5.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

{markdown_to_confluence-0.5.2.dist-info → markdown_to_confluence-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.5.2
+Version: 0.5.3
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -98,6 +98,15 @@ pip install markdown-to-confluence
 npm install -g @mermaid-js/mermaid-cli
 ```
 
+**Optional.** Pre-rendering PlantUML diagrams into PNG or SVG images requires Java, Graphviz and [PlantUML](https://plantuml.com/). (Refer to `--render-plantuml`.)
+
+1. **Install Java**: Version 8 or later from [Adoptium](https://adoptium.net/) or [Oracle](https://www.oracle.com/java/technologies/downloads/)
+2. **Install Graphviz**: Required for most diagram types in PlantUML (except sequence diagrams)
+   * **Ubuntu/Debian**: `sudo apt-get install Graphviz`
+   * **macOS**: `brew install graphviz`
+   * **Windows**: Download from [graphviz.org](https://graphviz.org/download/)
+3. **Download PlantUML JAR**: Download [plantuml.jar](https://github.com/plantuml/plantuml/releases) and set `PLANTUML_JAR` environment variable to point to it
+
 **Optional.** Converting formulas and equations to PNG or SVG images requires [Matplotlib](https://matplotlib.org/):
 
 ```sh
@@ -112,7 +121,11 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering in the synchronization phase requires a [marketplace app](https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence). (Refer to `--no-render-mermaid`.)
 
-**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
+**Optional.** PlantUML diagrams are embedded with compressed source data and are displayed using the [PlantUML Diagrams for Confluence](https://marketplace.atlassian.com/apps/1215115/plantuml-diagrams-for-confluence) app (if installed). (Refer to `--no-render-plantuml`.)
+
+Installing `plantuml.jar` (see above) helps display embedded diagrams with pre-calculated optimal dimensions.
+
+**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/). (Refer to `--no-render-latex`.)
 
 ## Getting started
 
@@ -218,7 +231,9 @@ Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes prece
 The generated-by text can also be templated with the following variables:
 
 - `%{filename}`: the name of the Markdown file
-- `%{filepath}`: the path of the Markdown file relative to the *source root*
+- `%{filestem}`: the name of the Markdown file without the extension
+- `%{filepath}`: the path of the Markdown file relative to the _source root_
+- `%{filedir}`: the dirname of the `%{filepath}` (the path without the filename)
 
 When publishing a directory hierarchy, the *source root* is the directory in which *md2conf* is launched. When publishing a single file, this is the directory in which the Markdown file resides.
 
@@ -372,6 +387,11 @@ Likewise, if you have a nested list, make sure that nested items are indented by
 
 Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
 
+* Relative paths (e.g. `path/to/image.png` or `../to/image.png`) resolve to absolute paths w.r.t. the Markdown document location.
+* Absolute paths (e.g. `/path/to/image.png`) are interpreted w.r.t. to the synchronization root (typically the shell current directory).
+
+As a security measure, resolved paths can only reference files that are in the directory hierarchy of the synchronization root; you can't use `..` to leave the top-level directory of the synchronization root.
+
 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.
@@ -605,7 +625,9 @@ Specifically, image references for status labels (e.g. `![My label][STATUS-RED]`
 
 ### Running the tool
 
-You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
+#### Command line
+
+You can synchronize a (directory of) Markdown file(s) with Confluence using the command-line tool `md2conf`:
 
 ```sh
 $ python3 -m md2conf sample/index.md
@@ -643,6 +665,8 @@ options:
   --no-render-drawio    Upload draw.io diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-mermaid      Render Mermaid diagrams as image files. (Installed utility required to convert.)
   --no-render-mermaid   Upload Mermaid diagram sources as Confluence page attachments. (Marketplace app required to display.)
+  --render-plantuml     Render PlantUML diagrams as image files. (Installed utility required to convert.)
+  --no-render-plantuml  Upload PlantUML diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-latex        Render LaTeX formulas as image files. (Matplotlib required to convert.)
   --no-render-latex     Inline LaTeX formulas in Confluence page. (Marketplace app required to display.)
   --diagram-output-format {png,svg}
@@ -667,6 +691,58 @@ options:
                         Apply custom headers to all Confluence API requests.
 ```
 
+#### Python
+
+*md2conf* has a Python interface. Create a `ConnectionProperties` object to set connection parameters to the Confluence server, and a `DocumentOptions` object to configure how Markdown files are converted into pages on a Confluence wiki site. Open a connection to the Confluence server with the context manager `ConfluenceAPI`, and instantiate a `Publisher` to start converting documents.
+
+```python
+from md2conf.api import ConfluenceAPI
+from md2conf.environment import ConnectionProperties
+from md2conf.options import ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
+from md2conf.publisher import Publisher
+
+properties = ConnectionProperties(
+    api_url=...,
+    domain=...,
+    base_path=...,
+    user_name=...,
+    api_key=...,
+    space_key=...,
+    headers=...,
+)
+options = DocumentOptions(
+    root_page_id=...,
+    keep_hierarchy=...,
+    title_prefix=...,
+    generated_by=...,
+    converter=ConverterOptions(
+        heading_anchors=...,
+        ignore_invalid_url=...,
+        skip_title_heading=...,
+        prefer_raster=...,
+        render_drawio=...,
+        render_mermaid=...,
+        render_plantuml=...,
+        render_latex=...,
+        diagram_output_format=...,
+        webui_links=...,
+        use_panel=...,
+        layout=LayoutOptions(
+            image=ImageLayoutOptions(
+                alignment=...,
+                max_width=...,
+            ),
+            table=TableLayoutOptions(
+                width=...,
+                display_mode=...,
+            ),
+        ),
+    ),
+)
+with ConfluenceAPI(properties) as api:
+    Publisher(api, options).process(mdpath)
+```
+
 ### Confluence REST API v1 vs. v2
 
 *md2conf* version 0.3.0 has switched to using [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/) for API calls such as retrieving current page content. Earlier versions used [Confluence REST API v1](https://developer.atlassian.com/cloud/confluence/rest/v1/) exclusively. Unfortunately, Atlassian has decommissioned Confluence REST API v1 for several endpoints in Confluence Cloud as of due date March 31, 2025, and we don't have access to an environment where we could test retired v1 endpoints.

markdown_to_confluence-0.5.3.dist-info/RECORD

@@ -0,0 +1,55 @@
+markdown_to_confluence-0.5.3.dist-info/licenses/LICENSE,sha256=SEEBf2BMI1LUHnDvyHnV6L12A6zTAOQcsyMvaawAXWo,1077
+md2conf/__init__.py,sha256=CqQHkYFE1AAs4GhMm1nConbt3V7wksgDXzqm5mg6F6I,402
+md2conf/__main__.py,sha256=Wxz6Rx1Sx_J0FbaCY2HpByHqTMbxDEs1v5VzfdQh32U,13891
+md2conf/api.py,sha256=GVPElSP9qILA5IaEvtKaxjsoRQSsGMMoRhCxjjzLadM,42703
+md2conf/attachment.py,sha256=Nc3qGDENWBnsI6OVwMLXnk0EyEITpvov9MluDFD90ZI,1689
+md2conf/coalesce.py,sha256=YHnqFwow5wCj6OQ3oosig01D2lxWusAScMF4HAUO2-g,1305
+md2conf/collection.py,sha256=ukN74VCa4HaGSh6tLXpLd0j_UNPywcnKI0X7usgdSCo,824
+md2conf/compatibility.py,sha256=4ZNN6VLqxSbI1kowdsPproGZqwxBISys4Z22vBfe6Z8,687
+md2conf/converter.py,sha256=C6cROI8bUswyNZ1jSC0lf_9J-S6ojrXLbrkSDALuKR8,63065
+md2conf/csf.py,sha256=6H9G-5cZyyWMJr0tFskPNiWdQ2Ehq-V8EhlvvxhukWY,6582
+md2conf/emoticon.py,sha256=0g4rkx3d58xU4nnLak5ms7i0FSDnq0WJrLVFRgGyLC8,542
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/environment.py,sha256=TfNEz3Pyw9qe7f8i7e_kph16c09fhZ4cLNZZzIjmI18,3892
+md2conf/extension.py,sha256=5d2CtfULwiqlqwpOqbvlVu2KQ-kVBkDDYAhnHXbq79I,2227
+md2conf/external.py,sha256=ZRL0mCY02Gp4XfqRdbap2YdOihSpY2LA6tdGJBfC-FQ,1693
+md2conf/formatting.py,sha256=ygL59VgpioX069axEX-7XjKs0sUjTfIZiBE5fWmITxc,4557
+md2conf/frontmatter.py,sha256=iWtn_oXoLQxvCsdI3OXs1ylWGmB-gc7mMLpSGg113i4,1888
+md2conf/image.py,sha256=udlnUY_xOmI-PJAqWqXBF7hAO3pj_VW7u5hXhBw4HcA,5260
+md2conf/latex.py,sha256=haZKkUxSEcPj3fVmiIVZAwgszqNqGLk1GQ7i8KGHpo0,2226
+md2conf/local.py,sha256=eY3WpY-lNzLZeAfxX1ACVEhuzz0HDYX_sNQogJfkqcM,3673
+md2conf/markdown.py,sha256=4Km-AbQH04nDgPF0ijo-Ld7o8jTPXzENIMn7P1qIk0o,3148
+md2conf/matcher.py,sha256=Xg4YSb87iPkCzhKuKytBut6NOkEab3IM-AjzXbwy64U,6774
+md2conf/metadata.py,sha256=NOjbCIrwLgTIIeNgmo7w5JXuT-pxOXBGSg-irfdpokk,976
+md2conf/options.py,sha256=MJka7h0ly6D5QQNXEi9ios1uQbqHQpyn07XciHV-mF8,4385
+md2conf/png.py,sha256=wbo8tgm8Vxi56q5PLoTutZBU6qF73KJ6TJbs7G7LPG4,6166
+md2conf/processor.py,sha256=yqRb1Njn8XWxx22byq5nrobeH9AOp55mHTVoBUJlN2A,10203
+md2conf/publisher.py,sha256=6WfyZxWB59PrOro6wgkgXuFcnf7AqarlUfHo-Twzu9k,8509
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/scanner.py,sha256=wvh5IlD2VnAwulqY6PUe33k1D8Uag0kqTs9pQ-YFq8g,3736
+md2conf/serializer.py,sha256=W4_yLJfT3vLw0PUg88lpUEnvn64CjaX3ZaKgIrwcxfw,1786
+md2conf/svg.py,sha256=b98hxpVL-yFojln8NunxQRJSabMdfvazo7FkFySjALY,11054
+md2conf/text.py,sha256=cnYV_JQp_v91LbQHo3qvxcEuhIdaPjCjkmLOKINcNv4,1736
+md2conf/toc.py,sha256=HCtnREEucmGfqzwq-Dk6Q4ZgxW5Z8nZk6lg8UfhcoI0,2413
+md2conf/uri.py,sha256=my0deyR5SlppJrYCbXF1Zz94QA1JT-HTWe9pKw7AJ_A,1158
+md2conf/xml.py,sha256=uaaUDs0hfluNX74dfkY_Dxu1KmeNDGogpGRGpUVEfE4,5526
+md2conf/drawio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/drawio/extension.py,sha256=-k0pAhIZXDjiKeHlTJl2MGWMYpG-PmXK91-_vBMQZnE,4389
+md2conf/drawio/render.py,sha256=veSu5gjm5ggLnmaH7uvH9qNeOygBJpqhSKK_LJs0QTk,8581
+md2conf/mermaid/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/mermaid/config.py,sha256=5Dec2QcdB_GtnuXIW6nhJK8J5caduNZU1oz1mcmmb44,376
+md2conf/mermaid/extension.py,sha256=1drXVM_KbS00dcjSCRru0wwbil4zq3aR81dHMhfe7zA,4021
+md2conf/mermaid/render.py,sha256=cGq3hOemgsbh6btt7uJaRxzH4EmGis0K6_qNW5YrhIk,1834
+md2conf/mermaid/scanner.py,sha256=oIpaNxiZBNcmggnjlyYGcIVOXcYQWjf1lEVdyIwE4xE,1379
+md2conf/plantuml/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/plantuml/config.py,sha256=j0ONhkzmAPagh00ltamTKlVEvXa6R284We9pDxRy-5U,378
+md2conf/plantuml/extension.py,sha256=-WEL6Ssa3Kz_7D_AQSnB1da0bylyYZivmRQwlOBfYcM,6281
+md2conf/plantuml/render.py,sha256=fwwKJIv_q1Fm9Vd8af7OcEG-5MkojZ-fxrQgA33grE8,3818
+md2conf/plantuml/scanner.py,sha256=Oso6VbHVuMaPMKMazQc_bf4hhOT5WeJN5WiVPM8peyM,1347
+markdown_to_confluence-0.5.3.dist-info/METADATA,sha256=7r3TveKAaJPBk14SGcJHuCXuDYD0rt7KUK6a_A8p1gE,43775
+markdown_to_confluence-0.5.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.5.3.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.5.3.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.5.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.5.3.dist-info/RECORD,,

{markdown_to_confluence-0.5.2.dist-info → markdown_to_confluence-0.5.3.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2025 Levente Hunyadi
+Copyright (c) 2022-2026 Levente Hunyadi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

md2conf/__init__.py

@@ -5,9 +5,9 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2022-2025, Levente Hunyadi"
+__copyright__ = "Copyright 2022-2026, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __status__ = "Production"

md2conf/__main__.py

@@ -4,7 +4,7 @@ Publish Markdown files to Confluence wiki.
 Parses Markdown files, converts Markdown content into the Confluence Storage Format (XHTML), and invokes
 Confluence API endpoints to upload images and content.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -19,10 +19,10 @@ from pathlib import Path
 from typing import Any, Iterable, Literal, Sequence
 
 from . import __version__
-from .domain import ConfluenceDocumentOptions, ConfluencePageID
-from .environment import ArgumentError, ConfluenceConnectionProperties, ConfluenceSiteProperties
-from .extra import override
+from .compatibility import override
+from .environment import ArgumentError, ConfluenceSiteProperties, ConnectionProperties
 from .metadata import ConfluenceSiteMetadata
+from .options import ConfluencePageID, ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions
 
 
 class Arguments(argparse.Namespace):
@@ -44,6 +44,7 @@ class Arguments(argparse.Namespace):
     prefer_raster: bool
     render_drawio: bool
     render_mermaid: bool
+    render_plantuml: bool
     render_latex: bool
     diagram_output_format: Literal["png", "svg"]
     local: bool
@@ -191,6 +192,19 @@ def get_parser() -> argparse.ArgumentParser:
         action="store_false",
         help="Upload Mermaid diagram sources as Confluence page attachments. (Marketplace app required to display.)",
     )
+    parser.add_argument(
+        "--render-plantuml",
+        dest="render_plantuml",
+        action="store_true",
+        default=True,
+        help="Render PlantUML diagrams as image files. (Installed utility required to convert.)",
+    )
+    parser.add_argument(
+        "--no-render-plantuml",
+        dest="render_plantuml",
+        action="store_false",
+        help="Upload PlantUML diagram sources as Confluence page attachments. (Marketplace app required to display.)",
+    )
     parser.add_argument(
         "--render-latex",
         dest="render_latex",
@@ -322,23 +336,30 @@ def main() -> None:
         format="%(asctime)s - %(levelname)s - %(funcName)s [%(lineno)d] - %(message)s",
     )
 
-    options = ConfluenceDocumentOptions(
-        heading_anchors=args.heading_anchors,
-        ignore_invalid_url=args.ignore_invalid_url,
-        skip_title_heading=args.skip_title_heading,
-        title_prefix=args.title_prefix,
-        generated_by=args.generated_by,
+    options = DocumentOptions(
         root_page_id=ConfluencePageID(args.root_page) if args.root_page else None,
         keep_hierarchy=args.keep_hierarchy,
-        prefer_raster=args.prefer_raster,
-        render_drawio=args.render_drawio,
-        render_mermaid=args.render_mermaid,
-        render_latex=args.render_latex,
-        diagram_output_format=args.diagram_output_format,
-        webui_links=args.webui_links,
-        alignment=args.alignment,
-        max_image_width=args.max_image_width,
-        use_panel=args.use_panel,
+        title_prefix=args.title_prefix,
+        generated_by=args.generated_by,
+        converter=ConverterOptions(
+            heading_anchors=args.heading_anchors,
+            ignore_invalid_url=args.ignore_invalid_url,
+            skip_title_heading=args.skip_title_heading,
+            prefer_raster=args.prefer_raster,
+            render_drawio=args.render_drawio,
+            render_mermaid=args.render_mermaid,
+            render_plantuml=args.render_plantuml,
+            render_latex=args.render_latex,
+            diagram_output_format=args.diagram_output_format,
+            webui_links=args.webui_links,
+            use_panel=args.use_panel,
+            layout=LayoutOptions(
+                image=ImageLayoutOptions(
+                    alignment=args.alignment,
+                    max_width=args.max_image_width,
+                ),
+            ),
+        ),
     )
     if args.local:
         from .local import LocalConverter
@@ -364,7 +385,7 @@ def main() -> None:
         from .publisher import Publisher
 
         try:
-            properties = ConfluenceConnectionProperties(
+            properties = ConnectionProperties(
                 api_url=args.api_url,
                 domain=args.domain,
                 base_path=args.path,
@@ -377,10 +398,7 @@ def main() -> None:
             parser.error(str(e))
         try:
             with ConfluenceAPI(properties) as api:
-                Publisher(
-                    api,
-                    options,
-                ).process(args.mdpath)
+                Publisher(api, options).process(args.mdpath)
         except HTTPError as err:
             logging.error(err)
 

md2conf/api.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -25,8 +25,8 @@ import requests
 import truststore
 from requests.adapters import HTTPAdapter
 
-from .environment import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
-from .extra import override
+from .compatibility import override
+from .environment import ArgumentError, ConfluenceError, ConnectionProperties, PageError
 from .metadata import ConfluenceSiteMetadata
 from .serializer import JsonType, json_to_object, object_to_json_payload
 
@@ -35,6 +35,7 @@ T = TypeVar("T")
 # spellchecker: disable
 mimetypes.add_type("application/vnd.openxmlformats-officedocument.wordprocessingml.document", ".docx", strict=True)
 mimetypes.add_type("text/vnd.mermaid", ".mmd", strict=True)
+mimetypes.add_type("text/vnd.plantuml", ".puml", strict=True)
 mimetypes.add_type("application/vnd.oasis.opendocument.presentation", ".odp", strict=True)
 mimetypes.add_type("application/vnd.oasis.opendocument.spreadsheet", ".ods", strict=True)
 mimetypes.add_type("application/vnd.oasis.opendocument.text", ".odt", strict=True)
@@ -370,11 +371,11 @@ class ConfluenceAPI:
     Encapsulates operations that can be invoked via the [Confluence REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/).
     """
 
-    properties: ConfluenceConnectionProperties
+    properties: ConnectionProperties
     session: "ConfluenceSession | None" = None
 
-    def __init__(self, properties: ConfluenceConnectionProperties | None = None) -> None:
-        self.properties = properties or ConfluenceConnectionProperties()
+    def __init__(self, properties: ConnectionProperties | None = None) -> None:
+        self.properties = properties or ConnectionProperties()
 
     def __enter__(self) -> "ConfluenceSession":
         """
@@ -626,7 +627,16 @@ class ConfluenceSession:
 
         return id
 
+    @overload
+    def get_space_id(self, *, space_id: str | None = None) -> str | None: ...
+
+    @overload
+    def get_space_id(self, *, space_key: str | None = None) -> str | None: ...
+
     def get_space_id(self, *, space_id: str | None = None, space_key: str | None = None) -> str | None:
+        return self._get_space_id(space_id=space_id, space_key=space_key)
+
+    def _get_space_id(self, *, space_id: str | None = None, space_key: str | None = None) -> str | None:
         """
         Coalesces a space ID or space key into a space ID, accounting for site default.
 
@@ -647,6 +657,15 @@ class ConfluenceSession:
         # space ID and key are unset, and no default space is configured
         return None
 
+    def get_homepage_id(self, space_id: str) -> str:
+        """
+        Returns the page ID corresponding to the space home page.
+        """
+
+        path = f"/spaces/{space_id}"
+        data = self._get(ConfluenceVersion.VERSION_2, path, dict[str, JsonType])
+        return typing.cast(str, data["homepageId"])
+
     def get_attachment_by_name(self, page_id: str, filename: str) -> ConfluenceAttachment:
         """
         Retrieves a Confluence page attachment by an unprefixed file name.
@@ -831,7 +850,7 @@ class ConfluenceSession:
         query = {
             "title": title,
         }
-        space_id = self.get_space_id(space_id=space_id, space_key=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
 
@@ -1006,7 +1025,7 @@ class ConfluenceSession:
         :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)
+        space_id = self._get_space_id(space_id=space_id, space_key=space_key)
         path = "/pages"
         query = {"title": title}
         if space_id is not None:

md2conf/attachment.py

@@ -0,0 +1,72 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class ImageData:
+    path: Path
+    description: str | None = None
+
+
+@dataclass
+class EmbeddedFileData:
+    data: bytes
+    description: str | None = None
+
+
+class AttachmentCatalog:
+    "Maintains a list of files and binary data to be uploaded to Confluence as attachments."
+
+    images: list[ImageData]
+    embedded_files: dict[str, EmbeddedFileData]
+
+    def __init__(self) -> None:
+        self.images = []
+        self.embedded_files = {}
+
+    def add_image(self, data: ImageData) -> None:
+        self.images.append(data)
+
+    def add_embed(self, filename: str, data: EmbeddedFileData) -> None:
+        self.embedded_files[filename] = data
+
+
+def attachment_name(ref: 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 (.)
+    """
+
+    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("/", "_")

md2conf/coalesce.py

@@ -0,0 +1,43 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import copy
+import dataclasses
+from typing import Any, ClassVar, Protocol, TypeVar
+
+
+class DataclassInstance(Protocol):
+    __dataclass_fields__: ClassVar[dict[str, dataclasses.Field[Any]]]
+
+
+D = TypeVar("D", bound=DataclassInstance)
+
+
+def coalesce(target: D, source: D) -> D:
+    """
+    Implements nullish coalescing assignment on each field of a data-class.
+
+    Iterates over each field of the data-class, and evaluates the right operand and assigns it to the left only if
+    the left operand is `None`. Applies recursively when the field is a data-class.
+
+    :returns: A newly created data-class instance.
+    """
+
+    updates: dict[str, Any] = {}
+    for field in dataclasses.fields(target):
+        target_field = getattr(target, field.name, None)
+        source_field = getattr(source, field.name, None)
+
+        if target_field is None:
+            if source_field is not None:
+                updates[field.name] = copy.deepcopy(source_field)
+        elif dataclasses.is_dataclass(field.type):
+            if source_field is not None:
+                updates[field.name] = coalesce(target_field, source_field)
+
+    return dataclasses.replace(target, **updates)

md2conf/collection.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """

md2conf/{extra.py → compatibility.py}

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """