markdown-to-confluence 0.5.2__tar.gz → 0.5.4__tar.gz

{markdown_to_confluence-0.5.2 → markdown_to_confluence-0.5.4}/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.4/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.2/markdown_to_confluence.egg-info → markdown_to_confluence-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.5.2
+Version: 0.5.4
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -62,7 +62,6 @@ This Python package
 * Text with **bold**, *italic*, `monospace`, <ins>underline</ins> and ~~strikethrough~~
 * Link to [sections on the same page](#getting-started) or [external locations](http://example.com/)
 * Subscript and superscript
-* Math formulas with LaTeX notation
 * Emoji
 * Ordered and unordered lists
 * Block quotes
@@ -76,6 +75,8 @@ This Python package
 * [Tasklists](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-tasklists)
 * draw\.io diagrams
 * [Mermaid diagrams](https://mermaid.live/)
+* PlantUML diagrams
+* Math formulas with LaTeX notation
 * Confluence status labels and date widget
 
 Whenever possible, the implementation uses [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/) to fetch space properties, and get, create or update page content.
@@ -98,6 +99,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 +122,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
 
@@ -185,48 +199,54 @@ If you lack appropriate permissions, you will get an *Unauthorized* response fro
 
 ### Associating a Markdown file with a wiki page
 
-Each Markdown file is associated with a Confluence wiki page with a Markdown comment:
+Each Markdown file is associated with a Confluence wiki page either *explicitly* or *implicitly*.
+
+#### Explicit association
+
+We associate a Markdown document with a Confluence page explicitly by specifying the related Confluence page ID in a Markdown comment:
 
 ```markdown
 <!-- confluence-page-id: 20250001023 -->
 ```
 
-The above tells the tool to synchronize the Markdown file with the given Confluence page ID. This implies that the Confluence wiki page must exist such that it has an ID. The comment can be placed anywhere in the source file.
+The above tells the tool to synchronize the Markdown file with the given Confluence page ID. The Confluence wiki page must be created beforehand. The comment can be placed anywhere in the source file.
 
-### Setting the Confluence space
+#### Implicit association
 
-If you work in an environment where there are multiple Confluence spaces, and some Markdown pages may go into one space, whereas other pages may go into another, you can set the target space on a per-document basis:
+Each Markdown document is automatically paired with a Confluence page in the target space if they have the same title.
 
-```markdown
-<!-- confluence-space-key: SPACE -->
-```
+If a Confluence page with the given title doesn't exist, it is created automatically, and its identifier is injected into the source as a Markdown comment.
 
-This overrides the default space set via command-line arguments or environment variables.
+If a Confluence page already exists whose title matches the Markdown document title, additional precautions are taken to avoid overwriting an unrelated page. Each implicitly associated page has to trace back to a trusted well-known Confluence page via parent-child relationships before its content would be synchronized. Trusted Confluence pages include:
 
-### Setting generated-by prompt text for wiki pages
+* the *root page* whose page ID is
+    * specified in the command line, or
+    * extracted from the index file of a directory that is being synchronized
+* a page associated with a Markdown document via a page ID
+    * embedded as a Markdown comment, or
+    * specified in the Markdown front-matter
 
-In order to ensure readers are not editing a generated document, the tool adds a warning message at the top of the Confluence page as an *info panel*. You can customize the text that appears. The text can contain markup as per the [Confluence Storage Format](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html), and is emitted directly into the *info panel* macro.
+If a Confluence page doesn't have a trusted ancestor, synchronization fails. This restricts updates to subtrees of well-known pages.
 
-Provide generated-by prompt text in the Markdown file with a tag:
+### Setting the Confluence space
+
+If you work in an environment where there are multiple Confluence spaces, and some Markdown pages may go into one space, whereas other pages may go into another, you can set the target space on a per-document basis:
 
 ```markdown
-<!-- generated-by: Do not edit! Check out the <a href="https://example.com/project">original source</a>. -->
+<!-- confluence-space-key: SPACE -->
 ```
 
-Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
-
-The generated-by text can also be templated with the following variables:
+This overrides the default space set via command-line arguments or environment variables.
 
-- `%{filename}`: the name of the Markdown file
-- `%{filepath}`: the path of the Markdown file relative to the *source root*
+### Page title
 
-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.
+*md2conf* makes a best-effort attempt at setting the Confluence wiki page title when it publishes a Markdown document the first time. The following act as sources for deriving a page title:
 
-It can be used with the CLI `--generated-by` option or directly in the files:
+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. Both JSON and YAML syntax are 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`) and a digest. The digest is included to ensure the title is unique across the Confluence space.
 
-```markdown
-<!-- generated-by: Do not edit! Check out the file %{filepath} in the repo -->
-```
+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.
 
 ### Publishing a single page
 
@@ -252,7 +272,7 @@ The title of each Markdown file (either the text of the topmost unique heading (
 
 ```
 docs
-├── index.md: Root page
+├── index.md: Eternal golden braid
 ├── computer-science
 │   ├── index.md: Introduction to computer science
 │   ├── algebra.md: Linear algebra
@@ -263,7 +283,7 @@ docs
 │   └── statistics
 │       ├── index.md: Introduction to statistics
 │       └── median.md: Mean vs. median
-└── ethics.md: Ethical considerations
+└── ethics.md: History of ethics
 ```
 
 #### Page hierarchy in Confluence
@@ -271,7 +291,7 @@ docs
 Observe how `index.md` and `README.md` files have assumed parent (or ancestor) role for any Markdown files in the same directory (or below).
 
 ```
-Root page
+Eternal golden braid
 ├── Introduction to computer science
 │   ├── Linear algebra
 │   └── Theory of algorithms
@@ -279,7 +299,7 @@ Root page
 │   ├── Consciousness and intelligence
 │   └── Introduction to statistics
 │       └── Mean vs. median
-└── Ethical considerations
+└── History of ethics
 ```
 
 ### Subscript and superscript
@@ -298,57 +318,6 @@ The short name notation `:smile:` in a Markdown document is converted into the c
 <ac:emoticon ac:name="smile" ac:emoji-shortname=":smile:" ac:emoji-id="1f604" ac:emoji-fallback="&#128516;"/>
 ```
 
-### Colors
-
-Confluence allows setting text color and highlight color. Even though Markdown doesn't directly support colors, it is possible to set text and highlight color via the HTML element `<span>` and the CSS attributes `color` and `background-color`, respectively:
-
-Text in <span style="color: rgb(255,86,48);">red</span>, <span style="color: rgb(54,179,126);">green</span> and <span style="color: rgb(76,154,255);">blue</span>:
-
-```markdown
-Text in <span style="color: rgb(255,86,48);">red</span>, <span style="color: rgb(54,179,126);">green</span> and <span style="color: rgb(76,154,255);">blue</span>.
-```
-
-Highlight in <span style="background-color: rgb(198,237,251);">teal</span>, <span style="background-color: rgb(211,241,167);">lime</span> and <span style="background-color: rgb(254,222,200);">yellow</span>:
-
-```markdown
-Highlight in <span style="background-color: rgb(198,237,251);">teal</span>, <span style="background-color: rgb(211,241,167);">lime</span> and <span style="background-color: rgb(254,222,200);">yellow</span>.
-```
-
-Highlighting is also supported via `==marks==`. However, the background color is not customizable.
-
-The following table shows standard text colors (CSS `color`) that are available via Confluence UI:
-
-| Color name    | CSS attribute value |
-| :------------ | :------------------ |
-| bold blue     | rgb(7,71,166)       |
-| blue          | rgb(76,154,255)     |
-| subtle blue   | rgb(179,212,255)    |
-| bold teal     | rgb(0,141,166)      |
-| teal          | rgb(0,184,217)      |
-| subtle teal   | rgb(179,245,255)    |
-| bold green    | rgb(0,102,68)       |
-| green         | rgb(54,179,126)     |
-| subtle green  | rgb(171,245,209)    |
-| bold orange   | rgb(255,153,31)     |
-| yellow        | rgb(255,196,0)      |
-| subtle yellow | rgb(255,240,179)    |
-| bold red      | rgb(191,38,0)       |
-| red           | rgb(255,86,48)      |
-| subtle red    | rgb(255,189,173)    |
-| bold purple   | rgb(64,50,148)      |
-| purple        | rgb(101,84,192)     |
-| subtle purple | rgb(234,230,255)    |
-
-The following table shows standard highlight colors (CSS `background-color`) that are available via Confluence UI:
-
-| Color name    | CSS attribute value |
-| ------------- | ------------------- |
-| teal          | rgb(198,237,251)    |
-| lime          | rgb(211,241,167)    |
-| yellow        | rgb(254,222,200)    |
-| magenta       | rgb(253,208,236)    |
-| purple        | rgb(223,216,253)    |
-
 ### Lists and tables
 
 If your Markdown lists or tables don't appear in Confluence as expected, verify that the list or table is delimited by a blank line both before and after, as per strict Markdown syntax. While some previewers accept a more lenient syntax (e.g. an itemized list immediately following a paragraph), *md2conf* uses [Python-Markdown](https://python-markdown.github.io/) internally to convert Markdown into XHTML, which expects the Markdown document to adhere to the stricter syntax.
@@ -372,10 +341,43 @@ 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.
 
+### draw\.io diagrams
+
+With the command-line option `--no-render-drawio` (default), editable diagram data is extracted from images with embedded draw\.io diagrams (`*.drawio.png` and `*.drawio.svg`), and uploaded to Confluence as attachments. Files that match `*.drawio` or `*.drawio.xml` are uploaded as-is. You need a [marketplace app](https://marketplace.atlassian.com/apps/1210933/draw-io-diagrams-uml-bpmn-aws-erd-flowcharts) to view and edit these diagrams on a Confluence page.
+
+With the command-line option `--render-drawio`, images with embedded draw\.io diagrams (`*.drawio.png` and `*.drawio.svg`) are uploaded unchanged, and shown on the Confluence page as images. These diagrams are not editable in Confluence. When both an SVG and a PNG image is available, PNG is preferred. Files that match `*.drawio` or `*.drawio.xml` are converted into PNG or SVG images by invoking draw\.io as a command-line utility, and the generated images are uploaded to Confluence as attachments, and shown as images.
+
+### Mermaid diagrams
+
+You can add [Mermaid diagrams](https://mermaid.js.org/) to your Markdown documents to create visual representations of systems, processes, and relationships. There are two ways to include a Mermaid diagram:
+
+* an image reference to a `.mmd` or `.mermaid` file, i.e. `![My diagram](figure/diagram.mmd)`, or
+* a fenced code block with the language specifier `mermaid`.
+
+*md2conf* offers two options to publish the diagram:
+
+1. Pre-render into an image (command-line option `--render-mermaid`). The source file or code block is interpreted by and converted into a PNG or SVG image with the Mermaid diagram utility [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). The generated image is then uploaded to Confluence as an attachment to the page.
+2. Display on demand (command-line option `--no-render-mermaid`). The code block is transformed into a [diagram macro](https://stratus-addons.atlassian.net/wiki/spaces/MDFC/overview), which is processed by Confluence. You need a separate [marketplace app](https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence) to turn macro definitions into images when a Confluence page is visited.
+
+If you are running into issues with the pre-rendering approach (e.g. misaligned labels in the generated image), verify if `mermaid-cli` can process the Mermaid source:
+
+```sh
+mmdc -i sample.mmd -o sample.png -b transparent --scale 2
+```
+
+Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
+
+Note that `mermaid-cli` has some implicit dependencies (e.g. a headless browser) that may not be immediately available in a CI/CD environment such as GitHub Actions. Refer to the `Dockerfile` in the *md2conf* project root, or [mermaid-cli documentation](https://github.com/mermaid-js/mermaid-cli) on how to install these dependencies such as a `chromium-browser` and various fonts.
+
 ### LaTeX math formulas
 
 Inline formulas can be enclosed with `$` signs, or delimited with `\(` and `\)`, i.e.
@@ -393,16 +395,15 @@ is shown as
 
 $$\int _{a}^{b}f(x)dx=F(b)-F(a)$$
 
-Displaying math formulas in Confluence requires the extension [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
+If installed, *md2conf* can pre-render math formulas with [Matplotlib](https://matplotlib.org/). This approach doesn't require a third-party Confluence extension.
 
-### HTML in Markdown
+Displaying math formulas in Confluence (without pre-rendering) requires the extension [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
 
-*md2conf* relays HTML elements nested in Markdown content to Confluence (such as `e<sup>x</sup>` for superscript). However, Confluence uses an extension of XHTML, i.e. the content must qualify as valid XML too. In particular, unterminated tags (e.g. `<br>` or `<img ...>`) or inconsistent nesting (e.g. `<b><i></b></i>`) are not permitted, and will raise an XML parsing error. When an HTML element has no content such as `<br>` or `<img>`, use a self-closing tag:
+### Alignment
 
-```html
-<br/>
-<img src="image.png" width="24" height="24" />
-```
+You can configure diagram and image alignment using the JSON/YAML front-matter attribute `alignment` or the command-line argument of the same name. Possible values are `center` (default), `left` and `right`. The value configured in the Markdown file front-matter takes precedence.
+
+Unfortunately, not every third-party app supports every alignment variant. For example, the draw\.io marketplace app supports left and center but not right alignment; and diagrams produced by the Mermaid marketplace app are always centered, ignoring the setting for alignment.
 
 ### Confluence widgets
 
@@ -436,39 +437,108 @@ Use the pseudo-language `csf` in a Markdown code block to pass content directly
 ```
 ````
 
-### Ignoring files
+### Implicit URLs
 
-Skip files and subdirectories in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax (and constraints) 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.
+*md2conf* implicitly defines some URLs, as if you included the following at the start of the Markdown document for each URL:
 
-Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into. To skip an entire directory, add the name of the directory without a trailing `/`.
+```markdown
+[CUSTOM-URL]: https://example.com/path/to/resource
+```
 
-Relative paths to items in a nested directory are not supported. You must put `.mdignore` in the same directory where the items to be skipped reside.
+Specifically, image references for status labels (e.g. `![My label][STATUS-RED]`) are automatically resolved into internally defined URLs via this mechanism.
 
-If you add the `synchronized` attribute to JSON or YAML front-matter with the value `false`, the document content (including attachments) and metadata (e.g. tags) will not be synchronized with Confluence:
+### Colors
 
-```yaml
----
-title: "Collaborating with other teams"
-page_id: "19830101"
-synchronized: false
----
+Confluence allows setting text color and highlight color. Even though Markdown doesn't directly support colors, it is possible to set text and highlight color via the HTML element `<span>` and the CSS attributes `color` and `background-color`, respectively:
 
-This Markdown document is neither parsed, nor synchronized with Confluence.
+Text in <span style="color: rgb(255,86,48);">red</span>, <span style="color: rgb(54,179,126);">green</span> and <span style="color: rgb(76,154,255);">blue</span>:
+
+```markdown
+Text in <span style="color: rgb(255,86,48);">red</span>, <span style="color: rgb(54,179,126);">green</span> and <span style="color: rgb(76,154,255);">blue</span>.
 ```
 
-This is useful if you have a page in a hierarchy that participates in parent-child relationships but whose content is edited directly in Confluence. Specifically, these documents can be referenced with relative links from other Markdown documents in the file system tree.
+Highlight in <span style="background-color: rgb(198,237,251);">teal</span>, <span style="background-color: rgb(211,241,167);">lime</span> and <span style="background-color: rgb(254,222,200);">yellow</span>:
 
-### Page title
+```markdown
+Highlight in <span style="background-color: rgb(198,237,251);">teal</span>, <span style="background-color: rgb(211,241,167);">lime</span> and <span style="background-color: rgb(254,222,200);">yellow</span>.
+```
 
-*md2conf* makes a best-effort attempt at setting the Confluence wiki page title when it publishes a Markdown document the first time. The following act as sources for deriving a page title:
+Highlighting is also supported via `==marks==`. However, the background color is not customizable.
 
-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. Both JSON and YAML syntax are 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`) and a digest. The digest is included to ensure the title is unique across the Confluence space.
+The following table shows standard text colors (CSS `color`) that are available via Confluence UI:
 
-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.
+| Color name    | CSS attribute value |
+| :------------ | :------------------ |
+| bold blue     | rgb(7,71,166)       |
+| blue          | rgb(76,154,255)     |
+| subtle blue   | rgb(179,212,255)    |
+| bold teal     | rgb(0,141,166)      |
+| teal          | rgb(0,184,217)      |
+| subtle teal   | rgb(179,245,255)    |
+| bold green    | rgb(0,102,68)       |
+| green         | rgb(54,179,126)     |
+| subtle green  | rgb(171,245,209)    |
+| bold orange   | rgb(255,153,31)     |
+| yellow        | rgb(255,196,0)      |
+| subtle yellow | rgb(255,240,179)    |
+| bold red      | rgb(191,38,0)       |
+| red           | rgb(255,86,48)      |
+| subtle red    | rgb(255,189,173)    |
+| bold purple   | rgb(64,50,148)      |
+| purple        | rgb(101,84,192)     |
+| subtle purple | rgb(234,230,255)    |
 
-#### Avoiding duplicate titles
+The following table shows standard highlight colors (CSS `background-color`) that are available via Confluence UI:
+
+| Color name    | CSS attribute value |
+| ------------- | ------------------- |
+| teal          | rgb(198,237,251)    |
+| lime          | rgb(211,241,167)    |
+| yellow        | rgb(254,222,200)    |
+| magenta       | rgb(253,208,236)    |
+| purple        | rgb(223,216,253)    |
+
+### HTML in Markdown
+
+*md2conf* relays HTML elements nested in Markdown content to Confluence (such as `e<sup>x</sup>` for superscript). However, Confluence uses an extension of XHTML, i.e. the content must qualify as valid XML too. In particular, unterminated tags (e.g. `<br>` or `<img ...>`) or inconsistent nesting (e.g. `<b><i></b></i>`) are not permitted, and will raise an XML parsing error. When an HTML element has no content such as `<br>` or `<img>`, use a self-closing tag:
+
+```html
+<br/>
+<img src="image.png" width="24" height="24" />
+```
+
+### Links to attachments
+
+If *md2conf* encounters a Markdown link that points to a file in the directory hierarchy being synchronized, it automatically uploads the file as an attachment to the Confluence page. Activating the link in Confluence downloads the file. Typical examples include PDFs (`*.pdf`), word processor documents (`*.docx`), spreadsheets (`*.xlsx`), plain text files (`*.txt`) or logs (`*.log`). The MIME type is set based on the file type.
+
+### Setting generated-by prompt text for wiki pages
+
+In order to ensure readers are not editing a generated document, the tool adds a warning message at the top of the Confluence page as an *info panel*. You can customize the text that appears. The text can contain markup as per the [Confluence Storage Format](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html), and is emitted directly into the *info panel* macro.
+
+Provide generated-by prompt text in the Markdown file with a tag:
+
+```markdown
+<!-- generated-by: Do not edit! Check out the <a href="https://example.com/project">original source</a>. -->
+```
+
+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 -->
+```
+
+### 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.
 
@@ -520,6 +590,28 @@ While the structure remains semantically correct, the visual separation is lost.
 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
 
+### Ignoring files
+
+Skip files and subdirectories in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax (and constraints) 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. To skip an entire directory, add the name of the directory without a trailing `/`.
+
+Relative paths to items in a nested directory are not supported. You must put `.mdignore` in the same directory where the items to be skipped reside.
+
+If you add the `synchronized` attribute to JSON or YAML front-matter with the value `false`, the document content (including attachments) and metadata (e.g. tags) will not be synchronized with Confluence:
+
+```yaml
+---
+title: "Collaborating with other teams"
+page_id: "19830101"
+synchronized: false
+---
+
+This Markdown document is neither parsed, nor synchronized with Confluence.
+```
+
+This is useful if you have a page in a hierarchy that participates in parent-child relationships but whose content is edited directly in Confluence. Specifically, these documents can be referenced with relative links from other Markdown documents in the file system tree.
+
 ### Labels
 
 If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
@@ -551,61 +643,15 @@ properties:
 
 The attribute `properties` is parsed as a dictionary with keys of type string and values of type JSON. *md2conf* passes JSON values to Confluence REST API unchanged.
 
-### draw\.io diagrams
-
-With the command-line option `--no-render-drawio` (default), editable diagram data is extracted from images with embedded draw\.io diagrams (`*.drawio.png` and `*.drawio.svg`), and uploaded to Confluence as attachments. Files that match `*.drawio` or `*.drawio.xml` are uploaded as-is. You need a [marketplace app](https://marketplace.atlassian.com/apps/1210933/draw-io-diagrams-uml-bpmn-aws-erd-flowcharts) to view and edit these diagrams on a Confluence page.
-
-With the command-line option `--render-drawio`, images with embedded draw\.io diagrams (`*.drawio.png` and `*.drawio.svg`) are uploaded unchanged, and shown on the Confluence page as images. These diagrams are not editable in Confluence. When both an SVG and a PNG image is available, PNG is preferred. Files that match `*.drawio` or `*.drawio.xml` are converted into PNG or SVG images by invoking draw\.io as a command-line utility, and the generated images are uploaded to Confluence as attachments, and shown as images.
-
-### Mermaid diagrams
-
-You can add [Mermaid diagrams](https://mermaid.js.org/) to your Markdown documents to create visual representations of systems, processes, and relationships. There are two ways to include a Mermaid diagram:
-
-* an image reference to a `.mmd` or `.mermaid` file, i.e. `![My diagram](figure/diagram.mmd)`, or
-* a fenced code block with the language specifier `mermaid`.
-
-*md2conf* offers two options to publish the diagram:
-
-1. Pre-render into an image (command-line option `--render-mermaid`). The source file or code block is interpreted by and converted into a PNG or SVG image with the Mermaid diagram utility [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). The generated image is then uploaded to Confluence as an attachment to the page.
-2. Display on demand (command-line option `--no-render-mermaid`). The code block is transformed into a [diagram macro](https://stratus-addons.atlassian.net/wiki/spaces/MDFC/overview), which is processed by Confluence. You need a separate [marketplace app](https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence) to turn macro definitions into images when a Confluence page is visited.
-
-If you are running into issues with the pre-rendering approach (e.g. misaligned labels in the generated image), verify if `mermaid-cli` can process the Mermaid source:
-
-```sh
-mmdc -i sample.mmd -o sample.png -b transparent --scale 2
-```
-
-Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
-
-Note that `mermaid-cli` has some implicit dependencies (e.g. a headless browser) that may not be immediately available in a CI/CD environment such as GitHub Actions. Refer to the `Dockerfile` in the *md2conf* project root, or [mermaid-cli documentation](https://github.com/mermaid-js/mermaid-cli) on how to install these dependencies such as a `chromium-browser` and various fonts.
-
-### Alignment
-
-You can configure diagram and image alignment using the JSON/YAML front-matter attribute `alignment` or the command-line argument of the same name. Possible values are `center` (default), `left` and `right`. The value configured in the Markdown file front-matter takes precedence.
-
-Unfortunately, not every third-party app supports every alignment variant. For example, the draw\.io marketplace app supports left and center but not right alignment; and diagrams produced by the Mermaid marketplace app are always centered, ignoring the setting for alignment.
-
-### Links to attachments
-
-If *md2conf* encounters a Markdown link that points to a file in the directory hierarchy being synchronized, it automatically uploads the file as an attachment to the Confluence page. Activating the link in Confluence downloads the file. Typical examples include PDFs (`*.pdf`), word processor documents (`*.docx`), spreadsheets (`*.xlsx`), plain text files (`*.txt`) or logs (`*.log`). The MIME type is set based on the file type.
-
-### Implicit URLs
-
-*md2conf* implicitly defines some URLs, as if you included the following at the start of the Markdown document for each URL:
-
-```markdown
-[CUSTOM-URL]: https://example.com/path/to/resource
-```
-
-Specifically, image references for status labels (e.g. `![My label][STATUS-RED]`) are automatically resolved into internally defined URLs via this mechanism.
-
 ### Local output
 
 *md2conf* supports local output, in which the tool doesn't communicate with the Confluence REST API. Instead, it reads a single Markdown file or a directory of Markdown files, and writes Confluence Storage Format (`*.csf`) output for each document. (Confluence Storage Format is a derivative of XHTML with Confluence-specific tags for complex elements such as images with captions, code blocks, info panels, collapsed sections, etc.) You can push the generated output to Confluence by invoking the API (e.g. with `curl`).
 
 ### 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
@@ -615,7 +661,7 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf mdpath [OPTIONS]
+usage: md2conf mdpath [mdpath ...] [OPTIONS]
 
 positional arguments:
   mdpath                Path to Markdown file or directory to convert and publish.
@@ -639,10 +685,13 @@ options:
   --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.
+  --skip-update         Skip saving Confluence page ID in Markdown files.
   --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}
@@ -667,6 +716,58 @@ options:
                         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
 
 *md2conf* version 0.3.0 has switched to using [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/) for API calls such as retrieving current page content. Earlier versions used [Confluence REST API v1](https://developer.atlassian.com/cloud/confluence/rest/v1/) exclusively. Unfortunately, Atlassian has decommissioned Confluence REST API v1 for several endpoints in Confluence Cloud as of due date March 31, 2025, and we don't have access to an environment where we could test retired v1 endpoints.