Publish rich Markdown documentation to Confluence.
Install tovald with pipx install tovald
or run virtualenv uv run tovald
.
Export the following variables :
CONFLUENCE_SERVER_URL
: confluence instance URLCONFLUENCE_SPACE_KEY
: target confluence spaceCONFLUENCE_PARENT_PAGE
(optional): any parent page in a given spaceCONFLUENCE_PAT
: service account personal access tokenCONFLUENCE_SOURCES_URL
(optional): sources repository URL
usage: tovald [-h] [-v] DOCUMENTATION
positional arguments:
DOCUMENTATION
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
In Confluence, documentation is organized using a hierarchical structure of pages and sub-pages.
- Page 1
- Sub-page 1
- Sub-page 2
- Sub-sub-page 1
- Page 2
- Sub-page 3
Similarly, in tovald documentation structure, each page is represented as a folder containing an index.md
file and an optional .assets
folder.
- The
index.md
file holds the content of the page, and the first-level# heading
is used as the page title in the page tree view. - The
.assets
folder contains any static asset required by the given index page.
doc
├── index.md
└── operational-guide
├── .assets
│ └── demo.png
└── index.md
Standard markdown is supported, as well as MyST flavored syntax.
Most Confluence built-in features are also available via confluencebuilder (ie. Jira integration, emoticon, mentions, macros, ...).
Project management is achieved with uv
.
$ uv sync --dev
Install pre-commit hooks.
$ uv run pre-commit install [--install-hooks]
Tovald is just a modest wrapper around various tools: