markdown-to-confluence 0.2.6__py3-none-any.whl → 0.3.0__py3-none-any.whl

md2conf/converter.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -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, Union
+from typing import Any, Literal, Optional, 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
@@ -45,7 +46,7 @@ class ParseError(RuntimeError):
     pass
 
 
-def starts_with_any(text: str, prefixes: List[str]) -> bool:
+def starts_with_any(text: str, prefixes: list[str]) -> bool:
     "True if text starts with any of the listed prefixes."
 
     for prefix in prefixes:
@@ -72,7 +73,7 @@ def emoji_generator(
     alt: str,
     title: Optional[str],
     category: Optional[str],
-    options: Dict[str, Any],
+    options: dict[str, Any],
     md: markdown.Markdown,
 ) -> xml.etree.ElementTree.Element:
     name = (alias or shortname).strip(":")
@@ -106,7 +107,7 @@ def markdown_to_html(content: str) -> str:
     )
 
 
-def _elements_from_strings(dtd_path: Path, items: List[str]) -> ET._Element:
+def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
     """
     Creates a fragment of several XML nodes from their string representation wrapped in a root element.
 
@@ -140,7 +141,7 @@ def _elements_from_strings(dtd_path: Path, items: List[str]) -> ET._Element:
         raise ParseError(e)
 
 
-def elements_from_strings(items: List[str]) -> ET._Element:
+def elements_from_strings(items: list[str]) -> ET._Element:
     "Creates a fragment of several XML nodes from their string representation wrapped in a root element."
 
     if sys.version_info >= (3, 9):
@@ -286,7 +287,7 @@ class ConfluenceConverterOptions:
         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.
-    :param web_links: When true, convert relative URLs to Confluence Web UI links.
+    :param webui_links: When true, convert relative URLs to Confluence Web UI links.
     """
 
     ignore_invalid_url: bool = False
@@ -303,17 +304,17 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     path: Path
     base_dir: Path
     root_dir: Path
-    links: List[str]
-    images: List[Path]
-    embedded_images: Dict[str, bytes]
-    page_metadata: Dict[Path, ConfluencePageMetadata]
+    links: list[str]
+    images: list[Path]
+    embedded_images: dict[str, bytes]
+    page_metadata: dict[Path, ConfluencePageMetadata]
 
     def __init__(
         self,
         options: ConfluenceConverterOptions,
         path: Path,
         root_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         super().__init__()
         self.options = options
@@ -350,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)
@@ -432,39 +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 path:
+        if not src:
             raise DocumentError("image lacks `src` attribute")
 
-        if is_absolute_url(path):
-            # images whose `src` attribute is an absolute URL cannot be converted into an `ac:image`;
-            # Confluence images are expected to refer to an uploaded attachment
-            raise DocumentError("image has a `src` attribute that is an absolute URL")
+        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)
 
-        relative_path = Path(path)
+    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
-        png_file = relative_path.with_suffix(".png")
-        if relative_path.suffix == ".svg" and (self.base_dir / png_file).exists():
-            relative_path = png_file
+        png_file = path.with_suffix(".png")
+        if path.suffix == ".svg" and (self.base_dir / png_file).exists():
+            path = png_file
 
-        self.images.append(relative_path)
-        caption = image.attrib["alt"]
-        image_name = attachment_name(relative_path)
-        return AC(
-            "image",
-            {
-                ET.QName(namespaces["ac"], "align"): "center",
-                ET.QName(namespaces["ac"], "layout"): "center",
-            },
+        self.images.append(path)
+        image_name = attachment_name(path)
+
+        elements: list[ET._Element] = []
+        elements.append(
             RI(
                 "attachment",
                 # refers to an attachment uploaded alongside the page
                 {ET.QName(namespaces["ri"], "filename"): image_name},
-            ),
-            AC("caption", HTML.p(caption)),
+            )
         )
+        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")
@@ -491,7 +525,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             AC(
                 "parameter",
                 {ET.QName(namespaces["ac"], "name"): "theme"},
-                "Midnight",
+                "Default",
             ),
             AC(
                 "parameter",
@@ -865,8 +899,8 @@ class DocumentError(RuntimeError):
     pass
 
 
-def extract_value(pattern: str, text: str) -> Tuple[Optional[str], str]:
-    values: List[str] = []
+def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
+    values: list[str] = []
 
     def _repl_func(matchobj: re.Match) -> str:
         values.append(matchobj.group(1))
@@ -887,7 +921,7 @@ class ConfluenceQualifiedID:
         self.space_key = space_key
 
 
-def extract_qualified_id(text: str) -> Tuple[Optional[ConfluenceQualifiedID], str]:
+def extract_qualified_id(text: str) -> tuple[Optional[ConfluenceQualifiedID], str]:
     "Extracts the Confluence page ID and space key from a Markdown document."
 
     page_id, text = extract_value(r"<!--\s+confluence-page-id:\s*(\d+)\s+-->", text)
@@ -901,12 +935,26 @@ def extract_qualified_id(text: str) -> Tuple[Optional[ConfluenceQualifiedID], st
     return ConfluenceQualifiedID(page_id, space_key), text
 
 
-def extract_frontmatter(text: str) -> Tuple[Optional[str], str]:
+def extract_frontmatter(text: str) -> tuple[Optional[str], str]:
     "Extracts the front matter from a Markdown document."
 
     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."
 
@@ -926,8 +974,8 @@ class ConfluenceDocumentOptions:
         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 generated_by: Text to use as the generated-by prompt (or `None` to omit a prompt).
+    :param root_page_id: Confluence page to assume root page role for publishing a directory of Markdown files.
     :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
     :param diagram_output_format: Target image format for diagrams.
     :param webui_links: When true, convert relative URLs to Confluence Web UI links.
@@ -944,8 +992,9 @@ class ConfluenceDocumentOptions:
 
 class ConfluenceDocument:
     id: ConfluenceQualifiedID
-    links: List[str]
-    images: List[Path]
+    title: Optional[str]
+    links: list[str]
+    images: list[Path]
 
     options: ConfluenceDocumentOptions
     root: ET._Element
@@ -955,7 +1004,7 @@ class ConfluenceDocument:
         path: Path,
         options: ConfluenceDocumentOptions,
         root_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         self.options = options
         path = path.resolve(True)
@@ -982,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)

md2conf/emoji.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """

md2conf/matcher.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -10,12 +10,17 @@ import os.path
 from dataclasses import dataclass
 from fnmatch import fnmatch
 from pathlib import Path
-from typing import Iterable, List, Optional
+from typing import Iterable, Optional
 
 
 @dataclass
 class Entry:
-    "Represents a file or directory entry."
+    """
+    Represents a file or directory entry.
+
+    :param name: Name of the file-system entry.
+    :param is_dir: True if the entry is a directory.
+    """
 
     name: str
     is_dir: bool
@@ -42,7 +47,7 @@ class Matcher:
     "Compares file and directory names against a list of exclude/include patterns."
 
     options: MatcherOptions
-    rules: List[str]
+    rules: list[str]
 
     def __init__(self, options: MatcherOptions, directory: Path) -> None:
         self.options = options
@@ -92,7 +97,7 @@ class Matcher:
 
         return not self.is_excluded(name, is_dir)
 
-    def filter(self, items: Iterable[Entry]) -> List[Entry]:
+    def filter(self, items: Iterable[Entry]) -> list[Entry]:
         """
         Returns only those elements from the input that don't match any of the exclusion rules.
 
@@ -102,7 +107,7 @@ class Matcher:
 
         return [item for item in items if self.is_included(item.name, item.is_dir)]
 
-    def scandir(self, path: Path) -> List[Entry]:
+    def scandir(self, path: Path) -> list[Entry]:
         """
         Returns only those entries in a directory whose name doesn't match any of the exclusion rules.
 

md2conf/mermaid.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """

md2conf/processor.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -10,7 +10,7 @@ import hashlib
 import logging
 import os
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Optional
 
 from .converter import (
     ConfluenceDocument,
@@ -60,7 +60,7 @@ class Processor:
         LOGGER.info("Synchronizing directory: %s", local_dir)
 
         # Step 1: build index of all page metadata
-        page_metadata: Dict[Path, ConfluencePageMetadata] = {}
+        page_metadata: dict[Path, ConfluencePageMetadata] = {}
         self._index_directory(local_dir, page_metadata)
         LOGGER.info("Indexed %d page(s)", len(page_metadata))
 
@@ -83,7 +83,7 @@ class Processor:
         self,
         path: Path,
         root_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         "Processes a single Markdown file."
 
@@ -95,7 +95,7 @@ class Processor:
     def _index_directory(
         self,
         local_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         "Indexes Markdown files in a directory recursively."
 
@@ -103,8 +103,8 @@ class Processor:
 
         matcher = Matcher(MatcherOptions(source=".mdignore", extension="md"), local_dir)
 
-        files: List[Path] = []
-        directories: List[Path] = []
+        files: list[Path] = []
+        directories: list[Path] = []
         for entry in os.scandir(local_dir):
             if matcher.is_excluded(entry.name, entry.is_dir()):
                 continue

md2conf/properties.py

@@ -1,13 +1,13 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
 import os
-from typing import Dict, Optional
+from typing import Optional
 
 
 class ConfluenceError(RuntimeError):
@@ -20,7 +20,7 @@ class ConfluenceProperties:
     space_key: str
     user_name: Optional[str]
     api_key: str
-    headers: Optional[Dict[str, str]]
+    headers: Optional[dict[str, str]]
 
     def __init__(
         self,
@@ -29,7 +29,7 @@ class ConfluenceProperties:
         user_name: Optional[str] = None,
         api_key: Optional[str] = None,
         space_key: Optional[str] = None,
-        headers: Optional[Dict[str, str]] = None,
+        headers: Optional[dict[str, str]] = None,
     ) -> None:
         opt_domain = domain or os.getenv("CONFLUENCE_DOMAIN")
         opt_base_path = base_path or os.getenv("CONFLUENCE_PATH")

md2conf/util.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """

markdown_to_confluence-0.2.6.dist-info/RECORD

@@ -1,21 +0,0 @@
-md2conf/__init__.py,sha256=aD2z2fkqyEVbUDQvLSJxfFUOpwMYt5lAZIUAQocULuM,402
-md2conf/__main__.py,sha256=6iOI28W_d71tlnCMFpZwvkBmBt5-HazlZsz69gS4Oak,6894
-md2conf/api.py,sha256=T-g_VS_cVahcYOs2jBVW38J7MSS94JxzMXlqohd_Sfw,17326
-md2conf/application.py,sha256=DSnqBx5hOWWVopnjo1iK_tbQg_7H8MhNPx_SAC3ovXQ,9157
-md2conf/converter.py,sha256=5cxxHnI9ux0pi-VW-CArBCGcpMClb8qEJZQd--NyrdY,35042
-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.6.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-markdown_to_confluence-0.2.6.dist-info/METADATA,sha256=kRQoSGz7LUCqHS7YhX9xsGae9OTql11hMWEnNP0ZRAw,13540
-markdown_to_confluence-0.2.6.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-markdown_to_confluence-0.2.6.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.2.6.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.2.6.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.2.6.dist-info/RECORD,,