markdown-to-confluence 0.4.2__tar.gz → 0.4.4__tar.gz

{markdown_to_confluence-0.4.2/markdown_to_confluence.egg-info → markdown_to_confluence-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.4.2
+Version: 0.4.4
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -58,7 +58,7 @@ 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 (with HTML tags `<sub>` and `<sup>`)
-* Math formulas with LaTeX notation [^math]
+* Math formulas with LaTeX notation
 * Emoji
 * Ordered and unordered lists
 * Block quotes
@@ -69,8 +69,10 @@ This Python package
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
 * [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
-* draw\.io diagrams [^drawio]
-* [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images) [^mermaid]
+* [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/) in code blocks (converted to images)
+* 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.
 
@@ -84,9 +86,9 @@ pip install markdown-to-confluence
 
 ### Command-line utilities
 
-**Optional.** Converting `*.drawio` diagrams into PNG or SVG images requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
+**Optional.** Converting `*.drawio` diagrams to PNG or SVG images before uploading to Confluence as attachments requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
 
-**Optional.** Converting code blocks of Mermaid diagrams into PNG or SVG images requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
+**Optional.** Converting code blocks of Mermaid diagrams to PNG or SVG images before uploading to Confluence as attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -98,9 +100,9 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Editable draw\.io diagrams require [draw.io Diagrams marketplace app](https://marketplace.atlassian.com/apps/1210933/draw-io-diagrams-uml-bpmn-aws-erd-flowcharts). (Refer to `--no-render-drawio`.)
 
-**Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering requires a marketplace app. (Refer to `--no-render-mermaid`.)
+**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 requires [LaTeX Math marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations).
+**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/).
 
 ## Getting started
 
@@ -279,7 +281,7 @@ Highlight in <span style="background-color: rgb(198,237,251);">teal</span>, <spa
 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)    |
@@ -340,6 +342,45 @@ $$\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/).
 
+### 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" />
+```
+
+### Confluence widgets
+
+*md2conf* supports some Confluence widgets. If the appropriate code is found when a Markdown document is processed, it is automatically replaced with Confluence Storage Format XML that produces the corresponding widget.
+
+| Markdown code                              | Confluence equivalent                                   |
+| :----------------------------------------- | :------------------------------------------------------ |
+| `![My label][STATUS-GRAY]`                 | gray status label (with specified label text)           |
+| `![My label][STATUS-PURPLE]`               | purple status label                                     |
+| `![My label][STATUS-BLUE]`                 | blue status label                                       |
+| `![My label][STATUS-RED]`                  | red status label                                        |
+| `![My label][STATUS-YELLOW]`               | yellow status label                                     |
+| `![My label][STATUS-GREEN]`                | green status label                                      |
+| `<input type="date" value="YYYY-MM-DD" />` | date widget (with year, month and day set as specified) |
+
+Use the pseudo-language `csf` in a Markdown code block to pass content directly to Confluence. The content must be a single XML node that conforms to Confluence Storage Format (typically an `ac:structured-macro`) but is otherwise not validated. The following example shows how to create a panel similar to an *info panel* but with custom background color and emoji. Notice that `ac:rich-text-body` uses XHTML, not Markdown.
+
+````md
+```csf
+<ac:structured-macro ac:name="panel" ac:schema-version="1">
+  <ac:parameter ac:name="panelIcon">:slight_smile:</ac:parameter>
+  <ac:parameter ac:name="panelIconId">1f642</ac:parameter>
+  <ac:parameter ac:name="panelIconText">&#128578;</ac:parameter>
+  <ac:parameter ac:name="bgColor">#FFF0B3</ac:parameter>
+  <ac:rich-text-body>
+    <p>A <em>custom colored panel</em> with a 🙂 emoji</p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+```
+````
+
 ### Ignoring files
 
 Skip files 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.
@@ -414,7 +455,7 @@ With the command-line option `--render-drawio`, images with embedded draw\.io di
 You can include [Mermaid diagrams](https://mermaid.js.org/) in your Markdown documents to create visual representations of systems, processes, and relationships. When a Markdown document contains a 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 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. This is the approach we use and support.
-2. Display on demand (command-line option `--no-render-mermaid`). The code block is transformed into a [diagram macro](https://atlasauthority.atlassian.net/wiki/spaces/MARKDOWNCLOUD/pages/2946826241/Diagram+Macro), which is processed by Confluence. You need a [marketplace app](https://marketplace.atlassian.com/apps/1211438/markdown-html-plantuml-latex-diagrams-open-api-mermaid) to turn macro definitions into images when a Confluence page is visited.
+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 [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:
 
@@ -424,6 +465,16 @@ mmdc -i sample.mmd -o sample.png -b transparent --scale 2
 
 Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
 
+### Implicit URLs
+
+*md2conf* implicitly defines some URLs, as if you included the following at the start of the Markdown document for each URL:
+
+```md
+[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`).
@@ -523,7 +574,3 @@ FROM leventehunyadi/md2conf:latest
 
 CMD ["-d", "example.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "SPACE", "./"]
 ```
-
-[^math]: Requires installing Confluence plugin [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
-[^drawio]: Converting draw\.io diagrams to images before uploading to Confluence requires an installation of [draw.io](https://www.drawio.com/). Editable draw\.io diagrams require separate marketplace app.
-[^mermaid]: Converting Mermaid diagrams to images before uploading to Confluence requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). Displaying Mermaid diagrams on the fly requires separate marketplace app.

{markdown_to_confluence-0.4.2 → markdown_to_confluence-0.4.4}/README.md

@@ -16,7 +16,7 @@ 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 (with HTML tags `<sub>` and `<sup>`)
-* Math formulas with LaTeX notation [^math]
+* Math formulas with LaTeX notation
 * Emoji
 * Ordered and unordered lists
 * Block quotes
@@ -27,8 +27,10 @@ This Python package
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
 * [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
-* draw\.io diagrams [^drawio]
-* [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images) [^mermaid]
+* [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/) in code blocks (converted to images)
+* 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.
 
@@ -42,9 +44,9 @@ pip install markdown-to-confluence
 
 ### Command-line utilities
 
-**Optional.** Converting `*.drawio` diagrams into PNG or SVG images requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
+**Optional.** Converting `*.drawio` diagrams to PNG or SVG images before uploading to Confluence as attachments requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
 
-**Optional.** Converting code blocks of Mermaid diagrams into PNG or SVG images requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
+**Optional.** Converting code blocks of Mermaid diagrams to PNG or SVG images before uploading to Confluence as attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -56,9 +58,9 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Editable draw\.io diagrams require [draw.io Diagrams marketplace app](https://marketplace.atlassian.com/apps/1210933/draw-io-diagrams-uml-bpmn-aws-erd-flowcharts). (Refer to `--no-render-drawio`.)
 
-**Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering requires a marketplace app. (Refer to `--no-render-mermaid`.)
+**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 requires [LaTeX Math marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations).
+**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/).
 
 ## Getting started
 
@@ -237,7 +239,7 @@ Highlight in <span style="background-color: rgb(198,237,251);">teal</span>, <spa
 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)    |
@@ -298,6 +300,45 @@ $$\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/).
 
+### 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" />
+```
+
+### Confluence widgets
+
+*md2conf* supports some Confluence widgets. If the appropriate code is found when a Markdown document is processed, it is automatically replaced with Confluence Storage Format XML that produces the corresponding widget.
+
+| Markdown code                              | Confluence equivalent                                   |
+| :----------------------------------------- | :------------------------------------------------------ |
+| `![My label][STATUS-GRAY]`                 | gray status label (with specified label text)           |
+| `![My label][STATUS-PURPLE]`               | purple status label                                     |
+| `![My label][STATUS-BLUE]`                 | blue status label                                       |
+| `![My label][STATUS-RED]`                  | red status label                                        |
+| `![My label][STATUS-YELLOW]`               | yellow status label                                     |
+| `![My label][STATUS-GREEN]`                | green status label                                      |
+| `<input type="date" value="YYYY-MM-DD" />` | date widget (with year, month and day set as specified) |
+
+Use the pseudo-language `csf` in a Markdown code block to pass content directly to Confluence. The content must be a single XML node that conforms to Confluence Storage Format (typically an `ac:structured-macro`) but is otherwise not validated. The following example shows how to create a panel similar to an *info panel* but with custom background color and emoji. Notice that `ac:rich-text-body` uses XHTML, not Markdown.
+
+````md
+```csf
+<ac:structured-macro ac:name="panel" ac:schema-version="1">
+  <ac:parameter ac:name="panelIcon">:slight_smile:</ac:parameter>
+  <ac:parameter ac:name="panelIconId">1f642</ac:parameter>
+  <ac:parameter ac:name="panelIconText">&#128578;</ac:parameter>
+  <ac:parameter ac:name="bgColor">#FFF0B3</ac:parameter>
+  <ac:rich-text-body>
+    <p>A <em>custom colored panel</em> with a 🙂 emoji</p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+```
+````
+
 ### Ignoring files
 
 Skip files 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.
@@ -372,7 +413,7 @@ With the command-line option `--render-drawio`, images with embedded draw\.io di
 You can include [Mermaid diagrams](https://mermaid.js.org/) in your Markdown documents to create visual representations of systems, processes, and relationships. When a Markdown document contains a 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 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. This is the approach we use and support.
-2. Display on demand (command-line option `--no-render-mermaid`). The code block is transformed into a [diagram macro](https://atlasauthority.atlassian.net/wiki/spaces/MARKDOWNCLOUD/pages/2946826241/Diagram+Macro), which is processed by Confluence. You need a [marketplace app](https://marketplace.atlassian.com/apps/1211438/markdown-html-plantuml-latex-diagrams-open-api-mermaid) to turn macro definitions into images when a Confluence page is visited.
+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 [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:
 
@@ -382,6 +423,16 @@ mmdc -i sample.mmd -o sample.png -b transparent --scale 2
 
 Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
 
+### Implicit URLs
+
+*md2conf* implicitly defines some URLs, as if you included the following at the start of the Markdown document for each URL:
+
+```md
+[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`).
@@ -481,7 +532,3 @@ FROM leventehunyadi/md2conf:latest
 
 CMD ["-d", "example.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "SPACE", "./"]
 ```
-
-[^math]: Requires installing Confluence plugin [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
-[^drawio]: Converting draw\.io diagrams to images before uploading to Confluence requires an installation of [draw.io](https://www.drawio.com/). Editable draw\.io diagrams require separate marketplace app.
-[^mermaid]: Converting Mermaid diagrams to images before uploading to Confluence requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). Displaying Mermaid diagrams on the fly requires separate marketplace app.

{markdown_to_confluence-0.4.2 → markdown_to_confluence-0.4.4/markdown_to_confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.4.2
+Version: 0.4.4
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -58,7 +58,7 @@ 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 (with HTML tags `<sub>` and `<sup>`)
-* Math formulas with LaTeX notation [^math]
+* Math formulas with LaTeX notation
 * Emoji
 * Ordered and unordered lists
 * Block quotes
@@ -69,8 +69,10 @@ This Python package
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
 * [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
-* draw\.io diagrams [^drawio]
-* [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images) [^mermaid]
+* [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/) in code blocks (converted to images)
+* 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.
 
@@ -84,9 +86,9 @@ pip install markdown-to-confluence
 
 ### Command-line utilities
 
-**Optional.** Converting `*.drawio` diagrams into PNG or SVG images requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
+**Optional.** Converting `*.drawio` diagrams to PNG or SVG images before uploading to Confluence as attachments requires installing [draw.io](https://www.drawio.com/). (Refer to `--render-drawio`.)
 
-**Optional.** Converting code blocks of Mermaid diagrams into PNG or SVG images requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
+**Optional.** Converting code blocks of Mermaid diagrams to PNG or SVG images before uploading to Confluence as attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). (Refer to `--render-mermaid`.)
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -98,9 +100,9 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Editable draw\.io diagrams require [draw.io Diagrams marketplace app](https://marketplace.atlassian.com/apps/1210933/draw-io-diagrams-uml-bpmn-aws-erd-flowcharts). (Refer to `--no-render-drawio`.)
 
-**Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering requires a marketplace app. (Refer to `--no-render-mermaid`.)
+**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 requires [LaTeX Math marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations).
+**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/).
 
 ## Getting started
 
@@ -279,7 +281,7 @@ Highlight in <span style="background-color: rgb(198,237,251);">teal</span>, <spa
 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)    |
@@ -340,6 +342,45 @@ $$\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/).
 
+### 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" />
+```
+
+### Confluence widgets
+
+*md2conf* supports some Confluence widgets. If the appropriate code is found when a Markdown document is processed, it is automatically replaced with Confluence Storage Format XML that produces the corresponding widget.
+
+| Markdown code                              | Confluence equivalent                                   |
+| :----------------------------------------- | :------------------------------------------------------ |
+| `![My label][STATUS-GRAY]`                 | gray status label (with specified label text)           |
+| `![My label][STATUS-PURPLE]`               | purple status label                                     |
+| `![My label][STATUS-BLUE]`                 | blue status label                                       |
+| `![My label][STATUS-RED]`                  | red status label                                        |
+| `![My label][STATUS-YELLOW]`               | yellow status label                                     |
+| `![My label][STATUS-GREEN]`                | green status label                                      |
+| `<input type="date" value="YYYY-MM-DD" />` | date widget (with year, month and day set as specified) |
+
+Use the pseudo-language `csf` in a Markdown code block to pass content directly to Confluence. The content must be a single XML node that conforms to Confluence Storage Format (typically an `ac:structured-macro`) but is otherwise not validated. The following example shows how to create a panel similar to an *info panel* but with custom background color and emoji. Notice that `ac:rich-text-body` uses XHTML, not Markdown.
+
+````md
+```csf
+<ac:structured-macro ac:name="panel" ac:schema-version="1">
+  <ac:parameter ac:name="panelIcon">:slight_smile:</ac:parameter>
+  <ac:parameter ac:name="panelIconId">1f642</ac:parameter>
+  <ac:parameter ac:name="panelIconText">&#128578;</ac:parameter>
+  <ac:parameter ac:name="bgColor">#FFF0B3</ac:parameter>
+  <ac:rich-text-body>
+    <p>A <em>custom colored panel</em> with a 🙂 emoji</p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+```
+````
+
 ### Ignoring files
 
 Skip files 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.
@@ -414,7 +455,7 @@ With the command-line option `--render-drawio`, images with embedded draw\.io di
 You can include [Mermaid diagrams](https://mermaid.js.org/) in your Markdown documents to create visual representations of systems, processes, and relationships. When a Markdown document contains a 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 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. This is the approach we use and support.
-2. Display on demand (command-line option `--no-render-mermaid`). The code block is transformed into a [diagram macro](https://atlasauthority.atlassian.net/wiki/spaces/MARKDOWNCLOUD/pages/2946826241/Diagram+Macro), which is processed by Confluence. You need a [marketplace app](https://marketplace.atlassian.com/apps/1211438/markdown-html-plantuml-latex-diagrams-open-api-mermaid) to turn macro definitions into images when a Confluence page is visited.
+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 [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:
 
@@ -424,6 +465,16 @@ mmdc -i sample.mmd -o sample.png -b transparent --scale 2
 
 Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
 
+### Implicit URLs
+
+*md2conf* implicitly defines some URLs, as if you included the following at the start of the Markdown document for each URL:
+
+```md
+[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`).
@@ -523,7 +574,3 @@ FROM leventehunyadi/md2conf:latest
 
 CMD ["-d", "example.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "SPACE", "./"]
 ```
-
-[^math]: Requires installing Confluence plugin [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
-[^drawio]: Converting draw\.io diagrams to images before uploading to Confluence requires an installation of [draw.io](https://www.drawio.com/). Editable draw\.io diagrams require separate marketplace app.
-[^mermaid]: Converting Mermaid diagrams to images before uploading to Confluence requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). Displaying Mermaid diagrams on the fly requires separate marketplace app.

{markdown_to_confluence-0.4.2 → markdown_to_confluence-0.4.4}/markdown_to_confluence.egg-info/SOURCES.txt

@@ -16,11 +16,13 @@ md2conf/api.py
 md2conf/application.py
 md2conf/collection.py
 md2conf/converter.py
+md2conf/csf.py
+md2conf/domain.py
 md2conf/drawio.py
-md2conf/emoji.py
 md2conf/entities.dtd
 md2conf/extra.py
 md2conf/local.py
+md2conf/markdown.py
 md2conf/matcher.py
 md2conf/mermaid.py
 md2conf/metadata.py
@@ -29,8 +31,11 @@ md2conf/properties.py
 md2conf/puppeteer-config.json
 md2conf/py.typed
 md2conf/scanner.py
+md2conf/toc.py
+md2conf/uri.py
 md2conf/xml.py
 tests/__init__.py
+tests/emoji.py
 tests/test_conversion.py
 tests/test_drawio.py
 tests/test_matcher.py
@@ -48,11 +53,15 @@ tests/source/fenced.md
 tests/source/footnote.md
 tests/source/ignore.md
 tests/source/images.md
+tests/source/macro.md
 tests/source/math.md
 tests/source/mermaid.md
 tests/source/missing.md
 tests/source/sections.md
+tests/source/status.md
+tests/source/table.md
 tests/source/tags.md
+tests/source/tasklist.md
 tests/source/title.md
 tests/source/figure/diagram.drawio
 tests/source/figure/diagram.drawio.png
@@ -69,9 +78,13 @@ tests/target/collapsed.xml
 tests/target/fenced.xml
 tests/target/footnote.xml
 tests/target/images.xml
+tests/target/macro.xml
 tests/target/math.xml
 tests/target/mermaid.xml
 tests/target/missing.xml
 tests/target/sections.xml
+tests/target/status.xml
+tests/target/table.xml
 tests/target/tags.xml
+tests/target/tasklist.xml
 tests/target/images/images.xml

{markdown_to_confluence-0.4.2 → markdown_to_confluence-0.4.4}/md2conf/__init__.py

@@ -5,7 +5,7 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.4.2"
+__version__ = "0.4.4"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

{markdown_to_confluence-0.4.2 → markdown_to_confluence-0.4.4}/md2conf/__main__.py

@@ -17,14 +17,9 @@ import typing
 from pathlib import Path
 from typing import Any, Iterable, Literal, Optional, Sequence, Union
 
-import requests
-
 from . import __version__
-from .api import ConfluenceAPI
-from .application import Application
-from .converter import ConfluenceDocumentOptions, ConfluencePageID
+from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .extra import override
-from .local import LocalConverter
 from .metadata import ConfluenceSiteMetadata
 from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceSiteProperties
 
@@ -52,7 +47,7 @@ class Arguments(argparse.Namespace):
 
 
 class KwargsAppendAction(argparse.Action):
-    """Append key-value pairs to a dictionary"""
+    """Append key-value pairs to a dictionary."""
 
     @override
     def __call__(
@@ -72,6 +67,30 @@ class KwargsAppendAction(argparse.Action):
         setattr(namespace, self.dest, d)
 
 
+def unsupported(prefer: str) -> type[argparse.Action]:
+    class UnsupportedAction(argparse.Action):
+        """Display an error for unsupported command-line options."""
+
+        @override
+        def __call__(
+            self,
+            parser: argparse.ArgumentParser,
+            namespace: argparse.Namespace,
+            values: Union[None, str, Sequence[Any]],
+            option_string: Optional[str] = None,
+        ) -> None:
+            raise argparse.ArgumentError(
+                self,
+                f"this command-line option is no longer supported, use `--{prefer}`",
+            )
+
+        @override
+        def __repr__(self) -> str:
+            return f"{unsupported.__name__}({repr(prefer)})"
+
+    return UnsupportedAction
+
+
 class PositionalOnlyHelpFormatter(argparse.HelpFormatter):
     def _format_usage(
         self,
@@ -189,12 +208,18 @@ def main() -> None:
         help="Inline Mermaid diagram in Confluence page. (Marketplace app required.)",
     )
     parser.add_argument(
-        "--render-mermaid-format",
+        "--diagram-output-format",
         dest="diagram_output_format",
         choices=["png", "svg"],
         default="png",
         help="Format for rendering Mermaid and draw.io diagrams (default: 'png').",
     )
+    parser.add_argument(
+        "--render-mermaid-format",
+        action=unsupported("diagram-output-format"),
+        metavar="FORMAT",
+        help="Format for rendering Mermaid diagrams (default: 'png').",
+    )
     parser.add_argument(
         "--heading-anchors",
         action="store_true",
@@ -256,6 +281,8 @@ def main() -> None:
         webui_links=args.webui_links,
     )
     if args.local:
+        from .local import LocalConverter
+
         try:
             site_properties = ConfluenceSiteProperties(
                 domain=args.domain,
@@ -271,6 +298,11 @@ def main() -> None:
         )
         LocalConverter(options, site_metadata).process(args.mdpath)
     else:
+        from requests import HTTPError, JSONDecodeError
+
+        from .api import ConfluenceAPI
+        from .application import Application
+
         try:
             properties = ConfluenceConnectionProperties(
                 api_url=args.api_url,
@@ -289,14 +321,14 @@ def main() -> None:
                     api,
                     options,
                 ).process(args.mdpath)
-        except requests.exceptions.HTTPError as err:
+        except HTTPError as err:
             logging.error(err)
 
             # print details for a response with JSON body
             if err.response is not None:
                 try:
                     logging.error(err.response.json())
-                except requests.exceptions.JSONDecodeError:
+                except JSONDecodeError:
                     pass
 
             sys.exit(1)

{markdown_to_confluence-0.4.2 → markdown_to_confluence-0.4.4}/md2conf/api.py

@@ -27,6 +27,8 @@ from .properties import ArgumentError, ConfluenceConnectionProperties, Confluenc
 
 T = TypeVar("T")
 
+mimetypes.add_type("text/vnd.mermaid", ".mmd", strict=True)
+
 
 def _json_to_object(
     typ: type[T],
@@ -642,7 +644,7 @@ class ConfluenceSession:
                     return
             elif raw_data is not None:
                 if not force and attachment.fileSize == len(raw_data):
-                    LOGGER.info("Up-to-date embedded image: %s", attachment_name)
+                    LOGGER.info("Up-to-date embedded file: %s", attachment_name)
                     return
             else:
                 raise NotImplementedError("parameter match not exhaustive")