markdown-to-confluence 0.5.3__py3-none-any.whl → 0.5.4__py3-none-any.whl

md2conf/__main__.py

@@ -16,17 +16,22 @@ import sys
 import typing
 from io import StringIO
 from pathlib import Path
+from types import TracebackType
 from typing import Any, Iterable, Literal, Sequence
 
+from requests.exceptions import HTTPError, JSONDecodeError
+
 from . import __version__
 from .compatibility import override
 from .environment import ArgumentError, ConfluenceSiteProperties, ConnectionProperties
 from .metadata import ConfluenceSiteMetadata
 from .options import ConfluencePageID, ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions
 
+LOGGER = logging.getLogger(__name__)
+
 
 class Arguments(argparse.Namespace):
-    mdpath: Path
+    mdpath: list[Path]
     domain: str | None
     path: str | None
     api_url: str | None
@@ -41,6 +46,7 @@ class Arguments(argparse.Namespace):
     skip_title_heading: bool
     title_prefix: str | None
     generated_by: str | None
+    skip_update: bool
     prefer_raster: bool
     render_drawio: bool
     render_mermaid: bool
@@ -100,7 +106,7 @@ def get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(formatter_class=PositionalOnlyHelpFormatter)
     parser.prog = os.path.basename(os.path.dirname(__file__))
     parser.add_argument("--version", action="version", version=__version__)
-    parser.add_argument("mdpath", help="Path to Markdown file or directory to convert and publish.")
+    parser.add_argument("mdpath", type=Path, nargs="+", help="Path to Markdown file or directory to convert and publish.")
     parser.add_argument("-d", "--domain", help="Confluence organization domain.")
     parser.add_argument("-p", "--path", help="Base path for Confluence (default: '/wiki/').")
     parser.add_argument(
@@ -166,6 +172,12 @@ def get_parser() -> argparse.ArgumentParser:
         const=None,
         help="Do not add 'generated by a tool' prompt to pages.",
     )
+    parser.add_argument(
+        "--skip-update",
+        action="store_true",
+        default=False,
+        help="Skip saving Confluence page ID in Markdown files.",
+    )
     parser.add_argument(
         "--render-drawio",
         dest="render_drawio",
@@ -324,13 +336,31 @@ def get_help() -> str:
         return buf.getvalue()
 
 
+def _exception_hook(exc_type: type[BaseException], exc_value: BaseException, traceback: TracebackType | None) -> None:
+    LOGGER.exception("Exception raised: %s", exc_type.__name__, exc_info=exc_value)
+    ex: BaseException | None = exc_value
+    while ex is not None:
+        print(f"\033[95m{ex.__class__.__name__}\033[0m: {ex}")
+
+        if isinstance(ex, HTTPError):
+            # print details for a response with JSON body
+            if ex.response is not None:
+                try:
+                    LOGGER.error(ex.response.json())
+                except JSONDecodeError:
+                    pass
+
+        ex = ex.__cause__
+
+
+sys.excepthook = _exception_hook
+
+
 def main() -> None:
     parser = get_parser()
     args = Arguments()
     parser.parse_args(namespace=args)
 
-    args.mdpath = Path(args.mdpath)
-
     logging.basicConfig(
         level=getattr(logging, args.loglevel.upper(), logging.INFO),
         format="%(asctime)s - %(levelname)s - %(funcName)s [%(lineno)d] - %(message)s",
@@ -341,6 +371,7 @@ def main() -> None:
         keep_hierarchy=args.keep_hierarchy,
         title_prefix=args.title_prefix,
         generated_by=args.generated_by,
+        skip_update=args.skip_update,
         converter=ConverterOptions(
             heading_anchors=args.heading_anchors,
             ignore_invalid_url=args.ignore_invalid_url,
@@ -377,10 +408,10 @@ def main() -> None:
             base_path=site_properties.base_path,
             space_key=site_properties.space_key,
         )
-        LocalConverter(options, site_metadata).process(args.mdpath)
+        converter = LocalConverter(options, site_metadata)
+        for item in args.mdpath:
+            converter.process(item)
     else:
-        from requests import HTTPError, JSONDecodeError
-
         from .api import ConfluenceAPI
         from .publisher import Publisher
 
@@ -396,20 +427,10 @@ def main() -> None:
             )
         except ArgumentError as e:
             parser.error(str(e))
-        try:
-            with ConfluenceAPI(properties) as api:
-                Publisher(api, options).process(args.mdpath)
-        except HTTPError as err:
-            logging.error(err)
-
-            # print details for a response with JSON body
-            if err.response is not None:
-                try:
-                    logging.error(err.response.json())
-                except JSONDecodeError:
-                    pass
-
-            sys.exit(1)
+        with ConfluenceAPI(properties) as api:
+            publisher = Publisher(api, options)
+            for item in args.mdpath:
+                publisher.process(item)
 
 
 if __name__ == "__main__":

md2conf/api.py

@@ -890,10 +890,10 @@ class ConfluenceSession:
                 else:
                     raise
 
-        # This should not be reached, but satisfies type checker
+        # this should not be reached, but satisfies type checker
         if last_error is not None:
             raise last_error
-        raise ConfluenceError(f"Failed to get page {page_id}")
+        raise ConfluenceError(f"failed to get page: {page_id}")
 
     def get_page_properties(self, page_id: str) -> ConfluencePageProperties:
         """
@@ -1058,6 +1058,7 @@ class ConfluenceSession:
 
         :param title: Page title. Pages in the same Confluence space must have a unique title.
         :param parent_id: Identifies the parent page for a new child page.
+        :returns: Confluence page info for the found or newly created page.
         """
 
         parent_page = self.get_page_properties(parent_id)

md2conf/converter.py

@@ -633,7 +633,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             absolute_path = (self.base_dir / path).resolve()
 
         if not absolute_path.exists():
-            self._warn_or_raise(f"path to image {path} does not exist")
+            self._warn_or_raise(f"path to image does not exist: {path}")
             return None
 
         if not is_directory_within(absolute_path, self.root_dir):
@@ -802,7 +802,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         content = blockquote[0]
         if content.text is None:
-            raise DocumentError("empty content")
+            raise DocumentError("empty content for GitHub alert")
 
         pattern = re.compile(r"^\[!([A-Z]+)\]\s*")
         match = pattern.match(content.text)
@@ -839,7 +839,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         content = blockquote[0]
         if content.text is None:
-            raise DocumentError("empty content")
+            raise DocumentError("empty content for GitLab alert")
 
         pattern = re.compile(r"^(FLAG|NOTE|WARNING|DISCLAIMER):\s*")
         match = pattern.match(content.text)
@@ -1324,10 +1324,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         tasks: list[ElementType] = []
         for index, item in enumerate(elem, start=1):
             if item.text is None:
-                raise NotImplementedError("pre-condition check not exhaustive")
+                raise NotImplementedError("pre-condition check for tasklist not exhaustive")
             match = re.match(r"^\[([x X])\]", item.text)
             if match is None:
-                raise NotImplementedError("pre-condition check not exhaustive")
+                raise NotImplementedError("pre-condition check for tasklist not exhaustive")
 
             status = "incomplete" if match.group(1).isspace() else "complete"
             item.text = item.text[3:]
@@ -1630,7 +1630,7 @@ class ConfluenceDocument:
         try:
             self.root = elements_from_strings(content)
         except ParseError as ex:
-            raise ConversionError(path) from ex
+            raise ConversionError(f"failed to convert Markdown file: {path}") from ex
 
         # configure HTML-to-Confluence converter
         converter_options = copy.deepcopy(self.options.converter)
@@ -1641,8 +1641,8 @@ class ConfluenceDocument:
         # execute HTML-to-Confluence converter
         try:
             converter.visit(self.root)
-        except DocumentError as ex:
-            raise ConversionError(path) from ex
+        except RuntimeError as ex:
+            raise ConversionError(f"failed to convert Markdown file: {path}") from ex
 
         # extract information discovered by converter
         self.links = converter.links

md2conf/drawio/extension.py

@@ -14,7 +14,7 @@ import lxml.etree as ET
 from md2conf.attachment import EmbeddedFileData, ImageData, attachment_name
 from md2conf.compatibility import override, path_relative_to
 from md2conf.csf import AC_ATTR, AC_ELEM
-from md2conf.extension import MarketplaceExtension
+from md2conf.extension import ExtensionError, MarketplaceExtension
 from md2conf.formatting import ImageAlignment, ImageAttributes
 
 from .render import extract_diagram, render_diagram
@@ -38,11 +38,11 @@ class DrawioExtension(MarketplaceExtension):
         elif absolute_path.name.endswith((".drawio", ".drawio.xml")):
             return self._transform_drawio(absolute_path, attrs)
         else:
-            raise RuntimeError(f"unrecognized image format: {absolute_path.suffix}")
+            raise ExtensionError(f"unrecognized image format: {absolute_path.suffix}")
 
     @override
     def transform_fenced(self, content: str) -> ElementType:
-        raise RuntimeError("draw.io diagrams cannot be defined in fenced code blocks")
+        raise ExtensionError("draw.io diagrams cannot be defined in fenced code blocks")
 
     def _transform_drawio(self, absolute_path: Path, attrs: ImageAttributes) -> ElementType:
         relative_path = path_relative_to(absolute_path, self.base_dir)

md2conf/extension.py

@@ -19,6 +19,10 @@ from .image import ImageGenerator
 ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
 
 
+class ExtensionError(RuntimeError):
+    pass
+
+
 @dataclass
 class ExtensionOptions:
     """

md2conf/external.py

@@ -7,13 +7,14 @@ Copyright 2022-2026, Levente Hunyadi
 """
 
 import logging
+import re
 import subprocess
 from typing import Sequence
 
 LOGGER = logging.getLogger(__name__)
 
 
-def execute_subprocess(command: Sequence[str], data: bytes, *, application: str | None = None) -> bytes:
+def execute_subprocess(command: Sequence[str], data: bytes, *, application: str) -> bytes:
     """
     Executes a subprocess, feeding input to stdin, and capturing output from stdout.
 
@@ -37,13 +38,29 @@ def execute_subprocess(command: Sequence[str], data: bytes, *, application: str
     stdout, stderr = proc.communicate(input=data)
 
     if proc.returncode:
-        messages = [f"failed to execute {application or 'application'}; exit code: {proc.returncode}"]
-        console_output = stdout.decode("utf-8")
-        if console_output:
-            messages.append(f"output:\n{console_output}")
-        console_error = stderr.decode("utf-8")
-        if console_error:
-            messages.append(f"error:\n{console_error}")
+        message = f"failed to execute {application}; exit code: {proc.returncode}"
+        LOGGER.error("Failed to execute %s; exit code: %d", application, proc.returncode)
+        messages = [message]
+        if stdout:
+            try:
+                console_output = stdout.decode("utf-8")
+                LOGGER.error(console_output)
+                messages.append(f"output:\n{console_output}")
+            except UnicodeDecodeError:
+                LOGGER.error("%s returned binary data on stdout", application)
+                pass
+        if stderr:
+            try:
+                console_error = stderr.decode("utf-8")
+                LOGGER.error(console_error)
+
+                # omit Node.js exception stack trace
+                console_error = re.sub(r"^\s+at.*:\d+:\d+\)$\n", "", console_error, flags=re.MULTILINE).rstrip()
+
+                messages.append(f"error:\n{console_error}")
+            except UnicodeDecodeError:
+                LOGGER.error("%s returned binary data on stderr", application)
+                pass
         raise RuntimeError("\n".join(messages))
 
     return stdout

md2conf/image.py

@@ -58,12 +58,13 @@ class ImageGenerator:
 
         # infer SVG dimensions if not already specified
         if absolute_path.suffix == ".svg" and attrs.width is None and attrs.height is None:
-            svg_width, svg_height = get_svg_dimensions(absolute_path)
-            if svg_width is not None:
+            dimensions = get_svg_dimensions(absolute_path)
+            if dimensions is not None:
+                width, height = dimensions
                 attrs = ImageAttributes(
                     context=attrs.context,
-                    width=svg_width,
-                    height=svg_height,
+                    width=width,
+                    height=height,
                     alt=attrs.alt,
                     title=attrs.title,
                     caption=attrs.caption,
@@ -78,17 +79,17 @@ class ImageGenerator:
         "Emits Confluence Storage Format XHTML for an attached raster or vector image."
 
         # extract dimensions and update attributes based on format
-        width: int | None
-        height: int | None
+        dimensions: tuple[int, int] | None
         match self.options.output_format:
             case "svg":
-                image_data, width, height = fix_svg_get_dimensions(image_data)
+                image_data, dimensions = fix_svg_get_dimensions(image_data)
             case "png":
-                width, height = extract_png_dimensions(data=image_data)
+                dimensions = extract_png_dimensions(data=image_data)
 
         # only update attributes if we successfully extracted dimensions and the base attributes don't already have explicit dimensions
-        if (width is not None or height is not None) and (attrs.width is None and attrs.height is None):
+        if dimensions is not None and (attrs.width is None and attrs.height is None):
             # create updated image attributes with extracted dimensions
+            width, height = dimensions
             attrs = ImageAttributes(
                 context=attrs.context,
                 width=width,

md2conf/mermaid/render.py

@@ -67,7 +67,7 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png", co
         str(config.scale or 2),
     ]
     if _is_docker():
-        root = os.path.dirname(os.path.dirname(__file__))
+        root = os.path.dirname(__file__)
         cmd.extend(["-p", os.path.join(root, "puppeteer-config.json")])
 
     return execute_subprocess(cmd, source.encode("utf-8"), application="Mermaid")

md2conf/options.py

@@ -106,6 +106,7 @@ class DocumentOptions:
     :param keep_hierarchy: Whether to maintain source directory structure when exporting to Confluence.
     :param title_prefix: String to prepend to Confluence page title for each published page.
     :param generated_by: Text to use as the generated-by prompt (or `None` to omit a prompt).
+    :param skip_update: Whether to skip saving Confluence page ID in Markdown files.
     :param converter: Options for converting an HTML tree into Confluence Storage Format.
     """
 
@@ -113,4 +114,5 @@ class DocumentOptions:
     keep_hierarchy: bool = False
     title_prefix: str | None = None
     generated_by: str | None = "This page has been generated with a tool."
+    skip_update: bool = False
     converter: ConverterOptions = dataclasses.field(default_factory=ConverterOptions)

md2conf/plantuml/extension.py

@@ -19,7 +19,7 @@ from md2conf.compatibility import override, path_relative_to
 from md2conf.csf import AC_ATTR, AC_ELEM
 from md2conf.extension import MarketplaceExtension
 from md2conf.formatting import ImageAttributes
-from md2conf.svg import get_svg_dimensions_from_bytes
+from md2conf.svg import get_svg_dimensions
 
 from .config import PlantUMLConfigProperties
 from .render import compress_plantuml_data, has_plantuml, render_diagram
@@ -87,7 +87,7 @@ class PlantUMLExtension(MarketplaceExtension):
                 image_data = render_diagram(content, "svg", config=config)
 
                 # extract dimensions from SVG
-                width, height = get_svg_dimensions_from_bytes(image_data)
+                dimensions = get_svg_dimensions(image_data)
 
                 # generate SVG filename and add as attachment
                 if relative_path is not None:
@@ -98,11 +98,11 @@ class PlantUMLExtension(MarketplaceExtension):
                     svg_filename = attachment_name(f"embedded_{plantuml_hash}.svg")
                     self.attachments.add_embed(svg_filename, EmbeddedFileData(image_data))
 
-                return self._create_plantuml_macro(content, svg_filename, width, height)
+                return self._create_plantuml_macro(content, svg_filename, dimensions)
             else:
                 return self._create_plantuml_macro(content)
 
-    def _create_plantuml_macro(self, source: str, filename: str | None = None, width: int | None = None, height: int | None = None) -> ElementType:
+    def _create_plantuml_macro(self, source: str, filename: str | None = None, dimensions: tuple[int, int] | None = None) -> ElementType:
         """
         A PlantUML diagram using a `structured-macro` with embedded data.
 
@@ -128,7 +128,8 @@ class PlantUMLExtension(MarketplaceExtension):
             parameters.append(AC_ELEM("parameter", {AC_ATTR("name"): "filename"}, filename))
 
         # add optional dimension parameters if available
-        if width is not None:
+        if dimensions is not None:
+            width, height = dimensions
             parameters.append(
                 AC_ELEM(
                     "parameter",
@@ -136,7 +137,6 @@ class PlantUMLExtension(MarketplaceExtension):
                     str(width),
                 )
             )
-        if height is not None:
             parameters.append(
                 AC_ELEM(
                     "parameter",

md2conf/plantuml/render.py

@@ -92,17 +92,16 @@ def render_diagram(
     if config is None:
         config = PlantUMLConfigProperties()
 
-    # Build command for PlantUML with pipe mode
-    # -pipe: read from stdin and write to stdout
-    # -t<format>: output format (png or svg)
-    # -charset utf-8: ensure UTF-8 encoding
+    # command for PlantUML with pipe mode
     cmd = _get_plantuml_command()
     cmd.extend(
         [
-            "-pipe",
-            f"-t{output_format}",
-            "-charset",
+            "--charset",
             "utf-8",
+            "--format",
+            output_format,
+            "--no-error-image",
+            "--pipe",
         ]
     )
 

md2conf/png.py

@@ -12,6 +12,10 @@ from struct import unpack
 from typing import BinaryIO, Iterable, overload
 
 
+class ImageFormatError(RuntimeError):
+    pass
+
+
 class _Chunk:
     "Data chunk in binary data as per the PNG image format."
 
@@ -34,7 +38,7 @@ def _read_signature(f: BinaryIO) -> None:
 
     signature = f.read(8)
     if signature != b"\x89PNG\r\n\x1a\n":
-        raise ValueError("not a valid PNG file")
+        raise ImageFormatError("not a valid PNG file")
 
 
 def _read_chunk(f: BinaryIO) -> _Chunk | None:
@@ -45,7 +49,7 @@ def _read_chunk(f: BinaryIO) -> _Chunk | None:
         return None
 
     if len(length_bytes) != 4:
-        raise ValueError("expected: 4 bytes storing chunk length")
+        raise ImageFormatError("expected: 4 bytes storing chunk length")
 
     length = int.from_bytes(length_bytes, "big")
 
@@ -53,7 +57,7 @@ def _read_chunk(f: BinaryIO) -> _Chunk | None:
     data_bytes = f.read(data_length)
     actual_length = len(data_bytes)
     if actual_length != data_length:
-        raise ValueError(f"expected: {length} bytes storing chunk data; got: {actual_length}")
+        raise ImageFormatError(f"expected: {length} bytes storing chunk data; got: {actual_length}")
 
     chunk_type = data_bytes[0:4]
     chunk_data = data_bytes[4:-4]
@@ -75,12 +79,12 @@ def _extract_png_dimensions(source_file: BinaryIO) -> tuple[int, int]:
     # validate IHDR (Image Header) chunk
     ihdr = _read_chunk(source_file)
     if ihdr is None:
-        raise ValueError("missing IHDR chunk")
+        raise ImageFormatError("missing IHDR chunk")
 
     if ihdr.length != 13:
-        raise ValueError("invalid chunk length")
+        raise ImageFormatError("invalid chunk length")
     if ihdr.name != b"IHDR":
-        raise ValueError(f"expected: IHDR chunk; got: {ihdr.name!r}")
+        raise ImageFormatError(f"expected: IHDR chunk; got: {ihdr.name!r}")
 
     (
         width,

md2conf/processor.py

@@ -15,11 +15,12 @@ from typing import Iterable
 
 from .collection import ConfluencePageCollection
 from .converter import ConfluenceDocument
-from .environment import ArgumentError
+from .environment import ArgumentError, PageError
 from .matcher import DirectoryEntry, FileEntry, Matcher, MatcherOptions
 from .metadata import ConfluenceSiteMetadata
 from .options import ConfluencePageID, DocumentOptions
 from .scanner import Scanner
+from .toc import unique_title
 
 LOGGER = logging.getLogger(__name__)
 
@@ -143,6 +144,22 @@ class Processor:
         Processes a sub-tree rooted at an ancestor node.
         """
 
+        # verify if pages have a unique title to avoid overwrites within synchronized set
+        title_to_path: dict[str, Path] = {}
+        duplicates: set[Path] = set()
+        for node in root.all():
+            if node.title is not None:
+                path = title_to_path.get(node.title)
+                if path is not None:
+                    duplicates.add(path)
+                    duplicates.add(node.absolute_path)
+                else:
+                    title_to_path[node.title] = node.absolute_path
+        if duplicates:
+            raise PageError(
+                f"expected: each synchronized page to have a unique title but duplicates found in files: {', '.join(str(p) for p in sorted(list(duplicates)))}"
+            )
+
         # synchronize directory tree structure with page hierarchy in space (find matching pages in Confluence)
         self._synchronize_tree(root, self.options.root_page_id)
 
@@ -246,14 +263,18 @@ class Processor:
         LOGGER.info("Indexing file: %s", path)
 
         # extract information from a Markdown document found in a local directory.
-        document = Scanner().read(path)
+        with open(path, "r", encoding="utf-8") as f:
+            text = f.read()
 
+        document = Scanner().parse(text)
         props = document.properties
+        title = props.title or unique_title(text)
+
         return DocumentNode(
             absolute_path=path,
             page_id=props.page_id,
             space_key=props.space_key,
-            title=props.title,
+            title=title,
             synchronized=props.synchronized if props.synchronized is not None else True,
         )