Diagrams
Use a fenced code block to embed an SVG image of a diagram in your Doks site using the free Kroki service.
Unlike JavaScript solutions that require client-side rendering, this approach embeds an SVG image in your page.
Hugo supports GoAT diagrams (ASCII diagrams) natively.
Overview
Kroki generates diagrams from textual descriptions, and provides a unified API with support for D2, Mermaid, PlantUML, and other diagram types.
You can create:
- Block diagrams
- Container diagrams
- Gantt diagrams
- Mind maps
- Sequence diagrams
- UML diagrams
- Word clouds
- And more…
Visit the Kroki site for more examples.
Examples
D2
```kroki {type=d2}
# Actors
hans: Hans Niemann
defendants: {
mc: Magnus Carlsen
playmagnus: Play Magnus Group
chesscom: Chess.com
naka: Hikaru Nakamura
mc -> playmagnus: Owns majority
playmagnus <-> chesscom: Merger talks
chesscom -> naka: Sponsoring
}
# Accusations
hans -> defendants: 'sueing for $100M'
# Offense
defendants.naka -> hans: Accused of cheating on his stream
defendants.mc -> hans: Lost then withdrew with accusations
defendants.chesscom -> hans: 72 page report of cheating
```Mermaid
```kroki {type=mermaid}
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
```PlantUML
```kroki {type=plantuml}
@startmindmap
skinparam monochrome true
+ OS
++ Ubuntu
+++ Linux Mint
+++ Kubuntu
+++ Lubuntu
+++ KDE Neon
++ LMDE
++ SolydXK
++ SteamOS
++ Raspbian
-- Windows 95
-- Windows 98
-- Windows NT
--- Windows 8
--- Windows 10
@endmindmap
```Performance
The render hook calls Hugo’s resources.GetRemote function to request the SVG image from the Kroki API. Hugo caches the result, and invalidates the cache when (a) you edit the LaTeX markup, or (b) the cache expires.
To optimize performance in a CI/CD environment such as Cloudflare Pages, GitHub Pages, or Netlify, you should:
Edit your site configuration to store the
getresourcecache in the project’sresourcesdirectory, setting the cache to never expire:hugo.toml [getresource] dir = ':resourceDir/_gen' maxAge = -1Check the
resourcesdirectory into source control.
In this configuration, Hugo will use the cached resources when building your site locally and remotely, invalidating the cache when you change the LaTeX markup.