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

{markdown_to_confluence-0.2.6.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.6
+Version: 0.2.7
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -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)

{markdown_to_confluence-0.2.6.dist-info → markdown_to_confluence-0.2.7.dist-info}/RECORD

@@ -1,8 +1,8 @@
-md2conf/__init__.py,sha256=aD2z2fkqyEVbUDQvLSJxfFUOpwMYt5lAZIUAQocULuM,402
+md2conf/__init__.py,sha256=U8zdop7-AIrfwCYzWiwKfhCEPF_1QEKPt4Zwq-38LlU,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/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
@@ -12,10 +12,10 @@ 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,,
+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,,

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.6"
+__version__ = "0.2.7"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2024, Levente Hunyadi"
 __license__ = "MIT"

md2conf/api.py

@@ -420,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:
@@ -435,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,
 )
@@ -174,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(
@@ -187,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(
@@ -249,7 +240,7 @@ class Application:
 
         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

@@ -23,6 +23,7 @@ from urllib.parse import ParseResult, urlparse, urlunparse
 
 import lxml.etree as ET
 import markdown
+import yaml
 from lxml.builder import ElementMaker
 
 from . import mermaid
@@ -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)
+
+    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)))
 
-        relative_path = Path(path)
+        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")
@@ -907,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."
 
@@ -944,6 +992,7 @@ class ConfluenceDocumentOptions:
 
 class ConfluenceDocument:
     id: ConfluenceQualifiedID
+    title: Optional[str]
     links: List[str]
     images: List[Path]
 
@@ -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)