markdown-to-confluence 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

{markdown_to_confluence-0.2.5.dist-info → markdown_to_confluence-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: markdown-to-confluence
-Version: 0.2.5
+Version: 0.2.7
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -22,10 +22,10 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 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: types-lxml>=2024.11.8
+Requires-Dist: markdown>=3.7
+Requires-Dist: types-markdown>=3.7
+Requires-Dist: pymdown-extensions>=10.12
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
@@ -50,7 +50,7 @@ This Python package
 * 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)
+* Images (uploaded as Confluence page attachments or hosted externally)
 * Tables
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
 * [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
@@ -75,11 +75,11 @@ npm install -g @mermaid-js/mermaid-cli
 
 In order to get started, you will need
 
-* your organization domain name (e.g. `instructure.atlassian.net`),
+* your organization domain name (e.g. `example.atlassian.net`),
 * base path for Confluence wiki (typically `/wiki/` for managed Confluence, `/` for on-premise)
 * your Confluence username (e.g. `levente.hunyadi@instructure.com`) (only if required by your deployment),
 * a Confluence API token (a string of alphanumeric characters), and
-* the space key in Confluence (e.g. `DAP`) you are publishing content to.
+* the space key in Confluence (e.g. `SPACE`) you are publishing content to.
 
 ### Obtaining an API token
 
@@ -93,11 +93,11 @@ In order to get started, you will need
 Confluence organization domain, base path, username, API token and space key can be specified at runtime or set as Confluence environment variables (e.g. add to your `~/.profile` on Linux, or `~/.bash_profile` or `~/.zshenv` on MacOS):
 
 ```bash
-export CONFLUENCE_DOMAIN='instructure.atlassian.net'
+export CONFLUENCE_DOMAIN='example.atlassian.net'
 export CONFLUENCE_PATH='/wiki/'
 export CONFLUENCE_USER_NAME='levente.hunyadi@instructure.com'
 export CONFLUENCE_API_KEY='0123456789abcdef'
-export CONFLUENCE_SPACE_KEY='DAP'
+export CONFLUENCE_SPACE_KEY='SPACE'
 ```
 
 On Windows, these can be set via system properties.
@@ -129,7 +129,7 @@ The above tells the tool to synchronize the Markdown file with the given Conflue
 If you work in an environment where there are multiple Confluence spaces, and some Markdown pages may go into one space, whereas other pages may go into another, you can set the target space on a per-document basis:
 
 ```markdown
-<!-- confluence-space-key: DAP -->
+<!-- confluence-space-key: SPACE -->
 ```
 
 This overrides the default space set via command-line arguments or environment variables.
@@ -146,9 +146,17 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+### Publishing a single page
+
+*md2conf* has two modes of operation: *single-page mode* and *directory mode*.
+
+In single-page mode, you specify a single Markdown file as the source, which can contain absolute links to external locations (e.g. `https://example.com`) but not relative links to other pages (e.g. `local.md`). In other words, the page must be stand-alone.
+
 ### Publishing a directory
 
-*md2conf* allows you to convert and publish a directory of Markdown files rather than a single Markdown file if you pass a directory as `mdpath`. This will traverse the specified directory recursively, and synchronize each Markdown file.
+*md2conf* allows you to convert and publish a directory of Markdown files rather than a single Markdown file in *directory mode* if you pass a directory as the source. This will traverse the specified directory recursively, and synchronize each Markdown file.
+
+First, *md2conf* builds an index of pages in the directory hierarchy. The index maps each Markdown file path to a Confluence page ID. Whenever a relative link is encountered in a Markdown file, the relative link is replaced with a Confluence URL to the referenced page with the help of the index. All relative links must point to Markdown files that are located in the directory hierarchy.
 
 If a Markdown file doesn't yet pair up with a Confluence page, *md2conf* creates a new page and assigns a parent. Parent-child relationships are reflected in the navigation panel in Confluence. You can set a root page ID with the command-line option `-r`, which constitutes the topmost parent. (This could correspond to the landing page of your Confluence space. The Confluence page ID is always revealed when you edit a page.) Whenever a directory contains the file `index.md` or `README.md`, this page becomes the future parent page, and all Markdown files in this directory (and possibly nested directories) become its child pages (unless they already have a page ID). However, if an `index.md` or `README.md` file is subsequently found in one of the nested directories, it becomes the parent page of that directory, and any of its subdirectories.
 
@@ -216,7 +224,7 @@ You can run the Docker container via `docker run` or via `Dockerfile`. Either ca
 With `docker run`, you can pass Confluence domain, user, API and space key directly to `docker run`:
 
 ```sh
-docker run --rm --name md2conf -v $(pwd):/data leventehunyadi/md2conf:latest -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+docker run --rm --name md2conf -v $(pwd):/data leventehunyadi/md2conf:latest -d example.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s SPACE ./
 ```
 
 Alternatively, you can use a separate file `.env` to pass these parameters as environment variables:
@@ -234,11 +242,11 @@ With the `Dockerfile` approach, you can extend the base image:
 ```Dockerfile
 FROM leventehunyadi/md2conf:latest
 
-ENV CONFLUENCE_DOMAIN='instructure.atlassian.net'
+ENV CONFLUENCE_DOMAIN='example.atlassian.net'
 ENV CONFLUENCE_PATH='/wiki/'
 ENV CONFLUENCE_USER_NAME='levente.hunyadi@instructure.com'
 ENV CONFLUENCE_API_KEY='0123456789abcdef'
-ENV CONFLUENCE_SPACE_KEY='DAP'
+ENV CONFLUENCE_SPACE_KEY='SPACE'
 
 CMD ["./"]
 ```
@@ -248,5 +256,5 @@ Alternatively,
 ```Dockerfile
 FROM leventehunyadi/md2conf:latest
 
-CMD ["-d", "instructure.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "DAP", "./"]
+CMD ["-d", "example.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "SPACE", "./"]
 ```

markdown_to_confluence-0.2.7.dist-info/RECORD

@@ -0,0 +1,21 @@
+md2conf/__init__.py,sha256=U8zdop7-AIrfwCYzWiwKfhCEPF_1QEKPt4Zwq-38LlU,402
+md2conf/__main__.py,sha256=6iOI28W_d71tlnCMFpZwvkBmBt5-HazlZsz69gS4Oak,6894
+md2conf/api.py,sha256=NmAbNWTrTSi2ZDGYymy70Fw6HcgrmB-Ua4re4yLJvVc,17715
+md2conf/application.py,sha256=-kFpMRtSpQUU1hsiW5O73gL1X9McQWpvyAAEUxEnpuU,8869
+md2conf/converter.py,sha256=S8Kka35Y99w0J00CYi-DQwsKzlHAvBfaSCf10mb1FZk,36596
+md2conf/emoji.py,sha256=w9oiOIxzObAE7HTo3f6aETT1_D3t3yZwr88ynU4ENm0,1924
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/matcher.py,sha256=mYMltZOLypK4O-SJugLgicOwUMem67hiNLg_kPFoJkU,3583
+md2conf/mermaid.py,sha256=gqA6Hg6WcPDdR7JOClezAgNZj2Gq4pXJSgmOUlUt6Dk,2192
+md2conf/processor.py,sha256=E-Na-a8tNp4CaoRPA5etcXdHXNRdgyMrf6bfKa9P7O4,4781
+md2conf/properties.py,sha256=iVIc0h0XtS3Y2LCywX1C9cvmVQ0WljOMt8pl2MDMVCI,1990
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/util.py,sha256=ftf60MiW7S7rW45ipWX6efP_Sv2F2qpyIDHrGA0cBiw,743
+markdown_to_confluence-0.2.7.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+markdown_to_confluence-0.2.7.dist-info/METADATA,sha256=76K_O_5b__MnKT7FuLXgCHX6hR5dZio3mK6RWR4DyCA,13551
+markdown_to_confluence-0.2.7.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+markdown_to_confluence-0.2.7.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.2.7.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.2.7.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.2.7.dist-info/RECORD,,

{markdown_to_confluence-0.2.5.dist-info → markdown_to_confluence-0.2.7.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.3.0)
+Generator: setuptools (75.6.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.2.5"
+__version__ = "0.2.7"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2024, Levente Hunyadi"
 __license__ = "MIT"

md2conf/api.py

@@ -178,17 +178,30 @@ class ConfluenceSession:
     def upload_attachment(
         self,
         page_id: str,
-        attachment_path: Path,
         attachment_name: str,
+        *,
+        attachment_path: Optional[Path] = None,
         raw_data: Optional[bytes] = None,
+        content_type: Optional[str] = None,
         comment: Optional[str] = None,
-        *,
         space_key: Optional[str] = None,
         force: bool = False,
     ) -> None:
-        content_type = mimetypes.guess_type(attachment_path, strict=True)[0]
 
-        if not raw_data and not attachment_path.is_file():
+        if attachment_path is None and raw_data is None:
+            raise ConfluenceError("required: `attachment_path` or `raw_data`")
+
+        if attachment_path is not None and raw_data is not None:
+            raise ConfluenceError("expected: either `attachment_path` or `raw_data`")
+
+        if content_type is None:
+            if attachment_path is not None:
+                name = str(attachment_path)
+            else:
+                name = attachment_name
+            content_type, _ = mimetypes.guess_type(name, strict=True)
+
+        if attachment_path is not None and not attachment_path.is_file():
             raise ConfluenceError(f"file not found: {attachment_path}")
 
         try:
@@ -196,14 +209,16 @@ class ConfluenceSession:
                 page_id, attachment_name, space_key=space_key
             )
 
-            if not raw_data:
+            if attachment_path is not None:
                 if not force and attachment.file_size == attachment_path.stat().st_size:
                     LOGGER.info("Up-to-date attachment: %s", attachment_name)
                     return
-            else:
+            elif raw_data is not None:
                 if not force and attachment.file_size == len(raw_data):
                     LOGGER.info("Up-to-date embedded image: %s", attachment_name)
                     return
+            else:
+                raise NotImplementedError("never occurs")
 
             id = removeprefix(attachment.id, "att")
             path = f"/content/{page_id}/child/attachment/{id}/data"
@@ -213,7 +228,7 @@ class ConfluenceSession:
 
         url = self._build_url(path)
 
-        if not raw_data:
+        if attachment_path is not None:
             with open(attachment_path, "rb") as attachment_file:
                 file_to_upload = {
                     "comment": comment,
@@ -230,24 +245,27 @@ class ConfluenceSession:
                     files=file_to_upload,  # type: ignore
                     headers={"X-Atlassian-Token": "no-check"},
                 )
-        else:
+        elif raw_data is not None:
             LOGGER.info("Uploading raw data: %s", attachment_name)
 
+            raw_file = io.BytesIO(raw_data)
+            raw_file.name = attachment_name
             file_to_upload = {
                 "comment": comment,
                 "file": (
                     attachment_name,  # will truncate path component
-                    io.BytesIO(raw_data),  # type: ignore
+                    raw_file,  # type: ignore
                     content_type,
                     {"Expires": "0"},
                 ),
             }
-
             response = self.session.post(
                 url,
                 files=file_to_upload,  # type: ignore
                 headers={"X-Atlassian-Token": "no-check"},
             )
+        else:
+            raise NotImplementedError("never occurs")
 
         response.raise_for_status()
         data = response.json()
@@ -402,12 +420,23 @@ class ConfluenceSession:
         new_content: str,
         *,
         space_key: Optional[str] = None,
+        title: Optional[str] = None,
     ) -> None:
+        """
+        Update a page via the Confluence API.
+
+        :param page_id: The Confluence page ID.
+        :param new_content: Confluence Storage Format XHTML.
+        :param space_key: The Confluence space key (unless the default space is to be used).
+        :param title: New title to assign to the page. Needs to be unique within a space.
+        """
+
         page = self.get_page(page_id, space_key=space_key)
+        new_title = title or page.title
 
         try:
             old_content = sanitize_confluence(page.content)
-            if old_content == new_content:
+            if page.title == new_title and old_content == new_content:
                 LOGGER.info("Up-to-date page: %s", page_id)
                 return
         except ParseError as exc:
@@ -417,7 +446,7 @@ class ConfluenceSession:
         data = {
             "id": page_id,
             "type": "page",
-            "title": page.title,  # title needs to be unique within a space so the original title is maintained
+            "title": new_title,
             "space": {"key": space_key or self.space_key},
             "body": {"storage": {"value": new_content, "representation": "storage"}},
             "version": {"minorEdit": True, "number": page.version + 1},

md2conf/application.py

@@ -11,8 +11,6 @@ import os.path
 from pathlib import Path
 from typing import Dict, List, Optional
 
-import yaml
-
 from .api import ConfluencePage, ConfluenceSession
 from .converter import (
     ConfluenceDocument,
@@ -20,7 +18,7 @@ from .converter import (
     ConfluencePageMetadata,
     ConfluenceQualifiedID,
     attachment_name,
-    extract_frontmatter,
+    extract_frontmatter_title,
     extract_qualified_id,
     read_qualified_id,
 )
@@ -52,17 +50,31 @@ class Application:
         else:
             raise ValueError(f"expected: valid file or directory path; got: {path}")
 
-    def synchronize_page(self, page_path: Path) -> None:
+    def synchronize_page(
+        self, page_path: Path, root_dir: Optional[Path] = None
+    ) -> None:
         "Synchronizes a single Markdown page with Confluence."
 
         page_path = page_path.resolve(True)
-        self._synchronize_page(page_path, {})
+        if root_dir is None:
+            root_dir = page_path.parent
+        else:
+            root_dir = root_dir.resolve(True)
 
-    def synchronize_directory(self, local_dir: Path) -> None:
+        self._synchronize_page(page_path, root_dir, {})
+
+    def synchronize_directory(
+        self, local_dir: Path, root_dir: Optional[Path] = None
+    ) -> None:
         "Synchronizes a directory of Markdown pages with Confluence."
 
-        LOGGER.info("Synchronizing directory: %s", local_dir)
         local_dir = local_dir.resolve(True)
+        if root_dir is None:
+            root_dir = local_dir
+        else:
+            root_dir = root_dir.resolve(True)
+
+        LOGGER.info("Synchronizing directory: %s", local_dir)
 
         # Step 1: build index of all page metadata
         page_metadata: Dict[Path, ConfluencePageMetadata] = {}
@@ -76,17 +88,18 @@ class Application:
 
         # Step 2: convert each page
         for page_path in page_metadata.keys():
-            self._synchronize_page(page_path, page_metadata)
+            self._synchronize_page(page_path, root_dir, page_metadata)
 
     def _synchronize_page(
         self,
         page_path: Path,
+        root_dir: Path,
         page_metadata: Dict[Path, ConfluencePageMetadata],
     ) -> None:
         base_path = page_path.parent
 
         LOGGER.info("Synchronizing page: %s", page_path)
-        document = ConfluenceDocument(page_path, self.options, page_metadata)
+        document = ConfluenceDocument(page_path, self.options, root_dir, page_metadata)
 
         if document.id.space_key:
             with self.api.switch_space(document.id.space_key):
@@ -159,7 +172,7 @@ class Application:
             document = f.read()
 
         qualified_id, document = extract_qualified_id(document)
-        frontmatter, document = extract_frontmatter(document)
+        frontmatter_title, _ = extract_frontmatter_title(document)
 
         if qualified_id is not None:
             confluence_page = self.api.get_page(
@@ -172,15 +185,8 @@ class Application:
                 )
 
             # assign title from frontmatter if present
-            if title is None and frontmatter is not None:
-                properties = yaml.safe_load(frontmatter)
-                if isinstance(properties, dict):
-                    property_title = properties.get("title")
-                    if isinstance(property_title, str):
-                        title = property_title
-
             confluence_page = self._create_page(
-                absolute_path, document, title, parent_id
+                absolute_path, document, title or frontmatter_title, parent_id
             )
 
         return ConfluencePageMetadata(
@@ -221,21 +227,20 @@ class Application:
         for image in document.images:
             self.api.upload_attachment(
                 document.id.page_id,
-                base_path / image,
                 attachment_name(image),
+                attachment_path=base_path / image,
             )
 
-        for image, data in document.embedded_images.items():
+        for name, data in document.embedded_images.items():
             self.api.upload_attachment(
                 document.id.page_id,
-                Path("EMB") / image,
-                attachment_name(image),
+                name,
                 raw_data=data,
             )
 
         content = document.xhtml()
         LOGGER.debug("Generated Confluence Storage Format document:\n%s", content)
-        self.api.update_page(document.id.page_id, content)
+        self.api.update_page(document.id.page_id, content, title=document.title)
 
     def _update_markdown(
         self,

md2conf/converter.py

@@ -18,11 +18,12 @@ import uuid
 import xml.etree.ElementTree
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional, Tuple
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union
 from urllib.parse import ParseResult, urlparse, urlunparse
 
 import lxml.etree as ET
 import markdown
+import yaml
 from lxml.builder import ElementMaker
 
 from . import mermaid
@@ -301,9 +302,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
     options: ConfluenceConverterOptions
     path: Path
-    base_path: Path
+    base_dir: Path
+    root_dir: Path
     links: List[str]
-    images: List[str]
+    images: List[Path]
     embedded_images: Dict[str, bytes]
     page_metadata: Dict[Path, ConfluencePageMetadata]
 
@@ -311,12 +313,14 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         self,
         options: ConfluenceConverterOptions,
         path: Path,
+        root_dir: Path,
         page_metadata: Dict[Path, ConfluencePageMetadata],
     ) -> None:
         super().__init__()
         self.options = options
         self.path = path
-        self.base_path = path.parent
+        self.base_dir = path.parent
+        self.root_dir = root_dir
         self.links = []
         self.images = []
         self.embedded_images = {}
@@ -347,8 +351,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         heading.text = None
 
     def _transform_link(self, anchor: ET._Element) -> Optional[ET._Element]:
-        url = anchor.attrib["href"]
-        if is_absolute_url(url):
+        url = anchor.attrib.get("href")
+        if url is None or is_absolute_url(url):
             return None
 
         LOGGER.debug("Found link %s relative to %s", url, self.path)
@@ -383,9 +387,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         # convert the relative URL to absolute URL based on the base path value, then look up
         # the absolute path in the page metadata dictionary to discover the relative path
         # within Confluence that should be used
-        absolute_path = (self.base_path / relative_url.path).absolute()
-        if not str(absolute_path).startswith(str(self.base_path)):
-            msg = f"relative URL {url} points to outside base path: {self.base_path}"
+        absolute_path = (self.base_dir / relative_url.path).resolve(True)
+        if not str(absolute_path).startswith(str(self.root_dir)):
+            msg = f"relative URL {url} points to outside root path: {self.root_dir}"
             if self.options.ignore_invalid_url:
                 LOGGER.warning(msg)
                 anchor.attrib.pop("href")
@@ -393,8 +397,6 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             else:
                 raise DocumentError(msg)
 
-        relative_path = os.path.relpath(absolute_path, self.base_path)
-
         link_metadata = self.page_metadata.get(absolute_path)
         if link_metadata is None:
             msg = f"unable to find matching page for URL: {url}"
@@ -405,6 +407,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             else:
                 raise DocumentError(msg)
 
+        relative_path = os.path.relpath(absolute_path, self.base_dir)
         LOGGER.debug(
             "found link to page %s with metadata: %s", relative_path, link_metadata
         )
@@ -430,31 +433,72 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         return None
 
     def _transform_image(self, image: ET._Element) -> ET._Element:
-        path: str = image.attrib["src"]
+        src = image.attrib.get("src")
+
+        if not src:
+            raise DocumentError("image lacks `src` attribute")
+
+        attributes: Dict[str, Any] = {
+            ET.QName(namespaces["ac"], "align"): "center",
+            ET.QName(namespaces["ac"], "layout"): "center",
+        }
+        width = image.attrib.get("width")
+        if width is not None:
+            attributes.update({ET.QName(namespaces["ac"], "width"): width})
+        height = image.attrib.get("height")
+        if height is not None:
+            attributes.update({ET.QName(namespaces["ac"], "height"): height})
+
+        caption = image.attrib.get("alt")
+
+        if is_absolute_url(src):
+            return self._transform_external_image(src, caption, attributes)
+        else:
+            return self._transform_attached_image(Path(src), caption, attributes)
+
+    def _transform_external_image(
+        self, url: str, caption: Optional[str], attributes: Dict[str, Any]
+    ) -> ET._Element:
+        "Emits Confluence Storage Format XHTML for an external image."
+
+        elements: List[ET._Element] = []
+        elements.append(
+            RI(
+                "url",
+                # refers to an external image
+                {ET.QName(namespaces["ri"], "value"): url},
+            )
+        )
+        if caption is not None:
+            elements.append(AC("caption", HTML.p(caption)))
+
+        return AC("image", attributes, *elements)
+
+    def _transform_attached_image(
+        self, path: Path, caption: Optional[str], attributes: Dict[str, Any]
+    ) -> ET._Element:
+        "Emits Confluence Storage Format XHTML for an attached image."
 
         # prefer PNG over SVG; Confluence displays SVG in wrong size, and text labels are truncated
-        if path and is_relative_url(path):
-            relative_path = Path(path)
-            if (
-                relative_path.suffix == ".svg"
-                and (self.base_path / relative_path.with_suffix(".png")).exists()
-            ):
-                path = str(relative_path.with_suffix(".png"))
+        png_file = path.with_suffix(".png")
+        if path.suffix == ".svg" and (self.base_dir / png_file).exists():
+            path = png_file
 
         self.images.append(path)
-        caption = image.attrib["alt"]
-        return AC(
-            "image",
-            {
-                ET.QName(namespaces["ac"], "align"): "center",
-                ET.QName(namespaces["ac"], "layout"): "center",
-            },
+        image_name = attachment_name(path)
+
+        elements: List[ET._Element] = []
+        elements.append(
             RI(
                 "attachment",
-                {ET.QName(namespaces["ri"], "filename"): attachment_name(path)},
-            ),
-            AC("caption", HTML.p(caption)),
+                # refers to an attachment uploaded alongside the page
+                {ET.QName(namespaces["ri"], "filename"): image_name},
+            )
         )
+        if caption is not None:
+            elements.append(AC("caption", HTML.p(caption)))
+
+        return AC("image", attributes, *elements)
 
     def _transform_block(self, code: ET._Element) -> ET._Element:
         language = code.attrib.get("class")
@@ -757,6 +801,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             tail: str = child.tail
             child.tail = tail.replace("\n", " ")
 
+        if not isinstance(child.tag, str):
+            return None
+
         if self.options.heading_anchors:
             # <h1>...</h1>
             # <h2>...</h2> ...
@@ -894,6 +941,20 @@ def extract_frontmatter(text: str) -> Tuple[Optional[str], str]:
     return extract_value(r"(?ms)\A---$(.+?)^---$", text)
 
 
+def extract_frontmatter_title(text: str) -> Tuple[Optional[str], str]:
+    frontmatter, text = extract_frontmatter(text)
+
+    title: Optional[str] = None
+    if frontmatter is not None:
+        properties = yaml.safe_load(frontmatter)
+        if isinstance(properties, dict):
+            property_title = properties.get("title")
+            if isinstance(property_title, str):
+                title = property_title
+
+    return title, text
+
+
 def read_qualified_id(absolute_path: Path) -> Optional[ConfluenceQualifiedID]:
     "Reads the Confluence page ID and space key from a Markdown document."
 
@@ -931,8 +992,9 @@ class ConfluenceDocumentOptions:
 
 class ConfluenceDocument:
     id: ConfluenceQualifiedID
+    title: Optional[str]
     links: List[str]
-    images: List[str]
+    images: List[Path]
 
     options: ConfluenceDocumentOptions
     root: ET._Element
@@ -941,10 +1003,11 @@ class ConfluenceDocument:
         self,
         path: Path,
         options: ConfluenceDocumentOptions,
+        root_dir: Path,
         page_metadata: Dict[Path, ConfluencePageMetadata],
     ) -> None:
         self.options = options
-        path = path.absolute()
+        path = path.resolve(True)
 
         with open(path, "r", encoding="utf-8") as f:
             text = f.read()
@@ -968,7 +1031,7 @@ class ConfluenceDocument:
         )
 
         # extract frontmatter
-        frontmatter, text = extract_frontmatter(text)
+        self.title, text = extract_frontmatter_title(text)
 
         # convert to HTML
         html = markdown_to_html(text)
@@ -998,6 +1061,7 @@ class ConfluenceDocument:
                 webui_links=self.options.webui_links,
             ),
             path,
+            root_dir,
             page_metadata,
         )
         converter.visit(self.root)
@@ -1009,7 +1073,7 @@ class ConfluenceDocument:
         return elements_to_string(self.root)
 
 
-def attachment_name(name: str) -> str:
+def attachment_name(name: Union[Path, str]) -> str:
     """
     Safe name for use with attachment uploads.
 
@@ -1018,7 +1082,7 @@ def attachment_name(name: str) -> str:
     * Special characters: hyphen (-), underscore (_), period (.)
     """
 
-    return re.sub(r"[^\-0-9A-Za-z_.]", "_", name)
+    return re.sub(r"[^\-0-9A-Za-z_.]", "_", str(name))
 
 
 def sanitize_confluence(html: str) -> str:

md2conf/mermaid.py

@@ -56,6 +56,10 @@ def render(source: str, output_format: Literal["png", "svg"] = "png") -> bytes:
         filename,
         "--outputFormat",
         output_format,
+        "--backgroundColor",
+        "transparent",
+        "--scale",
+        "2",
     ]
     root = os.path.dirname(__file__)
     if is_docker():

md2conf/processor.py

@@ -10,7 +10,7 @@ import hashlib
 import logging
 import os
 from pathlib import Path
-from typing import Dict, List
+from typing import Dict, List, Optional
 
 from .converter import (
     ConfluenceDocument,
@@ -42,15 +42,22 @@ class Processor:
         if path.is_dir():
             self.process_directory(path)
         elif path.is_file():
-            self.process_page(path, {})
+            self.process_page(path)
         else:
             raise ValueError(f"expected: valid file or directory path; got: {path}")
 
-    def process_directory(self, local_dir: Path) -> None:
+    def process_directory(
+        self, local_dir: Path, root_dir: Optional[Path] = None
+    ) -> None:
         "Recursively scans a directory hierarchy for Markdown files."
 
-        LOGGER.info("Synchronizing directory: %s", local_dir)
         local_dir = local_dir.resolve(True)
+        if root_dir is None:
+            root_dir = local_dir
+        else:
+            root_dir = root_dir.resolve(True)
+
+        LOGGER.info("Synchronizing directory: %s", local_dir)
 
         # Step 1: build index of all page metadata
         page_metadata: Dict[Path, ConfluencePageMetadata] = {}
@@ -59,15 +66,28 @@ class Processor:
 
         # Step 2: convert each page
         for page_path in page_metadata.keys():
-            self.process_page(page_path, page_metadata)
+            self._process_page(page_path, root_dir, page_metadata)
 
-    def process_page(
-        self, path: Path, page_metadata: Dict[Path, ConfluencePageMetadata]
-    ) -> None:
+    def process_page(self, path: Path, root_dir: Optional[Path] = None) -> None:
         "Processes a single Markdown file."
 
         path = path.resolve(True)
-        document = ConfluenceDocument(path, self.options, page_metadata)
+        if root_dir is None:
+            root_dir = path.parent
+        else:
+            root_dir = root_dir.resolve(True)
+
+        self._process_page(path, root_dir, {})
+
+    def _process_page(
+        self,
+        path: Path,
+        root_dir: Path,
+        page_metadata: Dict[Path, ConfluencePageMetadata],
+    ) -> None:
+        "Processes a single Markdown file."
+
+        document = ConfluenceDocument(path, self.options, root_dir, page_metadata)
         content = document.xhtml()
         with open(path.with_suffix(".csf"), "w", encoding="utf-8") as f:
             f.write(content)

markdown_to_confluence-0.2.5.dist-info/RECORD

@@ -1,21 +0,0 @@
-md2conf/__init__.py,sha256=0eak9lvskuCqGJnGeno6SHoCiBFAX5IQLHVBx1LV0w8,402
-md2conf/__main__.py,sha256=6iOI28W_d71tlnCMFpZwvkBmBt5-HazlZsz69gS4Oak,6894
-md2conf/api.py,sha256=EZSHbuH5O9fPyW7iLAX0Fqw8njXmvd6sEbgseP-eUUc,16498
-md2conf/application.py,sha256=hmfLiofGulN8zUw2uXuueohCkDh978sqLkoUot928qM,8796
-md2conf/converter.py,sha256=8X8tNELqwAaZYSVvczJl_ZpJL9tu2ImCBXaQBQvGgeM,34413
-md2conf/emoji.py,sha256=w9oiOIxzObAE7HTo3f6aETT1_D3t3yZwr88ynU4ENm0,1924
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/matcher.py,sha256=mYMltZOLypK4O-SJugLgicOwUMem67hiNLg_kPFoJkU,3583
-md2conf/mermaid.py,sha256=Tsibd1aOn4hRYv6emQg0hrZMPTkflIeXHVbZ7nQ5lSc,2108
-md2conf/processor.py,sha256=tUt5D4_D3uhofg2Bn23owBJmkVHj4tSll0zI95J6cdk,4243
-md2conf/properties.py,sha256=iVIc0h0XtS3Y2LCywX1C9cvmVQ0WljOMt8pl2MDMVCI,1990
-md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-md2conf/util.py,sha256=ftf60MiW7S7rW45ipWX6efP_Sv2F2qpyIDHrGA0cBiw,743
-markdown_to_confluence-0.2.5.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-markdown_to_confluence-0.2.5.dist-info/METADATA,sha256=E7j_aFJ7rT4SOpoUIa40G2QJL_7PjuXBA5JvdANRIdc,12764
-markdown_to_confluence-0.2.5.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
-markdown_to_confluence-0.2.5.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.2.5.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.2.5.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.2.5.dist-info/RECORD,,