markdown-kroki 0.2.0

Diagram extension for Python-Markdown using Kroki server.

markdown-kroki

Diagram extension for Python-Markdown using Kroki server.

This extension converts various diagram code blocks into Base64 encoded data: URI. This enables PDF generation with tools like MkDocs to PDF/WeasyPrint without requiring JavaScript, even during web browsing.

Install

pip install markdown-kroki

Requirements

Internet access to the public Kroki server

Default setting with no options.

Self-Managed Kroki server (recommended)

Here is a sample Docker Compose file.

ref. Kroki.io > Install > Using Docker or Podman

docker compose up -d

The default port used by MkDocs (mkdocs serve) may conflict with the default port of a Dockerized Kroki instance. Consequently, you will need to change the port configuration for one of them.

Usage

```{diagram language} formant=[svg|png] {img tag attribute}="value" {diagram option}="value"
```

MkDocs Integration

# mkdocs.yml
markdown_extensions:
  - markdown_kroki:
      kroki_url: http://localhost:18000  # default: https://kroki.io

Python code

import markdown
from markdown_kroki import KrokiDiagramExtension

markdown_text = """```plantuml format="svg" theme="sketchy-outline" width="300"
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
@enduml
```"""

html_output = markdown.markdown(markdown_text, extensions=[
                                KrokiDiagramExtension(kroki_url='https://kroki.io')])

print(html_output)

<p><img src="data:image/svg+xml;base64,PHN2ZyBhcmlhLXJvbGVkZXNjcmlwdGlvbj0ic2VxdWVuY2UiIHJvbGU
9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiB2aWV3Qm94PSItNTAgLTEwIDc1MCA1NzQiIHN0eWxlPSJtYXgtd2lkd
Gg6IDc1MHB4OyBiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsiIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk
...
...
...
IHgxPSIyNzYiLz48L3N2Zz4=" width="300" ></p>

Process flow

sequenceDiagram
    participant application as Application<br/>(eg MkDocs)
    participant markdown as Python Markdown
    participant extension as KrokiDiagramExtension
    participant engine as Kroki Server

    application->>markdown: Markdown + Diagrams
    markdown->>extension: Preprocessor
    extension->>engine: Diagram code 
    engine-->>engine: Convert
    engine-->>extension: Image Data
    extension-->>extension: Base64 encode
    extension-->>markdown: Markdown + data URI image
    markdown-->>application: HTML + data URI image