markdown-to-confluence 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

md2conf/converter.py

@@ -35,6 +35,7 @@ from .mermaid import MermaidConfigProperties
 from .metadata import ConfluenceSiteMetadata
 from .scanner import MermaidScanner, ScannedDocument, Scanner
 from .serializer import JsonType
+from .svg import fix_svg_dimensions, get_svg_dimensions, get_svg_dimensions_from_bytes
 from .toc import TableOfContentsBuilder
 from .uri import is_absolute_url, to_uuid_urn
 from .xml import element_to_text
@@ -42,6 +43,27 @@ from .xml import element_to_text
 ElementType = ET._Element  # pyright: ignore [reportPrivateUsage]
 
 
+def apply_generated_by_template(template: str, path: Path) -> str:
+    """Apply template substitution to the generated_by string.
+
+    Supported placeholders:
+    - %{filepath}: Full path to the file (relative to the root directory)
+    - %{filename}: Just the filename
+
+    :param template: The template string with placeholders
+    :param path: The path to the file being converted
+    :returns: The template string with placeholders replaced
+    """
+
+    return template.replace(
+        "%{filepath}",
+        path.as_posix(),
+    ).replace(
+        "%{filename}",
+        path.name,
+    )
+
+
 def get_volatile_attributes() -> list[str]:
     "Returns a list of volatile attributes that frequently change as a Confluence storage format XHTML document is updated."
 
@@ -81,6 +103,12 @@ def is_directory_within(absolute_path: Path, base_path: Path) -> bool:
     return absolute_path.as_posix().startswith(base_path.as_posix())
 
 
+def fix_absolute_path(path: Path, root_path: Path) -> Path:
+    "Make absolute path relative to another root path."
+
+    return root_path / path.relative_to(path.root)
+
+
 def encode_title(text: str) -> str:
     "Converts a title string such that it is safe to embed into a Confluence URL."
 
@@ -95,6 +123,7 @@ def encode_title(text: str) -> str:
 
 
 # supported code block languages, for which syntax highlighting is available
+# spellchecker: disable
 _LANGUAGES = {
     "abap": "abap",
     "actionscript3": "actionscript3",
@@ -179,6 +208,7 @@ _LANGUAGES = {
     "xquery": "xquery",
     "yaml": "yaml",
 }
+# spellchecker: enable
 
 
 class NodeVisitor(ABC):
@@ -270,6 +300,7 @@ class ImageAttributes:
     :param title: Title text (a.k.a. image tooltip).
     :param caption: Caption text (shown below figure).
     :param alignment: Alignment for block-level images.
+    :param display_width: Constrained display width in pixels (if different from natural width).
     """
 
     context: FormattingContext
@@ -279,6 +310,7 @@ class ImageAttributes:
     title: str | None
     caption: str | None
     alignment: ImageAlignment = ImageAlignment.CENTER
+    display_width: int | None = None
 
     def __post_init__(self) -> None:
         if self.caption is None and self.context is FormattingContext.BLOCK:
@@ -303,7 +335,9 @@ class ImageAttributes:
                 attributes[AC_ATTR("original-height")] = str(self.height)
             if self.width is not None:
                 attributes[AC_ATTR("custom-width")] = "true"
-                attributes[AC_ATTR("width")] = str(self.width)
+                # Use display_width if set, otherwise use natural width
+                effective_width = self.display_width or self.width
+                attributes[AC_ATTR("width")] = str(effective_width)
 
         elif self.context is FormattingContext.INLINE:
             if self.width is not None:
@@ -349,6 +383,7 @@ class ConfluenceConverterOptions:
         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 skip_title_heading: Whether to remove the first heading from document body when used as page title.
     :param prefer_raster: Whether to choose PNG files over SVG files when available.
     :param render_drawio: Whether to pre-render (or use the pre-rendered version of) draw.io diagrams.
     :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
@@ -356,11 +391,13 @@ class ConfluenceConverterOptions:
     :param diagram_output_format: Target image format for diagrams.
     :param webui_links: When true, convert relative URLs to Confluence Web UI links.
     :param alignment: Alignment for block-level images and formulas.
+    :param max_image_width: Maximum display width for images in pixels.
     :param use_panel: Whether to transform admonitions and alerts into a Confluence custom panel.
     """
 
     ignore_invalid_url: bool = False
     heading_anchors: bool = False
+    skip_title_heading: bool = False
     prefer_raster: bool = True
     render_drawio: bool = False
     render_mermaid: bool = False
@@ -368,8 +405,23 @@ class ConfluenceConverterOptions:
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False
     alignment: Literal["center", "left", "right"] = "center"
+    max_image_width: int | None = None
     use_panel: bool = False
 
+    def calculate_display_width(self, natural_width: int | None) -> int | None:
+        """
+        Calculate the display width for an image, applying max_image_width constraint if set.
+
+        :param natural_width: The natural width of the image in pixels.
+        :returns: The constrained display width, or None if no constraint is needed.
+        """
+
+        if natural_width is None or self.max_image_width is None:
+            return None
+        if natural_width <= self.max_image_width:
+            return None  # no constraint needed, image is already within limits
+        return self.max_image_width
+
 
 @dataclass
 class ImageData:
@@ -545,9 +597,11 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
 
         # discard original value: relative links always require transformation
         anchor.attrib.pop("href")
-
-        # convert the relative URL to absolute path based on the base path value
-        absolute_path = (self.base_dir / relative_url.path).resolve()
+        if relative_url.path.startswith("/"):
+            absolute_path = fix_absolute_path(path=Path(relative_url.path), root_path=self.root_dir).resolve()
+        else:
+            # convert the relative URL to absolute path based on the base path value
+            absolute_path = (self.base_dir / relative_url.path).resolve()
 
         # look up the absolute path in the page metadata dictionary to discover the relative path within Confluence that should be used
         if not is_directory_within(absolute_path, self.root_dir):
@@ -668,7 +722,14 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         pixel_width = int(width) if width is not None and width.isdecimal() else None
         pixel_height = int(height) if height is not None and height.isdecimal() else None
         attrs = ImageAttributes(
-            context, width=pixel_width, height=pixel_height, alt=alt, title=title, caption=None, alignment=ImageAlignment(self.options.alignment)
+            context,
+            width=pixel_width,
+            height=pixel_height,
+            alt=alt,
+            title=title,
+            caption=None,
+            alignment=ImageAlignment(self.options.alignment),
+            display_width=self.options.calculate_display_width(pixel_width),
         )
 
         if is_absolute_url(src):
@@ -716,8 +777,11 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     def _verify_image_path(self, path: Path) -> Path | None:
         "Checks whether an image path is safe to use."
 
-        # resolve relative path into absolute path w.r.t. base dir
-        absolute_path = (self.base_dir / path).resolve()
+        if path.is_absolute():
+            absolute_path = fix_absolute_path(path=path, root_path=self.root_dir).resolve()
+        else:
+            # resolve relative path into absolute path w.r.t. base dir
+            absolute_path = (self.base_dir / path).resolve()
 
         if not absolute_path.exists():
             self._warn_or_raise(f"path to image {path} does not exist")
@@ -738,6 +802,21 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             if png_file.exists():
                 absolute_path = png_file
 
+        # 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:
+                attrs = ImageAttributes(
+                    context=attrs.context,
+                    width=svg_width,
+                    height=svg_height,
+                    alt=attrs.alt,
+                    title=attrs.title,
+                    caption=attrs.caption,
+                    alignment=attrs.alignment,
+                    display_width=self.options.calculate_display_width(svg_width),
+                )
+
         self.images.append(ImageData(absolute_path, attrs.alt))
         image_name = attachment_name(path_relative_to(absolute_path, self.base_dir))
         return self._create_attached_image(image_name, attrs)
@@ -926,8 +1005,29 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 content = f.read()
             config = self._extract_mermaid_config(content)
             image_data = mermaid.render_diagram(content, self.options.diagram_output_format, config=config)
+
+            # Extract dimensions and fix SVG if that's the output format
+            if self.options.diagram_output_format == "svg":
+                # Fix SVG to have explicit width/height instead of percentages
+                image_data = fix_svg_dimensions(image_data)
+
+                if attrs.width is None and attrs.height is None:
+                    svg_width, svg_height = get_svg_dimensions_from_bytes(image_data)
+                    if svg_width is not None or svg_height is not None:
+                        attrs = ImageAttributes(
+                            context=attrs.context,
+                            width=svg_width,
+                            height=svg_height,
+                            alt=attrs.alt,
+                            title=attrs.title,
+                            caption=attrs.caption,
+                            alignment=attrs.alignment,
+                            display_width=self.options.calculate_display_width(svg_width),
+                        )
+
             image_filename = attachment_name(relative_path.with_suffix(f".{self.options.diagram_output_format}"))
             self.embedded_files[image_filename] = EmbeddedFileData(image_data, attrs.alt)
+
             return self._create_attached_image(image_filename, attrs)
         else:
             self.images.append(ImageData(absolute_path, attrs.alt))
@@ -940,10 +1040,31 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if self.options.render_mermaid:
             config = self._extract_mermaid_config(content)
             image_data = mermaid.render_diagram(content, self.options.diagram_output_format, config=config)
+
+            # Extract dimensions and fix SVG if that's the output format
+            attrs = ImageAttributes.EMPTY_BLOCK
+            if self.options.diagram_output_format == "svg":
+                # Fix SVG to have explicit width/height instead of percentages
+                image_data = fix_svg_dimensions(image_data)
+
+                svg_width, svg_height = get_svg_dimensions_from_bytes(image_data)
+                if svg_width is not None or svg_height is not None:
+                    attrs = ImageAttributes(
+                        context=FormattingContext.BLOCK,
+                        width=svg_width,
+                        height=svg_height,
+                        alt=None,
+                        title=None,
+                        caption=None,
+                        alignment=ImageAlignment(self.options.alignment),
+                        display_width=self.options.calculate_display_width(svg_width),
+                    )
+
             image_hash = hashlib.md5(image_data).hexdigest()
             image_filename = attachment_name(f"embedded_{image_hash}.{self.options.diagram_output_format}")
             self.embedded_files[image_filename] = EmbeddedFileData(image_data)
-            return self._create_attached_image(image_filename, ImageAttributes.EMPTY_BLOCK)
+
+            return self._create_attached_image(image_filename, attrs)
         else:
             mermaid_data = content.encode("utf-8")
             mermaid_hash = hashlib.md5(mermaid_data).hexdigest()
@@ -1301,7 +1422,16 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if self.options.diagram_output_format == "png":
             width, height = get_png_dimensions(data=image_data)
             image_data = remove_png_chunks(["pHYs"], source_data=image_data)
-            attrs = ImageAttributes(context, width=width, height=height, alt=content, title=None, caption="", alignment=ImageAlignment(self.options.alignment))
+            attrs = ImageAttributes(
+                context,
+                width=width,
+                height=height,
+                alt=content,
+                title=None,
+                caption="",
+                alignment=ImageAlignment(self.options.alignment),
+                display_width=self.options.calculate_display_width(width),
+            )
         else:
             attrs = ImageAttributes.empty(context)
 
@@ -1386,8 +1516,16 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         """
         Transforms a footnote reference.
 
+        When a footnote is referenced multiple times, Python-Markdown generates
+        different `id` attributes for each reference:
+        - First reference: `fnref:NAME`
+        - Second reference: `fnref2:NAME`
+        - Third reference: `fnref3:NAME`
+        - etc.
+
         ```
         <sup id="fnref:NAME"><a class="footnote-ref" href="#fn:NAME">REF</a></sup>
+        <sup id="fnref2:NAME"><a class="footnote-ref" href="#fn:NAME">REF</a></sup>
         ```
         """
 
@@ -1395,9 +1533,14 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             raise DocumentError("expected: `<sup>` as the HTML element for a footnote reference")
 
         ref_id = elem.attrib.pop("id", "")
-        if not ref_id.startswith("fnref:"):
-            raise DocumentError("expected: attribute `id` of format `fnref:NAME` applied on `<sup>` for a footnote reference")
-        footnote_ref = ref_id.removeprefix("fnref:")
+        # Match fnref:NAME, fnref2:NAME, fnref3:NAME, etc.
+        match = re.match(r"^fnref(\d*):(.+)$", ref_id)
+        if match is None:
+            raise DocumentError("expected: attribute `id` of format `fnref:NAME` or `fnrefN:NAME` applied on `<sup>` for a footnote reference")
+        numeric_suffix = match.group(1)
+        footnote_name = match.group(2)
+        # Build anchor name: first reference uses NAME, subsequent references use NAME-N
+        footnote_ref = f"{footnote_name}-{numeric_suffix}" if numeric_suffix else footnote_name
 
         link = next((elem.iterchildren(tag="a")), None)
         if link is None:
@@ -1443,6 +1586,13 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         """
         Transforms the footnote definition block.
 
+        When a footnote is referenced multiple times, Python-Markdown generates
+        multiple back-reference links in the footnote definition:
+        - First reference: `#fnref:NAME`
+        - Second reference: `#fnref2:NAME`
+        - Third reference: `#fnref3:NAME`
+        - etc.
+
         ```
         <div class="footnote">
             <hr/>
@@ -1453,6 +1603,13 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             </ol>
         </div>
         ```
+
+        With multiple references to the same footnote:
+        ```
+        <li id="fn:NAME">
+            <p>TEXT <a class="footnote-backref" href="#fnref:NAME">↩</a><a class="footnote-backref" href="#fnref2:NAME">↩</a></p>
+        </li>
+        ```
         """
 
         ordered_list = next((elem.iterchildren(tag="ol")), None)
@@ -1468,21 +1625,33 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 raise DocumentError("expected: attribute `id` of format `fn:NAME` applied on `<li>` for a footnote definition")
             footnote_def = def_id.removeprefix("fn:")
 
-            paragraph = next((list_item.iterchildren(tag="p")), None)
-            if paragraph is None:
+            # find the last paragraph, which is where the backref links are placed
+            paragraphs = list(list_item.iterchildren(tag="p"))
+            if not paragraphs:
                 raise DocumentError("expected: `<p>` as a child of `<li>` in a footnote definition")
+            last_paragraph = paragraphs[-1]
+
+            # collect all backref anchors (there may be multiple when a footnote is referenced multiple times)
+            # pattern matches #fnref:NAME, #fnref2:NAME, #fnref3:NAME, etc.
+            # store tuples of (anchor_element, number, footnote_name)
+            backref_info: list[tuple[ElementType, int | None, str]] = []
+            for anchor in list(last_paragraph.iterchildren(tag="a")):
+                href = anchor.get("href", "")
+                match = re.match(r"^#fnref(\d*):(.+)$", href)
+                if match is not None:
+                    backref_info.append((anchor, int(match.group(1), base=10) if match.group(1) else None, match.group(2)))
+
+            if not backref_info:
+                raise DocumentError(
+                    "expected: at least one `<a>` element with `href` attribute of format `#fnref:NAME` or `#fnrefN:NAME` in a footnote definition"
+                )
 
-            ref_anchor = next((paragraph.iterchildren(tag="a", reversed=True)), None)
-            if ref_anchor is None:
-                raise DocumentError("expected: `<a>` as the last HTML element in a footnote definition")
-
-            ref_href = ref_anchor.get("href", "")
-            if not ref_href.startswith("#fnref:"):
-                raise DocumentError("expected: attribute `href` of format `#fnref:NAME` applied on last element `<a>` for a footnote definition")
-            footnote_ref = ref_href.removeprefix("#fnref:")
+            # remove all back-links generated by Python-Markdown
+            for anchor, _, _ in backref_info:
+                last_paragraph.remove(anchor)
 
-            # remove back-link generated by Python-Markdown
-            paragraph.remove(ref_anchor)
+            # use the first paragraph for the anchor placement
+            first_paragraph = paragraphs[0]
 
             # build new anchor for footnote definition
             def_anchor = AC_ELEM(
@@ -1498,20 +1667,40 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 ),
             )
 
-            # build new link to footnote reference in page body
-            ref_link = AC_ELEM(
-                "link",
-                {
-                    AC_ATTR("anchor"): f"footnote-ref-{footnote_ref}",
-                },
-                AC_ELEM("link-body", ET.CDATA("↩")),
-            )
+            # build back-links to each footnote reference in page body:
+            # * for single reference: ↩
+            # * for multiple references: ↩¹ ↩² ↩³ ...
+            for _, number, footnote_name in backref_info:
+                # build anchor name matching the reference anchor:
+                # * first reference: footnote-ref-NAME
+                # * subsequent references: footnote-ref-NAME-N
+                if number is None:
+                    anchor_name = f"footnote-ref-{footnote_name}"
+                    if len(backref_info) > 1:
+                        link_text = "↩¹"
+                    else:
+                        link_text = "↩"
+                else:
+                    anchor_name = f"footnote-ref-{footnote_name}-{number}"
+
+                    # use superscript numbers for references
+                    superscript_digits = str.maketrans("0123456789", "⁰¹²³⁴⁵⁶⁷⁸⁹")
+                    link_text = f"↩{str(number).translate(superscript_digits)}"
+
+                ref_link = AC_ELEM(
+                    "link",
+                    {
+                        AC_ATTR("anchor"): anchor_name,
+                    },
+                    AC_ELEM("link-body", ET.CDATA(link_text)),
+                )
+
+                last_paragraph.append(ref_link)
 
-            # append children synthesized for Confluence
-            paragraph.insert(0, def_anchor)
-            def_anchor.tail = paragraph.text
-            paragraph.text = None
-            paragraph.append(ref_link)
+            # append anchor to first paragraph
+            first_paragraph.insert(0, def_anchor)
+            def_anchor.tail = first_paragraph.text
+            first_paragraph.text = None
 
     def _transform_tasklist(self, elem: ElementType) -> ElementType:
         """
@@ -1699,7 +1888,8 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 return self._transform_inline_math(child)
 
         # <sup id="fnref:NAME"><a class="footnote-ref" href="#fn:NAME">1</a></sup>
-        elif child.tag == "sup" and child.get("id", "").startswith("fnref:"):
+        # Multiple references: <sup id="fnref2:NAME">...</sup>, <sup id="fnref3:NAME">...</sup>
+        elif child.tag == "sup" and re.match(r"^fnref\d*:", child.get("id", "")):
             self._transform_footnote_ref(child)
             return None
 
@@ -1807,6 +1997,7 @@ class ConfluenceDocument:
             generated_by = None
 
         if generated_by is not None:
+            generated_by = apply_generated_by_template(generated_by, path.relative_to(root_dir))
             generated_by_html = markdown_to_html(generated_by)
 
             content = [
@@ -1848,6 +2039,59 @@ class ConfluenceDocument:
         self.labels = document.tags
         self.properties = document.properties
 
+        # Remove the first heading if:
+        # 1. The option is enabled
+        # 2. Title was NOT from front-matter (document.title is None)
+        # 3. A title was successfully extracted from heading (self.title is not None)
+        if converter_options.skip_title_heading and document.title is None and self.title is not None:
+            self._remove_first_heading()
+
+    def _remove_first_heading(self) -> None:
+        """
+        Removes the first heading element from the document root.
+
+        This is used when the title was extracted from the first unique top-level heading
+        and the user has requested to skip it from the body to avoid duplication.
+
+        Handles the case where a generated-by info panel may be present as the first child.
+        """
+
+        # Find the first heading element (h1-h6) in the root
+        heading_pattern = re.compile(r"^h[1-6]$", re.IGNORECASE)
+
+        for idx, child in enumerate(self.root):
+            if not isinstance(child.tag, str):
+                continue
+
+            if heading_pattern.match(child.tag) is None:
+                continue
+
+            # Preserve any text that comes after the heading (tail text)
+            tail = child.tail
+
+            # Remove the heading
+            self.root.remove(child)
+
+            # If there was tail text, attach it to the previous sibling's tail
+            # or to the parent's text if this was the first child
+            if tail:
+                if idx > 0:
+                    # Append to previous sibling's tail
+                    prev_sibling = self.root[idx - 1]
+                    if prev_sibling.tail:
+                        prev_sibling.tail += tail
+                    else:
+                        prev_sibling.tail = tail
+                else:
+                    # No previous sibling, append to parent's text
+                    if self.root.text:
+                        self.root.text += tail
+                    else:
+                        self.root.text = tail
+
+            # Only remove the FIRST heading, then stop
+            break
+
     def xhtml(self) -> str:
         return elements_to_string(self.root)
 

md2conf/domain.py

@@ -20,10 +20,12 @@ class ConfluenceDocumentOptions:
     """
     Options that control the generated page content.
 
-    :param ignore_invalid_url: When true, ignore invalid URLs in input, emit a warning and replace the anchor with
-        plain text; when false, raise an exception.
     :param heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
         conversion rules for the identifier.
+    :param ignore_invalid_url: When true, ignore invalid URLs in input, emit a warning and replace the anchor with
+        plain text; when false, raise an exception.
+    :param skip_title_heading: Whether to remove the first heading from document body when used as page title.
+    :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 root_page_id: Confluence page to assume root page role for publishing a directory of Markdown files.
     :param keep_hierarchy: Whether to maintain source directory structure when exporting to Confluence.
@@ -34,11 +36,15 @@ class ConfluenceDocumentOptions:
     :param diagram_output_format: Target image format for diagrams.
     :param webui_links: When true, convert relative URLs to Confluence Web UI links.
     :param alignment: Alignment for block-level images and formulas.
+    :param max_image_width: Maximum display width for images [px]. Wider images are scaled down for page display.
+        Original size kept for full-size viewing.
     :param use_panel: Whether to transform admonitions and alerts into a Confluence custom panel.
     """
 
-    ignore_invalid_url: bool = False
     heading_anchors: bool = False
+    ignore_invalid_url: bool = False
+    skip_title_heading: bool = False
+    title_prefix: str | None = None
     generated_by: str | None = "This page has been generated with a tool."
     root_page_id: ConfluencePageID | None = None
     keep_hierarchy: bool = False
@@ -49,4 +55,5 @@ class ConfluenceDocumentOptions:
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False
     alignment: Literal["center", "left", "right"] = "center"
+    max_image_width: int | None = None
     use_panel: bool = False

md2conf/latex.py

@@ -44,16 +44,16 @@ else:
 
     def _render_latex(expression: str, f: BinaryIO, *, format: Literal["png", "svg"], dpi: int, font_size: int) -> None:
         # create a figure with no axis
-        fig = plt.figure(dpi=dpi)
+        fig = plt.figure(dpi=dpi)  # pyright: ignore[reportUnknownMemberType]
 
         # transparent background
         fig.patch.set_alpha(0)
 
         # add LaTeX text
-        fig.text(x=0, y=0, s=f"${expression}$", fontsize=font_size)
+        fig.text(x=0, y=0, s=f"${expression}$", fontsize=font_size)  # pyright: ignore[reportUnknownMemberType]
 
         # save the image
-        fig.savefig(
+        fig.savefig(  # pyright: ignore[reportUnknownMemberType]
             f,
             transparent=True,
             format=format,
@@ -209,7 +209,7 @@ def _get_png_dimensions(source_file: BinaryIO) -> tuple[int, int]:
 
     _read_signature(source_file)
 
-    # validate IHDR chunk
+    # validate IHDR (Image Header) chunk
     ihdr = _read_chunk(source_file)
     if ihdr is None:
         raise ValueError("missing IHDR chunk")

md2conf/publisher.py

@@ -81,6 +81,9 @@ class SynchronizingProcessor(Processor):
                 digest = self._generate_hash(node.absolute_path)
                 title = f"{node.absolute_path.stem} [{digest}]"
 
+            if self.options.title_prefix is not None:
+                title = f"{self.options.title_prefix} {title}"
+
             # look up page by (possibly auto-generated) title
             page = self.api.get_or_create_page(title, parent_id.page_id)
 

md2conf/scanner.py

@@ -23,8 +23,8 @@ T = TypeVar("T")
 def extract_value(pattern: str, text: str) -> tuple[str | None, str]:
     values: list[str] = []
 
-    def _repl_func(matchobj: re.Match[str]) -> str:
-        values.append(matchobj.group(1))
+    def _repl_func(match: re.Match[str]) -> str:
+        values.append(match.group(1))
         return ""
 
     text = re.sub(pattern, _repl_func, text, count=1, flags=re.ASCII)

md2conf/serializer.py

@@ -6,9 +6,11 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
+import sys
+from datetime import datetime
 from typing import TypeVar
 
-from cattrs.preconf.json import make_converter
+from cattrs.preconf.orjson import make_converter
 
 JsonType = None | bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
 JsonComposite = dict[str, "JsonType"] | list["JsonType"]
@@ -19,6 +21,16 @@ T = TypeVar("T")
 _converter = make_converter(forbid_extra_keys=False)
 
 
+if sys.version_info < (3, 11):
+
+    @_converter.register_structure_hook
+    def datetime_structure_hook(value: str, cls: type[datetime]) -> datetime:
+        if value.endswith("Z"):
+            # fromisoformat() prior to Python version 3.11 does not support military time zones like "Zulu" for UTC
+            value = f"{value[:-1]}+00:00"
+        return datetime.fromisoformat(value)
+
+
 @_converter.register_structure_hook
 def json_type_structure_hook(value: JsonType, cls: type[JsonType]) -> JsonType:
     return value
@@ -49,4 +61,4 @@ def object_to_json_payload(data: object) -> bytes:
     :returns: JSON string encoded in UTF-8.
     """
 
-    return _converter.dumps(data).encode("utf-8")
+    return _converter.dumps(data)