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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.4.6
+Version: 0.4.8
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -26,20 +26,20 @@ 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: markdown>=3.9
 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"
+Requires-Dist: typing-extensions>=4.15; python_version < "3.12"
 Provides-Extra: dev
-Requires-Dist: markdown_doc>=0.1.4; python_version >= "3.10" and extra == "dev"
-Requires-Dist: types-lxml>=2025.3.30; extra == "dev"
-Requires-Dist: types-markdown>=3.8; extra == "dev"
+Requires-Dist: markdown_doc>=0.1.5; python_version >= "3.10" and extra == "dev"
+Requires-Dist: types-lxml>=2025.8.25; extra == "dev"
+Requires-Dist: types-markdown>=3.9; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Requires-Dist: types-requests>=2.32; extra == "dev"
-Requires-Dist: mypy>=1.16; extra == "dev"
-Requires-Dist: ruff>=0.12; extra == "dev"
+Requires-Dist: mypy>=1.18; extra == "dev"
+Requires-Dist: ruff>=0.13; extra == "dev"
 Provides-Extra: formulas
 Requires-Dist: matplotlib>=3.9; extra == "formulas"
 Dynamic: license-file
@@ -425,9 +425,9 @@ Use the pseudo-language `csf` in a Markdown code block to pass content directly
 
 ### Ignoring files
 
-Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax (and constraints) 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.
+Skip files and subdirectories in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax (and constraints) 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.
+Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into. To skip an entire directory, add the name of the directory without a trailing `/`.
 
 Relative paths to items in a nested directory are not supported. You must put `.mdignore` in the same directory where the items to be skipped reside.
 
@@ -501,7 +501,7 @@ You can add [Mermaid diagrams](https://mermaid.js.org/) to your Markdown documen
 
 *md2conf* offers two options to publish the diagram:
 
-1. Pre-render into an image (command-line option `--render-mermaid`). The source file or 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.
+1. Pre-render into an image (command-line option `--render-mermaid`). The source file or 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.
 2. Display on demand (command-line option `--no-render-mermaid`). The code block is transformed into a [diagram macro](https://stratus-addons.atlassian.net/wiki/spaces/MDFC/overview), which is processed by Confluence. You need a separate [marketplace app](https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence) to turn macro definitions into images when a Confluence page is visited.
 
 If you are running into issues with the pre-rendering approach (e.g. misaligned labels in the generated image), verify if `mermaid-cli` can process the Mermaid source:
@@ -512,6 +512,14 @@ mmdc -i sample.mmd -o sample.png -b transparent --scale 2
 
 Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
 
+Note that `mermaid-cli` has some implicit dependencies (e.g. a headless browser) that may not be immediately available in a CI/CD environment such as GitHub Actions. Refer to the `Dockerfile` in the *md2conf* project root, or [mermaid-cli documentation](https://github.com/mermaid-js/mermaid-cli) on how to install these dependencies such as a `chromium-browser` and various fonts.
+
+### Alignment
+
+You can configure diagram and image alignment using the JSON/YAML front-matter attribute `alignment` or the command-line argument of the same name. Possible values are `center` (default), `left` and `right`. The value configured in the Markdown file front-matter takes precedence.
+
+Unfortunately, not every third-party app supports every alignment variant. For example, the draw\.io marketplace app supports left and center but not right alignment; and diagrams produced by the Mermaid marketplace app are always centered, ignoring the setting for alignment.
+
 ### Links to attachments
 
 If *md2conf* encounters a Markdown link that points to a file in the directory hierarchy being synchronized, it automatically uploads the file as an attachment to the Confluence page. Activating the link in Confluence downloads the file. Typical examples include PDFs (`*.pdf`), word processor documents (`*.docx`), spreadsheets (`*.xlsx`), plain text files (`*.txt`) or logs (`*.log`). The MIME type is set based on the file type.
@@ -581,8 +589,17 @@ options:
   --headers KEY=VALUE [KEY=VALUE ...]
                         Apply custom headers to all Confluence API requests.
   --webui-links         Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)
+  --alignment {center,left,right}
+                        Alignment for block-level images and formulas (default: 'center').
+  --use-panel           Transform admonitions and alerts into a Confluence custom panel.
 ```
 
+### 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.
+
+If you are restricted to an environment with Confluence REST API v1, we recommend *md2conf* [version 0.2.7](https://pypi.org/project/markdown-to-confluence/0.2.7/). Even though we don't actively support it, we are not aware of any major issues, making it a viable option in an on-premise environment with only Confluence REST API v1 support.
+
 ### Using the Docker container
 
 You can run the Docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options. The final argument `./` corresponds to `mdpath` in the command-line utility.

markdown_to_confluence-0.4.8.dist-info/RECORD

@@ -0,0 +1,34 @@
+markdown_to_confluence-0.4.8.dist-info/licenses/LICENSE,sha256=56L-Y0dyZwyVlINRJRz3PNw-ka-oLVaAq-7d8zo6qlc,1077
+md2conf/__init__.py,sha256=TJ8zRe5RlBILNw8pD-Rt3pUrUYCUfh8o4qSdv3ulu2U,402
+md2conf/__main__.py,sha256=pp3Zi60gmhXRqK0uoR4lZMVLlOO8ryAmk8UMPiI-Cew,11527
+md2conf/api.py,sha256=uEPMcR4B-07MMFM96m92z7Znnj7pzhkLLAGcOIseERY,41398
+md2conf/collection.py,sha256=EobgMRJgkYloWlY03NZJ52MRC_SGLpTVCHkltDbQyt0,837
+md2conf/converter.py,sha256=WMtwfnU50-y-LyENbaxKI7Br9gmoLxBCIZIvpeXxli8,69532
+md2conf/csf.py,sha256=rugs3qC2aJQCJSTczeBw9WhqSZZtMq14LjwT0V1b6Hc,6476
+md2conf/domain.py,sha256=rN6QSuoP3JMj-WE8BAggHqHEO8nJbnQDf0b0uhStNZk,2221
+md2conf/drawio.py,sha256=0FoCl0BWxyxO-KLPlDZPyYvSTRpgu9Z6yFKl10TGGMI,8594
+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=i5C_ZqsBG_Df1bNoMJpAKpiYMFcMEn5aoAv6bdSsE1k,7674
+md2conf/local.py,sha256=mvp2kA_eo6JUQ_rlM7zDdEFgBPVxMr3VKP_X1nsLjHE,3747
+md2conf/markdown.py,sha256=czabU17tUfhSX1JQGiI_TrMrTmtoVThOwFu_To_Oi_w,3176
+md2conf/matcher.py,sha256=8g2yiKXfEkYJPIvKD2cswTG9BxFY24BtVcPgKaEVAs8,6812
+md2conf/mermaid.py,sha256=hGrITJVvhHprjQVoezQ1nQeo6a_lqNihF8L-oJ4t5rc,2633
+md2conf/metadata.py,sha256=LzZM-oPNnzCULmLhF516tPlV5zZBknccwMHt8Nan-xg,1007
+md2conf/processor.py,sha256=G1icOxYsPAOjK4fnVdA-vwTsRiZMBpEAmMPOwfOebtQ,9733
+md2conf/publisher.py,sha256=V4TzmrJ5LAv61EPpDYUGWv_6KHb-BcDjtYdByNt6su8,8665
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/scanner.py,sha256=O4iOgmSqTe1CYgmdaiF1QyAESzA4SRNEKVY9gOodXDY,7035
+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=SpFfcfZm1BPbB4zZM2UC1K-GkzHRhFiotiPMPt5_XPI,5541
+markdown_to_confluence-0.4.8.dist-info/METADATA,sha256=9qSXRbEN4QV6hAhzdIQAW_Bj8iW__Go_vhqBbVFrAJE,36555
+markdown_to_confluence-0.4.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.4.8.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.4.8.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.4.8.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.4.8.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.6"
+__version__ = "0.4.8"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -46,6 +46,8 @@ class Arguments(argparse.Namespace):
     local: bool
     headers: dict[str, str]
     webui_links: bool
+    alignment: Literal["center", "left", "right"]
+    use_panel: bool
 
 
 class KwargsAppendAction(argparse.Action):
@@ -74,7 +76,7 @@ class PositionalOnlyHelpFormatter(argparse.HelpFormatter):
         self,
         usage: Optional[str],
         actions: Iterable[argparse.Action],
-        groups: Iterable[argparse._MutuallyExclusiveGroup],
+        groups: Iterable[argparse._MutuallyExclusiveGroup],  # pyright: ignore[reportPrivateUsage]
         prefix: Optional[str],
     ) -> str:
         # filter only positional arguments
@@ -242,6 +244,19 @@ def get_parser() -> argparse.ArgumentParser:
         default=False,
         help="Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)",
     )
+    parser.add_argument(
+        "--alignment",
+        dest="alignment",
+        choices=["center", "left", "right"],
+        default="center",
+        help="Alignment for block-level images and formulas (default: 'center').",
+    )
+    parser.add_argument(
+        "--use-panel",
+        action="store_true",
+        default=False,
+        help="Transform admonitions and alerts into a Confluence custom panel.",
+    )
     return parser
 
 
@@ -275,6 +290,8 @@ def main() -> None:
         render_latex=args.render_latex,
         diagram_output_format=args.diagram_output_format,
         webui_links=args.webui_links,
+        alignment=args.alignment,
+        use_panel=args.use_panel,
     )
     if args.local:
         from .local import LocalConverter

md2conf/api.py

@@ -17,7 +17,7 @@ import typing
 from dataclasses import dataclass
 from pathlib import Path
 from types import TracebackType
-from typing import Any, Optional, TypeVar
+from typing import Any, Optional, TypeVar, overload
 from urllib.parse import urlencode, urlparse, urlunparse
 
 import requests
@@ -71,16 +71,24 @@ def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
 LOGGER = logging.getLogger(__name__)
 
 
-def response_cast(response_type: type[T], response: requests.Response) -> T:
+@overload
+def response_cast(response_type: None, response: requests.Response) -> None: ...
+
+
+@overload
+def response_cast(response_type: type[T], response: requests.Response) -> T: ...
+
+
+def response_cast(response_type: Optional[type[T]], response: requests.Response) -> Optional[T]:
     "Converts a response body into the expected type."
 
     if response.text:
         LOGGER.debug("Received HTTP payload:\n%s", response.text)
     response.raise_for_status()
-    if response_type is not type(None):
-        return _json_to_object(response_type, response.json())
-    else:
+    if response_type is None:
         return None
+    else:
+        return _json_to_object(response_type, response.json())
 
 
 @enum.unique
@@ -450,7 +458,7 @@ class ConfluenceSession:
 
             if not domain or not base_path:
                 data = self._get(ConfluenceVersion.VERSION_2, "/spaces", ConfluenceResultSet, query={"limit": "1"})
-                base_url = data._links.base
+                base_url = data._links.base  # pyright: ignore[reportPrivateUsage]
 
                 _, domain, base_path, _, _, _ = urlparse(base_url)
                 if not base_path.endswith("/"):
@@ -548,23 +556,23 @@ class ConfluenceSession:
 
         return items
 
-    def _build_request(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> tuple[str, dict[str, str], bytes]:
+    def _build_request(self, version: ConfluenceVersion, path: str, body: Any, response_type: Optional[type[T]]) -> tuple[str, dict[str, str], bytes]:
         "Generates URL, headers and raw payload for a typed request/response."
 
         url = self._build_url(version, path)
-        if response_type is not type(None):
-            headers = {
-                "Content-Type": "application/json; charset=utf-8",
-                "Accept": "application/json",
-            }
-        else:
-            headers = {
-                "Content-Type": "application/json; charset=utf-8",
-            }
+        headers = {"Content-Type": "application/json"}
+        if response_type is not None:
+            headers["Accept"] = "application/json"
         data = json_dump_string(object_to_json(body)).encode("utf-8")
         return url, headers, data
 
-    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T:
+    @overload
+    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: None) -> None: ...
+
+    @overload
+    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T: ...
+
+    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: Optional[type[T]]) -> Optional[T]:
         "Creates a new object via Confluence REST API."
 
         url, headers, data = self._build_request(version, path, body, response_type)
@@ -572,7 +580,13 @@ class ConfluenceSession:
         response.raise_for_status()
         return response_cast(response_type, response)
 
-    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T:
+    @overload
+    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: None) -> None: ...
+
+    @overload
+    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T: ...
+
+    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: Optional[type[T]]) -> Optional[T]:
         "Updates an existing object via Confluence REST API."
 
         url, headers, data = self._build_request(version, path, body, response_type)
@@ -806,7 +820,7 @@ class ConfluenceSession:
         )
 
         LOGGER.info("Updating attachment: %s", attachment_id)
-        self._put(ConfluenceVersion.VERSION_1, path, request, type(None))
+        self._put(ConfluenceVersion.VERSION_1, path, request, None)
 
     def get_page_properties_by_title(
         self,
@@ -899,7 +913,7 @@ class ConfluenceSession:
             version=ConfluenceContentVersion(number=version, minorEdit=True),
         )
         LOGGER.info("Updating page: %s", page_id)
-        self._put(ConfluenceVersion.VERSION_2, path, request, type(None))
+        self._put(ConfluenceVersion.VERSION_2, path, request, None)
 
     def create_page(
         self,
@@ -934,7 +948,7 @@ class ConfluenceSession:
             url,
             data=json_dump_string(object_to_json(request)).encode("utf-8"),
             headers={
-                "Content-Type": "application/json; charset=utf-8",
+                "Content-Type": "application/json",
                 "Accept": "application/json",
             },
             verify=True,
@@ -995,7 +1009,7 @@ class ConfluenceSession:
             url,
             params=query,
             headers={
-                "Content-Type": "application/json; charset=utf-8",
+                "Content-Type": "application/json",
                 "Accept": "application/json",
             },
             verify=True,
@@ -1048,7 +1062,7 @@ class ConfluenceSession:
         """
 
         path = f"/content/{page_id}/label"
-        self._post(ConfluenceVersion.VERSION_1, path, labels, type(None))
+        self._post(ConfluenceVersion.VERSION_1, path, labels, None)
 
     def remove_labels(self, page_id: str, labels: list[ConfluenceLabel]) -> None:
         """