/mkdocs-kroki-plugin

MkDocs plugin for Kroki-Diagrams

Primary LanguagePythonMIT LicenseMIT

mkdocs-kroki-plugin

This is a MkDocs plugin to embed Kroki-Diagrams into your documentation.

Setup

Install the plugin using pip:

pip install mkdocs-kroki-plugin

Activate the plugin in mkdocs.yml:

plugins:
  ...
  - kroki:

Config

  • ServerURL - URL of your kroki-Server, default: https://kroki.io
  • FencePrefix - Diagram prefix, default: kroki-
  • EnableBlockDiag - Enable BlockDiag (and the related Diagrams), default: True
  • Enablebpmn - Enable BPMN, default: True
  • EnableExcalidraw - Enable Excalidraw, default: True
  • EnableMermaid - Enable Mermaid, default: True
  • EnableDiagramsnet - Enable diagrams.net (draw.io), default: False
  • HttpMethod - Http method to use (GET or POST), default: GET (Note: you have to enable DownloadImages if you want to use POST!)
  • DownloadImages - Download diagrams from kroki as static assets instead of just creating kroki links, default: False
  • DownloadDir - The asset directory to place downloaded images in, default: images/kroki_generated
  • FileTypes - File types you want to use, default: [svg], (Note: not all file formats works with all diagram types https://kroki.io/#support)
  - kroki:
      FileTypes:
        - png
        - svg
  • FileTypeOverrides - Overrides for specific diagrams to set the desired file type default: None,
  - kroki:
      FileTypeOverrides:
        mermaid: png

Usage

Use code-fences with a tag of kroki-<Module> to replace the code with the wanted diagram.

Diagram options can be set as well.

Example for BlockDiag:

```kroki-blockdiag no-transparency=false
blockdiag {
  blockdiag -> generates -> "block-diagrams";
  blockdiag -> is -> "very easy!";

  blockdiag [color = "greenyellow"];
  "block-diagrams" [color = "pink"];
  "very easy!" [color = "orange"];
}
```

You can render diagram from file with @from_file: directive:

```kroki-bpmn
@from_file:path/to/diagram.bpmn
```

See Also

Diagram examples can be found here.

More information about installing a self-manged Kroki-Service here.

More Plugins for MkDocs can be found here

Pre-Release-Versions

Install the newest pre-release version using pip:

pip install -i https://test.pypi.org/simple/ mkdocs-kroki-plugin