📖 mkdocs + 👁️ iolanta

Features

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

• Automatic page → page 🔗 links;
• Tables generated from YAML data;
• Project roadmaps;
• Architecture Decision Records.
• Something missing? Or anything doesn't work? Submit ➕ an issue!

Installation

Python ⩾ 3.10 required.

mkdocs-iolanta is on PyPI.

pip install 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 {% raw %}{{ render("render") }}{% endraw %} 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.