markdown-to-confluence 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

md2conf/converter.py

@@ -25,7 +25,9 @@ import markdown
 import yaml
 from lxml.builder import ElementMaker
 
-from . import mermaid
+from .mermaid import render_diagram
+from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
+from .properties import PageError
 
 namespaces = {
     "ac": "http://atlassian.com/content",
@@ -91,9 +93,11 @@ def markdown_to_html(content: str) -> str:
         extensions=[
             "admonition",
             "markdown.extensions.tables",
-            "markdown.extensions.fenced_code",
+            # "markdown.extensions.fenced_code",
             "pymdownx.emoji",
+            "pymdownx.highlight",  # required by `pymdownx.superfences`
             "pymdownx.magiclink",
+            "pymdownx.superfences",
             "pymdownx.tilde",
             "sane_lists",
             "md_in_html",
@@ -101,7 +105,10 @@ def markdown_to_html(content: str) -> str:
         extension_configs={
             "pymdownx.emoji": {
                 "emoji_generator": emoji_generator,
-            }
+            },
+            "pymdownx.highlight": {
+                "use_pygments": False,
+            },
         },
     )
 
@@ -136,8 +143,8 @@ def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
 
     try:
         return ET.fromstringlist(data, parser=parser)
-    except ET.XMLSyntaxError as e:
-        raise ParseError(e)
+    except ET.XMLSyntaxError as ex:
+        raise ParseError() from ex
 
 
 def elements_from_strings(items: list[str]) -> ET._Element:
@@ -234,15 +241,6 @@ _languages = [
 ]
 
 
-@dataclass
-class ConfluencePageMetadata:
-    domain: str
-    base_path: str
-    page_id: str
-    space_key: Optional[str]
-    title: str
-
-
 class NodeVisitor:
     def visit(self, node: ET._Element) -> None:
         "Recursively visits all descendants of this node."
@@ -271,6 +269,53 @@ def title_to_identifier(title: str) -> str:
     return s
 
 
+def element_to_text(node: ET._Element) -> str:
+    "Returns all text contained in an element as a concatenated string."
+
+    return "".join(node.itertext()).strip()
+
+
+@dataclass
+class TableOfContentsEntry:
+    level: int
+    text: str
+
+
+class TableOfContents:
+    "Builds a table of contents from Markdown headings."
+
+    headings: list[TableOfContentsEntry]
+
+    def __init__(self) -> None:
+        self.headings = []
+
+    def add(self, level: int, text: str) -> None:
+        """
+        Adds a heading to the table of contents.
+
+        :param level: Markdown heading level (e.g. `1` for first-level heading).
+        :param text: Markdown heading text.
+        """
+
+        self.headings.append(TableOfContentsEntry(level, text))
+
+    def get_title(self) -> Optional[str]:
+        """
+        Returns a proposed document title (if unique).
+
+        :returns: Title text, or `None` if no unique title can be inferred.
+        """
+
+        for level in range(1, 7):
+            try:
+                (title,) = (item.text for item in self.headings if item.level == level)
+                return title
+            except ValueError:
+                pass
+
+        return None
+
+
 @dataclass
 class ConfluenceConverterOptions:
     """
@@ -299,9 +344,11 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     path: Path
     base_dir: Path
     root_dir: Path
+    toc: TableOfContents
     links: list[str]
     images: list[Path]
     embedded_images: dict[str, bytes]
+    site_metadata: ConfluenceSiteMetadata
     page_metadata: dict[Path, ConfluencePageMetadata]
 
     def __init__(
@@ -309,6 +356,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         options: ConfluenceConverterOptions,
         path: Path,
         root_dir: Path,
+        site_metadata: ConfluenceSiteMetadata,
         page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         super().__init__()
@@ -316,14 +364,14 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         self.path = path
         self.base_dir = path.parent
         self.root_dir = root_dir
+        self.toc = TableOfContents()
         self.links = []
         self.images = []
         self.embedded_images = {}
+        self.site_metadata = site_metadata
         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)
 
@@ -336,7 +384,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             AC(
                 "parameter",
                 {ET.QName(namespaces["ac"], "name"): ""},
-                title_to_identifier(title),
+                title_to_identifier(element_to_text(heading)),
             ),
         )
 
@@ -409,13 +457,20 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         self.links.append(url)
 
         if self.options.webui_links:
-            page_url = f"{link_metadata.base_path}pages/viewpage.action?pageId={link_metadata.page_id}"
+            page_url = f"{self.site_metadata.base_path}pages/viewpage.action?pageId={link_metadata.page_id}"
         else:
-            page_url = f"{link_metadata.base_path}spaces/{link_metadata.space_key}/pages/{link_metadata.page_id}/{link_metadata.title}"
+            space_key = link_metadata.space_key or self.site_metadata.space_key
+
+            if space_key is None:
+                raise DocumentError(
+                    "Confluence space key required for building full web URLs"
+                )
+
+            page_url = f"{self.site_metadata.base_path}spaces/{space_key}/pages/{link_metadata.page_id}/{link_metadata.title}"
 
         components = ParseResult(
             scheme="https",
-            netloc=link_metadata.domain,
+            netloc=self.site_metadata.domain,
             path=page_url,
             params="",
             query="",
@@ -527,11 +582,6 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 {ET.QName(namespaces["ac"], "name"): "language"},
                 language,
             ),
-            AC(
-                "parameter",
-                {ET.QName(namespaces["ac"], "name"): "linenumbers"},
-                "true",
-            ),
             AC("plain-text-body", ET.CDATA(content)),
         )
 
@@ -539,7 +589,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         "Transforms a Mermaid diagram code block."
 
         if self.options.render_mermaid:
-            image_data = mermaid.render(content, self.options.diagram_output_format)
+            image_data = render_diagram(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}"
@@ -799,10 +849,15 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if not isinstance(child.tag, str):
             return None
 
-        if self.options.heading_anchors:
-            # <h1>...</h1>
-            # <h2>...</h2> ...
-            if re.match(r"^h[1-6]$", child.tag, flags=re.IGNORECASE) is not None:
+        # <h1>...</h1>
+        # <h2>...</h2> ...
+        m = re.match(r"^h([1-6])$", child.tag, flags=re.IGNORECASE)
+        if m is not None:
+            level = int(m.group(1))
+            title = element_to_text(child)
+            self.toc.add(level, title)
+
+            if self.options.heading_anchors:
                 self._transform_heading(child)
                 return None
 
@@ -891,7 +946,7 @@ class ConfluenceStorageFormatCleaner(NodeVisitor):
 
 
 class DocumentError(RuntimeError):
-    pass
+    "Raised when a converted Markdown document has an unexpected element or attribute."
 
 
 def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
@@ -906,6 +961,14 @@ def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
     return value, text
 
 
+@dataclass
+class ConfluencePageID:
+    page_id: str
+
+    def __init__(self, page_id: str):
+        self.page_id = page_id
+
+
 @dataclass
 class ConfluenceQualifiedID:
     page_id: str
@@ -980,13 +1043,17 @@ class ConfluenceDocumentOptions:
     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
+    root_page_id: Optional[ConfluencePageID] = None
     keep_hierarchy: bool = False
     render_mermaid: bool = False
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False
 
 
+class ConversionError(RuntimeError):
+    "Raised when a Markdown document cannot be converted to Confluence Storage Format."
+
+
 class ConfluenceDocument:
     id: ConfluenceQualifiedID
     title: Optional[str]
@@ -996,14 +1063,15 @@ class ConfluenceDocument:
     options: ConfluenceDocumentOptions
     root: ET._Element
 
-    def __init__(
-        self,
+    @classmethod
+    def create(
+        cls,
         path: Path,
         options: ConfluenceDocumentOptions,
         root_dir: Path,
+        site_metadata: ConfluenceSiteMetadata,
         page_metadata: dict[Path, ConfluencePageMetadata],
-    ) -> None:
-        self.options = options
+    ) -> "ConfluenceDocument":
         path = path.resolve(True)
 
         with open(path, "r", encoding="utf-8") as f:
@@ -1019,35 +1087,61 @@ class ConfluenceDocument:
                     metadata.page_id, metadata.space_key
                 )
         if qualified_id is None:
-            raise ValueError("missing Confluence page ID")
+            raise PageError("missing Confluence page ID")
+
+        return ConfluenceDocument(
+            path, text, qualified_id, options, root_dir, site_metadata, page_metadata
+        )
+
+    def __init__(
+        self,
+        path: Path,
+        text: str,
+        qualified_id: ConfluenceQualifiedID,
+        options: ConfluenceDocumentOptions,
+        root_dir: Path,
+        site_metadata: ConfluenceSiteMetadata,
+        page_metadata: dict[Path, ConfluencePageMetadata],
+    ) -> None:
+        self.options = options
         self.id = qualified_id
 
+        # extract frontmatter
+        self.title, text = extract_frontmatter_title(text)
+
         # extract 'generated-by' tag text
         generated_by_tag, text = extract_value(
             r"<!--\s+generated-by:\s*(.*)\s+-->", text
         )
 
-        # extract frontmatter
-        self.title, text = extract_frontmatter_title(text)
-
         # convert to HTML
         html = markdown_to_html(text)
 
         # parse Markdown document
         if self.options.generated_by is not None:
-            generated_by = self.options.generated_by
             if generated_by_tag is not None:
-                generated_by = generated_by_tag
+                generated_by_text = generated_by_tag
+            else:
+                generated_by_text = self.options.generated_by
+        else:
+            generated_by_text = None
+
+        if generated_by_text is not None:
+            generated_by_html = markdown_to_html(generated_by_text)
 
             content = [
                 '<ac:structured-macro ac:name="info" ac:schema-version="1">',
-                f"<ac:rich-text-body><p>{generated_by}</p></ac:rich-text-body>",
+                f"<ac:rich-text-body>{generated_by_html}</ac:rich-text-body>",
                 "</ac:structured-macro>",
                 html,
             ]
         else:
             content = [html]
-        self.root = elements_from_strings(content)
+
+        try:
+            self.root = elements_from_strings(content)
+        except ParseError as ex:
+            raise ConversionError(path) from ex
 
         converter = ConfluenceStorageFormatConverter(
             ConfluenceConverterOptions(
@@ -1059,6 +1153,7 @@ class ConfluenceDocument:
             ),
             path,
             root_dir,
+            site_metadata,
             page_metadata,
         )
         converter.visit(self.root)
@@ -1066,6 +1161,9 @@ class ConfluenceDocument:
         self.images = converter.images
         self.embedded_images = converter.embedded_images
 
+        if self.title is None:
+            self.title = converter.toc.get_title()
+
     def xhtml(self) -> str:
         return elements_to_string(self.root)
 

md2conf/emoji.py

@@ -10,6 +10,8 @@ import pathlib
 
 import pymdownx.emoji1_db as emoji_db
 
+EMOJI_PAGE_ID = "86918529216"
+
 
 def generate_source(path: pathlib.Path) -> None:
     "Generates a source Markdown document for testing emojis."
@@ -17,7 +19,7 @@ def generate_source(path: pathlib.Path) -> None:
     emojis = emoji_db.emoji
 
     with open(path, "w") as f:
-        print("<!-- confluence-page-id: 86918529216 -->", file=f)
+        print(f"<!-- confluence-page-id: {EMOJI_PAGE_ID} -->", file=f)
         print("<!-- This file has been generated by a script. -->", file=f)
         print(file=f)
         print("## Emoji", file=f)

md2conf/local.py

@@ -0,0 +1,132 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import hashlib
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+from .converter import (
+    ConfluenceDocument,
+    ConfluenceDocumentOptions,
+    ConfluencePageID,
+    ConfluenceQualifiedID,
+    extract_qualified_id,
+)
+from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
+from .processor import Converter, Processor, ProcessorFactory
+from .properties import PageError
+
+LOGGER = logging.getLogger(__name__)
+
+
+class LocalProcessor(Processor):
+    """
+    Transforms a single Markdown page or a directory of Markdown pages into Confluence Storage Format (CSF) documents.
+    """
+
+    def __init__(
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        *,
+        out_dir: Optional[Path],
+        root_dir: Path,
+    ) -> None:
+        """
+        Initializes a new processor instance.
+
+        :param options: Options that control the generated page content.
+        :param site: Data associated with a Confluence wiki site.
+        :param out_dir: File system directory to write generated CSF documents to.
+        :param root_dir: File system directory that acts as topmost root node.
+        """
+
+        super().__init__(options, site, root_dir)
+        self.out_dir = out_dir or root_dir
+
+    def _get_or_create_page(
+        self,
+        absolute_path: Path,
+        parent_id: Optional[ConfluencePageID],
+        *,
+        title: Optional[str] = None,
+    ) -> ConfluencePageMetadata:
+        """
+        Extracts metadata from a Markdown file.
+        """
+
+        # parse file
+        with open(absolute_path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        qualified_id, text = extract_qualified_id(text)
+
+        if qualified_id is None:
+            if parent_id is None:
+                raise PageError(
+                    f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
+                )
+
+            hash = hashlib.md5(text.encode("utf-8"))
+            digest = "".join(f"{c:x}" for c in hash.digest())
+            LOGGER.info("Identifier %s assigned to page: %s", digest, absolute_path)
+            qualified_id = ConfluenceQualifiedID(digest)
+
+        return ConfluencePageMetadata(
+            page_id=qualified_id.page_id,
+            space_key=qualified_id.space_key,
+            title="",
+            overwrite=True,
+        )
+
+    def _save_document(self, document: ConfluenceDocument, path: Path) -> None:
+        """
+        Saves a new version of a Confluence document.
+
+        A derived class may invoke Confluence REST API to persist the new version.
+        """
+
+        content = document.xhtml()
+        out_path = self.out_dir / path.relative_to(self.root_dir).with_suffix(".csf")
+        os.makedirs(out_path.parent, exist_ok=True)
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(content)
+
+
+class LocalProcessorFactory(ProcessorFactory):
+    out_dir: Optional[Path]
+
+    def __init__(
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        out_dir: Optional[Path] = None,
+    ) -> None:
+        super().__init__(options, site)
+        self.out_dir = out_dir
+
+    def create(self, root_dir: Path) -> Processor:
+        return LocalProcessor(
+            self.options, self.site, out_dir=self.out_dir, root_dir=root_dir
+        )
+
+
+class LocalConverter(Converter):
+    """
+    The entry point for Markdown to Confluence conversion.
+    """
+
+    def __init__(
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        out_dir: Optional[Path] = None,
+    ) -> None:
+        super().__init__(LocalProcessorFactory(options, site, out_dir))

md2conf/mermaid.py

@@ -47,7 +47,7 @@ def has_mmdc() -> bool:
     return shutil.which(executable) is not None
 
 
-def render(source: str, output_format: Literal["png", "svg"] = "png") -> bytes:
+def render_diagram(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}"

md2conf/metadata.py

@@ -0,0 +1,42 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ConfluenceSiteMetadata:
+    """
+    Data associated with a Confluence wiki site.
+
+    :param domain: Confluence organization domain (e.g. `levente-hunyadi.atlassian.net`).
+    :param base_path: Base path for Confluence (default: `/wiki/`).
+    :param space_key: Confluence space key for new pages (e.g. `~hunyadi` or `INST`).
+    """
+
+    domain: str
+    base_path: str
+    space_key: Optional[str]
+
+
+@dataclass
+class ConfluencePageMetadata:
+    """
+    Data associated with a Confluence page.
+
+    :param page_id: Confluence page ID.
+    :param space_key: Confluence space key.
+    :param title: Document title.
+    :param overwrite: True if operations are allowed to update document properties (e.g. title).
+    """
+
+    page_id: str
+    space_key: Optional[str]
+    title: str
+    overwrite: bool