mkdocs + iolanta

Features

By integrating MkDocs static site builder with Iolanta knowledge management workspace, you can empower your static site with:

Links

Easily link from page to page; check out {{ render("linking-to-pages") }} for more info.

Tables

Visualize tables from YAML data with iolanta-tables plugin.

Roadmaps

Draw roadmaps with iolanta-roadmap plugin.

ADRs

Manage Architecture Decision Records with iolanta-adr.

Something missing?

Or anything doesn't work? — submit an issue!

Installation

Python ⩾ 3.10 required.

mkdocs-iolanta is on PyPI.

pip poetrypipenvpdm conda

bash pip install mkdocs-iolanta

bash poetry add mkdocs-iolanta

bash pipenv install mkdocs-iolanta

bash pdm add mkdocs-iolanta

bash conda install -c conda-forge mkdocs-iolanta

Configuration

Open your mkdocs.yml configuration file and configure its plugins section as follows:

yaml plugins: - search # (1)! - … - iolanta # (2)! - macros: # (3)! on_error_fail: true # (4)! - …

1. The search plugin is built-in and automatically enabled if mkdocs.yml does not specify any plugins at all. But if it does, this built-in plugin must be enabled explicitly.
2. Support iolanta capabilities for this documentation site.
3. This enables mkdocs-macros-plugin which is required to utilize Iolanta capabilities on MkDocs pages, such as {{ render("render") }} macro.
4. This setting is highly recommended. If there is an error during rendering MkDocs macros, including those macros provided by Iolanta, the site build will throw an error — making the issue easier to notice both on local development and in CI.