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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.5.0
+Version: 0.5.2
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -26,18 +26,19 @@ License-File: LICENSE
 Requires-Dist: cattrs>=25.3
 Requires-Dist: lxml>=6.0
 Requires-Dist: markdown>=3.10
-Requires-Dist: pymdown-extensions>=10.17
+Requires-Dist: orjson>=3.11
+Requires-Dist: pymdown-extensions>=10.19
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: truststore>=0.10
 Requires-Dist: typing-extensions>=4.15; python_version < "3.12"
 Provides-Extra: dev
-Requires-Dist: markdown_doc>=0.1.5; extra == "dev"
-Requires-Dist: types-lxml>=2025.8.25; extra == "dev"
+Requires-Dist: markdown_doc>=0.1.6; extra == "dev"
+Requires-Dist: types-lxml>=2025.11.25; extra == "dev"
 Requires-Dist: types-markdown>=3.10; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Requires-Dist: types-requests>=2.32; extra == "dev"
-Requires-Dist: mypy>=1.18; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
 Requires-Dist: ruff>=0.14; extra == "dev"
 Provides-Extra: formulas
 Requires-Dist: matplotlib>=3.9; extra == "formulas"
@@ -214,6 +215,19 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+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*
+
+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.
+
+It can be used with the CLI `--generated-by` option or directly in the files:
+
+```markdown
+<!-- generated-by: Do not edit! Check out the file %{filepath} in the repo -->
+```
+
 ### Publishing a single page
 
 *md2conf* has two modes of operation: *single-page mode* and *directory mode*.
@@ -454,6 +468,58 @@ This is useful if you have a page in a hierarchy that participates in parent-chi
 
 If the `title` attribute (in the front-matter) or the topmost unique heading (in the document body) changes, the Confluence page title is updated. A warning is raised if the new title conflicts with the title of another page, and thus cannot be updated.
 
+#### Avoiding duplicate titles
+
+By default, when *md2conf* extracts a page title from the first unique heading in a Markdown document, the heading remains in the document body. This means the title appears twice on the Confluence page: once as the page title at the top, and once as the first heading in the content.
+
+To avoid this duplication, use the `--skip-title-heading` option. When enabled, *md2conf* removes the first heading from the document body if it was used as the page title. This option only takes effect when:
+
+1. The title was extracted from the document's first unique heading (not from front-matter), AND
+2. There is exactly one top-level heading in the document.
+
+If the title comes from the `title` attribute in front-matter, the heading is preserved in the document body regardless of this setting, as the heading and title are considered separate.
+
+**Example without `--skip-title-heading` (default):**
+
+Markdown:
+```markdown
+# Installation Guide
+
+Follow these steps...
+```
+
+Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts with heading "Installation Guide", followed by "Follow these steps..."
+
+**Example with `--skip-title-heading`:**
+
+Same Markdown source, but Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts directly with "Follow these steps..." (heading removed)
+
+**Edge case: Abstract or introductory text before the title:**
+
+When a document has content before the first heading (like an abstract), removing the heading eliminates the visual separator between the introductory text and the main content:
+
+```markdown
+This is an abstract paragraph providing context.
+
+# Document Title
+
+This is the main document content.
+```
+
+With `--skip-title-heading`, the output becomes:
+- Page title: "Document Title"
+- Content: "This is an abstract paragraph..." flows directly into "This is the main document content..." (no heading separator)
+
+While the structure remains semantically correct, the visual separation is lost. If you need to maintain separation, consider these workarounds:
+
+1. **Use a horizontal rule:** Add `---` after the abstract to create visual separation
+2. **Use an admonition block:** Wrap the abstract in an info/note block
+3. **Use front-matter title:** Set `title` in front-matter to keep the heading in the body
+
 ### Labels
 
 If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
@@ -570,7 +636,7 @@ options:
   -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
   --keep-hierarchy      Maintain source directory structure when exporting to Confluence.
   --flatten-hierarchy   Flatten directories with no index.md or README.md when exporting to Confluence.
-  --generated-by GENERATED_BY
+  --generated-by MARKDOWN
                         Add prompt to pages (default: 'This page has been generated with a tool.').
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.
   --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.)
@@ -581,16 +647,24 @@ 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').
+  --prefer-raster       Prefer PNG over SVG when both exist (default: enabled).
+  --no-prefer-raster    Use SVG files directly instead of preferring PNG equivalents.
   --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.
-  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
-  --headers KEY=VALUE [KEY=VALUE ...]
-                        Apply custom headers to all Confluence API requests.
+  --skip-title-heading  Skip the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).
+  --no-skip-title-heading
+                        Keep the first heading in document body even when used as page title (default).
+  --title-prefix TEXT   String to prepend to Confluence page title for each published page.
   --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').
+  --max-image-width MAX_IMAGE_WIDTH
+                        Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.
   --use-panel           Transform admonitions and alerts into a Confluence custom panel.
+  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
+  --headers KEY=VALUE [KEY=VALUE ...]
+                        Apply custom headers to all Confluence API requests.
 ```
 
 ### Confluence REST API v1 vs. v2

{markdown_to_confluence-0.5.0.dist-info → markdown_to_confluence-0.5.2.dist-info}/RECORD

@@ -1,35 +1,36 @@
-markdown_to_confluence-0.5.0.dist-info/licenses/LICENSE,sha256=56L-Y0dyZwyVlINRJRz3PNw-ka-oLVaAq-7d8zo6qlc,1077
-md2conf/__init__.py,sha256=Ec01qZ3V1WkyzOh0MJegHd4kdvDCJhS5KjwuCfk_BRs,402
-md2conf/__main__.py,sha256=ZAwZ2YqKUxKiVx8CQsrnso9z2deP5Xn80kqqf2o3AbY,11472
-md2conf/api.py,sha256=yFDsE_5IpCXG4z24ZrxF8QjF07ep3HiBHqaWKcGKf1k,40731
+markdown_to_confluence-0.5.2.dist-info/licenses/LICENSE,sha256=56L-Y0dyZwyVlINRJRz3PNw-ka-oLVaAq-7d8zo6qlc,1077
+md2conf/__init__.py,sha256=TZU4q64xgFKmFudp0-NIfMbAgcFihMCih-5sjAybGKs,402
+md2conf/__main__.py,sha256=GdYd7v6YpIbOcvaUNh_5TZXwnEGbaxlsIS0sJtMmyhE,13152
+md2conf/api.py,sha256=v4QXiNFGHyIhYZWb36uG-AR4HBPoj2GZI939ao9SOIQ,41989
 md2conf/collection.py,sha256=nghFS5kK4kPbpLE7IHi4rprJK-Mu4KXNxjHYM9Rc5SQ,824
-md2conf/converter.py,sha256=BM94de0CAQGXOTSve7_042y3VF_yu77NITX5FUUeJPQ,69446
+md2conf/converter.py,sha256=S6JiC-v5jqEVv4lcvCKxfLO-dZpHNLEfuocFBslIpaA,79924
 md2conf/csf.py,sha256=rugs3qC2aJQCJSTczeBw9WhqSZZtMq14LjwT0V1b6Hc,6476
-md2conf/domain.py,sha256=EsaAfUaT2qIrK91uRyxaPEY4kSq-nzhccErxVqHdooc,2205
+md2conf/domain.py,sha256=opq_O_NOz097HC4Q8VA7aNba6Snq09euTCi-Ag-bvAo,2685
 md2conf/drawio.py,sha256=IqFlAegrKM5SQf5CqHD8STIzskH7Rpm9RtWwn_nXVTc,8581
 md2conf/emoticon.py,sha256=P2L5oQvnRXeVifJQ3sJ2Ck-6ptbxumq2vsT-rM0W0Ms,484
 md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
 md2conf/environment.py,sha256=BhI7YktY7G26HOhGlUvTkH2Vmfa4E_dhu2snzbBgMvE,3902
 md2conf/extra.py,sha256=VuMxuOnnC2Qwy6y52ukIxsaYhrZArRqMmRHRE4QZl8g,687
-md2conf/latex.py,sha256=3eFgsvaq6ROAc2skW1Wq21CX_pJai1Yc9t861Z3s5XA,7600
+md2conf/latex.py,sha256=vZJakhwiSPkprz5IkJZOUw9H4FVXj_kksgMKoF8N_pI,7747
 md2conf/local.py,sha256=Ou-j7kZWbHxC8Si8Yg7myqtTQ1He6mYQW1NpX3LLIcY,3704
 md2conf/markdown.py,sha256=t-z19Zs_91_jzRvwmOsWqCDt0Tdghmk5bpNUON0YlKc,3148
 md2conf/matcher.py,sha256=hkM49osFM9nrXRXe4pwcGCg0rrLsmKep7AYY_S01kNY,6774
 md2conf/mermaid.py,sha256=9P4VV69dooaFBNUjdTIpzq7BFA8rDMqEif1O7XKWPdM,2617
 md2conf/metadata.py,sha256=_kt_lh4gCzVRRhhrDk-cJCk9WMcX9ZDWB6hL0Lw3xoI,976
 md2conf/processor.py,sha256=8Y-NSxAuqSHMSN9vhw_83HisGAmq87XAY98dis_xZ0Y,9690
-md2conf/publisher.py,sha256=yI7gObPZLrNEXbiPKBJwkBPcGLI17UwzKd8FQe3U8bE,8634
+md2conf/publisher.py,sha256=ma0E_Kcxd86Qe_ywdhiTydkoJFRp6MI_Hy2ImFMKWsA,8752
 md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
 md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-md2conf/scanner.py,sha256=o46fTQXuTpbtvpnQPW3CW4ydIb5bM362K2TFpwO51P0,6782
-md2conf/serializer.py,sha256=fRpbGUH_6liMDNeJl0LikgpSytle-7o4o3zE339592U,1343
+md2conf/scanner.py,sha256=xxzNm3IRnlS0yAkStTHCigeLd6hUyvMYIBKFpTBEPf4,6776
+md2conf/serializer.py,sha256=JrBj8Z9zP8PjBeVAlRRqnMKDoz6IvkRbTd6K-JgFVow,1757
+md2conf/svg.py,sha256=LImoEKerVdXGkTnR6SogKvsR7WJNDVvMN1Ju_usbrNs,10306
 md2conf/text.py,sha256=fHOrUaPXAjE4iRhHqFq-CiI-knpo4wvyHCWp0crewqA,1736
 md2conf/toc.py,sha256=ZrfUfTv_Jiv27G4SBNjK3b-1ClYKoqN5yPRsEWp6IXk,2413
 md2conf/uri.py,sha256=KbLBdRFtZTQTZd8b4j0LtE8Pb68Ly0WkemF4iW-EAB4,1158
 md2conf/xml.py,sha256=Fu00Eg8c0VgMHIjRDBJBSNWtui8obEtowkiR7gHTduM,5526
-markdown_to_confluence-0.5.0.dist-info/METADATA,sha256=1Dm2_wAu9FaYnxv5haqzq8XLND4QC3o823C5f6-0a_4,36435
-markdown_to_confluence-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-markdown_to_confluence-0.5.0.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.5.0.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.5.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.5.0.dist-info/RECORD,,
+markdown_to_confluence-0.5.2.dist-info/METADATA,sha256=fts0cqy6A_o_QztqMmfVGWoY1kLEDftLNPKGhPsoMQo,40071
+markdown_to_confluence-0.5.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.5.2.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.5.2.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.5.2.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.5.2.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.5.0"
+__version__ = "0.5.2"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -34,11 +34,14 @@ class Arguments(argparse.Namespace):
     api_key: str | None
     space: str | None
     loglevel: str
-    ignore_invalid_url: bool
     heading_anchors: bool
+    ignore_invalid_url: bool
     root_page: str | None
     keep_hierarchy: bool
+    skip_title_heading: bool
+    title_prefix: str | None
     generated_by: str | None
+    prefer_raster: bool
     render_drawio: bool
     render_mermaid: bool
     render_latex: bool
@@ -47,6 +50,7 @@ class Arguments(argparse.Namespace):
     headers: dict[str, str]
     webui_links: bool
     alignment: Literal["center", "left", "right"]
+    max_image_width: int | None
     use_panel: bool
 
 
@@ -151,6 +155,7 @@ def get_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--generated-by",
         default="This page has been generated with a tool.",
+        metavar="MARKDOWN",
         help="Add prompt to pages (default: 'This page has been generated with a tool.').",
     )
     parser.add_argument(
@@ -206,6 +211,19 @@ def get_parser() -> argparse.ArgumentParser:
         default="png",
         help="Format for rendering Mermaid and draw.io diagrams (default: 'png').",
     )
+    parser.add_argument(
+        "--prefer-raster",
+        dest="prefer_raster",
+        action="store_true",
+        default=True,
+        help="Prefer PNG over SVG when both exist (default: enabled).",
+    )
+    parser.add_argument(
+        "--no-prefer-raster",
+        dest="prefer_raster",
+        action="store_false",
+        help="Use SVG files directly instead of preferring PNG equivalents.",
+    )
     parser.add_argument(
         "--heading-anchors",
         action="store_true",
@@ -225,18 +243,22 @@ def get_parser() -> argparse.ArgumentParser:
         help="Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.",
     )
     parser.add_argument(
-        "--local",
+        "--skip-title-heading",
         action="store_true",
         default=False,
-        help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
+        help="Skip the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).",
     )
     parser.add_argument(
-        "--headers",
-        nargs="+",
-        required=False,
-        action=KwargsAppendAction,
-        metavar="KEY=VALUE",
-        help="Apply custom headers to all Confluence API requests.",
+        "--no-skip-title-heading",
+        dest="skip_title_heading",
+        action="store_false",
+        help="Keep the first heading in document body even when used as page title (default).",
+    )
+    parser.add_argument(
+        "--title-prefix",
+        default=None,
+        metavar="TEXT",
+        help="String to prepend to Confluence page title for each published page.",
     )
     parser.add_argument(
         "--webui-links",
@@ -251,12 +273,33 @@ def get_parser() -> argparse.ArgumentParser:
         default="center",
         help="Alignment for block-level images and formulas (default: 'center').",
     )
+    parser.add_argument(
+        "--max-image-width",
+        dest="max_image_width",
+        type=int,
+        default=None,
+        help="Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.",
+    )
     parser.add_argument(
         "--use-panel",
         action="store_true",
         default=False,
         help="Transform admonitions and alerts into a Confluence custom panel.",
     )
+    parser.add_argument(
+        "--local",
+        action="store_true",
+        default=False,
+        help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
+    )
+    parser.add_argument(
+        "--headers",
+        nargs="+",
+        required=False,
+        action=KwargsAppendAction,
+        metavar="KEY=VALUE",
+        help="Apply custom headers to all Confluence API requests.",
+    )
     return parser
 
 
@@ -282,15 +325,19 @@ def main() -> None:
     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,
         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,
     )
     if args.local:

md2conf/api.py

@@ -11,7 +11,9 @@ import enum
 import io
 import logging
 import mimetypes
+import random
 import ssl
+import time
 import typing
 from dataclasses import dataclass
 from pathlib import Path
@@ -30,6 +32,7 @@ from .serializer import JsonType, json_to_object, object_to_json_payload
 
 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("application/vnd.oasis.opendocument.presentation", ".odp", strict=True)
@@ -37,6 +40,7 @@ mimetypes.add_type("application/vnd.oasis.opendocument.spreadsheet", ".ods", str
 mimetypes.add_type("application/vnd.oasis.opendocument.text", ".odt", strict=True)
 mimetypes.add_type("application/vnd.openxmlformats-officedocument.presentationml.presentation", ".pptx", strict=True)
 mimetypes.add_type("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", ".xlsx", strict=True)
+# spellchecker: enable
 
 
 def build_url(base_url: str, query: dict[str, str] | None = None) -> str:
@@ -839,16 +843,38 @@ class ConfluenceSession:
         page = json_to_object(ConfluencePageProperties, results[0])
         return page
 
-    def get_page(self, page_id: str) -> ConfluencePage:
+    def get_page(self, page_id: str, *, retries: int = 3, retry_delay: float = 1.0) -> ConfluencePage:
         """
         Retrieves Confluence wiki page details and content.
 
+        Includes retry logic to handle eventual consistency issues when fetching
+        a newly created page that may not be immediately available via the API.
+
         :param page_id: The Confluence page ID.
+        :param retries: Number of retry attempts for 404 errors (default: 3).
+        :param retry_delay: Initial delay in seconds between retries, doubles each attempt (default: 1.0).
         :returns: Confluence page info and content.
         """
 
         path = f"/pages/{page_id}"
-        return self._get(ConfluenceVersion.VERSION_2, path, ConfluencePage, query={"body-format": "storage"})
+        last_error: requests.HTTPError | None = None
+
+        for attempt in range(retries + 1):
+            try:
+                return self._get(ConfluenceVersion.VERSION_2, path, ConfluencePage, query={"body-format": "storage"})
+            except requests.HTTPError as e:
+                if e.response is not None and e.response.status_code == 404 and attempt < retries:
+                    delay = retry_delay * (2**attempt) + random.uniform(0, 1)
+                    LOGGER.debug("Page %s not found, retrying in %.1f seconds (attempt %d/%d)", page_id, delay, attempt + 1, retries)
+                    time.sleep(delay)
+                    last_error = e
+                else:
+                    raise
+
+        # This should not be reached, but satisfies type checker
+        if last_error is not None:
+            raise last_error
+        raise ConfluenceError(f"Failed to get page {page_id}")
 
     def get_page_properties(self, page_id: str) -> ConfluencePageProperties:
         """