markdown-to-confluence 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

{markdown_to_confluence-0.3.1.dist-info → markdown_to_confluence-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.3.1
+Version: 0.3.3
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -30,6 +30,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: types-requests>=2.32
+Dynamic: license-file
 
 # Publish Markdown files to Confluence wiki
 
@@ -166,7 +167,7 @@ The concepts above are illustrated in the following sections.
 
 #### File-system directory hierarchy
 
-The title of each Markdown file (either the text of the first heading (`#`), or the title specified in front-matter) is shown next to the file name.
+The title of each Markdown file (either the text of the topmost unique heading (`#`), or the title specified in front-matter) is shown next to the file name.
 
 ```
 .
@@ -197,12 +198,30 @@ root
         └── Mean vs. median
 ```
 
+### Publishing images
+
+Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
+
+Unfortunately, Confluence struggles with SVG images, e.g. they may only show in *edit* mode, display in a wrong size or text labels in the image may be truncated. In order to mitigate the issue, whenever *md2conf* encounters a reference to an SVG image in a Markdown file, it checks whether a corresponding PNG image also exists in the same directory, and if a PNG image is found, it is published instead.
+
+External images referenced with an absolute URL retain the original URL.
+
 ### Ignoring files
 
 Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
 
 Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
 
+### Page title
+
+*md2conf* makes a best-effort attempt at setting the Confluence wiki page title when it publishes a Markdown document the first time. The following are probed in this order:
+
+1. The `title` attribute set in the [front-matter](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/). Front-matter is a block delimited by `---` at the beginning of a Markdown document. Currently, only YAML syntax is supported.
+2. The text of the topmost unique Markdown heading (`#`). For example, if a document has a single first-level heading (e.g. `# My document`), its text is used. However, if there are multiple first-level headings, this step is skipped.
+3. The file name (without the extension `.md`).
+
+If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
@@ -215,10 +234,8 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
-               [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY] [--no-generated-by]
-               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors]
-               [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
+usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--keep-hierarchy] [--generated-by GENERATED_BY] [--no-generated-by]
+               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
                mdpath
 
 positional arguments:
@@ -239,6 +256,7 @@ options:
   -l {debug,info,warning,error,critical}, --loglevel {debug,info,warning,error,critical}
                         Use this option to set the log verbosity.
   -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
+  --keep-hierarchy      Maintain source directory structure when exporting to Confluence.
   --generated-by GENERATED_BY
                         Add prompt to pages (default: 'This page has been generated with a tool.').
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.

markdown_to_confluence-0.3.3.dist-info/RECORD

@@ -0,0 +1,20 @@
+markdown_to_confluence-0.3.3.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+md2conf/__init__.py,sha256=NHoSu8tHMVLytWmla4BA_Uzkl-04rV_O8YkkFxUkT_E,402
+md2conf/__main__.py,sha256=aTRiXcvoIYMkwCGejL6MUriHXBo3qVP2Acr2I-XzMyg,7947
+md2conf/api.py,sha256=S5IB7j48wE9MHSj1jodHYmTE6scSXb80faULW6-5RjU,20376
+md2conf/application.py,sha256=FkJ9zYBLwYcCRkd_WiX6JI6nlw4QMETmrOXHeSzCwCE,9735
+md2conf/converter.py,sha256=B4Z8afTmhea6nSXhzDVxN55GfMvlY34tGqCLspQ_p5g,38983
+md2conf/emoji.py,sha256=48QJtOD0F3Be1laYLvAOwe0GxrJS-vcfjtCdiBsNcAc,1960
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/matcher.py,sha256=FgMFPvGiOqGezCs8OyerfsVo-iIHFoI6LRMzdcjM5UY,3693
+md2conf/mermaid.py,sha256=un_KHBDpG5Zad_QD3HN1uBwUxp4I-HVJYhNKbH7KwcA,2312
+md2conf/processor.py,sha256=9jPswgPewh2glLSHdgxyXesGxkcxPVa_h7oUhM9EsA4,4740
+md2conf/properties.py,sha256=TOCXLdTfYkKjRwZaMgvXw0mNCI4opEUwpBXro2Kv2B4,2467
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_to_confluence-0.3.3.dist-info/METADATA,sha256=SiOfBvA3jMCn3Hjd_Let9R-DqcMuPG48xP-1x2pg_JI,16495
+markdown_to_confluence-0.3.3.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+markdown_to_confluence-0.3.3.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.3.3.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.3.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.3.3.dist-info/RECORD,,

{markdown_to_confluence-0.3.1.dist-info → markdown_to_confluence-0.3.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.2)
+Generator: setuptools (80.3.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

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.3.1"
+__version__ = "0.3.3"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -22,18 +22,22 @@ import requests
 from . import __version__
 from .api import ConfluenceAPI
 from .application import Application
-from .converter import ConfluenceDocumentOptions
+from .converter import ConfluenceDocumentOptions, ConfluenceSiteMetadata
 from .processor import Processor
-from .properties import ConfluenceProperties
+from .properties import (
+    ArgumentError,
+    ConfluenceConnectionProperties,
+    ConfluenceSiteProperties,
+)
 
 
 class Arguments(argparse.Namespace):
     mdpath: Path
-    domain: str
-    path: str
-    username: str
-    apikey: str
-    space: str
+    domain: Optional[str]
+    path: Optional[str]
+    username: Optional[str]
+    apikey: Optional[str]
+    space: Optional[str]
     loglevel: str
     ignore_invalid_url: bool
     heading_anchors: bool
@@ -201,12 +205,33 @@ def main() -> None:
         diagram_output_format=args.diagram_output_format,
         webui_links=args.webui_links,
     )
-    properties = ConfluenceProperties(
-        args.domain, args.path, args.username, args.apikey, args.space, args.headers
-    )
     if args.local:
-        Processor(options, properties).process(args.mdpath)
+        try:
+            site_properties = ConfluenceSiteProperties(
+                domain=args.domain,
+                base_path=args.path,
+                space_key=args.space,
+            )
+        except ArgumentError as e:
+            parser.error(str(e))
+        site_metadata = ConfluenceSiteMetadata(
+            domain=site_properties.domain,
+            base_path=site_properties.base_path,
+            space_key=site_properties.space_key,
+        )
+        Processor(options, site_metadata).process(args.mdpath)
     else:
+        try:
+            properties = ConfluenceConnectionProperties(
+                args.domain,
+                args.path,
+                args.username,
+                args.apikey,
+                args.space,
+                args.headers,
+            )
+        except ArgumentError as e:
+            parser.error(str(e))
         try:
             with ConfluenceAPI(properties) as api:
                 Application(

md2conf/api.py

@@ -21,7 +21,12 @@ from urllib.parse import urlencode, urlparse, urlunparse
 import requests
 
 from .converter import ParseError, sanitize_confluence
-from .properties import ConfluenceError, ConfluenceProperties
+from .properties import (
+    ArgumentError,
+    ConfluenceConnectionProperties,
+    ConfluenceError,
+    PageError,
+)
 
 # a JSON type with possible `null` values
 JsonType = Union[
@@ -40,6 +45,18 @@ class ConfluenceVersion(enum.Enum):
     VERSION_2 = "api/v2"
 
 
+class ConfluencePageParentContentType(enum.Enum):
+    """
+    Content types that can be a parent to a Confluence page
+    """
+
+    PAGE = "page"
+    WHITEBOARD = "whiteboard"
+    DATABASE = "database"
+    EMBED = "embed"
+    FOLDER = "folder"
+
+
 def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
     "Builds a URL with scheme, host, port, path and query string parameters."
 
@@ -71,17 +88,21 @@ class ConfluenceAttachment:
 class ConfluencePage:
     id: str
     space_id: str
+    parent_id: str
+    parent_type: Optional[ConfluencePageParentContentType]
     title: str
     version: int
     content: str
 
 
 class ConfluenceAPI:
-    properties: ConfluenceProperties
+    properties: ConfluenceConnectionProperties
     session: Optional["ConfluenceSession"] = None
 
-    def __init__(self, properties: Optional[ConfluenceProperties] = None) -> None:
-        self.properties = properties or ConfluenceProperties()
+    def __init__(
+        self, properties: Optional[ConfluenceConnectionProperties] = None
+    ) -> None:
+        self.properties = properties or ConfluenceConnectionProperties()
 
     def __enter__(self) -> "ConfluenceSession":
         session = requests.Session()
@@ -128,7 +149,7 @@ class ConfluenceSession:
         session: requests.Session,
         domain: str,
         base_path: str,
-        space_key: Optional[str],
+        space_key: Optional[str] = None,
     ) -> None:
         self.session = session
         self.domain = domain
@@ -170,11 +191,9 @@ class ConfluenceSession:
 
         url = self._build_url(version, path, query)
         response = self.session.get(url)
-        response.raise_for_status()
-        if len(response.text) > 240:
-            LOGGER.debug("Received HTTP payload (truncated):\n%.240s...", response.text)
-        else:
+        if response.text:
             LOGGER.debug("Received HTTP payload:\n%s", response.text)
+        response.raise_for_status()
         return response.json()
 
     def _save(self, version: ConfluenceVersion, path: str, data: dict) -> None:
@@ -184,6 +203,8 @@ class ConfluenceSession:
             data=json.dumps(data),
             headers={"Content-Type": "application/json"},
         )
+        if response.text:
+            LOGGER.debug("Received HTTP payload:\n%s", response.text)
         response.raise_for_status()
 
     def space_id_to_key(self, id: str) -> str:
@@ -194,7 +215,7 @@ class ConfluenceSession:
             payload = self._invoke(
                 ConfluenceVersion.VERSION_2,
                 "/spaces",
-                {"ids": id, "type": "global", "status": "current"},
+                {"ids": id, "status": "current"},
             )
             payload = typing.cast(dict[str, JsonType], payload)
             results = typing.cast(list[JsonType], payload["results"])
@@ -216,7 +237,7 @@ class ConfluenceSession:
             payload = self._invoke(
                 ConfluenceVersion.VERSION_2,
                 "/spaces",
-                {"keys": key, "type": "global", "status": "current"},
+                {"keys": key, "status": "current"},
             )
             payload = typing.cast(dict[str, JsonType], payload)
             results = typing.cast(list[JsonType], payload["results"])
@@ -261,12 +282,11 @@ class ConfluenceSession:
         comment: Optional[str] = None,
         force: bool = False,
     ) -> None:
-
         if attachment_path is None and raw_data is None:
-            raise ConfluenceError("required: `attachment_path` or `raw_data`")
+            raise ArgumentError("required: `attachment_path` or `raw_data`")
 
         if attachment_path is not None and raw_data is not None:
-            raise ConfluenceError("expected: either `attachment_path` or `raw_data`")
+            raise ArgumentError("expected: either `attachment_path` or `raw_data`")
 
         if content_type is None:
             if attachment_path is not None:
@@ -276,7 +296,7 @@ class ConfluenceSession:
             content_type, _ = mimetypes.guess_type(name, strict=True)
 
         if attachment_path is not None and not attachment_path.is_file():
-            raise ConfluenceError(f"file not found: {attachment_path}")
+            raise PageError(f"file not found: {attachment_path}")
 
         try:
             attachment = self.get_attachment_by_name(page_id, attachment_name)
@@ -422,6 +442,12 @@ class ConfluenceSession:
         return ConfluencePage(
             id=page_id,
             space_id=typing.cast(str, data["spaceId"]),
+            parent_id=typing.cast(str, data["parentId"]),
+            parent_type=(
+                ConfluencePageParentContentType(typing.cast(str, data["parentType"]))
+                if data["parentType"] is not None
+                else None
+            ),
             title=typing.cast(str, data["title"]),
             version=typing.cast(int, version["number"]),
             content=typing.cast(str, storage["value"]),
@@ -493,9 +519,7 @@ class ConfluenceSession:
 
         coalesced_space_key = space_key or self.space_key
         if coalesced_space_key is None:
-            raise ConfluenceError(
-                "Confluence space key required for creating a new page"
-            )
+            raise ArgumentError("Confluence space key required for creating a new page")
 
         path = "/pages/"
         query = {
@@ -524,6 +548,12 @@ class ConfluenceSession:
         return ConfluencePage(
             id=typing.cast(str, data["id"]),
             space_id=typing.cast(str, data["spaceId"]),
+            parent_id=typing.cast(str, data["parentId"]),
+            parent_type=(
+                ConfluencePageParentContentType(typing.cast(str, data["parentType"]))
+                if data["parentType"] is not None
+                else None
+            ),
             title=typing.cast(str, data["title"]),
             version=typing.cast(int, version["number"]),
             content=typing.cast(str, storage["value"]),

md2conf/application.py

@@ -6,8 +6,9 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
+import hashlib
 import logging
-import os.path
+import os
 from pathlib import Path
 from typing import Optional
 
@@ -17,12 +18,14 @@ from .converter import (
     ConfluenceDocumentOptions,
     ConfluencePageMetadata,
     ConfluenceQualifiedID,
+    ConfluenceSiteMetadata,
     attachment_name,
     extract_frontmatter_title,
     extract_qualified_id,
     read_qualified_id,
 )
 from .matcher import Matcher, MatcherOptions
+from .properties import ArgumentError, PageError
 
 LOGGER = logging.getLogger(__name__)
 
@@ -48,7 +51,7 @@ class Application:
         elif path.is_file():
             self.synchronize_page(path)
         else:
-            raise ValueError(f"expected: valid file or directory path; got: {path}")
+            raise ArgumentError(f"expected: valid file or directory path; got: {path}")
 
     def synchronize_page(
         self, page_path: Path, root_dir: Optional[Path] = None
@@ -83,7 +86,7 @@ class Application:
             if self.options.root_page_id
             else None
         )
-        self._index_directory(local_dir, root_id, page_metadata)
+        self._index_directory(local_dir, root_dir, root_id, page_metadata)
         LOGGER.info("Indexed %d page(s)", len(page_metadata))
 
         # Step 2: convert each page
@@ -99,12 +102,21 @@ class Application:
         base_path = page_path.parent
 
         LOGGER.info("Synchronizing page: %s", page_path)
-        document = ConfluenceDocument(page_path, self.options, root_dir, page_metadata)
+        site_metadata = ConfluenceSiteMetadata(
+            domain=self.api.domain,
+            base_path=self.api.base_path,
+            space_key=self.api.space_key,
+        )
+
+        document = ConfluenceDocument.create(
+            page_path, self.options, root_dir, site_metadata, page_metadata
+        )
         self._update_document(document, base_path)
 
     def _index_directory(
         self,
         local_dir: Path,
+        root_dir: Path,
         root_id: Optional[ConfluenceQualifiedID],
         page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
@@ -144,7 +156,7 @@ class Application:
         if parent_doc is not None:
             files.remove(parent_doc)
 
-            metadata = self._get_or_create_page(parent_doc, root_id)
+            metadata = self._get_or_create_page(parent_doc, root_dir, root_id)
             LOGGER.debug("Indexed parent %s with metadata: %s", parent_doc, metadata)
             page_metadata[parent_doc] = metadata
 
@@ -153,16 +165,17 @@ class Application:
             parent_id = root_id
 
         for doc in files:
-            metadata = self._get_or_create_page(doc, parent_id)
+            metadata = self._get_or_create_page(doc, root_dir, parent_id)
             LOGGER.debug("Indexed %s with metadata: %s", doc, metadata)
             page_metadata[doc] = metadata
 
         for directory in directories:
-            self._index_directory(directory, parent_id, page_metadata)
+            self._index_directory(directory, root_dir, parent_id, page_metadata)
 
     def _get_or_create_page(
         self,
         absolute_path: Path,
+        root_dir: Path,
         parent_id: Optional[ConfluenceQualifiedID],
         *,
         title: Optional[str] = None,
@@ -176,19 +189,28 @@ class Application:
             document = f.read()
 
         qualified_id, document = extract_qualified_id(document)
-        frontmatter_title, _ = extract_frontmatter_title(document)
 
         if qualified_id is not None:
             confluence_page = self.api.get_page(qualified_id.page_id)
         else:
             if parent_id is None:
-                raise ValueError(
+                raise PageError(
                     f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
                 )
 
-            # assign title from frontmatter if present
+            # assign title from front-matter if present
+            if title is None:
+                title, _ = extract_frontmatter_title(document)
+
+            # use file name (without extension) and path hash if no title is supplied
+            if title is None:
+                relative_path = absolute_path.relative_to(root_dir)
+                hash = hashlib.md5(relative_path.as_posix().encode("utf-8"))
+                digest = "".join(f"{c:x}" for c in hash.digest())
+                title = f"{absolute_path.stem} [{digest}]"
+
             confluence_page = self._create_page(
-                absolute_path, document, title or frontmatter_title, parent_id
+                absolute_path, document, title, parent_id
             )
 
         space_key = (
@@ -198,8 +220,6 @@ class Application:
         )
 
         return ConfluencePageMetadata(
-            domain=self.api.domain,
-            base_path=self.api.base_path,
             page_id=confluence_page.id,
             space_key=space_key,
             title=confluence_page.title or "",
@@ -209,15 +229,11 @@ class Application:
         self,
         absolute_path: Path,
         document: str,
-        title: Optional[str],
+        title: str,
         parent_id: ConfluenceQualifiedID,
     ) -> ConfluencePage:
         "Creates a new Confluence page when Markdown file doesn't have an embedded page ID yet."
 
-        # use file name without extension if no title is supplied
-        if title is None:
-            title = absolute_path.stem
-
         confluence_page = self.api.get_or_create_page(
             title, parent_id.page_id, space_key=parent_id.space_key
         )

md2conf/converter.py

@@ -25,7 +25,8 @@ import markdown
 import yaml
 from lxml.builder import ElementMaker
 
-from . import mermaid
+from .mermaid import render_diagram
+from .properties import PageError
 
 namespaces = {
     "ac": "http://atlassian.com/content",
@@ -91,9 +92,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 +104,10 @@ def markdown_to_html(content: str) -> str:
         extension_configs={
             "pymdownx.emoji": {
                 "emoji_generator": emoji_generator,
-            }
+            },
+            "pymdownx.highlight": {
+                "use_pygments": False,
+            },
         },
     )
 
@@ -235,9 +241,14 @@ _languages = [
 
 
 @dataclass
-class ConfluencePageMetadata:
+class ConfluenceSiteMetadata:
     domain: str
     base_path: str
+    space_key: Optional[str]
+
+
+@dataclass
+class ConfluencePageMetadata:
     page_id: str
     space_key: Optional[str]
     title: str
@@ -271,6 +282,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 +357,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 +369,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         options: ConfluenceConverterOptions,
         path: Path,
         root_dir: Path,
+        site_metadata: ConfluenceSiteMetadata,
         page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         super().__init__()
@@ -316,14 +377,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 +397,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             AC(
                 "parameter",
                 {ET.QName(namespaces["ac"], "name"): ""},
-                title_to_identifier(title),
+                title_to_identifier(element_to_text(heading)),
             ),
         )
 
@@ -409,13 +470,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 +595,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 +602,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 +862,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 +959,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]:
@@ -996,14 +1064,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,7 +1088,23 @@ 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 'generated-by' tag text
@@ -1059,6 +1144,7 @@ class ConfluenceDocument:
             ),
             path,
             root_dir,
+            site_metadata,
             page_metadata,
         )
         converter.visit(self.root)
@@ -1066,6 +1152,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/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/processor.py

@@ -17,23 +17,24 @@ from .converter import (
     ConfluenceDocumentOptions,
     ConfluencePageMetadata,
     ConfluenceQualifiedID,
+    ConfluenceSiteMetadata,
     extract_qualified_id,
 )
 from .matcher import Matcher, MatcherOptions
-from .properties import ConfluenceProperties
+from .properties import ArgumentError
 
 LOGGER = logging.getLogger(__name__)
 
 
 class Processor:
     options: ConfluenceDocumentOptions
-    properties: ConfluenceProperties
+    site_metadata: ConfluenceSiteMetadata
 
     def __init__(
-        self, options: ConfluenceDocumentOptions, properties: ConfluenceProperties
+        self, options: ConfluenceDocumentOptions, site_metadata: ConfluenceSiteMetadata
     ) -> None:
         self.options = options
-        self.properties = properties
+        self.site_metadata = site_metadata
 
     def process(self, path: Path) -> None:
         "Processes a single Markdown file or a directory of Markdown files."
@@ -44,7 +45,7 @@ class Processor:
         elif path.is_file():
             self.process_page(path)
         else:
-            raise ValueError(f"expected: valid file or directory path; got: {path}")
+            raise ArgumentError(f"expected: valid file or directory path; got: {path}")
 
     def process_directory(
         self, local_dir: Path, root_dir: Optional[Path] = None
@@ -87,7 +88,9 @@ class Processor:
     ) -> None:
         "Processes a single Markdown file."
 
-        document = ConfluenceDocument(path, self.options, root_dir, page_metadata)
+        document = ConfluenceDocument.create(
+            path, self.options, root_dir, self.site_metadata, page_metadata
+        )
         content = document.xhtml()
         with open(path.with_suffix(".csf"), "w", encoding="utf-8") as f:
             f.write(content)
@@ -136,12 +139,10 @@ class Processor:
                 LOGGER.info("Identifier %s assigned to page: %s", digest, absolute_path)
                 qualified_id = ConfluenceQualifiedID(digest)
             else:
-                raise ValueError("required: page ID for local output")
+                raise ArgumentError("required: page ID for local output")
 
         return ConfluencePageMetadata(
-            domain=self.properties.domain,
-            base_path=self.properties.base_path,
             page_id=qualified_id.page_id,
-            space_key=qualified_id.space_key or self.properties.space_key,
+            space_key=qualified_id.space_key,
             title="",
         )

md2conf/properties.py

@@ -10,50 +10,74 @@ import os
 from typing import Optional
 
 
+class ArgumentError(ValueError):
+    "Raised when wrong arguments are passed to a function call."
+
+
+class PageError(ValueError):
+    "Raised in case there is an issue with a Confluence page."
+
+
 class ConfluenceError(RuntimeError):
-    pass
+    "Raised when a Confluence API call fails."
 
 
-class ConfluenceProperties:
+class ConfluenceSiteProperties:
     domain: str
     base_path: str
     space_key: Optional[str]
-    user_name: Optional[str]
-    api_key: str
-    headers: Optional[dict[str, str]]
 
     def __init__(
         self,
         domain: Optional[str] = None,
         base_path: Optional[str] = None,
-        user_name: Optional[str] = None,
-        api_key: Optional[str] = None,
         space_key: Optional[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")
-        opt_user_name = user_name or os.getenv("CONFLUENCE_USER_NAME")
-        opt_api_key = api_key or os.getenv("CONFLUENCE_API_KEY")
         opt_space_key = space_key or os.getenv("CONFLUENCE_SPACE_KEY")
 
         if not opt_domain:
-            raise ConfluenceError("Confluence domain not specified")
+            raise ArgumentError("Confluence domain not specified")
         if not opt_base_path:
             opt_base_path = "/wiki/"
-        if not opt_api_key:
-            raise ConfluenceError("Confluence API key not specified")
 
         if opt_domain.startswith(("http://", "https://")) or opt_domain.endswith("/"):
-            raise ConfluenceError(
+            raise ArgumentError(
                 "Confluence domain looks like a URL; only host name required"
             )
         if not opt_base_path.startswith("/") or not opt_base_path.endswith("/"):
-            raise ConfluenceError("Confluence base path must start and end with a '/'")
+            raise ArgumentError("Confluence base path must start and end with a '/'")
 
         self.domain = opt_domain
         self.base_path = opt_base_path
+        self.space_key = opt_space_key
+
+
+class ConfluenceConnectionProperties(ConfluenceSiteProperties):
+    "Properties related to connecting to Confluence."
+
+    user_name: Optional[str]
+    api_key: str
+    headers: Optional[dict[str, str]]
+
+    def __init__(
+        self,
+        domain: Optional[str] = None,
+        base_path: Optional[str] = None,
+        user_name: Optional[str] = None,
+        api_key: Optional[str] = None,
+        space_key: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        super().__init__(domain, base_path, space_key)
+
+        opt_user_name = user_name or os.getenv("CONFLUENCE_USER_NAME")
+        opt_api_key = api_key or os.getenv("CONFLUENCE_API_KEY")
+
+        if not opt_api_key:
+            raise ArgumentError("Confluence API key not specified")
+
         self.user_name = opt_user_name
         self.api_key = opt_api_key
-        self.space_key = opt_space_key
         self.headers = headers

markdown_to_confluence-0.3.1.dist-info/RECORD

@@ -1,20 +0,0 @@
-md2conf/__init__.py,sha256=AtPkcrgEezF8jnJ14ALB3VdF6UAWPR9EPSYtoi6y5Nc,402
-md2conf/__main__.py,sha256=ypjV_5mE0smlIRBFrpikgzXq18as2hY43HJxMLpzGp4,7145
-md2conf/api.py,sha256=uwIR_wBSQqvZ9XZ2m2009Hf8B5w7T5PUXJ88BU8CJmA,19520
-md2conf/application.py,sha256=5K-nCPHJZfIahjubrLtXTwI-zsTiD140fdYXDnh3GSk,9161
-md2conf/converter.py,sha256=MoGbXqh5rE4qkdxxY8RHcnoZ5mz0aEuFz9nmUnt0WdM,36397
-md2conf/emoji.py,sha256=IZeguWqcboeOyJkGLTVONDMO4ZXfYXPgfkp56PTI-hE,1924
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/matcher.py,sha256=FgMFPvGiOqGezCs8OyerfsVo-iIHFoI6LRMzdcjM5UY,3693
-md2conf/mermaid.py,sha256=Alzkv0BY-lju4ojtBdW2qtCLZ59MO9kaS2RpQO6Kyfk,2304
-md2conf/processor.py,sha256=G-MIh1jGq9jjgogHnlnRUSrNgiV6_xO6Fy7ct9alqgM,4769
-md2conf/properties.py,sha256=WaVVOYSck7drVQfcBJmBMa7Mb0KVOZl9UZHvLS1Du8U,1892
-md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-markdown_to_confluence-0.3.1.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-markdown_to_confluence-0.3.1.dist-info/METADATA,sha256=pTnAvuTg_rgETAUZbsN_5HYbOwXE7qVpDGvhaXMwB2Y,14936
-markdown_to_confluence-0.3.1.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
-markdown_to_confluence-0.3.1.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.3.1.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.3.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.3.1.dist-info/RECORD,,