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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.4.5
+Version: 0.4.7
 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.
@@ -559,6 +581,9 @@ 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.
 ```
 
 ### Using the Docker container

markdown_to_confluence-0.4.7.dist-info/RECORD

@@ -0,0 +1,34 @@
+markdown_to_confluence-0.4.7.dist-info/licenses/LICENSE,sha256=56L-Y0dyZwyVlINRJRz3PNw-ka-oLVaAq-7d8zo6qlc,1077
+md2conf/__init__.py,sha256=3R4-8WktKk6Q4JGEjAHqEU8S4u_w39RdcpBl-yL-0Tc,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=wghwaa_07cN-xXY1DIOJgy6VJjfnJWDjbT4aB5NAL08,68845
+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.7.dist-info/METADATA,sha256=iHeyUxkIuoI9_g9dvCLlxC4BCqnH3JStloGAfP-bWsY,34628
+markdown_to_confluence-0.4.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.4.7.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.4.7.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.4.7.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.4.7.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.7"
 __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):
@@ -45,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):
@@ -68,36 +71,12 @@ 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,
         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
@@ -112,7 +91,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 +106,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 +206,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 +244,31 @@ def main() -> None:
         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
+
+
+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)
 
@@ -294,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
@@ -316,7 +314,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 +330,7 @@ def main() -> None:
             parser.error(str(e))
         try:
             with ConfluenceAPI(properties) as api:
-                Application(
+                Publisher(
                     api,
                     options,
                 ).process(args.mdpath)