https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin

MkDocs plugin for Kroki-Diagrams
https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin

Last synced: 9 days ago
JSON representation

MkDocs plugin for Kroki-Diagrams

• Host: GitHub
• URL: https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin
• Owner: AVATEAM-IT-SYSTEMHAUS
• License: mit
• Created: 2021-04-13T09:57:17.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2024-08-12T09:35:28.000Z (3 months ago)
• Last Synced: 2024-10-01T19:08:58.603Z (about 1 month ago)
• Language: Python
• Size: 143 KB
• Stars: 46
• Watchers: 4
• Forks: 29
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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`:

```yaml

plugins:

  ...

  - kroki:

```

## Config

| Key | Description |

|---|---|

| `ServerURL` | URL of your kroki-Server, default: `!ENV [KROKI_SERVER_URL, '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:__ On `POST` the retrieved images are stored next to the including page in the build directory |

| `UserAgent` | User agent for requests to the kroki server, default: `kroki.plugin/`  |

| `FileTypes` | File types you want to use, default: `[svg]`
__Note:__ not all file formats work with all diagram types   |

| `FileTypeOverrides` | Overrides for specific diagram types to set the desired file type, default: empty |

| `TagFormat` | How the image will be included in the resulting HTML, default: `img`
(`img`, `object`, `svg`) |

| `FailFast` | Errors are raised as plugin errors, default: `false` |

Example:

```yaml

  - kroki:

      ServerURL: !ENV [KROKI_SERVER_URL, 'https://kroki.io']

      FileTypes:

        - png

        - svg

      FileTypeOverrides:

        mermaid: png

      FailFast: !ENV CI

```

## Usage

Use code-fences with a tag of kroki-`` to replace the code with the wanted diagram.

[Diagram options](https://docs.kroki.io/kroki/setup/diagram-options/) can be set as well.

Example for BlockDiag:

````markdown

```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:

````markdown

```kroki-bpmn

@from_file:path/to/diagram.bpmn

```

````

## See Also

Diagram examples can be found [here](https://kroki.io/examples.html).

More information about installing a self-manged Kroki-Service [here](https://docs.kroki.io/kroki/setup/install/).

More Plugins for MkDocs can be found [here](http://www.mkdocs.org/user-guide/plugins/)

## Pre-Release-Versions

Install the newest pre-release version using pip:

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

## Development

Setup:

```sh

git clone [email protected]:AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin.git

cd mkdocs-kroki-plugin

pipx install hatch

pipx install pre-commit

pre-commit install

```

Run tests (for all supported python versions):

```sh

hatch test -a

```

Run static code analysis:

```sh

hatch fmt

```