markdown-to-confluence 0.1.12__py3-none-any.whl → 0.2.0__py3-none-any.whl

{markdown_to_confluence-0.1.12.dist-info → markdown_to_confluence-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: markdown-to-confluence
-Version: 0.1.12
+Version: 0.2.0
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -21,13 +21,13 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lxml >=5.2
-Requires-Dist: types-lxml >=2024.4.14
-Requires-Dist: markdown >=3.6
-Requires-Dist: types-markdown >=3.6
-Requires-Dist: pymdown-extensions >=10.8
-Requires-Dist: requests >=2.32
-Requires-Dist: types-requests >=2.32
+Requires-Dist: lxml>=5.3
+Requires-Dist: types-lxml>=2024.8.7
+Requires-Dist: markdown>=3.6
+Requires-Dist: types-markdown>=3.6
+Requires-Dist: pymdown-extensions>=10.9
+Requires-Dist: requests>=2.32
+Requires-Dist: types-requests>=2.32
 
 # Publish Markdown files to Confluence wiki
 
@@ -45,12 +45,29 @@ This Python package
 
 * Sections and subsections
 * Text with **bold**, *italic*, `monospace`, <ins>underline</ins> and ~~strikethrough~~
-* Link to [external locations](http://example.com/)
+* Link to [sections on the same page](#getting-started) or [external locations](http://example.com/)
 * Ordered and unordered lists
 * Code blocks (e.g. Python, JSON, XML)
 * Image references (uploaded as Confluence page attachments)
-* [Table of Contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
-* [Admonitions](https://python-markdown.github.io/extensions/admonition/) (converted into *info*, *tip*, *note* and *warning* Confluence panels)
+* Tables
+* [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
+* [Admonitions](https://python-markdown.github.io/extensions/admonition/) and [alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
+* [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
+* [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images)
+
+## Installation
+
+Install the core package from PyPI:
+
+```sh
+pip install markdown-to-confluence
+```
+
+Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
+
+```sh
+npm install -g @mermaid-js/mermaid-cli
+```
 
 ## Getting started
 
@@ -131,7 +148,7 @@ Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes prece
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
 
-```console
+```sh
 $ python3 -m md2conf sample/example.md
 ```
 
@@ -139,14 +156,15 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY]
-               [--no-generated-by] [--ignore-invalid-url] [--local]
+usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE]
+               [--generated-by GENERATED_BY] [--no-generated-by] [--render-mermaid] [--no-render-mermaid]
+               [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local]
                mdpath
 
 positional arguments:
   mdpath                Path to Markdown file or directory to convert and publish.
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -d DOMAIN, --domain DOMAIN
                         Confluence organization domain.
@@ -163,6 +181,41 @@ optional arguments:
   --generated-by GENERATED_BY
                         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-mermaid      Render Mermaid diagrams as image files and add as attachments.
+  --no-render-mermaid   Inline Mermaid diagram in Confluence page.
+  --render-mermaid-format {png,svg}
+                        Format for rendering Mermaid diagrams (default: 'png').
+  --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --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.
 ```
+
+### 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.
+
+```sh
+docker run --rm --name md2conf hunyadi/md2conf -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+```
+
+Note that the entry point for the docker container's base image is `ENTRYPOINT ["python3", "-m", "md2conf"]`.
+
+```Dockerfile
+FROM hunyadi/md2conf:latest
+
+ENV CONFLUENCE_DOMAIN='instructure.atlassian.net'
+ENV CONFLUENCE_PATH='/wiki/'
+ENV CONFLUENCE_USER_NAME='levente.hunyadi@instructure.com'
+ENV CONFLUENCE_API_KEY='0123456789abcdef'
+ENV CONFLUENCE_SPACE_KEY='DAP'
+
+CMD ["./"]
+```
+
+Alternatively,
+
+```Dockerfile
+FROM hunyadi/md2conf:latest
+
+CMD ["-d", "instructure.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "DAP", "./"]
+```

markdown_to_confluence-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+md2conf/__init__.py,sha256=1KRpqiilQTkQz-oL8-HFPnI_6_3-_H0dq-SxQxDw56s,402
+md2conf/__main__.py,sha256=tWMEA_spxUTNNgViHtjsA85NzJixX-0G2zCq8BO3y_E,5230
+md2conf/api.py,sha256=Oc4FAQBNs85U8s-lbY0XwLBUcjm3Sd0_W59N4H3XAnE,15768
+md2conf/application.py,sha256=NnF84-cdW2cZUbU6VeHvuEg6g5NL5M9o2cpOSU7uv7o,5548
+md2conf/converter.py,sha256=XY7D8zpsVS7_PZzywciQ5YT2SHH5t1udPU5s2aPsmqs,27040
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/mermaid.py,sha256=3zawPXHXkCDhEK-WNtCH-gTqsLBDRzLrmlSo8ZW-Ii8,1371
+md2conf/processor.py,sha256=3JZkbFtMjbtnQLEm6wFum96ldjZ9xNJuL8JjFadyGmg,3084
+md2conf/properties.py,sha256=oXvtPssbougM1BTE9ytcD_1Yjc3nd7DDSHqEr0QoZAU,1811
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_to_confluence-0.2.0.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+markdown_to_confluence-0.2.0.dist-info/METADATA,sha256=nxwG4F2TX1do0lk38BCFIUMwqv6y2edErd2_5M-4la4,10023
+markdown_to_confluence-0.2.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+markdown_to_confluence-0.2.0.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.2.0.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.2.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.2.0.dist-info/RECORD,,

{markdown_to_confluence-0.1.12.dist-info → markdown_to_confluence-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (70.1.0)
+Generator: setuptools (75.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

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.1.12"
+__version__ = "0.2.0"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2024, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -2,7 +2,6 @@ import argparse
 import logging
 import os.path
 import sys
-import typing
 from pathlib import Path
 from typing import Optional
 
@@ -24,6 +23,7 @@ class Arguments(argparse.Namespace):
     space: str
     loglevel: str
     ignore_invalid_url: bool
+    heading_anchors: bool
     generated_by: Optional[str]
 
 
@@ -52,7 +52,7 @@ def main() -> None:
         "-l",
         "--loglevel",
         choices=[
-            typing.cast(str, logging.getLevelName(level)).lower()
+            logging.getLevelName(level).lower()
             for level in (
                 logging.DEBUG,
                 logging.INFO,
@@ -81,6 +81,32 @@ def main() -> None:
         const=None,
         help="Do not add 'generated by a tool' prompt to pages.",
     )
+    parser.add_argument(
+        "--render-mermaid",
+        dest="render_mermaid",
+        action="store_true",
+        default=True,
+        help="Render Mermaid diagrams as image files and add as attachments.",
+    )
+    parser.add_argument(
+        "--no-render-mermaid",
+        dest="render_mermaid",
+        action="store_false",
+        help="Inline Mermaid diagram in Confluence page.",
+    )
+    parser.add_argument(
+        "--render-mermaid-format",
+        dest="diagram_output_format",
+        choices=["png", "svg"],
+        default="png",
+        help="Format for rendering Mermaid diagrams (default: 'png').",
+    )
+    parser.add_argument(
+        "--heading-anchors",
+        action="store_true",
+        default=False,
+        help="Place an anchor at each section heading with GitHub-style same-page identifiers.",
+    )
     parser.add_argument(
         "--ignore-invalid-url",
         action="store_true",
@@ -107,9 +133,12 @@ def main() -> None:
     )
 
     options = ConfluenceDocumentOptions(
+        heading_anchors=args.heading_anchors,
         ignore_invalid_url=args.ignore_invalid_url,
         generated_by=args.generated_by,
         root_page_id=args.root_page,
+        render_mermaid=args.render_mermaid,
+        diagram_output_format=args.diagram_output_format,
     )
     properties = ConfluenceProperties(
         args.domain, args.path, args.username, args.apikey, args.space

md2conf/api.py

@@ -1,3 +1,4 @@
+import io
 import json
 import logging
 import mimetypes
@@ -177,7 +178,8 @@ class ConfluenceSession:
         extensions = typing.cast(Dict[str, JsonType], result["extensions"])
         media_type = typing.cast(str, extensions["mediaType"])
         file_size = typing.cast(int, extensions["fileSize"])
-        comment = typing.cast(str, extensions["comment"])
+        comment = extensions.get("comment", "")
+        comment = typing.cast(str, comment)
         return ConfluenceAttachment(id, media_type, file_size, comment)
 
     def upload_attachment(
@@ -185,6 +187,7 @@ class ConfluenceSession:
         page_id: str,
         attachment_path: Path,
         attachment_name: str,
+        raw_data: Optional[bytes] = None,
         comment: Optional[str] = None,
         *,
         space_key: Optional[str] = None,
@@ -192,7 +195,7 @@ class ConfluenceSession:
     ) -> None:
         content_type = mimetypes.guess_type(attachment_path, strict=True)[0]
 
-        if not attachment_path.is_file():
+        if not raw_data and not attachment_path.is_file():
             raise ConfluenceError(f"file not found: {attachment_path}")
 
         try:
@@ -200,9 +203,14 @@ class ConfluenceSession:
                 page_id, attachment_name, space_key=space_key
             )
 
-            if not force and attachment.file_size == attachment_path.stat().st_size:
-                LOGGER.info("Up-to-date attachment: %s", attachment_name)
-                return
+            if not raw_data:
+                if not force and attachment.file_size == attachment_path.stat().st_size:
+                    LOGGER.info("Up-to-date attachment: %s", attachment_name)
+                    return
+            else:
+                if not force and attachment.file_size == len(raw_data):
+                    LOGGER.info("Up-to-date embedded image: %s", attachment_name)
+                    return
 
             id = removeprefix(attachment.id, "att")
             path = f"/content/{page_id}/child/attachment/{id}/data"
@@ -212,17 +220,36 @@ class ConfluenceSession:
 
         url = self._build_url(path)
 
-        with open(attachment_path, "rb") as attachment_file:
+        if not raw_data:
+            with open(attachment_path, "rb") as attachment_file:
+                file_to_upload = {
+                    "comment": comment,
+                    "file": (
+                        attachment_name,  # will truncate path component
+                        attachment_file,
+                        content_type,
+                        {"Expires": "0"},
+                    ),
+                }
+                LOGGER.info("Uploading attachment: %s", attachment_name)
+                response = self.session.post(
+                    url,
+                    files=file_to_upload,  # type: ignore
+                    headers={"X-Atlassian-Token": "no-check"},
+                )
+        else:
+            LOGGER.info("Uploading raw data: %s", attachment_name)
+
             file_to_upload = {
                 "comment": comment,
                 "file": (
                     attachment_name,  # will truncate path component
-                    attachment_file,
+                    io.BytesIO(raw_data),  # type: ignore
                     content_type,
                     {"Expires": "0"},
                 ),
             }
-            LOGGER.info("Uploading attachment: %s", attachment_name)
+
             response = self.session.post(
                 url,
                 files=file_to_upload,  # type: ignore

md2conf/application.py

@@ -94,7 +94,7 @@ class Application:
         """
 
         # parse file
-        with open(absolute_path, "r") as f:
+        with open(absolute_path, "r", encoding="utf-8") as f:
             document = f.read()
 
         qualified_id, document = extract_qualified_id(document)
@@ -131,9 +131,20 @@ class Application:
         )
 
     def _update_document(self, document: ConfluenceDocument, base_path: Path) -> None:
+
         for image in document.images:
             self.api.upload_attachment(
-                document.id.page_id, base_path / image, attachment_name(image), ""
+                document.id.page_id,
+                base_path / image,
+                attachment_name(image),
+            )
+
+        for image, data in document.embedded_images.items():
+            self.api.upload_attachment(
+                document.id.page_id,
+                Path("EMB") / image,
+                attachment_name(image),
+                raw_data=data,
             )
 
         content = document.xhtml()
@@ -147,7 +158,7 @@ class Application:
         page_id: str,
         space_key: Optional[str],
     ) -> None:
-        with open(path, "w") as file:
+        with open(path, "w", encoding="utf-8") as file:
             file.write(f"<!-- confluence-page-id: {page_id} -->\n")
             if space_key:
                 file.write(f"<!-- confluence-space-key: {space_key} -->\n")

md2conf/converter.py

@@ -1,17 +1,23 @@
+# mypy: disable-error-code="dict-item"
+
+import hashlib
 import importlib.resources as resources
 import logging
 import os.path
 import pathlib
 import re
 import sys
+import uuid
 from dataclasses import dataclass
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Literal, Optional, Tuple
 from urllib.parse import ParseResult, urlparse, urlunparse
 
 import lxml.etree as ET
 import markdown
 from lxml.builder import ElementMaker
 
+from . import mermaid
+
 namespaces = {
     "ac": "http://atlassian.com/content",
     "ri": "http://atlassian.com/resource/identifier",
@@ -19,7 +25,6 @@ namespaces = {
 for key, value in namespaces.items():
     ET.register_namespace(key, value)
 
-
 HTML = ElementMaker()
 AC = ElementMaker(namespace=namespaces["ac"])
 RI = ElementMaker(namespace=namespaces["ri"])
@@ -51,6 +56,7 @@ def markdown_to_html(content: str) -> str:
             "pymdownx.magiclink",
             "pymdownx.tilde",
             "sane_lists",
+            "md_in_html",
         ],
     )
 
@@ -100,6 +106,10 @@ def elements_from_strings(items: List[str]) -> ET._Element:
             return _elements_from_strings(dtd_path, items)
 
 
+def elements_from_string(content: str) -> ET._Element:
+    return elements_from_strings([content])
+
+
 _languages = [
     "abap",
     "actionscript3",
@@ -139,6 +149,7 @@ _languages = [
     "kotlin",
     "livescript",
     "lua",
+    "mermaid",
     "mathematica",
     "matlab",
     "objectivec",
@@ -192,6 +203,8 @@ class ConfluencePageMetadata:
 
 class NodeVisitor:
     def visit(self, node: ET._Element) -> None:
+        "Recursively visits all descendants of this node."
+
         if len(node) < 1:
             return
 
@@ -207,6 +220,15 @@ class NodeVisitor:
         pass
 
 
+def title_to_identifier(title: str) -> str:
+    "Converts a section heading title to a GitHub-style Markdown same-page anchor."
+
+    s = title.strip().lower()
+    s = re.sub("[^ A-Za-z0-9]", "", s)
+    s = s.replace(" ", "-")
+    return s
+
+
 @dataclass
 class ConfluenceConverterOptions:
     """
@@ -214,9 +236,16 @@ class ConfluenceConverterOptions:
 
     :param ignore_invalid_url: When true, ignore invalid URLs in input, emit a warning and replace the anchor with
         plain text; when false, raise an exception.
+    :param heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
+        conversion rules for the identifier.
+    :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
+    :param diagram_output_format: Target image format for diagrams.
     """
 
     ignore_invalid_url: bool = False
+    heading_anchors: bool = False
+    render_mermaid: bool = False
+    diagram_output_format: Literal["png", "svg"] = "png"
 
 
 class ConfluenceStorageFormatConverter(NodeVisitor):
@@ -227,6 +256,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     base_path: pathlib.Path
     links: List[str]
     images: List[str]
+    embedded_images: Dict[str, bytes]
     page_metadata: Dict[pathlib.Path, ConfluencePageMetadata]
 
     def __init__(
@@ -241,8 +271,33 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         self.base_path = path.parent
         self.links = []
         self.images = []
+        self.embedded_images = {}
         self.page_metadata = page_metadata
 
+    def _transform_heading(self, heading: ET._Element) -> None:
+        title = "".join(heading.itertext()).strip()
+
+        for e in heading:
+            self.visit(e)
+
+        anchor = AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "anchor",
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+            },
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): ""},
+                title_to_identifier(title),
+            ),
+        )
+
+        # insert anchor as first child, pushing any text nodes
+        heading.insert(0, anchor)
+        anchor.tail = heading.text
+        heading.text = None
+
     def _transform_link(self, anchor: ET._Element) -> None:
         url = anchor.attrib["href"]
         if is_absolute_url(url):
@@ -344,20 +399,89 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             language = "none"
         content: str = code.text or ""
         content = content.rstrip()
+
+        if language == "mermaid":
+            return self._transform_mermaid(content)
+
         return AC(
             "structured-macro",
             {
                 ET.QName(namespaces["ac"], "name"): "code",
                 ET.QName(namespaces["ac"], "schema-version"): "1",
             },
-            AC("parameter", {ET.QName(namespaces["ac"], "name"): "theme"}, "Midnight"),
-            AC("parameter", {ET.QName(namespaces["ac"], "name"): "language"}, language),
             AC(
-                "parameter", {ET.QName(namespaces["ac"], "name"): "linenumbers"}, "true"
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): "theme"},
+                "Midnight",
+            ),
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): "language"},
+                language,
+            ),
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): "linenumbers"},
+                "true",
             ),
             AC("plain-text-body", ET.CDATA(content)),
         )
 
+    def _transform_mermaid(self, content: str) -> ET._Element:
+        "Transforms a Mermaid diagram code block."
+
+        if self.options.render_mermaid:
+            image_data = mermaid.render(content, self.options.diagram_output_format)
+            image_hash = hashlib.md5(image_data).hexdigest()
+            image_filename = attachment_name(
+                f"embedded_{image_hash}.{self.options.diagram_output_format}"
+            )
+            self.embedded_images[image_filename] = image_data
+            return AC(
+                "image",
+                {
+                    ET.QName(namespaces["ac"], "align"): "center",
+                    ET.QName(namespaces["ac"], "layout"): "center",
+                },
+                RI(
+                    "attachment",
+                    {ET.QName(namespaces["ri"], "filename"): image_filename},
+                ),
+            )
+        else:
+            local_id = str(uuid.uuid4())
+            macro_id = str(uuid.uuid4())
+            return AC(
+                "structured-macro",
+                {
+                    ET.QName(namespaces["ac"], "name"): "macro-diagram",
+                    ET.QName(namespaces["ac"], "schema-version"): "1",
+                    ET.QName(namespaces["ac"], "data-layout"): "default",
+                    ET.QName(namespaces["ac"], "local-id"): local_id,
+                    ET.QName(namespaces["ac"], "macro-id"): macro_id,
+                },
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): "sourceType"},
+                    "MacroBody",
+                ),
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): "attachmentPageId"},
+                ),
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): "syntax"},
+                    "Mermaid",
+                ),
+                AC(
+                    "parameter",
+                    {ET.QName(namespaces["ac"], "name"): "attachmentId"},
+                ),
+                AC("parameter", {ET.QName(namespaces["ac"], "name"): "url"}),
+                AC("plain-text-body", ET.CDATA(content)),
+            )
+
     def _transform_toc(self, code: ET._Element) -> ET._Element:
         return AC(
             "structured-macro",
@@ -371,10 +495,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
     def _transform_admonition(self, elem: ET._Element) -> ET._Element:
         """
-        Creates an info, tip, note or warning panel.
+        Creates an info, tip, note or warning panel from a Markdown admonition.
 
-        Transforms [Python-Markdown admonition](https://python-markdown.github.io/extensions/admonition/) syntax
-        into Confluence structured macro syntax.
+        Transforms [Python-Markdown admonition](https://python-markdown.github.io/extensions/admonition/)
+        syntax into one of the Confluence structured macros *info*, *tip*, *note*, or *warning*.
         """
 
         # <div class="admonition note">
@@ -401,7 +525,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 AC(
                     "parameter",
                     {ET.QName(namespaces["ac"], "name"): "title"},
-                    elem[0].text,
+                    elem[0].text or "",
                 ),
                 AC("rich-text-body", {}, *list(elem[1:])),
             ]
@@ -417,6 +541,87 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             *content,
         )
 
+    def _transform_alert(self, elem: ET._Element) -> ET._Element:
+        """
+        Creates an info, tip, note or warning panel from a GitHub alert.
+
+        Transforms
+        [GitHub alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)  # noqa: E501 # no way to make this link shorter
+        syntax into one of the Confluence structured macros *info*, *tip*, *note*, or *warning*.
+        """
+
+        pattern = re.compile(r"^\[!([A-Z]+)\]\s*")
+
+        content = elem[0]
+        if content.text is None:
+            raise DocumentError("empty content")
+
+        match = pattern.match(content.text)
+        if match is None:
+            raise DocumentError("not an alert")
+        alert = match.group(1)
+
+        if alert == "NOTE":
+            class_name = "note"
+        elif alert == "TIP":
+            class_name = "tip"
+        elif alert == "IMPORTANT":
+            class_name = "tip"
+        elif alert == "WARNING":
+            class_name = "warning"
+        elif alert == "CAUTION":
+            class_name = "warning"
+        else:
+            raise DocumentError(f"unsupported alert: {alert}")
+
+        for e in elem:
+            self.visit(e)
+
+        content.text = pattern.sub("", content.text, count=1)
+        return AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): class_name,
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+            },
+            AC("rich-text-body", {}, *list(elem)),
+        )
+
+    def _transform_section(self, elem: ET._Element) -> ET._Element:
+        """
+        Creates a collapsed section.
+
+        Transforms
+        [GitHub collapsed section](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)  # noqa: E501 # no way to make this link shorter
+        syntax into the Confluence structured macro *expand*.
+        """
+
+        if elem[0].tag != "summary":
+            raise DocumentError(
+                "expected: `<summary>` as first direct child of `<details>`"
+            )
+        if elem[0].tail is not None:
+            raise DocumentError('expected: attribute `markdown="1"` on `<details>`')
+
+        summary = "".join(elem[0].itertext()).strip()
+        elem.remove(elem[0])
+
+        self.visit(elem)
+
+        return AC(
+            "structured-macro",
+            {
+                ET.QName(namespaces["ac"], "name"): "expand",
+                ET.QName(namespaces["ac"], "schema-version"): "1",
+            },
+            AC(
+                "parameter",
+                {ET.QName(namespaces["ac"], "name"): "title"},
+                summary,
+            ),
+            AC("rich-text-body", {}, *list(elem)),
+        )
+
     def transform(self, child: ET._Element) -> Optional[ET._Element]:
         # normalize line breaks to regular space in element text
         if child.text:
@@ -426,6 +631,13 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             tail: str = child.tail
             child.tail = tail.replace("\n", " ")
 
+        if self.options.heading_anchors:
+            # <h1>...</h1>
+            # <h2>...</h2> ...
+            if re.match(r"^h[1-6]$", child.tag, flags=re.IGNORECASE) is not None:
+                self._transform_heading(child)
+                return None
+
         # <p><img src="..." /></p>
         if child.tag == "p" and len(child) == 1 and child[0].tag == "img":
             return self._transform_image(child[0])
@@ -448,6 +660,26 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         elif child.tag == "div" and "admonition" in child.attrib.get("class", ""):
             return self._transform_admonition(child)
 
+        # Alerts in GitHub
+        # <blockquote>
+        #   <p>[!TIP] ...</p>
+        # </blockquote>
+        elif (
+            child.tag == "blockquote"
+            and len(child) > 0
+            and child[0].tag == "p"
+            and child[0].text is not None
+            and child[0].text.startswith("[!")
+        ):
+            return self._transform_alert(child)
+
+        # <details markdown="1">
+        # <summary>...</summary>
+        # ...
+        # </details>
+        elif child.tag == "details" and len(child) > 1 and child[0].tag == "summary":
+            return self._transform_section(child)
+
         # <img src="..." alt="..." />
         elif child.tag == "img":
             return self._transform_image(child)
@@ -516,12 +748,20 @@ class ConfluenceDocumentOptions:
 
     :param ignore_invalid_url: When true, ignore invalid URLs in input, emit a warning and replace the anchor with
         plain text; when false, raise an exception.
+    :param heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
+        conversion rules for the identifier.
+    :param generated_by: Text to use as the generated-by prompt.
     :param show_generated: Whether to display a prompt "This page has been generated with a tool."
+    :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
+    :param diagram_output_format: Target image format for diagrams.
     """
 
     ignore_invalid_url: bool = False
+    heading_anchors: bool = False
     generated_by: Optional[str] = "This page has been generated with a tool."
     root_page_id: Optional[str] = None
+    render_mermaid: bool = False
+    diagram_output_format: Literal["png", "svg"] = "png"
 
 
 class ConfluenceDocument:
@@ -541,7 +781,7 @@ class ConfluenceDocument:
         self.options = options
         path = path.absolute()
 
-        with open(path, "r") as f:
+        with open(path, "r", encoding="utf-8") as f:
             text = f.read()
 
         # extract Confluence page ID
@@ -579,7 +819,10 @@ class ConfluenceDocument:
 
         converter = ConfluenceStorageFormatConverter(
             ConfluenceConverterOptions(
-                ignore_invalid_url=self.options.ignore_invalid_url
+                ignore_invalid_url=self.options.ignore_invalid_url,
+                heading_anchors=self.options.heading_anchors,
+                render_mermaid=self.options.render_mermaid,
+                diagram_output_format=self.options.diagram_output_format,
             ),
             path,
             page_metadata,
@@ -587,9 +830,10 @@ class ConfluenceDocument:
         converter.visit(self.root)
         self.links = converter.links
         self.images = converter.images
+        self.embedded_images = converter.embedded_images
 
     def xhtml(self) -> str:
-        return _content_to_string(self.root)
+        return elements_to_string(self.root)
 
 
 def attachment_name(name: str) -> str:
@@ -612,10 +856,10 @@ def sanitize_confluence(html: str) -> str:
 
     root = elements_from_strings([html])
     ConfluenceStorageFormatCleaner().visit(root)
-    return _content_to_string(root)
+    return elements_to_string(root)
 
 
-def _content_to_string(root: ET._Element) -> str:
+def elements_to_string(root: ET._Element) -> str:
     xml = ET.tostring(root, encoding="utf8", method="xml").decode("utf8")
     m = re.match(r"^<root\s+[^>]*>(.*)</root>\s*$", xml, re.DOTALL)
     if m:

md2conf/mermaid.py

@@ -0,0 +1,54 @@
+import os
+import os.path
+import shutil
+import subprocess
+from typing import Literal
+
+
+def has_mmdc() -> bool:
+    "True if Mermaid diagram converter is available on the OS."
+
+    if os.name == "nt":
+        executable = "mmdc.cmd"
+    else:
+        executable = "mmdc"
+    return shutil.which(executable) is not None
+
+
+def render(source: str, output_format: Literal["png", "svg"] = "png") -> bytes:
+    "Generates a PNG or SVG image from a Mermaid diagram source."
+
+    filename = f"tmp_mermaid.{output_format}"
+
+    if os.name == "nt":
+        executable = "mmdc.cmd"
+    else:
+        executable = "mmdc"
+    try:
+        cmd = [
+            executable,
+            "--input",
+            "-",
+            "--output",
+            filename,
+            "--outputFormat",
+            output_format,
+        ]
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stdin=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=False,
+        )
+        proc.communicate(input=source.encode("utf-8"))
+        if proc.returncode:
+            raise RuntimeError(
+                f"failed to convert Mermaid diagram; exit code: {proc.returncode}"
+            )
+        with open(filename, "rb") as image:
+            return image.read()
+
+    finally:
+        if os.path.exists(filename):
+            os.remove(filename)

md2conf/processor.py

@@ -69,13 +69,13 @@ class Processor:
 
         document = ConfluenceDocument(path, self.options, page_metadata)
         content = document.xhtml()
-        with open(path.with_suffix(".csf"), "w") as f:
+        with open(path.with_suffix(".csf"), "w", encoding="utf-8") as f:
             f.write(content)
 
     def _get_page(self, absolute_path: Path) -> ConfluencePageMetadata:
         "Extracts metadata from a Markdown file."
 
-        with open(absolute_path, "r") as f:
+        with open(absolute_path, "r", encoding="utf-8") as f:
             document = f.read()
 
         qualified_id, document = extract_qualified_id(document)

markdown_to_confluence-0.1.12.dist-info/RECORD

@@ -1,16 +0,0 @@
-md2conf/__init__.py,sha256=SS79zE1Jss2UJQH39HX6zMvAPO2MGjq3jjHny4L6dvY,403
-md2conf/__main__.py,sha256=L0XaHfV3GOPnyceWxUGamZXPfQUL3Dfsf_VpWeF08Qo,4246
-md2conf/api.py,sha256=xYqQbdy-0d_mqv-zDT0DCcLs17HYLdY2LfWoY2jhMB8,14738
-md2conf/application.py,sha256=ksWeDQGQs6xvAS8wdghwBMgWsGI6KMQiwlH5qaKXGv4,5221
-md2conf/converter.py,sha256=xiaf5hQHXPE3psTTk_pHVip4NDfeU-hos3Kkl1Pju50,18236
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/processor.py,sha256=f0JG8jqjsGq2sbxMdHNz6EyZ1KQ92nCKKYU3fxP6C0o,3048
-md2conf/properties.py,sha256=oXvtPssbougM1BTE9ytcD_1Yjc3nd7DDSHqEr0QoZAU,1811
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-markdown_to_confluence-0.1.12.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-markdown_to_confluence-0.1.12.dist-info/METADATA,sha256=HCmOX5YhQuc6v2szBgQa_VuGXaeZNKKBy8Q_Fi1GreQ,7875
-markdown_to_confluence-0.1.12.dist-info/WHEEL,sha256=cpQTJ5IWu9CdaPViMhC9YzF8gZuS5-vlfoFihTBC86A,91
-markdown_to_confluence-0.1.12.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.1.12.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.1.12.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.1.12.dist-info/RECORD,,