markdown-to-confluence 0.1.11__py3-none-any.whl → 0.1.12__py3-none-any.whl

{markdown_to_confluence-0.1.11.dist-info → markdown_to_confluence-0.1.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: markdown-to-confluence
-Version: 0.1.11
+Version: 0.1.12
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -21,13 +21,13 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lxml >=4.9
-Requires-Dist: types-lxml >=2023.10.21
-Requires-Dist: markdown >=3.5
-Requires-Dist: types-markdown >=3.5
-Requires-Dist: pymdown-extensions >=10.3
-Requires-Dist: requests >=2.31
-Requires-Dist: types-requests >=2.31
+Requires-Dist: lxml >=5.2
+Requires-Dist: types-lxml >=2024.4.14
+Requires-Dist: markdown >=3.6
+Requires-Dist: types-markdown >=3.6
+Requires-Dist: pymdown-extensions >=10.8
+Requires-Dist: requests >=2.32
+Requires-Dist: types-requests >=2.32
 
 # Publish Markdown files to Confluence wiki
 
@@ -36,6 +36,7 @@ Contributors to software projects typically write documentation in Markdown form
 Replicating documentation to Confluence by hand is tedious, and a lack of automated synchronization with the project repositories where the documents live leads to outdated documentation.
 
 This Python package
+
 * parses Markdown files,
 * converts Markdown content into the Confluence Storage Format (XHTML),
 * invokes Confluence API endpoints to upload images and content.
@@ -54,6 +55,7 @@ This Python package
 ## Getting started
 
 In order to get started, you will need
+
 * your organization domain name (e.g. `instructure.atlassian.net`),
 * base path for Confluence wiki (typically `/wiki/` for managed Confluence, `/` for on-premise)
 * your Confluence username (e.g. `levente.hunyadi@instructure.com`) (only if required by your deployment),
@@ -62,7 +64,7 @@ In order to get started, you will need
 
 ### Obtaining an API token
 
-1. Log in to https://id.atlassian.com/manage/api-tokens.
+1. Log in to <https://id.atlassian.com/manage/api-tokens>.
 2. Click *Create API token*.
 3. From the dialog that appears, enter a memorable and concise *Label* for your token and click *Create*.
 4. Click *Copy to clipboard*, then paste the token to your script, or elsewhere to save.
@@ -70,6 +72,7 @@ In order to get started, you will need
 ### Setting up the environment
 
 Confluence organization domain, base path, username, API token and space key can be specified at runtime or set as Confluence environment variables (e.g. add to your `~/.profile` on Linux, or `~/.bash_profile` or `~/.zshenv` on MacOS):
+
 ```bash
 export CONFLUENCE_DOMAIN='instructure.atlassian.net'
 export CONFLUENCE_PATH='/wiki/'
@@ -136,18 +139,18 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}]
-               [--generated-by GENERATED_BY] [--no-generated-by] [--ignore-invalid-url]
+usage: md2conf [-h] [-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] [--ignore-invalid-url] [--local]
                mdpath
 
 positional arguments:
   mdpath                Path to Markdown file or directory to convert and publish.
 
-options:
+optional arguments:
   -h, --help            show this help message and exit
   -d DOMAIN, --domain DOMAIN
                         Confluence organization domain.
-  -p PATH, --path PATH  Base path for Confluece wiki.
+  -p PATH, --path PATH  Base path for Confluence (default: '/wiki/').
   -u USERNAME, --username USERNAME
                         Confluence user name.
   -a APIKEY, --apikey APIKEY
@@ -156,8 +159,10 @@ options:
                         Confluence space key for pages to be published. If omitted, will default to user space.
   -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.
   --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.
   --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
+  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
 ```

markdown_to_confluence-0.1.12.dist-info/RECORD

@@ -0,0 +1,16 @@
+md2conf/__init__.py,sha256=SS79zE1Jss2UJQH39HX6zMvAPO2MGjq3jjHny4L6dvY,403
+md2conf/__main__.py,sha256=L0XaHfV3GOPnyceWxUGamZXPfQUL3Dfsf_VpWeF08Qo,4246
+md2conf/api.py,sha256=xYqQbdy-0d_mqv-zDT0DCcLs17HYLdY2LfWoY2jhMB8,14738
+md2conf/application.py,sha256=ksWeDQGQs6xvAS8wdghwBMgWsGI6KMQiwlH5qaKXGv4,5221
+md2conf/converter.py,sha256=xiaf5hQHXPE3psTTk_pHVip4NDfeU-hos3Kkl1Pju50,18236
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/processor.py,sha256=f0JG8jqjsGq2sbxMdHNz6EyZ1KQ92nCKKYU3fxP6C0o,3048
+md2conf/properties.py,sha256=oXvtPssbougM1BTE9ytcD_1Yjc3nd7DDSHqEr0QoZAU,1811
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_to_confluence-0.1.12.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+markdown_to_confluence-0.1.12.dist-info/METADATA,sha256=HCmOX5YhQuc6v2szBgQa_VuGXaeZNKKBy8Q_Fi1GreQ,7875
+markdown_to_confluence-0.1.12.dist-info/WHEEL,sha256=cpQTJ5IWu9CdaPViMhC9YzF8gZuS5-vlfoFihTBC86A,91
+markdown_to_confluence-0.1.12.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.1.12.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.1.12.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.1.12.dist-info/RECORD,,

{markdown_to_confluence-0.1.11.dist-info → markdown_to_confluence-0.1.12.dist-info}/WHEEL

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

markdown_to_confluence-0.1.12.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+md2conf = md2conf.__main__:main

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

md2conf/__main__.py

@@ -3,6 +3,7 @@ import logging
 import os.path
 import sys
 import typing
+from pathlib import Path
 from typing import Optional
 
 import requests
@@ -15,7 +16,7 @@ from .properties import ConfluenceProperties
 
 
 class Arguments(argparse.Namespace):
-    mdpath: str
+    mdpath: Path
     domain: str
     path: str
     username: str
@@ -26,104 +27,114 @@ class Arguments(argparse.Namespace):
     generated_by: Optional[str]
 
 
-parser = argparse.ArgumentParser()
-parser.prog = os.path.basename(os.path.dirname(__file__))
-parser.add_argument(
-    "mdpath", 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 Confluece wiki.")
-parser.add_argument("-u", "--username", help="Confluence user name.")
-parser.add_argument(
-    "-a",
-    "--apikey",
-    help="Confluence API key. Refer to documentation how to obtain one.",
-)
-parser.add_argument(
-    "-s",
-    "--space",
-    help="Confluence space key for pages to be published. If omitted, will default to user space.",
-)
-parser.add_argument(
-    "-l",
-    "--loglevel",
-    choices=[
-        typing.cast(str, logging.getLevelName(level)).lower()
-        for level in (
-            logging.DEBUG,
-            logging.INFO,
-            logging.WARN,
-            logging.ERROR,
-            logging.CRITICAL,
-        )
-    ],
-    default=logging.getLevelName(logging.INFO),
-    help="Use this option to set the log verbosity.",
-)
-parser.add_argument(
-    "-r",
-    dest="root_page",
-    help="Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.",
-)
-parser.add_argument(
-    "--generated-by",
-    default="This page has been generated with a tool.",
-    help="Add prompt to pages (default: 'This page has been generated with a tool.').",
-)
-parser.add_argument(
-    "--no-generated-by",
-    dest="generated_by",
-    action="store_const",
-    const=None,
-    help="Do not add 'generated by a tool' prompt to pages.",
-)
-parser.add_argument(
-    "--ignore-invalid-url",
-    action="store_true",
-    default=False,
-    help="Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.",
-)
-parser.add_argument(
-    "--local",
-    action="store_true",
-    default=False,
-    help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
-)
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.prog = os.path.basename(os.path.dirname(__file__))
+    parser.add_argument(
+        "mdpath", 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("-u", "--username", help="Confluence user name.")
+    parser.add_argument(
+        "-a",
+        "--apikey",
+        help="Confluence API key. Refer to documentation how to obtain one.",
+    )
+    parser.add_argument(
+        "-s",
+        "--space",
+        help="Confluence space key for pages to be published. If omitted, will default to user space.",
+    )
+    parser.add_argument(
+        "-l",
+        "--loglevel",
+        choices=[
+            typing.cast(str, logging.getLevelName(level)).lower()
+            for level in (
+                logging.DEBUG,
+                logging.INFO,
+                logging.WARN,
+                logging.ERROR,
+                logging.CRITICAL,
+            )
+        ],
+        default=logging.getLevelName(logging.INFO),
+        help="Use this option to set the log verbosity.",
+    )
+    parser.add_argument(
+        "-r",
+        dest="root_page",
+        help="Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.",
+    )
+    parser.add_argument(
+        "--generated-by",
+        default="This page has been generated with a tool.",
+        help="Add prompt to pages (default: 'This page has been generated with a tool.').",
+    )
+    parser.add_argument(
+        "--no-generated-by",
+        dest="generated_by",
+        action="store_const",
+        const=None,
+        help="Do not add 'generated by a tool' prompt to pages.",
+    )
+    parser.add_argument(
+        "--ignore-invalid-url",
+        action="store_true",
+        default=False,
+        help="Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.",
+    )
+    parser.add_argument(
+        "--local",
+        action="store_true",
+        default=False,
+        help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
+    )
 
-args = Arguments()
-parser.parse_args(namespace=args)
+    args = Arguments()
+    parser.parse_args(namespace=args)
 
-logging.basicConfig(
-    level=getattr(logging, args.loglevel.upper(), logging.INFO),
-    format="%(asctime)s - %(levelname)s - %(funcName)s [%(lineno)d] - %(message)s",
-)
+    # NOTE:  If we switch to modern type aware CLI tool like typer
+    #  the following line won't be necessary
+    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",
+    )
 
-options = ConfluenceDocumentOptions(
-    ignore_invalid_url=args.ignore_invalid_url,
-    generated_by=args.generated_by,
-    root_page_id=args.root_page,
-)
-properties = ConfluenceProperties(
-    args.domain, args.path, args.username, args.apikey, args.space
-)
-if args.local:
-    Processor(options, properties).process(args.mdpath)
-else:
-    try:
-        with ConfluenceAPI(properties) as api:
-            Application(
-                api,
-                options,
-            ).synchronize(args.mdpath)
-    except requests.exceptions.HTTPError as err:
-        logging.error(err)
+    options = ConfluenceDocumentOptions(
+        ignore_invalid_url=args.ignore_invalid_url,
+        generated_by=args.generated_by,
+        root_page_id=args.root_page,
+    )
+    properties = ConfluenceProperties(
+        args.domain, args.path, args.username, args.apikey, args.space
+    )
+    if args.local:
+        Processor(options, properties).process(args.mdpath)
+    else:
+        try:
+            with ConfluenceAPI(properties) as api:
+                Application(
+                    api,
+                    options,
+                ).synchronize(args.mdpath)
+        except requests.exceptions.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 requests.exceptions.JSONDecodeError:
-                pass
+            # print details for a response with JSON body
+            if err.response is not None:
+                try:
+                    logging.error(err.response.json())
+                except requests.exceptions.JSONDecodeError:
+                    pass
 
-        sys.exit(1)
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

md2conf/api.py

@@ -1,12 +1,11 @@
 import json
 import logging
 import mimetypes
-import os
-import os.path
 import sys
 import typing
 from contextlib import contextmanager
 from dataclasses import dataclass
+from pathlib import Path
 from types import TracebackType
 from typing import Dict, Generator, List, Optional, Type, Union
 from urllib.parse import urlencode, urlparse, urlunparse
@@ -184,15 +183,16 @@ class ConfluenceSession:
     def upload_attachment(
         self,
         page_id: str,
-        attachment_path: str,
+        attachment_path: Path,
         attachment_name: str,
         comment: Optional[str] = None,
         *,
         space_key: Optional[str] = None,
+        force: bool = False,
     ) -> None:
         content_type = mimetypes.guess_type(attachment_path, strict=True)[0]
 
-        if not os.path.isfile(attachment_path):
+        if not attachment_path.is_file():
             raise ConfluenceError(f"file not found: {attachment_path}")
 
         try:
@@ -200,7 +200,7 @@ class ConfluenceSession:
                 page_id, attachment_name, space_key=space_key
             )
 
-            if attachment.file_size == os.path.getsize(attachment_path):
+            if not force and attachment.file_size == attachment_path.stat().st_size:
                 LOGGER.info("Up-to-date attachment: %s", attachment_name)
                 return
 

md2conf/application.py

@@ -1,5 +1,6 @@
 import logging
 import os.path
+from pathlib import Path
 from typing import Dict, Optional
 
 from .api import ConfluenceSession
@@ -7,6 +8,7 @@ from .converter import (
     ConfluenceDocument,
     ConfluenceDocumentOptions,
     ConfluencePageMetadata,
+    attachment_name,
     extract_qualified_id,
 )
 
@@ -25,40 +27,42 @@ class Application:
         self.api = api
         self.options = options
 
-    def synchronize(self, path: str) -> None:
+    def synchronize(self, path: Path) -> None:
         "Synchronizes a single Markdown page or a directory of Markdown pages."
 
-        if os.path.isdir(path):
+        if path.is_dir():
             self.synchronize_directory(path)
-        elif os.path.isfile(path):
+        elif path.is_file():
             self.synchronize_page(path)
         else:
             raise ValueError(f"expected: valid file or directory path; got: {path}")
 
-    def synchronize_page(self, page_path: str) -> None:
+    def synchronize_page(self, page_path: Path) -> None:
         "Synchronizes a single Markdown page with Confluence."
 
         self._synchronize_page(page_path, {})
 
-    def synchronize_directory(self, dir: str) -> None:
+    def synchronize_directory(self, local_dir: Path) -> None:
         "Synchronizes a directory of Markdown pages with Confluence."
 
-        page_metadata: Dict[str, ConfluencePageMetadata] = {}
-        LOGGER.info(f"Synchronizing directory: {dir}")
+        page_metadata: Dict[Path, ConfluencePageMetadata] = {}
+        LOGGER.info(f"Synchronizing directory: {local_dir}")
 
         # Step 1: build index of all page metadata
-        for root, directories, files in os.walk(dir):
+        # NOTE: Pathlib.walk() is implemented only in Python 3.12+
+        # so sticking for old os.walk
+        for root, directories, files in os.walk(local_dir):
             for file_name in files:
-                # check the file extension
-                _, file_extension = os.path.splitext(file_name)
-                if file_extension.lower() != ".md":
-                    continue
+                # Reconstitute Path object back
+                docfile = (Path(root) / file_name).absolute()
 
-                absolute_path = os.path.join(os.path.abspath(root), file_name)
-                metadata = self._get_or_create_page(absolute_path)
+                # Skip non-markdown files
+                if docfile.suffix.lower() != ".md":
+                    continue
+                metadata = self._get_or_create_page(docfile)
 
-                LOGGER.debug(f"indexed {absolute_path} with metadata: {metadata}")
-                page_metadata[absolute_path] = metadata
+                LOGGER.debug(f"indexed {docfile} with metadata: {metadata}")
+                page_metadata[docfile] = metadata
 
         LOGGER.info(f"indexed {len(page_metadata)} pages")
 
@@ -68,10 +72,10 @@ class Application:
 
     def _synchronize_page(
         self,
-        page_path: str,
-        page_metadata: Dict[str, ConfluencePageMetadata],
+        page_path: Path,
+        page_metadata: Dict[Path, ConfluencePageMetadata],
     ) -> None:
-        base_path = os.path.dirname(page_path)
+        base_path = page_path.parent
 
         LOGGER.info(f"Synchronizing page: {page_path}")
         document = ConfluenceDocument(page_path, self.options, page_metadata)
@@ -83,7 +87,7 @@ class Application:
             self._update_document(document, base_path)
 
     def _get_or_create_page(
-        self, absolute_path: str, title: Optional[str] = None
+        self, absolute_path: Path, title: Optional[str] = None
     ) -> ConfluencePageMetadata:
         """
         Creates a new Confluence page if no page is linked in the Markdown document.
@@ -106,7 +110,7 @@ class Application:
 
             # use file name without extension if no title is supplied
             if title is None:
-                title, _ = os.path.splitext(os.path.basename(absolute_path))
+                title = absolute_path.stem
 
             confluence_page = self.api.get_or_create_page(
                 title, self.options.root_page_id
@@ -126,10 +130,10 @@ class Application:
             title=confluence_page.title or "",
         )
 
-    def _update_document(self, document: ConfluenceDocument, base_path: str) -> None:
+    def _update_document(self, document: ConfluenceDocument, base_path: Path) -> None:
         for image in document.images:
             self.api.upload_attachment(
-                document.id.page_id, os.path.join(base_path, image), image, ""
+                document.id.page_id, base_path / image, attachment_name(image), ""
             )
 
         content = document.xhtml()
@@ -138,7 +142,7 @@ class Application:
 
     def _update_markdown(
         self,
-        path: str,
+        path: Path,
         document: str,
         page_id: str,
         space_key: Optional[str],

md2conf/converter.py

@@ -207,11 +207,6 @@ class NodeVisitor:
         pass
 
 
-def _change_ext(path: str, target_ext: str) -> str:
-    root, source_ext = os.path.splitext(path)
-    return f"{root}{target_ext}"
-
-
 @dataclass
 class ConfluenceConverterOptions:
     """
@@ -228,22 +223,22 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     "Transforms a plain HTML tree into the Confluence storage format."
 
     options: ConfluenceConverterOptions
-    path: str
-    base_path: str
+    path: pathlib.Path
+    base_path: pathlib.Path
     links: List[str]
     images: List[str]
-    page_metadata: Dict[str, ConfluencePageMetadata]
+    page_metadata: Dict[pathlib.Path, ConfluencePageMetadata]
 
     def __init__(
         self,
         options: ConfluenceConverterOptions,
-        path: str,
-        page_metadata: Dict[str, ConfluencePageMetadata],
+        path: pathlib.Path,
+        page_metadata: Dict[pathlib.Path, ConfluencePageMetadata],
     ) -> None:
         super().__init__()
         self.options = options
         self.path = path
-        self.base_path = os.path.abspath(os.path.dirname(path)) + os.sep
+        self.base_path = path.parent
         self.links = []
         self.images = []
         self.page_metadata = page_metadata
@@ -270,9 +265,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         # convert the relative URL to absolute URL based on the base path value, then look up
         # the absolute path in the page metadata dictionary to discover the relative path
         # within Confluence that should be used
-        absolute_path = os.path.abspath(os.path.join(self.base_path, relative_url.path))
-        if not absolute_path.startswith(self.base_path):
-            msg = f"relative URL points to outside base path: {url}"
+        absolute_path = (self.base_path / relative_url.path).absolute()
+        if not str(absolute_path).startswith(str(self.base_path)):
+            msg = f"relative URL {url} points to outside base path: {self.base_path}"
             if self.options.ignore_invalid_url:
                 LOGGER.warning(msg)
                 anchor.attrib.pop("href")
@@ -314,10 +309,13 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         path: str = image.attrib["src"]
 
         # prefer PNG over SVG; Confluence displays SVG in wrong size, and text labels are truncated
-        if path and is_relative_url(path) and path.endswith(".svg"):
-            replacement_path = _change_ext(path, ".png")
-            if os.path.exists(os.path.join(self.base_path, replacement_path)):
-                path = replacement_path
+        if path and is_relative_url(path):
+            relative_path = pathlib.Path(path)
+            if (
+                relative_path.suffix == ".svg"
+                and (self.base_path / relative_path.with_suffix(".png")).exists()
+            ):
+                path = str(relative_path.with_suffix(".png"))
 
         self.images.append(path)
         caption = image.attrib["alt"]
@@ -327,7 +325,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 ET.QName(namespaces["ac"], "align"): "center",
                 ET.QName(namespaces["ac"], "layout"): "center",
             },
-            RI("attachment", {ET.QName(namespaces["ri"], "filename"): path}),
+            RI(
+                "attachment",
+                {ET.QName(namespaces["ri"], "filename"): attachment_name(path)},
+            ),
             AC("caption", HTML.p(caption)),
         )
 
@@ -391,6 +392,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if class_name is None:
             raise DocumentError(f"unsupported admonition label: {class_list}")
 
+        for e in elem:
+            self.visit(e)
+
         # <p class="admonition-title">Note</p>
         if "admonition-title" in elem[0].attrib.get("class", "").split(" "):
             content = [
@@ -530,27 +534,33 @@ class ConfluenceDocument:
 
     def __init__(
         self,
-        path: str,
+        path: pathlib.Path,
         options: ConfluenceDocumentOptions,
-        page_metadata: Dict[str, ConfluencePageMetadata],
+        page_metadata: Dict[pathlib.Path, ConfluencePageMetadata],
     ) -> None:
         self.options = options
-        path = os.path.abspath(path)
+        path = path.absolute()
 
         with open(path, "r") as f:
-            html = markdown_to_html(f.read())
+            text = f.read()
 
         # extract Confluence page ID
-        qualified_id, html = extract_qualified_id(html)
+        qualified_id, text = extract_qualified_id(text)
         if qualified_id is None:
             raise ValueError("missing Confluence page ID")
         self.id = qualified_id
 
         # extract 'generated-by' tag text
-        generated_by_tag, html = extract_value(
-            r"<!--\s+generated-by:\s*(.*)\s+-->", html
+        generated_by_tag, text = extract_value(
+            r"<!--\s+generated-by:\s*(.*)\s+-->", text
         )
 
+        # extract frontmatter
+        frontmatter, text = extract_value(r"(?ms)\A---$(.+?)^---$", text)
+
+        # convert to HTML
+        html = markdown_to_html(text)
+
         # parse Markdown document
         if self.options.generated_by is not None:
             generated_by = self.options.generated_by
@@ -582,6 +592,18 @@ class ConfluenceDocument:
         return _content_to_string(self.root)
 
 
+def attachment_name(name: str) -> str:
+    """
+    Safe name for use with attachment uploads.
+
+    Allowed characters:
+    * Alphanumeric characters: 0-9, a-z, A-Z
+    * Special characters: hyphen (-), underscore (_), period (.)
+    """
+
+    return re.sub(r"[^\-0-9A-Za-z_.]", "_", name)
+
+
 def sanitize_confluence(html: str) -> str:
     "Generates a sanitized version of a Confluence storage format XHTML document with no volatile attributes."
 

md2conf/processor.py

@@ -1,5 +1,6 @@
 import logging
-import os.path
+import os
+from pathlib import Path
 from typing import Dict
 
 from .converter import (
@@ -23,35 +24,37 @@ class Processor:
         self.options = options
         self.properties = properties
 
-    def process(self, path: str) -> None:
+    def process(self, path: Path) -> None:
         "Processes a single Markdown file or a directory of Markdown files."
 
-        if os.path.isdir(path):
+        if path.is_dir():
             self.process_directory(path)
-        elif os.path.isfile(path):
+        elif path.is_file():
             self.process_page(path, {})
         else:
             raise ValueError(f"expected: valid file or directory path; got: {path}")
 
-    def process_directory(self, dir: str) -> None:
+    def process_directory(self, local_dir: Path) -> None:
         "Recursively scans a directory hierarchy for Markdown files."
 
-        page_metadata: Dict[str, ConfluencePageMetadata] = {}
-        LOGGER.info(f"Synchronizing directory: {dir}")
+        page_metadata: Dict[Path, ConfluencePageMetadata] = {}
+        LOGGER.info(f"Synchronizing directory: {local_dir}")
 
         # Step 1: build index of all page metadata
-        for root, directories, files in os.walk(dir):
+        # NOTE: Pathlib.walk() is implemented only in Python 3.12+
+        # so sticking for old os.walk
+        for root, directories, files in os.walk(local_dir):
             for file_name in files:
-                # check the file extension
-                _, file_extension = os.path.splitext(file_name)
-                if file_extension.lower() != ".md":
-                    continue
+                # Reconstitute Path object back
+                docfile = (Path(root) / file_name).absolute()
 
-                absolute_path = os.path.join(os.path.abspath(root), file_name)
-                metadata = self._get_page(absolute_path)
+                # Skip non-markdown files
+                if docfile.suffix.lower() != ".md":
+                    continue
 
-                LOGGER.debug(f"indexed {absolute_path} with metadata: {metadata}")
-                page_metadata[absolute_path] = metadata
+                metadata = self._get_page(docfile)
+                LOGGER.debug(f"indexed {docfile} with metadata: {metadata}")
+                page_metadata[docfile] = metadata
 
         LOGGER.info(f"indexed {len(page_metadata)} pages")
 
@@ -60,17 +63,16 @@ class Processor:
             self.process_page(page_path, page_metadata)
 
     def process_page(
-        self, path: str, page_metadata: Dict[str, ConfluencePageMetadata]
+        self, path: Path, page_metadata: Dict[Path, ConfluencePageMetadata]
     ) -> None:
         "Processes a single Markdown file."
 
         document = ConfluenceDocument(path, self.options, page_metadata)
         content = document.xhtml()
-        output_path, _ = os.path.splitext(path)
-        with open(f"{output_path}.csf", "w") as f:
+        with open(path.with_suffix(".csf"), "w") as f:
             f.write(content)
 
-    def _get_page(self, absolute_path: str) -> ConfluencePageMetadata:
+    def _get_page(self, absolute_path: Path) -> ConfluencePageMetadata:
         "Extracts metadata from a Markdown file."
 
         with open(absolute_path, "r") as f:

md2conf/properties.py

@@ -1,5 +1,4 @@
 import os
-import os.path
 from typing import Optional
 
 

markdown_to_confluence-0.1.11.dist-info/RECORD

@@ -1,15 +0,0 @@
-md2conf/__init__.py,sha256=YKxQYqSyS46CCTga2WXYIsXcR7QG-GGWn3t1RhzjveE,403
-md2conf/__main__.py,sha256=g46ly26Otzfqve5lCVLoKdRdaOuEsx0of831swWE01o,3602
-md2conf/api.py,sha256=2xEUB8RgXGWxH8I-dGiAPH-1a_m3MBHxqJhOpT5P4A0,14702
-md2conf/application.py,sha256=nPzygYLZNW6YfPA9NC3qAznHQRrvTUndHiNqW24N3YU,5147
-md2conf/converter.py,sha256=yCcnFTkunqu3KkUJTLeNIHqz4CTAzAem-wGrGwVLR5k,17714
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/processor.py,sha256=nmrTlZhovHkTndFAVYMXm7owXfYlQf7-PyZUGDmE6PE,3007
-md2conf/properties.py,sha256=3KMsJhF-O2qJW-ew7ffpPyuVaZ58c24a6ZRP0HmiZ3o,1826
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-markdown_to_confluence-0.1.11.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-markdown_to_confluence-0.1.11.dist-info/METADATA,sha256=5KhaUfxu1yYQoIk289E-y9Q5_hkHofhht0JFMboQZTc,7580
-markdown_to_confluence-0.1.11.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-markdown_to_confluence-0.1.11.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.1.11.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.1.11.dist-info/RECORD,,