markdown-to-confluence 0.4.5__py3-none-any.whl → 0.4.6__py3-none-any.whl

{markdown_to_confluence-0.4.5.dist-info → markdown_to_confluence-0.4.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.4.5
+Version: 0.4.6
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -23,12 +23,14 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: certifi>=2025.8.3; python_version < "3.10"
 Requires-Dist: json_strong_typing>=0.4
 Requires-Dist: lxml>=6.0
 Requires-Dist: markdown>=3.8
 Requires-Dist: pymdown-extensions>=10.16
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: requests>=2.32
+Requires-Dist: truststore>=0.10; python_version >= "3.10"
 Requires-Dist: typing-extensions>=4.14; python_version < "3.12"
 Provides-Extra: dev
 Requires-Dist: markdown_doc>=0.1.4; python_version >= "3.10" and extra == "dev"
@@ -143,7 +145,7 @@ export CONFLUENCE_SPACE_KEY='SPACE'
 
 On Windows, these can be set via system properties.
 
-If you use Atlassian scoped API tokens, you should set API URL, substituting `CLOUD_ID` with your own Cloud ID:
+If you use Atlassian scoped API tokens, you may want to set API URL directly, substituting `CLOUD_ID` with your own Cloud ID:
 
 ```sh
 export CONFLUENCE_API_URL='https://api.atlassian.com/ex/confluence/CLOUD_ID/'
@@ -151,20 +153,27 @@ export CONFLUENCE_API_URL='https://api.atlassian.com/ex/confluence/CLOUD_ID/'
 
 In this case, *md2conf* can automatically determine `CONFLUENCE_DOMAIN` and `CONFLUENCE_PATH`.
 
+If you can't find your `CLOUD_ID` but assign both `CONFLUENCE_DOMAIN` and `CONFLUENCE_PATH`, *md2conf* makes a best-effort attempt to determine `CONFLUENCE_API_URL`.
+
 ### Permissions
 
 The tool requires appropriate permissions in Confluence in order to invoke endpoints.
 
-Required scopes for scoped API tokens are as follows:
+We recommend the following scopes for scoped API tokens:
 
+* `read:attachment:confluence`
+* `read:content:confluence`
+* `read:content-details:confluence`
+* `read:label:confluence`
 * `read:page:confluence`
-* `write:page:confluence`
 * `read:space:confluence`
-* `write:space:confluence`
-* `read:attachment:confluence`
 * `write:attachment:confluence`
-* `read:label:confluence`
+* `write:content:confluence`
 * `write:label:confluence`
+* `write:page:confluence`
+* `delete:attachment:confluence`
+* `delete:content:confluence`
+* `delete:page:confluence`
 
 If a Confluence username is set, the tool uses HTTP *Basic* authentication to pass the username and the API key to Confluence REST API endpoints. If no username is provided, the tool authenticates with HTTP *Bearer*, and passes the API key as the bearer token.
 
@@ -331,6 +340,21 @@ The following table shows standard highlight colors (CSS `background-color`) tha
 
 If your Markdown lists or tables don't appear in Confluence as expected, verify that the list or table is delimited by a blank line both before and after, as per strict Markdown syntax. While some previewers accept a more lenient syntax (e.g. an itemized list immediately following a paragraph), *md2conf* uses [Python-Markdown](https://python-markdown.github.io/) internally to convert Markdown into XHTML, which expects the Markdown document to adhere to the stricter syntax.
 
+Likewise, if you have a nested list, make sure that nested items are indented by exactly ***four*** spaces as compared to the parent node:
+
+```markdown
+1. List item 1
+    * Nested item 1
+        1. Item 1
+        2. Item 2
+    * Nested item 2
+        - Item 3
+        - Item 4
+2. List item 2
+    1. Nested item 3
+    2. Nested item 4
+```
+
 ### Publishing images
 
 Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
@@ -348,7 +372,7 @@ Inline formulas can be enclosed with `$` signs, or delimited with `\(` and `\)`,
 
 Block formulas can be enclosed with `$$`, or wrapped in code blocks specifying the language `math`:
 
-```md
+```markdown
 $$\int _{a}^{b}f(x)dx=F(b)-F(a)$$
 ```
 
@@ -385,7 +409,7 @@ Displaying math formulas in Confluence requires the extension [LaTeX Math for Co
 
 Use the pseudo-language `csf` in a Markdown code block to pass content directly to Confluence. The content must be a single XML node that conforms to Confluence Storage Format (typically an `ac:structured-macro`) but is otherwise not validated. The following example shows how to create a panel similar to an *info panel* but with custom background color and emoji. Notice that `ac:rich-text-body` uses XHTML, not Markdown.
 
-````md
+````markdown
 ```csf
 <ac:structured-macro ac:name="panel" ac:schema-version="1">
   <ac:parameter ac:name="panelIcon">:slight_smile:</ac:parameter>
@@ -496,7 +520,7 @@ If *md2conf* encounters a Markdown link that points to a file in the directory h
 
 *md2conf* implicitly defines some URLs, as if you included the following at the start of the Markdown document for each URL:
 
-```md
+```markdown
 [CUSTOM-URL]: https://example.com/path/to/resource
 ```
 
@@ -531,7 +555,7 @@ options:
   --api-url API_URL     Confluence API URL. Required for scoped tokens. Refer to documentation how to obtain one.
   -u, --username USERNAME
                         Confluence user name.
-  -a, --apikey, --api-key API_KEY
+  -a, --api-key API_KEY
                         Confluence API key. Refer to documentation how to obtain one.
   -s, --space SPACE     Confluence space key for pages to be published. If omitted, will default to user space.
   -l, --loglevel {debug,info,warning,error,critical}
@@ -550,8 +574,6 @@ options:
   --no-render-latex     Inline LaTeX formulas in Confluence page. (Marketplace app required to display.)
   --diagram-output-format {png,svg}
                         Format for rendering Mermaid and draw.io diagrams (default: 'png').
-  --render-mermaid-format FORMAT
-                        Format for rendering Mermaid diagrams (default: 'png').
   --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --no-heading-anchors  Don't place an anchor at each section heading.
   --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.

{markdown_to_confluence-0.4.5.dist-info → markdown_to_confluence-0.4.6.dist-info}/RECORD

@@ -1,33 +1,34 @@
-markdown_to_confluence-0.4.5.dist-info/licenses/LICENSE,sha256=56L-Y0dyZwyVlINRJRz3PNw-ka-oLVaAq-7d8zo6qlc,1077
-md2conf/__init__.py,sha256=uvviya0xS1aCIW7IU3EfeI_QkC_d9T_PiVsLEMXo9S4,402
-md2conf/__main__.py,sha256=gQncJ-mkhRyQyhrZg-uJ1RnN8aGw-sr0c83ydunFNj0,11661
-md2conf/api.py,sha256=VjXD0da4de5YtPCbUCjK0k1oD6vl59IQLItEapj0pyM,37861
-md2conf/application.py,sha256=PZDPUpoKjKBPTHwgVO20pGzTwER3paZuQbI-2_TWBgE,8563
+markdown_to_confluence-0.4.6.dist-info/licenses/LICENSE,sha256=56L-Y0dyZwyVlINRJRz3PNw-ka-oLVaAq-7d8zo6qlc,1077
+md2conf/__init__.py,sha256=-uM9--fczADkWeiQ7PSL-iFlkeCxy7lnd2KhxG3yFso,402
+md2conf/__main__.py,sha256=LiJ06zVr3wroMSLgkMf65ehraqJZgktvuN66dkBJaOI,10929
+md2conf/api.py,sha256=RcltUP8KhrhrUuVg7SqBqp-AvGZymjMXtUxpzRPGGGc,40847
 md2conf/collection.py,sha256=EobgMRJgkYloWlY03NZJ52MRC_SGLpTVCHkltDbQyt0,837
-md2conf/converter.py,sha256=hWqbXYSFymMkvobh-f3uUO6JG28EWHU_7s0QYPI6NKM,61400
-md2conf/csf.py,sha256=WIzGrX-RXAkr4XsgLIUT11WM1qwhjgcXZHI_cALXpyM,6397
+md2conf/converter.py,sha256=olL2FSop5TFxMfVXU4zWk1Lj_fwGN0c73F2ZYv8PU6s,63250
+md2conf/csf.py,sha256=VlB0rYRZ8u-bNDdzEvNy2XrJSxaL-MW_hVRHxcoBluU,6409
 md2conf/domain.py,sha256=NpeGl-I9_rgKYCKKZT1Ygg3nl5U0-jJHYYrzDVpMSGQ,1965
 md2conf/drawio.py,sha256=3RJFFzlp5a7SNVNCnwO_HCDfMy0DqYQeXfHWRPInOVE,8527
+md2conf/emoticon.py,sha256=P2L5oQvnRXeVifJQ3sJ2Ck-6ptbxumq2vsT-rM0W0Ms,484
 md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/environment.py,sha256=RC1jY_TKVbOv2bJxXn27Fj4fNWzyoNUQt6ltgUyVQAQ,3987
 md2conf/extra.py,sha256=VuMxuOnnC2Qwy6y52ukIxsaYhrZArRqMmRHRE4QZl8g,687
 md2conf/latex.py,sha256=yAClNclguPv-xWBMVWbqvYWLbyUHBVufc2aUzwyKHew,7586
 md2conf/local.py,sha256=mvp2kA_eo6JUQ_rlM7zDdEFgBPVxMr3VKP_X1nsLjHE,3747
 md2conf/markdown.py,sha256=czabU17tUfhSX1JQGiI_TrMrTmtoVThOwFu_To_Oi_w,3176
 md2conf/matcher.py,sha256=m5rZjYZSjhKfdeKS8JdPq7cG861Mc6rVZBkrIOZTHGE,6916
-md2conf/mermaid.py,sha256=7iziRC1Li3D85psR5NlnZ6BOePsOfFELgkNCAxahbZU,2240
+md2conf/mermaid.py,sha256=hGrITJVvhHprjQVoezQ1nQeo6a_lqNihF8L-oJ4t5rc,2633
 md2conf/metadata.py,sha256=LzZM-oPNnzCULmLhF516tPlV5zZBknccwMHt8Nan-xg,1007
-md2conf/processor.py,sha256=z2d2KMPEYWaxflOtH2UTwrjzpPU8TtLSEUvor85ez1Q,9732
-md2conf/properties.py,sha256=RC1jY_TKVbOv2bJxXn27Fj4fNWzyoNUQt6ltgUyVQAQ,3987
+md2conf/processor.py,sha256=62Yr33uNVEb11Q7SQ8m1KJHMoJozBPSzeUJQ0fwHig0,9733
+md2conf/publisher.py,sha256=uSyYb9SOQzMkSGKKQqsoOL5S2CfkVIEbXaCx6CY0Suw,8696
 md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
 md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-md2conf/scanner.py,sha256=Cyvjab8tBvKgubttQvNagS8nailuTvFBqUGoiX5MNp8,5351
+md2conf/scanner.py,sha256=APtENrcEgbslVfjjUnUyB81QpOmPoJgwfww0G7onNOY,6578
 md2conf/text.py,sha256=fHOrUaPXAjE4iRhHqFq-CiI-knpo4wvyHCWp0crewqA,1736
 md2conf/toc.py,sha256=hpqqDbFgNJg5-ul8qWjOglI3Am0sbwR-TLwGN5G9Qo0,2447
 md2conf/uri.py,sha256=KbLBdRFtZTQTZd8b4j0LtE8Pb68Ly0WkemF4iW-EAB4,1158
 md2conf/xml.py,sha256=Ybf3Ctt6EurVvel0eb1KezF33_e_cDpMwlUqHi4kNLE,5411
-markdown_to_confluence-0.4.5.dist-info/METADATA,sha256=zhCjkqQkp71Z28iRzGH-vLMczWaELkd-2FU_kiNv61k,33724
-markdown_to_confluence-0.4.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-markdown_to_confluence-0.4.5.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.4.5.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.4.5.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.4.5.dist-info/RECORD,,
+markdown_to_confluence-0.4.6.dist-info/METADATA,sha256=zgUR1Bz7EnzbcAkZVPVKqL123Y0L4NeWzbhxyq5yVH4,34414
+markdown_to_confluence-0.4.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.4.6.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.4.6.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.4.6.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.4.6.dist-info/RECORD,,

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.4.5"
+__version__ = "0.4.6"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -14,14 +14,15 @@ import logging
 import os.path
 import sys
 import typing
+from io import StringIO
 from pathlib import Path
 from typing import Any, Iterable, Literal, Optional, Sequence, Union
 
 from . import __version__
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
+from .environment import ArgumentError, ConfluenceConnectionProperties, ConfluenceSiteProperties
 from .extra import override
 from .metadata import ConfluenceSiteMetadata
-from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceSiteProperties
 
 
 class Arguments(argparse.Namespace):
@@ -68,30 +69,6 @@ class KwargsAppendAction(argparse.Action):
         setattr(namespace, self.dest, d)
 
 
-def unsupported(prefer: str) -> type[argparse.Action]:
-    class UnsupportedAction(argparse.Action):
-        """Display an error for unsupported command-line options."""
-
-        @override
-        def __call__(
-            self,
-            parser: argparse.ArgumentParser,
-            namespace: argparse.Namespace,
-            values: Union[None, str, Sequence[Any]],
-            option_string: Optional[str] = None,
-        ) -> None:
-            raise argparse.ArgumentError(
-                self,
-                f"this command-line option is no longer supported, use `--{prefer}`",
-            )
-
-        @override
-        def __repr__(self) -> str:
-            return f"{unsupported.__name__}({repr(prefer)})"
-
-    return UnsupportedAction
-
-
 class PositionalOnlyHelpFormatter(argparse.HelpFormatter):
     def _format_usage(
         self,
@@ -112,7 +89,7 @@ class PositionalOnlyHelpFormatter(argparse.HelpFormatter):
         return usage_str
 
 
-def main() -> None:
+def get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(formatter_class=PositionalOnlyHelpFormatter)
     parser.prog = os.path.basename(os.path.dirname(__file__))
     parser.add_argument("--version", action="version", version=__version__)
@@ -127,7 +104,6 @@ def main() -> None:
     parser.add_argument("-u", "--username", help="Confluence user name.")
     parser.add_argument(
         "-a",
-        "--apikey",
         "--api-key",
         dest="api_key",
         help="Confluence API key. Refer to documentation how to obtain one.",
@@ -228,12 +204,6 @@ def main() -> None:
         default="png",
         help="Format for rendering Mermaid and draw.io diagrams (default: 'png').",
     )
-    parser.add_argument(
-        "--render-mermaid-format",
-        action=unsupported("diagram-output-format"),
-        metavar="FORMAT",
-        help="Format for rendering Mermaid diagrams (default: 'png').",
-    )
     parser.add_argument(
         "--heading-anchors",
         action="store_true",
@@ -272,7 +242,18 @@ def main() -> None:
         default=False,
         help="Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)",
     )
+    return parser
+
 
+def get_help() -> str:
+    parser = get_parser()
+    with StringIO() as buf:
+        parser.print_help(file=buf)
+        return buf.getvalue()
+
+
+def main() -> None:
+    parser = get_parser()
     args = Arguments()
     parser.parse_args(namespace=args)
 
@@ -316,7 +297,7 @@ def main() -> None:
         from requests import HTTPError, JSONDecodeError
 
         from .api import ConfluenceAPI
-        from .application import Application
+        from .publisher import Publisher
 
         try:
             properties = ConfluenceConnectionProperties(
@@ -332,7 +313,7 @@ def main() -> None:
             parser.error(str(e))
         try:
             with ConfluenceAPI(properties) as api:
-                Application(
+                Publisher(
                     api,
                     options,
                 ).process(args.mdpath)

md2conf/api.py

@@ -11,6 +11,8 @@ import enum
 import io
 import logging
 import mimetypes
+import ssl
+import sys
 import typing
 from dataclasses import dataclass
 from pathlib import Path
@@ -19,11 +21,18 @@ from typing import Any, Optional, TypeVar
 from urllib.parse import urlencode, urlparse, urlunparse
 
 import requests
+from requests.adapters import HTTPAdapter
 from strong_typing.core import JsonType
 from strong_typing.serialization import DeserializerOptions, json_dump_string, json_to_object, object_to_json
 
+from .environment import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
+from .extra import override
 from .metadata import ConfluenceSiteMetadata
-from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
+
+if sys.version_info >= (3, 10):
+    import truststore
+else:
+    import certifi
 
 T = TypeVar("T")
 
@@ -336,9 +345,33 @@ class ConfluenceUpdateAttachmentRequest:
     version: ConfluenceContentVersion
 
 
+class TruststoreAdapter(HTTPAdapter):
+    """
+    Provides a general-case interface for HTTPS sessions to connect to HTTPS URLs.
+
+    This class implements the Transport Adapter interface in the Python library `requests`.
+
+    This class will usually be created by the :class:`requests.Session` class under the covers.
+    """
+
+    @override
+    def init_poolmanager(self, connections: int, maxsize: int, block: bool = False, **pool_kwargs: Any) -> None:
+        """
+        Adapts the pool manager to use the provided SSL context instead of the default.
+        """
+
+        if sys.version_info >= (3, 10):
+            ctx = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        else:
+            ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH, cafile=certifi.where())
+        ctx.check_hostname = True
+        ctx.verify_mode = ssl.CERT_REQUIRED
+        super().init_poolmanager(connections, maxsize, block, ssl_context=ctx, **pool_kwargs)  # type: ignore[no-untyped-call]
+
+
 class ConfluenceAPI:
     """
-    Represents an active connection to a Confluence server.
+    Encapsulates operations that can be invoked via the [Confluence REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/).
     """
 
     properties: ConfluenceConnectionProperties
@@ -348,7 +381,13 @@ class ConfluenceAPI:
         self.properties = properties or ConfluenceConnectionProperties()
 
     def __enter__(self) -> "ConfluenceSession":
+        """
+        Opens a connection to a Confluence server.
+        """
+
         session = requests.Session()
+        session.mount("https://", TruststoreAdapter())
+
         if self.properties.user_name:
             session.auth = (self.properties.user_name, self.properties.api_key)
         else:
@@ -372,6 +411,10 @@ class ConfluenceAPI:
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> None:
+        """
+        Closes an open connection.
+        """
+
         if self.session is not None:
             self.session.close()
             self.session = None
@@ -379,7 +422,7 @@ class ConfluenceAPI:
 
 class ConfluenceSession:
     """
-    Information about an open session to a Confluence server.
+    Represents an active connection to a Confluence server.
     """
 
     session: requests.Session
@@ -418,8 +461,31 @@ class ConfluenceSession:
         if not base_path:
             raise ArgumentError("Confluence base path not specified and cannot be inferred")
         self.site = ConfluenceSiteMetadata(domain, base_path, space_key)
+
         if not api_url:
-            self.api_url = f"https://{self.site.domain}{self.site.base_path}"
+            LOGGER.info("Discovering Confluence REST API URL")
+            try:
+                # obtain cloud ID to build URL for access with scoped token
+                response = self.session.get(f"https://{self.site.domain}/_edge/tenant_info", headers={"Accept": "application/json"}, verify=True)
+                if response.text:
+                    LOGGER.debug("Received HTTP payload:\n%s", response.text)
+                response.raise_for_status()
+                cloud_id = response.json()["cloudId"]
+
+                # try next-generation REST API URL
+                LOGGER.info("Probing scoped Confluence REST API URL")
+                self.api_url = f"https://api.atlassian.com/ex/confluence/{cloud_id}/"
+                url = self._build_url(ConfluenceVersion.VERSION_2, "/spaces", {"limit": "1"})
+                response = self.session.get(url, headers={"Accept": "application/json"}, verify=True)
+                if response.text:
+                    LOGGER.debug("Received HTTP payload:\n%s", response.text)
+                response.raise_for_status()
+
+                LOGGER.info("Configured scoped Confluence REST API URL: %s", self.api_url)
+            except requests.exceptions.HTTPError:
+                # fall back to classic REST API URL
+                self.api_url = f"https://{self.site.domain}{self.site.base_path}"
+                LOGGER.info("Configured classic Confluence REST API URL: %s", self.api_url)
 
     def close(self) -> None:
         self.session.close()
@@ -454,7 +520,7 @@ class ConfluenceSession:
         "Executes an HTTP request via Confluence API."
 
         url = self._build_url(version, path, query)
-        response = self.session.get(url, headers={"Accept": "application/json"})
+        response = self.session.get(url, headers={"Accept": "application/json"}, verify=True)
         if response.text:
             LOGGER.debug("Received HTTP payload:\n%s", response.text)
         response.raise_for_status()
@@ -466,7 +532,7 @@ class ConfluenceSession:
         items: list[JsonType] = []
         url = self._build_url(ConfluenceVersion.VERSION_2, path, query)
         while True:
-            response = self.session.get(url, headers={"Accept": "application/json"})
+            response = self.session.get(url, headers={"Accept": "application/json"}, verify=True)
             response.raise_for_status()
 
             payload = typing.cast(dict[str, JsonType], response.json())
@@ -502,22 +568,16 @@ class ConfluenceSession:
         "Creates a new object via Confluence REST API."
 
         url, headers, data = self._build_request(version, path, body, response_type)
-        response = self.session.post(
-            url,
-            data=data,
-            headers=headers,
-        )
+        response = self.session.post(url, data=data, headers=headers, verify=True)
+        response.raise_for_status()
         return response_cast(response_type, response)
 
     def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T:
         "Updates an existing object via Confluence REST API."
 
         url, headers, data = self._build_request(version, path, body, response_type)
-        response = self.session.put(
-            url,
-            data=data,
-            headers=headers,
-        )
+        response = self.session.put(url, data=data, headers=headers, verify=True)
+        response.raise_for_status()
         return response_cast(response_type, response)
 
     def space_id_to_key(self, id: str) -> str:
@@ -687,6 +747,7 @@ class ConfluenceSession:
                         "X-Atlassian-Token": "no-check",
                         "Accept": "application/json",
                     },
+                    verify=True,
                 )
         elif raw_data is not None:
             LOGGER.info("Uploading raw data: %s", attachment_name)
@@ -714,6 +775,7 @@ class ConfluenceSession:
                     "X-Atlassian-Token": "no-check",
                     "Accept": "application/json",
                 },
+                verify=True,
             )
         else:
             raise NotImplementedError("parameter match not exhaustive")
@@ -875,6 +937,7 @@ class ConfluenceSession:
                 "Content-Type": "application/json; charset=utf-8",
                 "Accept": "application/json",
             },
+            verify=True,
         )
         response.raise_for_status()
         return _json_to_object(ConfluencePage, response.json())
@@ -892,7 +955,7 @@ class ConfluenceSession:
         # move to trash
         url = self._build_url(ConfluenceVersion.VERSION_2, path)
         LOGGER.info("Moving page to trash: %s", page_id)
-        response = self.session.delete(url)
+        response = self.session.delete(url, verify=True)
         response.raise_for_status()
 
         if purge:
@@ -900,7 +963,7 @@ class ConfluenceSession:
             query = {"purge": "true"}
             url = self._build_url(ConfluenceVersion.VERSION_2, path, query)
             LOGGER.info("Permanently deleting page: %s", page_id)
-            response = self.session.delete(url)
+            response = self.session.delete(url, verify=True)
             response.raise_for_status()
 
     def page_exists(
@@ -935,6 +998,7 @@ class ConfluenceSession:
                 "Content-Type": "application/json; charset=utf-8",
                 "Accept": "application/json",
             },
+            verify=True,
         )
         response.raise_for_status()
         data = typing.cast(dict[str, JsonType], response.json())
@@ -999,7 +1063,7 @@ class ConfluenceSession:
             query = {"name": label.name}
 
             url = self._build_url(ConfluenceVersion.VERSION_1, path, query)
-            response = self.session.delete(url)
+            response = self.session.delete(url, verify=True)
             if response.text:
                 LOGGER.debug("Received HTTP payload:\n%s", response.text)
             response.raise_for_status()
@@ -1058,7 +1122,7 @@ class ConfluenceSession:
 
         path = f"/pages/{page_id}/properties/{property_id}"
         url = self._build_url(ConfluenceVersion.VERSION_2, path)
-        response = self.session.delete(url)
+        response = self.session.delete(url, verify=True)
         response.raise_for_status()
 
     def update_content_property_for_page(

md2conf/converter.py

@@ -21,17 +21,20 @@ from urllib.parse import ParseResult, quote_plus, urlparse
 
 import lxml.etree as ET
 from strong_typing.core import JsonType
+from strong_typing.exception import JsonTypeError
 
 from . import drawio, mermaid
 from .collection import ConfluencePageCollection
 from .csf import AC_ATTR, AC_ELEM, HTML, RI_ATTR, RI_ELEM, ParseError, elements_from_strings, elements_to_string, normalize_inline
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
+from .emoticon import emoji_to_emoticon
+from .environment import PageError
 from .extra import override, path_relative_to
 from .latex import get_png_dimensions, remove_png_chunks, render_latex
 from .markdown import markdown_to_html
+from .mermaid import MermaidConfigProperties
 from .metadata import ConfluenceSiteMetadata
-from .properties import PageError
-from .scanner import ScannedDocument, Scanner
+from .scanner import MermaidScanner, ScannedDocument, Scanner
 from .toc import TableOfContentsBuilder
 from .uri import is_absolute_url, to_uuid_urn
 from .xml import element_to_text
@@ -425,11 +428,15 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         anchor.tail = heading.text
         heading.text = None
 
-    def _warn_or_raise(self, msg: str) -> None:
+    def _anchor_warn_or_raise(self, anchor: ET._Element, msg: str) -> None:
         "Emit a warning or raise an exception when a path points to a resource that doesn't exist or is outside of the permitted hierarchy."
 
         if self.options.ignore_invalid_url:
             LOGGER.warning(msg)
+            if anchor.text:
+                anchor.text = "❌ " + anchor.text
+            elif len(anchor) > 0:
+                anchor.text = "❌ "
         else:
             raise DocumentError(msg)
 
@@ -478,7 +485,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         # look up the absolute path in the page metadata dictionary to discover the relative path within Confluence that should be used
         if not is_directory_within(absolute_path, self.root_dir):
-            self._warn_or_raise(f"relative URL {url} points to outside root path: {self.root_dir}")
+            self._anchor_warn_or_raise(anchor, f"relative URL {url} points to outside root path: {self.root_dir}")
             return None
 
         if absolute_path.suffix == ".md":
@@ -493,7 +500,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         link_metadata = self.page_metadata.get(absolute_path)
         if link_metadata is None:
-            self._warn_or_raise(f"unable to find matching page for URL: {relative_url.geturl()}")
+            self._anchor_warn_or_raise(anchor, f"unable to find matching page for URL: {relative_url.geturl()}")
             return None
 
         relative_path = os.path.relpath(absolute_path, self.base_dir)
@@ -529,7 +536,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         """
 
         if not absolute_path.exists():
-            self._warn_or_raise(f"relative URL points to non-existing file: {absolute_path}")
+            self._anchor_warn_or_raise(anchor, f"relative URL points to non-existing file: {absolute_path}")
             return None
 
         file_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
@@ -603,7 +610,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
             absolute_path = self._verify_image_path(path)
             if absolute_path is None:
-                return self._create_missing(path, attrs.caption)
+                return self._create_missing(path, attrs)
 
             if absolute_path.name.endswith(".drawio.png") or absolute_path.name.endswith(".drawio.svg"):
                 return self._transform_drawio_image(absolute_path, attrs)
@@ -630,6 +637,14 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         return AC_ELEM("image", attrs.as_dict(), *elements)
 
+    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 or is outside of the permitted hierarchy."
+
+        if self.options.ignore_invalid_url:
+            LOGGER.warning(msg)
+        else:
+            raise DocumentError(msg)
+
     def _verify_image_path(self, path: Path) -> Optional[Path]:
         "Checks whether an image path is safe to use."
 
@@ -749,30 +764,33 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             *parameters,
         )
 
-    def _create_missing(self, path: Path, caption: Optional[str]) -> ET._Element:
+    def _create_missing(self, path: Path, attrs: ImageAttributes) -> ET._Element:
         "A warning panel for a missing image."
 
-        message = HTML.p("Missing image: ", HTML.code(path.as_posix()))
-        if caption is not None:
-            content = [
-                AC_ELEM(
-                    "parameter",
-                    {AC_ATTR("name"): "title"},
-                    caption,
-                ),
-                AC_ELEM("rich-text-body", {}, message),
-            ]
-        else:
-            content = [AC_ELEM("rich-text-body", {}, message)]
+        if attrs.context is FormattingContext.BLOCK:
+            message = HTML.p("❌ Missing image: ", HTML.code(path.as_posix()))
+            if attrs.caption is not None:
+                content = [
+                    AC_ELEM(
+                        "parameter",
+                        {AC_ATTR("name"): "title"},
+                        attrs.caption,
+                    ),
+                    AC_ELEM("rich-text-body", {}, message),
+                ]
+            else:
+                content = [AC_ELEM("rich-text-body", {}, message)]
 
-        return AC_ELEM(
-            "structured-macro",
-            {
-                AC_ATTR("name"): "warning",
-                AC_ATTR("schema-version"): "1",
-            },
-            *content,
-        )
+            return AC_ELEM(
+                "structured-macro",
+                {
+                    AC_ATTR("name"): "warning",
+                    AC_ATTR("schema-version"): "1",
+                },
+                *content,
+            )
+        else:
+            return HTML.span({"style": "color: rgb(255,86,48);"}, "❌ ", HTML.code(path.as_posix()))
 
     def _transform_code_block(self, code: ET._Element) -> ET._Element:
         "Transforms a code block."
@@ -811,6 +829,15 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             AC_ELEM("plain-text-body", ET.CDATA(content)),
         )
 
+    def _extract_mermaid_config(self, content: str) -> Optional[MermaidConfigProperties]:
+        """Extract scale from Mermaid YAML front matter configuration."""
+        try:
+            properties = MermaidScanner().read(content)
+            return properties.config
+        except JsonTypeError as ex:
+            LOGGER.warning("Failed to extract Mermaid properties: %s", ex)
+            return None
+
     def _transform_external_mermaid(self, absolute_path: Path, attrs: ImageAttributes) -> ET._Element:
         "Emits Confluence Storage Format XHTML for a Mermaid diagram read from an external file."
 
@@ -821,7 +848,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if self.options.render_mermaid:
             with open(absolute_path, "r", encoding="utf-8") as f:
                 content = f.read()
-            image_data = mermaid.render_diagram(content, self.options.diagram_output_format)
+            config = self._extract_mermaid_config(content)
+            image_data = mermaid.render_diagram(content, self.options.diagram_output_format, config=config)
             image_filename = attachment_name(relative_path.with_suffix(f".{self.options.diagram_output_format}"))
             self.embedded_files[image_filename] = EmbeddedFileData(image_data, attrs.alt)
             return self._create_attached_image(image_filename, attrs)
@@ -834,7 +862,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         "Emits Confluence Storage Format XHTML for a Mermaid diagram defined in a fenced code block."
 
         if self.options.render_mermaid:
-            image_data = mermaid.render_diagram(content, self.options.diagram_output_format)
+            config = self._extract_mermaid_config(content)
+            image_data = mermaid.render_diagram(content, self.options.diagram_output_format, config=config)
             image_hash = hashlib.md5(image_data).hexdigest()
             image_filename = attachment_name(f"embedded_{image_hash}.{self.options.diagram_output_format}")
             self.embedded_files[image_filename] = EmbeddedFileData(image_data)
@@ -1057,7 +1086,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             AC_ELEM("rich-text-body", {}, *list(blockquote)),
         )
 
-    def _transform_section(self, details: ET._Element) -> ET._Element:
+    def _transform_collapsed(self, details: ET._Element) -> ET._Element:
         """
         Creates a collapsed section.
 
@@ -1115,11 +1144,15 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         unicode = elem.get("data-unicode", None)
         alt = elem.text or ""
 
+        # emoji with a matching emoticon:
         # <ac:emoticon ac:name="wink" ac:emoji-shortname=":wink:" ac:emoji-id="1f609" ac:emoji-fallback="&#128521;"/>
+        #
+        # emoji without a corresponding emoticon:
+        # <ac:emoticon ac:name="blue-star" ac:emoji-shortname=":shield:" ac:emoji-id="1f6e1" ac:emoji-fallback="&#128737;"/>
         return AC_ELEM(
             "emoticon",
             {
-                AC_ATTR("name"): shortname,
+                AC_ATTR("name"): emoji_to_emoticon(shortname),
                 AC_ATTR("emoji-shortname"): f":{shortname}:",
                 AC_ATTR("emoji-id"): unicode,
                 AC_ATTR("emoji-fallback"): alt,
@@ -1240,7 +1273,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         Transforms a footnote reference.
 
         ```
-        <sup id="fnref:NAME"><a class="footnote-ref" href="#fn:NAME">1</a></sup>
+        <sup id="fnref:NAME"><a class="footnote-ref" href="#fn:NAME">REF</a></sup>
         ```
         """
 
@@ -1498,7 +1531,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         # ...
         # </details>
         elif child.tag == "details" and len(child) > 1 and child[0].tag == "summary":
-            return self._transform_section(child)
+            return self._transform_collapsed(child)
 
         # <ol>...</ol>
         elif child.tag == "ol":
@@ -1526,6 +1559,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         # <table>...</table>
         elif child.tag == "table":
+            for td in child.iterdescendants("td", "th"):
+                normalize_inline(td)
             child.set("data-layout", "default")
             return None
 

md2conf/csf.py

@@ -152,7 +152,7 @@ def elements_to_string(root: ET._Element) -> str:
 
 
 def is_block_like(elem: ET._Element) -> bool:
-    return elem.tag in ["div", "li", "ol", "p", "pre", "ul"]
+    return elem.tag in ["div", "li", "ol", "p", "pre", "td", "th", "ul"]
 
 
 def normalize_inline(elem: ET._Element) -> None:

md2conf/emoticon.py

@@ -0,0 +1,22 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+_EMOJI_TO_EMOTICON = {
+    "grinning": "laugh",
+    "heart": "heart",
+    "slight_frown": "sad",
+    "slight_smile": "smile",
+    "stuck_out_tongue": "cheeky",
+    "thumbsdown": "thumbs-down",
+    "thumbsup": "thumbs-up",
+    "wink": "wink",
+}
+
+
+def emoji_to_emoticon(shortname: str) -> str:
+    return _EMOJI_TO_EMOTICON.get(shortname) or "blue-star"

md2conf/mermaid.py

@@ -11,11 +11,23 @@ import os
 import os.path
 import shutil
 import subprocess
-from typing import Literal
+from dataclasses import dataclass
+from typing import Literal, Optional
 
 LOGGER = logging.getLogger(__name__)
 
 
+@dataclass
+class MermaidConfigProperties:
+    """
+    Configuration options for rendering Mermaid diagrams.
+
+    :param scale: Scaling factor for the rendered diagram.
+    """
+
+    scale: Optional[float] = None
+
+
 def is_docker() -> bool:
     "True if the application is running in a Docker container."
 
@@ -44,9 +56,12 @@ def has_mmdc() -> bool:
     return shutil.which(executable) is not None
 
 
-def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") -> bytes:
+def render_diagram(source: str, output_format: Literal["png", "svg"] = "png", config: Optional[MermaidConfigProperties] = None) -> bytes:
     "Generates a PNG or SVG image from a Mermaid diagram source."
 
+    if config is None:
+        config = MermaidConfigProperties()
+
     cmd = [
         get_mmdc(),
         "--input",
@@ -58,7 +73,7 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") ->
         "--backgroundColor",
         "transparent",
         "--scale",
-        "2",
+        str(config.scale or 2),
     ]
     root = os.path.dirname(__file__)
     if is_docker():

md2conf/processor.py

@@ -16,9 +16,9 @@ from typing import Iterable, Optional
 from .collection import ConfluencePageCollection
 from .converter import ConfluenceDocument
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
+from .environment import ArgumentError
 from .matcher import DirectoryEntry, FileEntry, Matcher, MatcherOptions
 from .metadata import ConfluenceSiteMetadata
-from .properties import ArgumentError
 from .scanner import Scanner
 
 LOGGER = logging.getLogger(__name__)

md2conf/{application.py → publisher.py}

@@ -14,10 +14,10 @@ from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession,
 from .converter import ConfluenceDocument, attachment_name, get_volatile_attributes, get_volatile_elements
 from .csf import AC_ATTR, elements_from_string
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
+from .environment import PageError
 from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
-from .properties import PageError
 from .xml import is_xml_equal, unwrap_substitute
 
 LOGGER = logging.getLogger(__name__)
@@ -73,20 +73,23 @@ class SynchronizingProcessor(Processor):
             # verify if page exists
             page = self.api.get_page_properties(node.page_id)
             update = False
-        elif node.title is not None:
-            # look up page by title
-            page = self.api.get_or_create_page(node.title, parent_id.page_id)
+        else:
+            if node.title is not None:
+                # use title extracted from source metadata
+                title = node.title
+            else:
+                # assign an auto-generated title
+                digest = self._generate_hash(node.absolute_path)
+                title = f"{node.absolute_path.stem} [{digest}]"
+
+            # look up page by (possibly auto-generated) title
+            page = self.api.get_or_create_page(title, parent_id.page_id)
 
             if page.status is ConfluenceStatus.ARCHIVED:
+                # user has archived a page with this (auto-generated) title
                 raise PageError(f"unable to update archived page with ID {page.id}")
 
             update = True
-        else:
-            # always create a new page
-            digest = self._generate_hash(node.absolute_path)
-            title = f"{node.absolute_path.stem} [{digest}]"
-            page = self.api.create_page(parent_id.page_id, title, "")
-            update = True
 
         space_key = self.api.space_id_to_key(page.spaceId)
         if update:
@@ -215,7 +218,7 @@ class SynchronizingProcessorFactory(ProcessorFactory):
         return SynchronizingProcessor(self.api, self.options, root_dir)
 
 
-class Application(Converter):
+class Publisher(Converter):
     """
     The entry point for Markdown to Confluence conversion.
 

md2conf/scanner.py

@@ -15,6 +15,8 @@ import yaml
 from strong_typing.core import JsonType
 from strong_typing.serialization import DeserializerOptions, json_to_object
 
+from .mermaid import MermaidConfigProperties
+
 T = TypeVar("T")
 
 
@@ -155,3 +157,47 @@ class Scanner:
             properties=properties,
             text=text,
         )
+
+
+@dataclass
+class MermaidProperties:
+    """
+    An object that holds the front-matter properties structure for Mermaid diagrams.
+
+    :param title: The title of the diagram.
+    :param config: Configuration options for rendering.
+    """
+
+    title: Optional[str] = None
+    config: Optional[MermaidConfigProperties] = None
+
+
+class MermaidScanner:
+    """
+    Extracts properties from the JSON/YAML front-matter of a Mermaid diagram.
+    """
+
+    def read(self, content: str) -> MermaidProperties:
+        """
+        Extracts rendering preferences from a Mermaid front-matter content.
+
+        ```
+        ---
+        title: Tiny flow diagram
+        config:
+            scale: 1
+        ---
+        flowchart LR
+            A[Component A] --> B[Component B]
+            B --> C[Component C]
+        ```
+        """
+
+        properties, text = extract_frontmatter_properties(content)
+        if properties is not None:
+            front_matter = _json_to_object(MermaidProperties, properties)
+            config = front_matter.config or MermaidConfigProperties()
+
+            return MermaidProperties(title=front_matter.title, config=config)
+
+        return MermaidProperties()