Tovald

Publish rich Markdown documentation to Confluence.

usage (alpha)

Install tovald with pipx install tovald or run virtualenv uv run tovald.

Export the following variables :

• CONFLUENCE_SERVER_URL: confluence instance URL
• CONFLUENCE_SPACE_KEY: target confluence space
• CONFLUENCE_PARENT_PAGE (optional): any parent page in a given space
• CONFLUENCE_PAT: service account personal access token
• CONFLUENCE_SOURCES_URL (optional): sources repository URL
• CONFLUENCE_PUBLISH_PREFIX (optional): add page publication prefix

usage: tovald [-h] [-v] [-c] DOCUMENTATION

positional arguments:
  DOCUMENTATION

options:
  -h, --help     show this help message and exit
  -v, --version  show program's version number and exit
  -c, --cleanup

Documentation structure

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

Editorial guide

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, ...).

Contribution

Project management is achieved with uv.

$ uv sync --dev

Install pre-commit hooks.

$ uv run pre-commit install [--install-hooks]

Credits

Tovald is just a modest wrapper around various tools:

• sphinx-doc/sphinx
• sphinx-contrib/confluencebuilder
• executablebooks/MyST-Parser