markdown-to-confluence 0.5.1__tar.gz → 0.5.3__tar.gz

{markdown_to_confluence-0.5.1 → markdown_to_confluence-0.5.3}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2025 Levente Hunyadi
+Copyright (c) 2022-2026 Levente Hunyadi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

markdown_to_confluence-0.5.3/MANIFEST.in

@@ -0,0 +1,13 @@
+recursive-include tests *.py
+recursive-include tests *.md
+recursive-include tests *.txt
+recursive-include tests .mdignore
+recursive-include tests/source *.drawio
+recursive-include tests/source *.png
+recursive-include tests/source *.svg
+include tests/source/docs/sample.*
+exclude tests/source/emoji.md
+recursive-include tests/target *.xml
+recursive-include tests/target *.mmd
+recursive-include tests/target *.puml
+exclude tests/target/emoji.xml

{markdown_to_confluence-0.5.1/markdown_to_confluence.egg-info → markdown_to_confluence-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.5.1
+Version: 0.5.3
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -27,18 +27,18 @@ Requires-Dist: cattrs>=25.3
 Requires-Dist: lxml>=6.0
 Requires-Dist: markdown>=3.10
 Requires-Dist: orjson>=3.11
-Requires-Dist: pymdown-extensions>=10.17
+Requires-Dist: pymdown-extensions>=10.19
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: truststore>=0.10
 Requires-Dist: typing-extensions>=4.15; python_version < "3.12"
 Provides-Extra: dev
-Requires-Dist: markdown_doc>=0.1.5; extra == "dev"
-Requires-Dist: types-lxml>=2025.8.25; extra == "dev"
+Requires-Dist: markdown_doc>=0.1.6; extra == "dev"
+Requires-Dist: types-lxml>=2025.11.25; extra == "dev"
 Requires-Dist: types-markdown>=3.10; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Requires-Dist: types-requests>=2.32; extra == "dev"
-Requires-Dist: mypy>=1.18; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
 Requires-Dist: ruff>=0.14; extra == "dev"
 Provides-Extra: formulas
 Requires-Dist: matplotlib>=3.9; extra == "formulas"
@@ -98,6 +98,15 @@ pip install markdown-to-confluence
 npm install -g @mermaid-js/mermaid-cli
 ```
 
+**Optional.** Pre-rendering PlantUML diagrams into PNG or SVG images requires Java, Graphviz and [PlantUML](https://plantuml.com/). (Refer to `--render-plantuml`.)
+
+1. **Install Java**: Version 8 or later from [Adoptium](https://adoptium.net/) or [Oracle](https://www.oracle.com/java/technologies/downloads/)
+2. **Install Graphviz**: Required for most diagram types in PlantUML (except sequence diagrams)
+   * **Ubuntu/Debian**: `sudo apt-get install Graphviz`
+   * **macOS**: `brew install graphviz`
+   * **Windows**: Download from [graphviz.org](https://graphviz.org/download/)
+3. **Download PlantUML JAR**: Download [plantuml.jar](https://github.com/plantuml/plantuml/releases) and set `PLANTUML_JAR` environment variable to point to it
+
 **Optional.** Converting formulas and equations to PNG or SVG images requires [Matplotlib](https://matplotlib.org/):
 
 ```sh
@@ -112,7 +121,11 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering in the synchronization phase requires a [marketplace app](https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence). (Refer to `--no-render-mermaid`.)
 
-**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
+**Optional.** PlantUML diagrams are embedded with compressed source data and are displayed using the [PlantUML Diagrams for Confluence](https://marketplace.atlassian.com/apps/1215115/plantuml-diagrams-for-confluence) app (if installed). (Refer to `--no-render-plantuml`.)
+
+Installing `plantuml.jar` (see above) helps display embedded diagrams with pre-calculated optimal dimensions.
+
+**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/). (Refer to `--no-render-latex`.)
 
 ## Getting started
 
@@ -215,6 +228,21 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+The generated-by text can also be templated with the following variables:
+
+- `%{filename}`: the name of the Markdown file
+- `%{filestem}`: the name of the Markdown file without the extension
+- `%{filepath}`: the path of the Markdown file relative to the _source root_
+- `%{filedir}`: the dirname of the `%{filepath}` (the path without the filename)
+
+When publishing a directory hierarchy, the *source root* is the directory in which *md2conf* is launched. When publishing a single file, this is the directory in which the Markdown file resides.
+
+It can be used with the CLI `--generated-by` option or directly in the files:
+
+```markdown
+<!-- generated-by: Do not edit! Check out the file %{filepath} in the repo -->
+```
+
 ### Publishing a single page
 
 *md2conf* has two modes of operation: *single-page mode* and *directory mode*.
@@ -359,6 +387,11 @@ Likewise, if you have a nested list, make sure that nested items are indented by
 
 Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
 
+* Relative paths (e.g. `path/to/image.png` or `../to/image.png`) resolve to absolute paths w.r.t. the Markdown document location.
+* Absolute paths (e.g. `/path/to/image.png`) are interpreted w.r.t. to the synchronization root (typically the shell current directory).
+
+As a security measure, resolved paths can only reference files that are in the directory hierarchy of the synchronization root; you can't use `..` to leave the top-level directory of the synchronization root.
+
 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. (This seems to be a known issue in Confluence.) 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.
@@ -455,6 +488,58 @@ This is useful if you have a page in a hierarchy that participates in parent-chi
 
 If the `title` attribute (in the front-matter) or the topmost unique heading (in the document body) changes, the Confluence page title is updated. A warning is raised if the new title conflicts with the title of another page, and thus cannot be updated.
 
+#### Avoiding duplicate titles
+
+By default, when *md2conf* extracts a page title from the first unique heading in a Markdown document, the heading remains in the document body. This means the title appears twice on the Confluence page: once as the page title at the top, and once as the first heading in the content.
+
+To avoid this duplication, use the `--skip-title-heading` option. When enabled, *md2conf* removes the first heading from the document body if it was used as the page title. This option only takes effect when:
+
+1. The title was extracted from the document's first unique heading (not from front-matter), AND
+2. There is exactly one top-level heading in the document.
+
+If the title comes from the `title` attribute in front-matter, the heading is preserved in the document body regardless of this setting, as the heading and title are considered separate.
+
+**Example without `--skip-title-heading` (default):**
+
+Markdown:
+```markdown
+# Installation Guide
+
+Follow these steps...
+```
+
+Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts with heading "Installation Guide", followed by "Follow these steps..."
+
+**Example with `--skip-title-heading`:**
+
+Same Markdown source, but Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts directly with "Follow these steps..." (heading removed)
+
+**Edge case: Abstract or introductory text before the title:**
+
+When a document has content before the first heading (like an abstract), removing the heading eliminates the visual separator between the introductory text and the main content:
+
+```markdown
+This is an abstract paragraph providing context.
+
+# Document Title
+
+This is the main document content.
+```
+
+With `--skip-title-heading`, the output becomes:
+- Page title: "Document Title"
+- Content: "This is an abstract paragraph..." flows directly into "This is the main document content..." (no heading separator)
+
+While the structure remains semantically correct, the visual separation is lost. If you need to maintain separation, consider these workarounds:
+
+1. **Use a horizontal rule:** Add `---` after the abstract to create visual separation
+2. **Use an admonition block:** Wrap the abstract in an info/note block
+3. **Use front-matter title:** Set `title` in front-matter to keep the heading in the body
+
 ### Labels
 
 If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
@@ -540,7 +625,9 @@ Specifically, image references for status labels (e.g. `![My label][STATUS-RED]`
 
 ### Running the tool
 
-You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
+#### Command line
+
+You can synchronize a (directory of) Markdown file(s) with Confluence using the command-line tool `md2conf`:
 
 ```sh
 $ python3 -m md2conf sample/index.md
@@ -571,27 +658,89 @@ options:
   -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.
   --flatten-hierarchy   Flatten directories with no index.md or README.md when exporting to Confluence.
-  --generated-by GENERATED_BY
+  --generated-by MARKDOWN
                         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.
   --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.)
   --no-render-drawio    Upload draw.io diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-mermaid      Render Mermaid diagrams as image files. (Installed utility required to convert.)
   --no-render-mermaid   Upload Mermaid diagram sources as Confluence page attachments. (Marketplace app required to display.)
+  --render-plantuml     Render PlantUML diagrams as image files. (Installed utility required to convert.)
+  --no-render-plantuml  Upload PlantUML diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-latex        Render LaTeX formulas as image files. (Matplotlib required to convert.)
   --no-render-latex     Inline LaTeX formulas in Confluence page. (Marketplace app required to display.)
   --diagram-output-format {png,svg}
                         Format for rendering Mermaid and draw.io diagrams (default: 'png').
+  --prefer-raster       Prefer PNG over SVG when both exist (default: enabled).
+  --no-prefer-raster    Use SVG files directly instead of preferring PNG equivalents.
   --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --no-heading-anchors  Don't place an anchor at each section heading.
   --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.
-  --headers KEY=VALUE [KEY=VALUE ...]
-                        Apply custom headers to all Confluence API requests.
+  --skip-title-heading  Skip the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).
+  --no-skip-title-heading
+                        Keep the first heading in document body even when used as page title (default).
+  --title-prefix TEXT   String to prepend to Confluence page title for each published page.
   --webui-links         Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)
   --alignment {center,left,right}
                         Alignment for block-level images and formulas (default: 'center').
+  --max-image-width MAX_IMAGE_WIDTH
+                        Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.
   --use-panel           Transform admonitions and alerts into a Confluence custom panel.
+  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
+  --headers KEY=VALUE [KEY=VALUE ...]
+                        Apply custom headers to all Confluence API requests.
+```
+
+#### Python
+
+*md2conf* has a Python interface. Create a `ConnectionProperties` object to set connection parameters to the Confluence server, and a `DocumentOptions` object to configure how Markdown files are converted into pages on a Confluence wiki site. Open a connection to the Confluence server with the context manager `ConfluenceAPI`, and instantiate a `Publisher` to start converting documents.
+
+```python
+from md2conf.api import ConfluenceAPI
+from md2conf.environment import ConnectionProperties
+from md2conf.options import ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
+from md2conf.publisher import Publisher
+
+properties = ConnectionProperties(
+    api_url=...,
+    domain=...,
+    base_path=...,
+    user_name=...,
+    api_key=...,
+    space_key=...,
+    headers=...,
+)
+options = DocumentOptions(
+    root_page_id=...,
+    keep_hierarchy=...,
+    title_prefix=...,
+    generated_by=...,
+    converter=ConverterOptions(
+        heading_anchors=...,
+        ignore_invalid_url=...,
+        skip_title_heading=...,
+        prefer_raster=...,
+        render_drawio=...,
+        render_mermaid=...,
+        render_plantuml=...,
+        render_latex=...,
+        diagram_output_format=...,
+        webui_links=...,
+        use_panel=...,
+        layout=LayoutOptions(
+            image=ImageLayoutOptions(
+                alignment=...,
+                max_width=...,
+            ),
+            table=TableLayoutOptions(
+                width=...,
+                display_mode=...,
+            ),
+        ),
+    ),
+)
+with ConfluenceAPI(properties) as api:
+    Publisher(api, options).process(mdpath)
 ```
 
 ### Confluence REST API v1 vs. v2

{markdown_to_confluence-0.5.1 → markdown_to_confluence-0.5.3}/README.md

@@ -52,6 +52,15 @@ pip install markdown-to-confluence
 npm install -g @mermaid-js/mermaid-cli
 ```
 
+**Optional.** Pre-rendering PlantUML diagrams into PNG or SVG images requires Java, Graphviz and [PlantUML](https://plantuml.com/). (Refer to `--render-plantuml`.)
+
+1. **Install Java**: Version 8 or later from [Adoptium](https://adoptium.net/) or [Oracle](https://www.oracle.com/java/technologies/downloads/)
+2. **Install Graphviz**: Required for most diagram types in PlantUML (except sequence diagrams)
+   * **Ubuntu/Debian**: `sudo apt-get install Graphviz`
+   * **macOS**: `brew install graphviz`
+   * **Windows**: Download from [graphviz.org](https://graphviz.org/download/)
+3. **Download PlantUML JAR**: Download [plantuml.jar](https://github.com/plantuml/plantuml/releases) and set `PLANTUML_JAR` environment variable to point to it
+
 **Optional.** Converting formulas and equations to PNG or SVG images requires [Matplotlib](https://matplotlib.org/):
 
 ```sh
@@ -66,7 +75,11 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering in the synchronization phase requires a [marketplace app](https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence). (Refer to `--no-render-mermaid`.)
 
-**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
+**Optional.** PlantUML diagrams are embedded with compressed source data and are displayed using the [PlantUML Diagrams for Confluence](https://marketplace.atlassian.com/apps/1215115/plantuml-diagrams-for-confluence) app (if installed). (Refer to `--no-render-plantuml`.)
+
+Installing `plantuml.jar` (see above) helps display embedded diagrams with pre-calculated optimal dimensions.
+
+**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/). (Refer to `--no-render-latex`.)
 
 ## Getting started
 
@@ -169,6 +182,21 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+The generated-by text can also be templated with the following variables:
+
+- `%{filename}`: the name of the Markdown file
+- `%{filestem}`: the name of the Markdown file without the extension
+- `%{filepath}`: the path of the Markdown file relative to the _source root_
+- `%{filedir}`: the dirname of the `%{filepath}` (the path without the filename)
+
+When publishing a directory hierarchy, the *source root* is the directory in which *md2conf* is launched. When publishing a single file, this is the directory in which the Markdown file resides.
+
+It can be used with the CLI `--generated-by` option or directly in the files:
+
+```markdown
+<!-- generated-by: Do not edit! Check out the file %{filepath} in the repo -->
+```
+
 ### Publishing a single page
 
 *md2conf* has two modes of operation: *single-page mode* and *directory mode*.
@@ -313,6 +341,11 @@ Likewise, if you have a nested list, make sure that nested items are indented by
 
 Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
 
+* Relative paths (e.g. `path/to/image.png` or `../to/image.png`) resolve to absolute paths w.r.t. the Markdown document location.
+* Absolute paths (e.g. `/path/to/image.png`) are interpreted w.r.t. to the synchronization root (typically the shell current directory).
+
+As a security measure, resolved paths can only reference files that are in the directory hierarchy of the synchronization root; you can't use `..` to leave the top-level directory of the synchronization root.
+
 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. (This seems to be a known issue in Confluence.) 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.
@@ -409,6 +442,58 @@ This is useful if you have a page in a hierarchy that participates in parent-chi
 
 If the `title` attribute (in the front-matter) or the topmost unique heading (in the document body) changes, the Confluence page title is updated. A warning is raised if the new title conflicts with the title of another page, and thus cannot be updated.
 
+#### Avoiding duplicate titles
+
+By default, when *md2conf* extracts a page title from the first unique heading in a Markdown document, the heading remains in the document body. This means the title appears twice on the Confluence page: once as the page title at the top, and once as the first heading in the content.
+
+To avoid this duplication, use the `--skip-title-heading` option. When enabled, *md2conf* removes the first heading from the document body if it was used as the page title. This option only takes effect when:
+
+1. The title was extracted from the document's first unique heading (not from front-matter), AND
+2. There is exactly one top-level heading in the document.
+
+If the title comes from the `title` attribute in front-matter, the heading is preserved in the document body regardless of this setting, as the heading and title are considered separate.
+
+**Example without `--skip-title-heading` (default):**
+
+Markdown:
+```markdown
+# Installation Guide
+
+Follow these steps...
+```
+
+Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts with heading "Installation Guide", followed by "Follow these steps..."
+
+**Example with `--skip-title-heading`:**
+
+Same Markdown source, but Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts directly with "Follow these steps..." (heading removed)
+
+**Edge case: Abstract or introductory text before the title:**
+
+When a document has content before the first heading (like an abstract), removing the heading eliminates the visual separator between the introductory text and the main content:
+
+```markdown
+This is an abstract paragraph providing context.
+
+# Document Title
+
+This is the main document content.
+```
+
+With `--skip-title-heading`, the output becomes:
+- Page title: "Document Title"
+- Content: "This is an abstract paragraph..." flows directly into "This is the main document content..." (no heading separator)
+
+While the structure remains semantically correct, the visual separation is lost. If you need to maintain separation, consider these workarounds:
+
+1. **Use a horizontal rule:** Add `---` after the abstract to create visual separation
+2. **Use an admonition block:** Wrap the abstract in an info/note block
+3. **Use front-matter title:** Set `title` in front-matter to keep the heading in the body
+
 ### Labels
 
 If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
@@ -494,7 +579,9 @@ Specifically, image references for status labels (e.g. `![My label][STATUS-RED]`
 
 ### Running the tool
 
-You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
+#### Command line
+
+You can synchronize a (directory of) Markdown file(s) with Confluence using the command-line tool `md2conf`:
 
 ```sh
 $ python3 -m md2conf sample/index.md
@@ -525,27 +612,89 @@ options:
   -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.
   --flatten-hierarchy   Flatten directories with no index.md or README.md when exporting to Confluence.
-  --generated-by GENERATED_BY
+  --generated-by MARKDOWN
                         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.
   --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.)
   --no-render-drawio    Upload draw.io diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-mermaid      Render Mermaid diagrams as image files. (Installed utility required to convert.)
   --no-render-mermaid   Upload Mermaid diagram sources as Confluence page attachments. (Marketplace app required to display.)
+  --render-plantuml     Render PlantUML diagrams as image files. (Installed utility required to convert.)
+  --no-render-plantuml  Upload PlantUML diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-latex        Render LaTeX formulas as image files. (Matplotlib required to convert.)
   --no-render-latex     Inline LaTeX formulas in Confluence page. (Marketplace app required to display.)
   --diagram-output-format {png,svg}
                         Format for rendering Mermaid and draw.io diagrams (default: 'png').
+  --prefer-raster       Prefer PNG over SVG when both exist (default: enabled).
+  --no-prefer-raster    Use SVG files directly instead of preferring PNG equivalents.
   --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --no-heading-anchors  Don't place an anchor at each section heading.
   --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.
-  --headers KEY=VALUE [KEY=VALUE ...]
-                        Apply custom headers to all Confluence API requests.
+  --skip-title-heading  Skip the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).
+  --no-skip-title-heading
+                        Keep the first heading in document body even when used as page title (default).
+  --title-prefix TEXT   String to prepend to Confluence page title for each published page.
   --webui-links         Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)
   --alignment {center,left,right}
                         Alignment for block-level images and formulas (default: 'center').
+  --max-image-width MAX_IMAGE_WIDTH
+                        Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.
   --use-panel           Transform admonitions and alerts into a Confluence custom panel.
+  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
+  --headers KEY=VALUE [KEY=VALUE ...]
+                        Apply custom headers to all Confluence API requests.
+```
+
+#### Python
+
+*md2conf* has a Python interface. Create a `ConnectionProperties` object to set connection parameters to the Confluence server, and a `DocumentOptions` object to configure how Markdown files are converted into pages on a Confluence wiki site. Open a connection to the Confluence server with the context manager `ConfluenceAPI`, and instantiate a `Publisher` to start converting documents.
+
+```python
+from md2conf.api import ConfluenceAPI
+from md2conf.environment import ConnectionProperties
+from md2conf.options import ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
+from md2conf.publisher import Publisher
+
+properties = ConnectionProperties(
+    api_url=...,
+    domain=...,
+    base_path=...,
+    user_name=...,
+    api_key=...,
+    space_key=...,
+    headers=...,
+)
+options = DocumentOptions(
+    root_page_id=...,
+    keep_hierarchy=...,
+    title_prefix=...,
+    generated_by=...,
+    converter=ConverterOptions(
+        heading_anchors=...,
+        ignore_invalid_url=...,
+        skip_title_heading=...,
+        prefer_raster=...,
+        render_drawio=...,
+        render_mermaid=...,
+        render_plantuml=...,
+        render_latex=...,
+        diagram_output_format=...,
+        webui_links=...,
+        use_panel=...,
+        layout=LayoutOptions(
+            image=ImageLayoutOptions(
+                alignment=...,
+                max_width=...,
+            ),
+            table=TableLayoutOptions(
+                width=...,
+                display_mode=...,
+            ),
+        ),
+    ),
+)
+with ConfluenceAPI(properties) as api:
+    Publisher(api, options).process(mdpath)
 ```
 
 ### Confluence REST API v1 vs. v2