# 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`<br>__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/<version>` |
| `FileTypes` | File types you want to use, default: `[svg]`<br>__Note:__ not all file formats work with all diagram types <https://kroki.io/#support> |
| `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`<br>(`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-`<Module>` 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 git@github.com: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
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-kroki-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "diagram, kroki, markdown, mkdocs, python",
"author": null,
"author_email": "Benjamin Bittner <benjamin.bittner@avateam.com>, Antonia Siegert <oniboni@mailbox.org>",
"download_url": "https://files.pythonhosted.org/packages/5c/34/4a6c26c342bae4e864a99771fad867fa29f31a73887904b1bfb0301f598c/mkdocs_kroki_plugin-0.9.0.tar.gz",
"platform": null,
"description": "# mkdocs-kroki-plugin\n\nThis is a MkDocs plugin to embed Kroki-Diagrams into your documentation.\n\n## Setup\n\nInstall the plugin using pip:\n\n`pip install mkdocs-kroki-plugin`\n\nActivate the plugin in `mkdocs.yml`:\n\n```yaml\nplugins:\n ...\n - kroki:\n```\n\n## Config\n\n| Key | Description |\n|---|---|\n| `ServerURL` | URL of your kroki-Server, default: `!ENV [KROKI_SERVER_URL, 'https://kroki.io']` |\n| `FencePrefix` | Diagram prefix, default: `kroki-` |\n| `EnableBlockDiag` | Enable BlockDiag (and the related Diagrams), default: `true` |\n| `EnableBpmn` | Enable BPMN, default: `true` |\n| `EnableExcalidraw` | Enable Excalidraw, default: `true` |\n| `EnableMermaid` | Enable Mermaid, default: `true` |\n| `EnableDiagramsnet` | Enable diagrams.net (draw.io), default: `false` |\n| `HttpMethod` | Http method to use (`GET` or `POST`), default: `GET`<br>__Note:__ On `POST` the retrieved images are stored next to the including page in the build directory |\n| `UserAgent` | User agent for requests to the kroki server, default: `kroki.plugin/<version>` |\n| `FileTypes` | File types you want to use, default: `[svg]`<br>__Note:__ not all file formats work with all diagram types <https://kroki.io/#support> |\n| `FileTypeOverrides` | Overrides for specific diagram types to set the desired file type, default: empty |\n| `TagFormat` | How the image will be included in the resulting HTML, default: `img`<br>(`img`, `object`, `svg`) |\n| `FailFast` | Errors are raised as plugin errors, default: `false` |\n\nExample:\n```yaml\n - kroki:\n ServerURL: !ENV [KROKI_SERVER_URL, 'https://kroki.io']\n FileTypes:\n - png\n - svg\n FileTypeOverrides:\n mermaid: png\n FailFast: !ENV CI\n```\n\n## Usage\n\nUse code-fences with a tag of kroki-`<Module>` to replace the code with the wanted diagram.\n\n[Diagram options](https://docs.kroki.io/kroki/setup/diagram-options/) can be set as well.\n\nExample for BlockDiag:\n\n````markdown\n```kroki-blockdiag no-transparency=false\nblockdiag {\n blockdiag -> generates -> \"block-diagrams\";\n blockdiag -> is -> \"very easy!\";\n\n blockdiag [color = \"greenyellow\"];\n \"block-diagrams\" [color = \"pink\"];\n \"very easy!\" [color = \"orange\"];\n}\n```\n````\n\nYou can render diagram from file with `@from_file:` directive:\n\n````markdown\n```kroki-bpmn\n@from_file:path/to/diagram.bpmn\n```\n````\n\n## See Also\n\nDiagram examples can be found [here](https://kroki.io/examples.html).\n\nMore information about installing a self-manged Kroki-Service [here](https://docs.kroki.io/kroki/setup/install/).\n\nMore Plugins for MkDocs can be found [here](http://www.mkdocs.org/user-guide/plugins/)\n\n## Pre-Release-Versions\n\nInstall the newest pre-release version using pip:\n\n`pip install -i https://test.pypi.org/simple/ mkdocs-kroki-plugin`\n\n\n## Development\n\nSetup:\n\n```sh\ngit clone git@github.com:AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin.git\ncd mkdocs-kroki-plugin\npipx install hatch\npipx install pre-commit\npre-commit install\n```\n\nRun tests (for all supported python versions):\n\n```sh\nhatch test -a\n```\n\nRun static code analysis:\n\n```sh\nhatch fmt\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "MkDocs plugin for Kroki-Diagrams",
"version": "0.9.0",
"project_urls": {
"Documentation": "https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#readme",
"Issues": "https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin/issues",
"Source": "https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin"
},
"split_keywords": [
"diagram",
" kroki",
" markdown",
" mkdocs",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0e5144c14c9d022fb61706d8f03a391ab385dd6d20f9704efaa8af81ebc16c7d",
"md5": "040d0e36299bf06f1a394da821fb01ab",
"sha256": "da9e48241913b1749d79f9facb8c58ca413c3413c0637ea9c3e001e986134b52"
},
"downloads": -1,
"filename": "mkdocs_kroki_plugin-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "040d0e36299bf06f1a394da821fb01ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12066,
"upload_time": "2024-07-28T20:53:25",
"upload_time_iso_8601": "2024-07-28T20:53:25.329906Z",
"url": "https://files.pythonhosted.org/packages/0e/51/44c14c9d022fb61706d8f03a391ab385dd6d20f9704efaa8af81ebc16c7d/mkdocs_kroki_plugin-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c344a6c26c342bae4e864a99771fad867fa29f31a73887904b1bfb0301f598c",
"md5": "064e69406089648b9f15c7126660a1ee",
"sha256": "a153d2eaed6f661dbc8577c98e5d7d85609cc50c3a15ca37aa7260fc277f2306"
},
"downloads": -1,
"filename": "mkdocs_kroki_plugin-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "064e69406089648b9f15c7126660a1ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9829,
"upload_time": "2024-07-28T20:53:24",
"upload_time_iso_8601": "2024-07-28T20:53:24.418296Z",
"url": "https://files.pythonhosted.org/packages/5c/34/4a6c26c342bae4e864a99771fad867fa29f31a73887904b1bfb0301f598c/mkdocs_kroki_plugin-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-28 20:53:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AVATEAM-IT-SYSTEMHAUS",
"github_project": "mkdocs-kroki-plugin#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-kroki-plugin"
}
JSON
