# Kroki Diagram Service

> Kroki converts text-based diagram definitions into images (SVG, PNG, PDF). It supports 28+ diagram types including Mermaid, D2, PlantUML, Graphviz, and more.

## API Base URL

https://d.sub-net.at

## URL Pattern

GET /{diagram-type}/{output-format}/{encoded-source}
GET /{diagram-type}/{output-format}/{encoded-source}?{options}

## URL Encoding (Required)

All diagram source code must be compressed and base64url-encoded:

```python
import zlib, base64

def encode_diagram(source: str) -> str:
    compressed = zlib.compress(source.encode('utf-8'), 9)
    return base64.urlsafe_b64encode(compressed).decode('ascii')

# Example
source = "flowchart LR\n  A --> B"
encoded = encode_diagram(source)
url = f"https://d.sub-net.at/mermaid/svg/{encoded}"
```

## Output Formats

Supported formats depend on the diagram type — an unsupported combination
returns 400, e.g. `Unsupported output format: png for d2. Must be one of svg.`

- `svg` - Scalable vector graphics (all diagram types, recommended)
- `png` - Raster image (verified: mermaid, plantuml, graphviz — **NOT d2**)
- `pdf` - PDF document (verified: plantuml — NOT mermaid, NOT d2)
- `base64` - Base64-encoded output
- `txt` - ASCII art (where supported)
- `utxt` - Unicode text (where supported)

**D2 is SVG-only on this instance.** To get a PNG, convert the SVG locally
(rsvg-convert, inkscape or ImageMagick), e.g. `rsvg-convert -z 2 -o out.png out.svg`.

## Supported Diagram Types

### Recommended (Best Support)

| Type | Use Case | Dark Theme |
|------|----------|------------|
| mermaid | Flowcharts, sequences, ER, state, class diagrams | `%%{init: {'theme': 'dark'}}%%` prefix |
| d2 | Architecture, infrastructure diagrams | `?theme=200` query param |
| plantuml | UML diagrams (class, sequence, activity) | skinparam directives |
| graphviz | Directed graphs, DOT language | bgcolor attribute |

### All Supported Types

actdiag, blockdiag, bpmn, bytefield, c4plantuml, d2, dbml, ditaa, erd, excalidraw, graphviz (dot), mermaid, nomnoml, nwdiag, packetdiag, pikchr, plantuml, rackdiag, seqdiag, structurizr, svgbob, symbolator, tikz, umlet, vega, vegalite, wavedrom, wireviz

## Dark Theme Configuration

### Mermaid

Add this directive at the start of your diagram:

```
%%{init: {'theme': 'dark'}}%%
flowchart LR
    A[Start] --> B[End]
```

Custom theme variables:
```
%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#27AE60',
    'primaryTextColor': '#ECF0F1',
    'lineColor': '#4ade80',
    'secondaryColor': '#2C3E50',
    'tertiaryColor': '#1E2A36'
  }
}}%%
```

### D2

Use the `theme` query parameter:

```
https://d.sub-net.at/d2/svg/{encoded}?theme=200
```

Theme 200 is "Dark Mauve" - best for dark backgrounds. Theme 0 is the light default.

Remote icons are supported — the server fetches them at render time and embeds
them into the SVG:

```
server: "My Host" {
  icon: https://i.sub-net.at/icons/debian-linux.svg
}
```

### PlantUML

Add skinparam directives:

```plantuml
@startuml
skinparam backgroundColor #151C24
skinparam defaultFontColor #ECF0F1
skinparam ArrowColor #27AE60
skinparam classBorderColor #27AE60
skinparam classBackgroundColor #1E2A36
skinparam sequenceLifeLineBorderColor #4ade80

Alice -> Bob: Hello
@enduml
```

### Graphviz

Set graph attributes:

```dot
digraph G {
    bgcolor="#151C24"
    node [style=filled fillcolor="#1E2A36" fontcolor="#ECF0F1" color="#27AE60"]
    edge [color="#27AE60" fontcolor="#ECF0F1"]

    A -> B
}
```

## Examples

### Mermaid Flowchart

```python
source = """%%{init: {'theme': 'dark'}}%%
flowchart LR
    A[Input] --> B{Process}
    B -->|Yes| C[Output]
    B -->|No| D[Error]
"""
# https://d.sub-net.at/mermaid/svg/{encode_diagram(source)}
```

### D2 Architecture

```python
source = """
users -> load_balancer: HTTPS
load_balancer -> app1
load_balancer -> app2
app1 -> database
app2 -> database
"""
# https://d.sub-net.at/d2/svg/{encode_diagram(source)}?theme=200
```

### PlantUML Sequence

```python
source = """@startuml
skinparam backgroundColor #151C24
skinparam defaultFontColor #ECF0F1
Alice -> Bob: Request
Bob --> Alice: Response
@enduml"""
# https://d.sub-net.at/plantuml/svg/{encode_diagram(source)}
```

### Graphviz Directed Graph

```python
source = """digraph G {
    bgcolor="#151C24"
    node [style=filled fillcolor="#1E2A36" fontcolor="#ECF0F1" color="#27AE60"]
    edge [color="#4ade80"]
    A -> B -> C
    A -> C
}"""
# https://d.sub-net.at/graphviz/svg/{encode_diagram(source)}
```

## Embedding in Markdown

```markdown
![Diagram Title](https://d.sub-net.at/mermaid/svg/{encoded})
```

## Health Check

GET /health - Returns service health and version info

## Common Issues

1. **400 Bad Request** - Invalid encoding. Ensure you use zlib compression + urlsafe base64.
2. **Diagram syntax error** - Test your diagram at mermaid.live or the respective online editor first.
3. **Missing theme** - For dark UIs, always include theme directives in the source.
4. **400 "Unsupported output format: png for d2"** - D2 renders SVG only (see Output Formats). Convert SVG → PNG locally if needed.
5. **D2 `|md` markdown blocks missing in local PNGs** - `|md` nodes/titles become SVG `<foreignObject>`, which rsvg-convert and most rasterizers drop. Use plain string labels (single line — multi-line strings break the d2 title box) when the SVG will be rasterized.

## Brand Colors (Sub-Net)

| Color | Hex | Usage |
|-------|-----|-------|
| Charcoal | #2C3E50 | Primary text |
| Green | #27AE60 | Accent, links |
| Dark BG | #151C24 | Backgrounds |
| Card BG | #1E2A36 | Containers |
| Light Text | #ECF0F1 | Body text |