markdown-to-confluence 0.4.7__tar.gz → 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/PKG-INFO +30 -17
- markdown_to_confluence-0.4.7/markdown_to_confluence.egg-info/PKG-INFO → markdown_to_confluence-0.5.0/README.md +17 -49
- markdown_to_confluence-0.4.7/README.md → markdown_to_confluence-0.5.0/markdown_to_confluence.egg-info/PKG-INFO +62 -3
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/markdown_to_confluence.egg-info/SOURCES.txt +1 -0
- markdown_to_confluence-0.5.0/markdown_to_confluence.egg-info/requires.txt +22 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/__init__.py +1 -1
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/__main__.py +13 -13
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/api.py +55 -71
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/collection.py +2 -2
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/converter.py +43 -35
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/domain.py +3 -3
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/drawio.py +1 -1
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/environment.py +22 -22
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/latex.py +9 -9
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/local.py +5 -6
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/markdown.py +7 -7
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/matcher.py +5 -5
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/mermaid.py +3 -3
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/metadata.py +1 -2
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/processor.py +12 -12
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/publisher.py +1 -2
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/scanner.py +33 -41
- markdown_to_confluence-0.5.0/md2conf/serializer.py +52 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/toc.py +2 -3
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/xml.py +4 -6
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/pyproject.toml +12 -13
- markdown_to_confluence-0.5.0/tests/source/tasklist.md +19 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/panel.xml +11 -11
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/tasklist.xml +12 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_matcher.py +1 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_mermaid.py +4 -25
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_scanner.py +2 -2
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_xml.py +5 -5
- markdown_to_confluence-0.5.0/tests/utility.py +44 -0
- markdown_to_confluence-0.4.7/markdown_to_confluence.egg-info/requires.txt +0 -29
- markdown_to_confluence-0.4.7/tests/source/tasklist.md +0 -6
- markdown_to_confluence-0.4.7/tests/utility.py +0 -41
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/LICENSE +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/MANIFEST.in +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/markdown_to_confluence.egg-info/dependency_links.txt +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/markdown_to_confluence.egg-info/entry_points.txt +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/markdown_to_confluence.egg-info/top_level.txt +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/markdown_to_confluence.egg-info/zip-safe +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/csf.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/emoticon.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/entities.dtd +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/extra.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/puppeteer-config.json +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/py.typed +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/text.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/md2conf/uri.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/setup.cfg +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/setup.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/__init__.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/emoji.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/admonition.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/alert.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/alignment.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/anchors.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/basic.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/code.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/collapsed.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/fenced.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/figure/diagram.drawio +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/figure/diagram.drawio.png +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/figure/diagram.drawio.svg +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/figure/raster.png +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/figure/vector.svg +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/footnote.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/ignore.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/images/images.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/images.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/macro.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/math.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/mermaid.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/missing.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/sections.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/status.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/table.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/tags.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/title.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/source/toc.md +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/admonition.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/alert.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/alignment.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/anchors.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/basic.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/code.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/collapsed.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/fenced.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/footnote.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/images/images.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/images.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/macro.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/math.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/mermaid.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/missing.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/sections.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/status.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/table.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/tags.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/target/toc.xml +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_conversion.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_drawio.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_processor.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_text.py +0 -0
- {markdown_to_confluence-0.4.7 → markdown_to_confluence-0.5.0}/tests/test_unit.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: markdown-to-confluence
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Publish Markdown files to Confluence wiki
|
|
5
5
|
Author-email: Levente Hunyadi <hunyadi@gmail.com>
|
|
6
6
|
Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
|
|
@@ -13,33 +13,32 @@ Classifier: Environment :: Console
|
|
|
13
13
|
Classifier: Intended Audience :: End Users/Desktop
|
|
14
14
|
Classifier: Operating System :: OS Independent
|
|
15
15
|
Classifier: Programming Language :: Python :: 3
|
|
16
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
17
16
|
Classifier: Programming Language :: Python :: 3.10
|
|
18
17
|
Classifier: Programming Language :: Python :: 3.11
|
|
19
18
|
Classifier: Programming Language :: Python :: 3.12
|
|
20
19
|
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
21
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
22
|
Classifier: Typing :: Typed
|
|
23
|
-
Requires-Python: >=3.
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
24
|
Description-Content-Type: text/markdown
|
|
25
25
|
License-File: LICENSE
|
|
26
|
-
Requires-Dist:
|
|
27
|
-
Requires-Dist: json_strong_typing>=0.4
|
|
26
|
+
Requires-Dist: cattrs>=25.3
|
|
28
27
|
Requires-Dist: lxml>=6.0
|
|
29
|
-
Requires-Dist: markdown>=3.
|
|
30
|
-
Requires-Dist: pymdown-extensions>=10.
|
|
28
|
+
Requires-Dist: markdown>=3.10
|
|
29
|
+
Requires-Dist: pymdown-extensions>=10.17
|
|
31
30
|
Requires-Dist: PyYAML>=6.0
|
|
32
31
|
Requires-Dist: requests>=2.32
|
|
33
|
-
Requires-Dist: truststore>=0.10
|
|
34
|
-
Requires-Dist: typing-extensions>=4.
|
|
32
|
+
Requires-Dist: truststore>=0.10
|
|
33
|
+
Requires-Dist: typing-extensions>=4.15; python_version < "3.12"
|
|
35
34
|
Provides-Extra: dev
|
|
36
|
-
Requires-Dist: markdown_doc>=0.1.
|
|
37
|
-
Requires-Dist: types-lxml>=2025.
|
|
38
|
-
Requires-Dist: types-markdown>=3.
|
|
35
|
+
Requires-Dist: markdown_doc>=0.1.5; extra == "dev"
|
|
36
|
+
Requires-Dist: types-lxml>=2025.8.25; extra == "dev"
|
|
37
|
+
Requires-Dist: types-markdown>=3.10; extra == "dev"
|
|
39
38
|
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
|
|
40
39
|
Requires-Dist: types-requests>=2.32; extra == "dev"
|
|
41
|
-
Requires-Dist: mypy>=1.
|
|
42
|
-
Requires-Dist: ruff>=0.
|
|
40
|
+
Requires-Dist: mypy>=1.18; extra == "dev"
|
|
41
|
+
Requires-Dist: ruff>=0.14; extra == "dev"
|
|
43
42
|
Provides-Extra: formulas
|
|
44
43
|
Requires-Dist: matplotlib>=3.9; extra == "formulas"
|
|
45
44
|
Dynamic: license-file
|
|
@@ -425,9 +424,9 @@ Use the pseudo-language `csf` in a Markdown code block to pass content directly
|
|
|
425
424
|
|
|
426
425
|
### Ignoring files
|
|
427
426
|
|
|
428
|
-
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.
|
|
427
|
+
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.
|
|
429
428
|
|
|
430
|
-
Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
|
|
429
|
+
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 `/`.
|
|
431
430
|
|
|
432
431
|
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.
|
|
433
432
|
|
|
@@ -501,7 +500,7 @@ You can add [Mermaid diagrams](https://mermaid.js.org/) to your Markdown documen
|
|
|
501
500
|
|
|
502
501
|
*md2conf* offers two options to publish the diagram:
|
|
503
502
|
|
|
504
|
-
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.
|
|
503
|
+
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.
|
|
505
504
|
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.
|
|
506
505
|
|
|
507
506
|
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:
|
|
@@ -512,6 +511,14 @@ mmdc -i sample.mmd -o sample.png -b transparent --scale 2
|
|
|
512
511
|
|
|
513
512
|
Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
|
|
514
513
|
|
|
514
|
+
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.
|
|
515
|
+
|
|
516
|
+
### Alignment
|
|
517
|
+
|
|
518
|
+
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.
|
|
519
|
+
|
|
520
|
+
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.
|
|
521
|
+
|
|
515
522
|
### Links to attachments
|
|
516
523
|
|
|
517
524
|
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.
|
|
@@ -586,6 +593,12 @@ options:
|
|
|
586
593
|
--use-panel Transform admonitions and alerts into a Confluence custom panel.
|
|
587
594
|
```
|
|
588
595
|
|
|
596
|
+
### Confluence REST API v1 vs. v2
|
|
597
|
+
|
|
598
|
+
*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.
|
|
599
|
+
|
|
600
|
+
If you are restricted to an environment with Confluence REST API v1, we recommend *md2conf* [version 0.2.7](https://pypi.org/project/markdown-to-confluence/0.2.7/). Even though we don't actively support it, we are not aware of any major issues, making it a viable option in an on-premise environment with only Confluence REST API v1 support.
|
|
601
|
+
|
|
589
602
|
### Using the Docker container
|
|
590
603
|
|
|
591
604
|
You can run the Docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options. The final argument `./` corresponds to `mdpath` in the command-line utility.
|
|
@@ -1,49 +1,3 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: markdown-to-confluence
|
|
3
|
-
Version: 0.4.7
|
|
4
|
-
Summary: Publish Markdown files to Confluence wiki
|
|
5
|
-
Author-email: Levente Hunyadi <hunyadi@gmail.com>
|
|
6
|
-
Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
|
|
7
|
-
License-Expression: MIT
|
|
8
|
-
Project-URL: Homepage, https://github.com/hunyadi/md2conf
|
|
9
|
-
Project-URL: Source, https://github.com/hunyadi/md2conf
|
|
10
|
-
Keywords: markdown,converter,confluence
|
|
11
|
-
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
-
Classifier: Environment :: Console
|
|
13
|
-
Classifier: Intended Audience :: End Users/Desktop
|
|
14
|
-
Classifier: Operating System :: OS Independent
|
|
15
|
-
Classifier: Programming Language :: Python :: 3
|
|
16
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
-
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
-
Classifier: Typing :: Typed
|
|
23
|
-
Requires-Python: >=3.9
|
|
24
|
-
Description-Content-Type: text/markdown
|
|
25
|
-
License-File: LICENSE
|
|
26
|
-
Requires-Dist: certifi>=2025.8.3; python_version < "3.10"
|
|
27
|
-
Requires-Dist: json_strong_typing>=0.4
|
|
28
|
-
Requires-Dist: lxml>=6.0
|
|
29
|
-
Requires-Dist: markdown>=3.8
|
|
30
|
-
Requires-Dist: pymdown-extensions>=10.16
|
|
31
|
-
Requires-Dist: PyYAML>=6.0
|
|
32
|
-
Requires-Dist: requests>=2.32
|
|
33
|
-
Requires-Dist: truststore>=0.10; python_version >= "3.10"
|
|
34
|
-
Requires-Dist: typing-extensions>=4.14; python_version < "3.12"
|
|
35
|
-
Provides-Extra: dev
|
|
36
|
-
Requires-Dist: markdown_doc>=0.1.4; python_version >= "3.10" and extra == "dev"
|
|
37
|
-
Requires-Dist: types-lxml>=2025.3.30; extra == "dev"
|
|
38
|
-
Requires-Dist: types-markdown>=3.8; extra == "dev"
|
|
39
|
-
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
|
|
40
|
-
Requires-Dist: types-requests>=2.32; extra == "dev"
|
|
41
|
-
Requires-Dist: mypy>=1.16; extra == "dev"
|
|
42
|
-
Requires-Dist: ruff>=0.12; extra == "dev"
|
|
43
|
-
Provides-Extra: formulas
|
|
44
|
-
Requires-Dist: matplotlib>=3.9; extra == "formulas"
|
|
45
|
-
Dynamic: license-file
|
|
46
|
-
|
|
47
1
|
# Publish Markdown files to Confluence wiki
|
|
48
2
|
|
|
49
3
|
Contributors to software projects typically write documentation in Markdown format and host Markdown files in collaborative version control systems (VCS) such as GitHub or GitLab to track changes and facilitate the review process. However, not everyone at a company has access to VCS, and documents are often circulated in Confluence wiki instead.
|
|
@@ -425,9 +379,9 @@ Use the pseudo-language `csf` in a Markdown code block to pass content directly
|
|
|
425
379
|
|
|
426
380
|
### Ignoring files
|
|
427
381
|
|
|
428
|
-
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.
|
|
382
|
+
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.
|
|
429
383
|
|
|
430
|
-
Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
|
|
384
|
+
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 `/`.
|
|
431
385
|
|
|
432
386
|
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.
|
|
433
387
|
|
|
@@ -501,7 +455,7 @@ You can add [Mermaid diagrams](https://mermaid.js.org/) to your Markdown documen
|
|
|
501
455
|
|
|
502
456
|
*md2conf* offers two options to publish the diagram:
|
|
503
457
|
|
|
504
|
-
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.
|
|
458
|
+
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.
|
|
505
459
|
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.
|
|
506
460
|
|
|
507
461
|
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:
|
|
@@ -512,6 +466,14 @@ mmdc -i sample.mmd -o sample.png -b transparent --scale 2
|
|
|
512
466
|
|
|
513
467
|
Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
|
|
514
468
|
|
|
469
|
+
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.
|
|
470
|
+
|
|
471
|
+
### Alignment
|
|
472
|
+
|
|
473
|
+
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.
|
|
474
|
+
|
|
475
|
+
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.
|
|
476
|
+
|
|
515
477
|
### Links to attachments
|
|
516
478
|
|
|
517
479
|
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.
|
|
@@ -586,6 +548,12 @@ options:
|
|
|
586
548
|
--use-panel Transform admonitions and alerts into a Confluence custom panel.
|
|
587
549
|
```
|
|
588
550
|
|
|
551
|
+
### Confluence REST API v1 vs. v2
|
|
552
|
+
|
|
553
|
+
*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.
|
|
554
|
+
|
|
555
|
+
If you are restricted to an environment with Confluence REST API v1, we recommend *md2conf* [version 0.2.7](https://pypi.org/project/markdown-to-confluence/0.2.7/). Even though we don't actively support it, we are not aware of any major issues, making it a viable option in an on-premise environment with only Confluence REST API v1 support.
|
|
556
|
+
|
|
589
557
|
### Using the Docker container
|
|
590
558
|
|
|
591
559
|
You can run the Docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options. The final argument `./` corresponds to `mdpath` in the command-line utility.
|
|
@@ -1,3 +1,48 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: markdown-to-confluence
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Publish Markdown files to Confluence wiki
|
|
5
|
+
Author-email: Levente Hunyadi <hunyadi@gmail.com>
|
|
6
|
+
Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/hunyadi/md2conf
|
|
9
|
+
Project-URL: Source, https://github.com/hunyadi/md2conf
|
|
10
|
+
Keywords: markdown,converter,confluence
|
|
11
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: cattrs>=25.3
|
|
27
|
+
Requires-Dist: lxml>=6.0
|
|
28
|
+
Requires-Dist: markdown>=3.10
|
|
29
|
+
Requires-Dist: pymdown-extensions>=10.17
|
|
30
|
+
Requires-Dist: PyYAML>=6.0
|
|
31
|
+
Requires-Dist: requests>=2.32
|
|
32
|
+
Requires-Dist: truststore>=0.10
|
|
33
|
+
Requires-Dist: typing-extensions>=4.15; python_version < "3.12"
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: markdown_doc>=0.1.5; extra == "dev"
|
|
36
|
+
Requires-Dist: types-lxml>=2025.8.25; extra == "dev"
|
|
37
|
+
Requires-Dist: types-markdown>=3.10; extra == "dev"
|
|
38
|
+
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
|
|
39
|
+
Requires-Dist: types-requests>=2.32; extra == "dev"
|
|
40
|
+
Requires-Dist: mypy>=1.18; extra == "dev"
|
|
41
|
+
Requires-Dist: ruff>=0.14; extra == "dev"
|
|
42
|
+
Provides-Extra: formulas
|
|
43
|
+
Requires-Dist: matplotlib>=3.9; extra == "formulas"
|
|
44
|
+
Dynamic: license-file
|
|
45
|
+
|
|
1
46
|
# Publish Markdown files to Confluence wiki
|
|
2
47
|
|
|
3
48
|
Contributors to software projects typically write documentation in Markdown format and host Markdown files in collaborative version control systems (VCS) such as GitHub or GitLab to track changes and facilitate the review process. However, not everyone at a company has access to VCS, and documents are often circulated in Confluence wiki instead.
|
|
@@ -379,9 +424,9 @@ Use the pseudo-language `csf` in a Markdown code block to pass content directly
|
|
|
379
424
|
|
|
380
425
|
### Ignoring files
|
|
381
426
|
|
|
382
|
-
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.
|
|
427
|
+
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.
|
|
383
428
|
|
|
384
|
-
Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
|
|
429
|
+
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 `/`.
|
|
385
430
|
|
|
386
431
|
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.
|
|
387
432
|
|
|
@@ -455,7 +500,7 @@ You can add [Mermaid diagrams](https://mermaid.js.org/) to your Markdown documen
|
|
|
455
500
|
|
|
456
501
|
*md2conf* offers two options to publish the diagram:
|
|
457
502
|
|
|
458
|
-
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.
|
|
503
|
+
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.
|
|
459
504
|
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.
|
|
460
505
|
|
|
461
506
|
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:
|
|
@@ -466,6 +511,14 @@ mmdc -i sample.mmd -o sample.png -b transparent --scale 2
|
|
|
466
511
|
|
|
467
512
|
Ensure that `mermaid-cli` is set up, refer to *Installation* for instructions.
|
|
468
513
|
|
|
514
|
+
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.
|
|
515
|
+
|
|
516
|
+
### Alignment
|
|
517
|
+
|
|
518
|
+
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.
|
|
519
|
+
|
|
520
|
+
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.
|
|
521
|
+
|
|
469
522
|
### Links to attachments
|
|
470
523
|
|
|
471
524
|
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.
|
|
@@ -540,6 +593,12 @@ options:
|
|
|
540
593
|
--use-panel Transform admonitions and alerts into a Confluence custom panel.
|
|
541
594
|
```
|
|
542
595
|
|
|
596
|
+
### Confluence REST API v1 vs. v2
|
|
597
|
+
|
|
598
|
+
*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.
|
|
599
|
+
|
|
600
|
+
If you are restricted to an environment with Confluence REST API v1, we recommend *md2conf* [version 0.2.7](https://pypi.org/project/markdown-to-confluence/0.2.7/). Even though we don't actively support it, we are not aware of any major issues, making it a viable option in an on-premise environment with only Confluence REST API v1 support.
|
|
601
|
+
|
|
543
602
|
### Using the Docker container
|
|
544
603
|
|
|
545
604
|
You can run the Docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options. The final argument `./` corresponds to `mdpath` in the command-line utility.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
cattrs>=25.3
|
|
2
|
+
lxml>=6.0
|
|
3
|
+
markdown>=3.10
|
|
4
|
+
pymdown-extensions>=10.17
|
|
5
|
+
PyYAML>=6.0
|
|
6
|
+
requests>=2.32
|
|
7
|
+
truststore>=0.10
|
|
8
|
+
|
|
9
|
+
[:python_version < "3.12"]
|
|
10
|
+
typing-extensions>=4.15
|
|
11
|
+
|
|
12
|
+
[dev]
|
|
13
|
+
markdown_doc>=0.1.5
|
|
14
|
+
types-lxml>=2025.8.25
|
|
15
|
+
types-markdown>=3.10
|
|
16
|
+
types-PyYAML>=6.0
|
|
17
|
+
types-requests>=2.32
|
|
18
|
+
mypy>=1.18
|
|
19
|
+
ruff>=0.14
|
|
20
|
+
|
|
21
|
+
[formulas]
|
|
22
|
+
matplotlib>=3.9
|
|
@@ -5,7 +5,7 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
|
|
|
5
5
|
Confluence API endpoints to upload images and content.
|
|
6
6
|
"""
|
|
7
7
|
|
|
8
|
-
__version__ = "0.
|
|
8
|
+
__version__ = "0.5.0"
|
|
9
9
|
__author__ = "Levente Hunyadi"
|
|
10
10
|
__copyright__ = "Copyright 2022-2025, Levente Hunyadi"
|
|
11
11
|
__license__ = "MIT"
|
|
@@ -16,7 +16,7 @@ import sys
|
|
|
16
16
|
import typing
|
|
17
17
|
from io import StringIO
|
|
18
18
|
from pathlib import Path
|
|
19
|
-
from typing import Any, Iterable, Literal,
|
|
19
|
+
from typing import Any, Iterable, Literal, Sequence
|
|
20
20
|
|
|
21
21
|
from . import __version__
|
|
22
22
|
from .domain import ConfluenceDocumentOptions, ConfluencePageID
|
|
@@ -27,18 +27,18 @@ from .metadata import ConfluenceSiteMetadata
|
|
|
27
27
|
|
|
28
28
|
class Arguments(argparse.Namespace):
|
|
29
29
|
mdpath: Path
|
|
30
|
-
domain:
|
|
31
|
-
path:
|
|
32
|
-
api_url:
|
|
33
|
-
username:
|
|
34
|
-
api_key:
|
|
35
|
-
space:
|
|
30
|
+
domain: str | None
|
|
31
|
+
path: str | None
|
|
32
|
+
api_url: str | None
|
|
33
|
+
username: str | None
|
|
34
|
+
api_key: str | None
|
|
35
|
+
space: str | None
|
|
36
36
|
loglevel: str
|
|
37
37
|
ignore_invalid_url: bool
|
|
38
38
|
heading_anchors: bool
|
|
39
|
-
root_page:
|
|
39
|
+
root_page: str | None
|
|
40
40
|
keep_hierarchy: bool
|
|
41
|
-
generated_by:
|
|
41
|
+
generated_by: str | None
|
|
42
42
|
render_drawio: bool
|
|
43
43
|
render_mermaid: bool
|
|
44
44
|
render_latex: bool
|
|
@@ -58,8 +58,8 @@ class KwargsAppendAction(argparse.Action):
|
|
|
58
58
|
self,
|
|
59
59
|
parser: argparse.ArgumentParser,
|
|
60
60
|
namespace: argparse.Namespace,
|
|
61
|
-
values:
|
|
62
|
-
option_string:
|
|
61
|
+
values: str | Sequence[Any] | None,
|
|
62
|
+
option_string: str | None = None,
|
|
63
63
|
) -> None:
|
|
64
64
|
try:
|
|
65
65
|
d = dict(map(lambda x: x.split("="), typing.cast(Sequence[str], values)))
|
|
@@ -74,10 +74,10 @@ class KwargsAppendAction(argparse.Action):
|
|
|
74
74
|
class PositionalOnlyHelpFormatter(argparse.HelpFormatter):
|
|
75
75
|
def _format_usage(
|
|
76
76
|
self,
|
|
77
|
-
usage:
|
|
77
|
+
usage: str | None,
|
|
78
78
|
actions: Iterable[argparse.Action],
|
|
79
79
|
groups: Iterable[argparse._MutuallyExclusiveGroup], # pyright: ignore[reportPrivateUsage]
|
|
80
|
-
prefix:
|
|
80
|
+
prefix: str | None,
|
|
81
81
|
) -> str:
|
|
82
82
|
# filter only positional arguments
|
|
83
83
|
positional_actions = [a for a in actions if not a.option_strings]
|