| Name | mdtocf JSON |
| Version |
1.2.7
JSON |
| download |
| home_page | None |
| Summary | Markdown files/directory publishing to Atlassian Confluence |
| upload_time | 2025-08-06 16:15:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
markdown
confluence
atlassian
publish
mdtocf
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Markdown to Confluence Publisher (mdtocf)
Markdown files/directory publishing to Atlassian Confluence.
## Install from PyPI
https://pypi.org/project/mdtocf/
```bash
# python3 -m venv venv
# source venv/bin/activate
pip install mdtocf
```
## Publish to Confluence
```bash
python3 -m mdtocf.mdtocf --help
###
# Example usage:
# https://olafrv.atlassian.net/wiki/spaces/~5ed387058884020c24da5a42/pages/131089/Test
# - confluenceUsername: your Atlassian account email.
# - confluenceApiToken: see https://id.atlassian.com/manage-profile/security/api-tokens
# - confluenceUrl: your Atlassian Confluence URL, e.g. https://olafrv.atlassian.net
# - confluenceSpace: the target Confluence space ID, e.g. ~5ed387058884020c24da5a42
# - confluenceParentPageId: the target parent page ID, e.g. 131089
###
python3 -m mdtocf.mdtocf \
--confluenceUsername "olafrv@gmail.com" \
--confluenceApiToken "${CONFLUENCE_API_TOKEN}" \
--confluenceUrl "https://olafrv.atlassian.net" \
--confluenceSpace "~5ed387058884020c24da5a42" \
--confluenceParentPageId "131089" \
--confluencePageTitlePrefix "[Test] " \
--markdownDir ./examples \
--db ./examples.db
```
## Console Output
Output:
> **UPD** => Update in Confluence.
> **IDX** => Index page in Confluence.
> **SKP** => Skip update in Confluence.
> **DEL** => Delete page in Confluence.
```bash
# --- Delete ./examples.db file ---
# --- Delete all pages in Confluence space ---
# --- 1st run ---
UPD => Title: [Test] _index.md
IDX => Title: [Test] Folder B
UPD => Title: [Test] bb.md
UPD => Title: [Test] aa.md
UPD Att. => Title: example.png
UPD => Title: [Test] example.md
UPD Att. => Title: example.png
# --- 2nd run (re-run) ---
SKP => Title: [Test] _index.md
SKP => Title: [Test] Folder B
SKP => Title: [Test] bb.md
SKP => Title: [Test] aa.md
DEL Att. => Title: example.png
UPD Att. => Title: example.png
SKP => Title: [Test] example.md
DEL Att. => Title: example.png
UPD Att. => Title: example.png
# --- Delete all sub pages in Confluence space ---
# --- 3nd run ---
SKP => Title: [Test] _index.md
Can't find '[Test] _index.md' page on https://olafrv.atlassian.net/wiki
SKP => Title: [Test] Folder B
Can't find '[Test] Folder B' page on https://olafrv.atlassian.net/wiki
SKP => Title: [Test] bb.md
Can't find '[Test] bb.md' page on https://olafrv.atlassian.net/wiki
SKP => Title: [Test] aa.md
Can't find '[Test] aa.md' page on https://olafrv.atlassian.net/wiki
DEL Att. => Title: example.png
UPD Att. => Title: example.png
SKP => Title: [Test] example.md
Can't find '[Test] example.md' page on https://olafrv.atlassian.net/wiki
DEL Att. => Title: example.png
UPD Att. => Title: example.png
```
The *"Can't find..."* means *"not found but creating..."* (Python Atlassian API).
## Results in Confluence
Rendering and publishing **./examples** produce the following final result in Confluence:
# About Markdown Compatibility
This scripts depends on [Mistune v2 Markdown Parser](https://mistune.readthedocs.io/en/latest/),
compatible with [CommonMark](https://spec.commonmark.org)
The (optional) metadata heading in markdown (.md) files likes the one which
follows below used by [Hugo](https://gohugo.io/getting-started/quick-start/),
it is not part of CommonMarkdown standard, but just a popular way of specify
in YAML markdown metadata usable for external tools.
```yaml
---
title: My Page Title
date: 2019-03-26T08:47:11+01:00
draft: true
chapter: true
kind: index
---
```
It is parsed and partially used by this script to organize the content in
Atlassian Confluence.
# Development
Install from source as local editable package:
```bash
git clone "https://github.com/olafrv/mdtocf.git"
cd mdtocf
python3 -m venv venv
source venv/bin/activate
./release.sh # development and release to PyPI flow
```
# References
## Python v3
* https://docs.python.org/3/
* https://docs.python.org/3/howto/regex.html
* https://packaging.python.org/tutorials/packaging-projects/
* https://pip.pypa.io/en/stable/reference/pip_install/#git
* https://pip.pypa.io/en/latest/reference/pip_install/#requirements-file-format
* https://packaging.python.org/discussions/install-requires-vs-requirements/
## Markdown Utils
* https://spec.commonmark.org
* https://spec.commonmark.org/dingus/
* https://github.com/lepture/mistune
* https://mistune.readthedocs.io/en/latest/
## Confluence and Storage Format (Cloud API)
* https://pypi.org/project/atlassian-python-api/
* https://atlassian-python-api.readthedocs.io/confluence.html
* https://developer.atlassian.com/cloud/confluence/rest/
* https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html
* https://confluence.atlassian.com/doc/macros-139387.html
* https://confluence.atlassian.com/conf59/code-block-macro-792499083.html
* https://confluence.atlassian.com/confkb/how-to-get-confluence-page-id-648380445.html
* https://confluence.atlassian.com/doc/delete-or-restore-a-page-139429.html
Raw data
{
"_id": null,
"home_page": null,
"name": "mdtocf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "markdown, confluence, atlassian, publish, mdtocf",
"author": null,
"author_email": "Olaf Reitmaier Veracierta <olafrv@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ea/a0/8639247c6cca4c73f61a80db2c67510b740233407656c9addb6b5750afbe/mdtocf-1.2.7.tar.gz",
"platform": null,
"description": "# Markdown to Confluence Publisher (mdtocf)\n\nMarkdown files/directory publishing to Atlassian Confluence.\n\n## Install from PyPI\n\nhttps://pypi.org/project/mdtocf/\n\n```bash\n# python3 -m venv venv\n# source venv/bin/activate\npip install mdtocf\n```\n\n## Publish to Confluence\n\n```bash\npython3 -m mdtocf.mdtocf --help\n###\n# Example usage:\n# https://olafrv.atlassian.net/wiki/spaces/~5ed387058884020c24da5a42/pages/131089/Test\n# - confluenceUsername: your Atlassian account email.\n# - confluenceApiToken: see https://id.atlassian.com/manage-profile/security/api-tokens\n# - confluenceUrl: your Atlassian Confluence URL, e.g. https://olafrv.atlassian.net\n# - confluenceSpace: the target Confluence space ID, e.g. ~5ed387058884020c24da5a42\n# - confluenceParentPageId: the target parent page ID, e.g. 131089\n###\npython3 -m mdtocf.mdtocf \\\n --confluenceUsername \"olafrv@gmail.com\" \\\n --confluenceApiToken \"${CONFLUENCE_API_TOKEN}\" \\\n --confluenceUrl \"https://olafrv.atlassian.net\" \\\n --confluenceSpace \"~5ed387058884020c24da5a42\" \\\n --confluenceParentPageId \"131089\" \\\n --confluencePageTitlePrefix \"[Test] \" \\\n --markdownDir ./examples \\\n --db ./examples.db\n```\n\n## Console Output\n\nOutput:\n\n> **UPD** => Update in Confluence.\n> **IDX** => Index page in Confluence.\n> **SKP** => Skip update in Confluence.\n> **DEL** => Delete page in Confluence.\n\n```bash\n# --- Delete ./examples.db file ---\n# --- Delete all pages in Confluence space ---\n# --- 1st run ---\nUPD => Title: [Test] _index.md\nIDX => Title: [Test] Folder B\nUPD => Title: [Test] bb.md\nUPD => Title: [Test] aa.md\nUPD Att. => Title: example.png\nUPD => Title: [Test] example.md\nUPD Att. => Title: example.png\n# --- 2nd run (re-run) ---\nSKP => Title: [Test] _index.md\nSKP => Title: [Test] Folder B\nSKP => Title: [Test] bb.md\nSKP => Title: [Test] aa.md\nDEL Att. => Title: example.png\nUPD Att. => Title: example.png\nSKP => Title: [Test] example.md\nDEL Att. => Title: example.png\nUPD Att. => Title: example.png\n# --- Delete all sub pages in Confluence space ---\n# --- 3nd run ---\nSKP => Title: [Test] _index.md\nCan't find '[Test] _index.md' page on https://olafrv.atlassian.net/wiki\nSKP => Title: [Test] Folder B\nCan't find '[Test] Folder B' page on https://olafrv.atlassian.net/wiki\nSKP => Title: [Test] bb.md\nCan't find '[Test] bb.md' page on https://olafrv.atlassian.net/wiki\nSKP => Title: [Test] aa.md\nCan't find '[Test] aa.md' page on https://olafrv.atlassian.net/wiki\nDEL Att. => Title: example.png\nUPD Att. => Title: example.png\nSKP => Title: [Test] example.md\nCan't find '[Test] example.md' page on https://olafrv.atlassian.net/wiki\nDEL Att. => Title: example.png\nUPD Att. => Title: example.png\n```\nThe *\"Can't find...\"* means *\"not found but creating...\"* (Python Atlassian API).\n\n## Results in Confluence\n\nRendering and publishing **./examples** produce the following final result in Confluence:\n\n\n\n\n\n# About Markdown Compatibility\n\nThis scripts depends on [Mistune v2 Markdown Parser](https://mistune.readthedocs.io/en/latest/),\ncompatible with [CommonMark](https://spec.commonmark.org)\n\nThe (optional) metadata heading in markdown (.md) files likes the one which \nfollows below used by [Hugo](https://gohugo.io/getting-started/quick-start/), \nit is not part of CommonMarkdown standard, but just a popular way of specify \nin YAML markdown metadata usable for external tools.\n\n```yaml\n---\ntitle: My Page Title\ndate: 2019-03-26T08:47:11+01:00\ndraft: true\nchapter: true\nkind: index\n---\n```\n\nIt is parsed and partially used by this script to organize the content in\nAtlassian Confluence.\n\n# Development\n\nInstall from source as local editable package:\n\n```bash\ngit clone \"https://github.com/olafrv/mdtocf.git\"\ncd mdtocf\npython3 -m venv venv\nsource venv/bin/activate\n./release.sh # development and release to PyPI flow\n```\n\n# References\n\n## Python v3\n\n* https://docs.python.org/3/\n* https://docs.python.org/3/howto/regex.html\n* https://packaging.python.org/tutorials/packaging-projects/\n* https://pip.pypa.io/en/stable/reference/pip_install/#git\n* https://pip.pypa.io/en/latest/reference/pip_install/#requirements-file-format\n* https://packaging.python.org/discussions/install-requires-vs-requirements/\n\n## Markdown Utils\n\n* https://spec.commonmark.org\n* https://spec.commonmark.org/dingus/\n* https://github.com/lepture/mistune\n* https://mistune.readthedocs.io/en/latest/\n\n## Confluence and Storage Format (Cloud API)\n\n* https://pypi.org/project/atlassian-python-api/\n* https://atlassian-python-api.readthedocs.io/confluence.html\n* https://developer.atlassian.com/cloud/confluence/rest/\n* https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html\n* https://confluence.atlassian.com/doc/macros-139387.html\n* https://confluence.atlassian.com/conf59/code-block-macro-792499083.html\n* https://confluence.atlassian.com/confkb/how-to-get-confluence-page-id-648380445.html\n* https://confluence.atlassian.com/doc/delete-or-restore-a-page-139429.html\n",
"bugtrack_url": null,
"license": null,
"summary": "Markdown files/directory publishing to Atlassian Confluence",
"version": "1.2.7",
"project_urls": {
"Homepage": "https://github.com/olafrv/mdtocf",
"Issues": "https://github.com/olafrv/mdtocf/issues",
"Repository": "https://github.com/olafrv/mdtocf"
},
"split_keywords": [
"markdown",
" confluence",
" atlassian",
" publish",
" mdtocf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ab9a9bc7657b1cab2fa0f6a6e34b7a2b55bd6fd0c298d3ae62685fbe717bbea5",
"md5": "b14fb05acf959accccb53a8ca5ed553f",
"sha256": "2d42cb67906b382cd26ea866c8cda8d44417e4e95313ecba952594ebce2fb6d6"
},
"downloads": -1,
"filename": "mdtocf-1.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b14fb05acf959accccb53a8ca5ed553f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 9740,
"upload_time": "2025-08-06T16:15:27",
"upload_time_iso_8601": "2025-08-06T16:15:27.334761Z",
"url": "https://files.pythonhosted.org/packages/ab/9a/9bc7657b1cab2fa0f6a6e34b7a2b55bd6fd0c298d3ae62685fbe717bbea5/mdtocf-1.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eaa08639247c6cca4c73f61a80db2c67510b740233407656c9addb6b5750afbe",
"md5": "53f55d028f4391a01fe04da07a266abb",
"sha256": "ab2aeda70d33ab99c3c424c7e22bcd9a9fd22c6a8f49f3e7ab993c7808f30a7f"
},
"downloads": -1,
"filename": "mdtocf-1.2.7.tar.gz",
"has_sig": false,
"md5_digest": "53f55d028f4391a01fe04da07a266abb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 11119,
"upload_time": "2025-08-06T16:15:28",
"upload_time_iso_8601": "2025-08-06T16:15:28.260377Z",
"url": "https://files.pythonhosted.org/packages/ea/a0/8639247c6cca4c73f61a80db2c67510b740233407656c9addb6b5750afbe/mdtocf-1.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 16:15:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "olafrv",
"github_project": "mdtocf",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mdtocf"
}
