Kroki Edge Cases

Companion to [[Misc/Kroki Diagram Tests]]. Part 1 covers every remaining block name with a non-trivial diagram; part 2 pokes at the fence parser, the @from_file: resolver, encoding and failure paths. Each block states the expected result.

Part 1: complex diagrams per engine

Mermaid (local, several diagram kinds)

Sequence diagram with activation, loop and notes:

Class diagram with generics, relations and notes:

State diagram with composite state and fork:

Gantt chart (date scales, sections):

Pie chart and ER diagram:

Mermaid init directive and entity-escaped labels (#quot;, #lt; are Mermaid's own escapes):

PlantUML (mindmap, JSON, skinparam)

C4 with PlantUML

GraphViz (subgraphs, HTML-like labels, unicode)

D2 (containers, shapes, styled edges)

BlockDiag family (actdiag, nwdiag, packetdiag, rackdiag)

Ditaa

Pikchr

Svgbob (larger ASCII art)

UMLet

Symbolator (VHDL entity)

WireViz

Excalidraw (full file format)

BPMN (small but complete, with DI)

Structurizr (container view)

TikZ (nodes, loops, decorations)

Vega-Lite (layered chart with text labels)

DBML (enums, notes, indexes, composite keys)

WaveDrom (head, foot, groups, config)

Bytefield (defattrs, gaps, related boxes)

Nomnoml (directives, classifiers, nesting)

Part 2: outliers

Info-string variations

Extra tokens after the language are ignored (first word wins). Expected: an image.

markdown-it-attrs braces are stripped before rendering. Expected: an image.

Tilde fences are still fences. Expected: an image.

Block names are case-sensitive, like the plugin. Expected: a plain code block.

digraph { case -> sensitive }

Unknown prefix. Expected: a plain code block.

digraph { unknown -> prefix }

Nesting

Inside a callout. Expected: an image inside the callout box.

Inside a blockquote. Expected: an image, indented as a quote.

A quoted diagram:

Inside a list item. Expected: an image under the second bullet.

• First item

• Second item with a diagram:

  

• Third item

A fence shown as literal text inside a four-backtick markdown block. Expected: a code block showing the text, no image.

```graphviz
digraph { literal -> text }
```

Bodies

Empty body. Expected: a plain code block (nothing is sent anywhere).

Whitespace-only body. Expected: a plain code block.

Special characters that must survive HTML escaping and URL encoding (<, >, &, quotes, backslashes, tabs, emoji). Expected: an image with the exact labels.

The same in a locally rendered type. Expected: an image with the exact labels.

Exact duplicate of an earlier diagram (same source, same type). Expected: an image sharing the same /diagrams/<md5>.svg as the tilde-fence example above.

Size

A high-entropy GraphViz graph (400 nodes with random labels) whose encoded URL is about 7.4 KB. Kroki's default KROKI_MAX_URI_LENGTH is 4096 and kroki.io answers HTTP 414 for this one. Expected: [Kroki] Failed to download in a production build and a broken image with the remote URL left in place. A self-hosted Kroki with a raised limit renders it; obsidian-kroki has the same limitation.

A large diagram in a locally rendered type never touches a URL, so size limits do not apply. Expected: an image (large).

@from_file: variations

Leading blank line and trailing text after the path line are tolerated. Expected: the same image as the basic include test.

Windows-style separators. Expected: the same image.

A different engine from an include (.puml). Expected: a PlantUML image.

Path traversal. Expected: an error block "escapes the notes directory".

Kroki (graphviz): Include path escapes the notes directory: ../../../package.json

Absolute path. Expected: an error block "escapes the notes directory".

Kroki (graphviz): Included file not found: C:/Windows/win.ini

Directory instead of a file. Expected: an error block "Could not read included file".

Kroki (graphviz): Could not read included file Misc/kroki-includes: EISDIR: illegal operation on a directory, read

Keyword without a path. Expected: an error block "requires a path".

Kroki (graphviz): @from_file: requires a path

Keyword not at the start of the body is just diagram source. Expected: a Kroki syntax error, so a download failure and a broken image (see next section).

Invalid sources (failure paths)

Invalid GraphViz. Expected in npm run build: [Kroki] Failed to download (HTTP 400) and the remote URL kept, which the browser shows as a broken image. In dev: the remote URL is requested by the browser and returns 400.

Invalid Mermaid. Expected: [Kroki] Local render failed (mermaid) followed by a download attempt; kroki.io answers 400 (or 500 while its Mermaid service is down), so the remote URL is kept.

Mermaid diagram kind that isomorphic-mermaid may not support (gitGraph). Expected: either a local image or a logged local failure plus a Kroki fallback.

Vega-Lite referencing remote data. Expected: the local renderer fetches the URL at build time (network access); if that fails the build falls back to Kroki, which also needs network.