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

pip install mkdocs-iolanta

poetry add mkdocs-iolanta

pipenv install mkdocs-iolanta

pdm add mkdocs-iolanta

conda install -c conda-forge mkdocs-iolanta

Configuration

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

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.