markdown-to-confluence 0.5.3__py3-none-any.whl → 0.5.5__py3-none-any.whl

{markdown_to_confluence-0.5.3.dist-info → markdown_to_confluence-0.5.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.5.3
+Version: 0.5.5
 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.19
+Requires-Dist: pymdown-extensions>=10.20
 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"
+Requires-Dist: typing-extensions>=4.15; python_version < "3.11"
 Provides-Extra: dev
-Requires-Dist: markdown_doc>=0.1.6; extra == "dev"
-Requires-Dist: types-lxml>=2025.11.25; extra == "dev"
+Requires-Dist: markdown_doc>=0.1.7; extra == "dev"
+Requires-Dist: types-lxml>=2026.1.1; 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.19; extra == "dev"
+Requires-Dist: mypy[faster-cache]>=1.19; extra == "dev"
 Requires-Dist: ruff>=0.14; extra == "dev"
 Provides-Extra: formulas
 Requires-Dist: matplotlib>=3.9; extra == "formulas"
@@ -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.
@@ -198,50 +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
-- `%{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)
+### 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
 
@@ -267,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
@@ -278,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
@@ -286,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
@@ -294,7 +299,7 @@ Root page
 │   ├── Consciousness and intelligence
 │   └── Introduction to statistics
 │       └── Mean vs. median
-└── Ethical considerations
+└── History of ethics
 ```
 
 ### Subscript and superscript
@@ -313,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.
@@ -396,6 +350,34 @@ Unfortunately, Confluence struggles with SVG images, e.g. they may only show in
 
 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.
@@ -413,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
 
@@ -456,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)    |
+
+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
+### 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.
 
@@ -540,84 +590,87 @@ 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
 
-### Labels
-
-If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
-
-```yaml
----
-title: "Example document"
-tags: ["markdown", "md", "wiki"]
----
-```
-
-Any previously assigned labels are discarded. As per Confluence terminology, new labels have the `prefix` of `global`.
+### Ignoring files
 
-If a document has no `tags` attribute, existing Confluence labels are left intact.
+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.
 
-### Content properties
+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 `/`.
 
-The front-matter attribute `properties` in a Markdown document allows setting Confluence content properties on a page. Confluence content properties are a way to store structured metadata in the form of key-value pairs directly on Confluence content. The values in content properties are represented as JSON objects.
+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.
 
-Some content properties have special meaning to Confluence. For example, the following properties cause Confluence to display a wiki page with content confined to a fixed width in regular view mode, and taking the full page width in draft mode:
+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
 ---
-properties:
-  content-appearance-published: fixed-width
-  content-appearance-draft: full-width
+title: "Collaborating with other teams"
+page_id: "19830101"
+synchronized: false
 ---
-```
 
-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.
+This Markdown document is neither parsed, nor synchronized with Confluence.
+```
 
-### draw\.io diagrams
+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.
 
-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.
+### Excluding content sections
 
-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.
+When maintaining documentation in both Git repositories and Confluence, you may want certain content to appear only in the repository but not on Confluence pages. Use HTML comment markers to wrap and exclude specific sections from synchronization:
 
-### Mermaid diagrams
+```markdown
+# Project Documentation
 
-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:
+This content appears in both Git and Confluence.
 
-* 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`.
+<!-- confluence-skip-start -->
+## Internal References
+- See [internal design doc](../internal/design.md)
+- Related to issue #123
+- Development notes for the team
+<!-- confluence-skip-end -->
 
-*md2conf* offers two options to publish the diagram:
+## Getting Started
+This section is published to Confluence.
+```
 
-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.
+Content between `<!-- confluence-skip-start -->` and `<!-- confluence-skip-end -->` markers is removed before conversion and will not appear on the Confluence page. This is useful for:
 
-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:
+- Repository-specific navigation and cross-references
+- GitLab/GitHub-specific metadata
+- Content relevant only for developers with repository access
 
-```sh
-mmdc -i sample.mmd -o sample.png -b transparent --scale 2
-```
+Multiple exclusion blocks can be used in the same document.
 
-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.
+### Labels
 
-### Alignment
+If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
 
-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.
+```yaml
+---
+title: "Example document"
+tags: ["markdown", "md", "wiki"]
+---
+```
 
-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.
+Any previously assigned labels are discarded. As per Confluence terminology, new labels have the `prefix` of `global`.
 
-### Links to attachments
+If a document has no `tags` attribute, existing Confluence labels are left intact.
 
-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.
+### Content properties
 
-### Implicit URLs
+The front-matter attribute `properties` in a Markdown document allows setting Confluence content properties on a page. Confluence content properties are a way to store structured metadata in the form of key-value pairs directly on Confluence content. The values in content properties are represented as JSON objects.
 
-*md2conf* implicitly defines some URLs, as if you included the following at the start of the Markdown document for each URL:
+Some content properties have special meaning to Confluence. For example, the following properties cause Confluence to display a wiki page with content confined to a fixed width in regular view mode, and taking the full page width in draft mode:
 
-```markdown
-[CUSTOM-URL]: https://example.com/path/to/resource
+```yaml
+---
+properties:
+  content-appearance-published: fixed-width
+  content-appearance-draft: full-width
+---
 ```
 
-Specifically, image references for status labels (e.g. `![My label][STATUS-RED]`) are automatically resolved into internally defined URLs via this mechanism.
+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.
 
 ### Local output
 
@@ -637,7 +690,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.
@@ -657,35 +710,46 @@ options:
                         Use this option to set the log verbosity.
   -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
   --keep-hierarchy      Maintain source directory structure when exporting to Confluence.
-  --flatten-hierarchy   Flatten directories with no index.md or README.md when exporting to Confluence.
+  --skip-hierarchy      Flatten directories with no `index.md` or `README.md` when exporting to Confluence.
   --generated-by MARKDOWN
-                        Add prompt to pages (default: 'This page has been generated with a tool.').
+                        Add prompt to pages.
   --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.)
+  --skip-update         Skip saving Confluence page ID in Markdown files.
+  --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
+  --no-heading-anchors  Omit the extra anchor from section headings. (May break manually placed same-page references.) (default)
+  --force-valid-url     Raise an error when relative URLs point to an invalid location. (default)
+  --no-force-valid-url  Emit a warning but otherwise ignore relative URLs that point to an invalid location.
+  --skip-title-heading  Remove the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).
+  --keep-title-heading  Keep the first heading in document body even when used as page title. (default)
+  --prefer-raster       Prefer PNG over SVG when both exist. (default)
+  --no-prefer-raster    Use SVG files directly instead of preferring PNG equivalents.
+  --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.) (default)
   --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.)
+  --render-mermaid      Render Mermaid diagrams as image files. (Installed utility required to convert.) (default)
   --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.)
+  --render-plantuml     Render PlantUML diagrams as image files. (Installed utility required to convert.) (default)
   --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.)
+  --render-latex        Render LaTeX formulas as image files. (Matplotlib required to convert.) (default)
   --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.
-  --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.
+                        Format for rendering Mermaid and draw.io diagrams. (default: png)
   --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.
+  --no-webui-links      Use hierarchical links including space and page ID. (default)
   --use-panel           Transform admonitions and alerts into a Confluence custom panel.
+  --no-use-panel        Use standard Confluence macro types for admonitions and alerts (info, tip, note and warning). (default)
+  --layout-image-alignment {center,left,right,None}
+                        Alignment for block-level images and formulas.
+  --layout-image-max-width INT
+                        Maximum display width for images [px]. Wider images are scaled down for page display.
+  --layout-table-width INT
+                        Maximum table width in pixels.
+  --layout-table-display-mode {responsive,fixed}
+                        Set table display mode. (default: responsive)
+  --layout-alignment {center,left,right,None}
+                        Default alignment for block-level content.
+  --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
+  --title-prefix TEXT   String to prepend to Confluence page title for each published page.
+  --line-numbers        Inject line numbers in Markdown source to help localize conversion errors.
   --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.
@@ -698,46 +762,49 @@ options:
 ```python
 from md2conf.api import ConfluenceAPI
 from md2conf.environment import ConnectionProperties
-from md2conf.options import ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
+from md2conf.options import ConfluencePageID, ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
 from md2conf.publisher import Publisher
 
 properties = ConnectionProperties(
-    api_url=...,
-    domain=...,
-    base_path=...,
-    user_name=...,
-    api_key=...,
-    space_key=...,
-    headers=...,
+    domain=str() or None,
+    base_path=str() or None,
+    space_key=str() or None,
+    api_url=str() or None,
+    user_name=str() or None,
+    api_key=str(),
+    headers={str(): str()} or None,
 )
 options = DocumentOptions(
-    root_page_id=...,
-    keep_hierarchy=...,
-    title_prefix=...,
-    generated_by=...,
+    root_page_id=ConfluencePageID() or None,
+    keep_hierarchy=bool(),
+    title_prefix=str() or None,
+    generated_by=str() or None,
+    skip_update=bool(),
     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=...,
+        heading_anchors=bool(),
+        force_valid_url=bool(),
+        skip_title_heading=bool(),
+        prefer_raster=bool(),
+        render_drawio=bool(),
+        render_mermaid=bool(),
+        render_plantuml=bool(),
+        render_latex=bool(),
+        diagram_output_format='png' or 'svg',
+        webui_links=bool(),
+        use_panel=bool(),
         layout=LayoutOptions(
             image=ImageLayoutOptions(
-                alignment=...,
-                max_width=...,
+                alignment='center' or 'left' or 'right' or None,
+                max_width=int() or None,
             ),
             table=TableLayoutOptions(
-                width=...,
-                display_mode=...,
+                width=int() or None,
+                display_mode='responsive' or 'fixed',
             ),
+            alignment='center' or 'left' or 'right' or None,
         ),
     ),
+    line_numbers=bool(),
 )
 with ConfluenceAPI(properties) as api:
     Publisher(api, options).process(mdpath)