Diagrams

Use a fenced code block to embed an SVG image of a diagram in your Doks site using the free Kroki service.

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}
gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2014-01-12, 12d
        another task    :24d
```

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:

1. Edit your site configuration to store the getresource cache in the project’s resources directory, setting the cache to never expire:

   [getresource]
   dir = ':resourceDir/_gen'
   maxAge = -1

2. Check the resources directory 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.

Timeout#

If you’re experiencing failing builds and get error messages like:

ERROR The "kroki" code block render hook was unable to get the remote diagram. failed to fetch remote resource: Bad Request

Raise the timeout limit, for example:

timeout = "60s" # "30s" (default)