Configuration

Attributes

Attribute Description Default

Attribute	Description	Default
`kroki-server-url`	The URL of the Kroki server. See Self-Hosted Kroki.	`kroki.io`
`kroki-data-uri`	Embed images as data-URI elements in HTML so the file is completely self-contained. Only applies when `kroki-fetch-diagram` is enabled. The standard Asciidoctor `data-uri` attribute has the same effect. JavaScript only (see Feature parity (JavaScript vs Ruby)).	`false`
`kroki-fetch-diagram`	Download images from the Kroki server and save them to disk. Not available in the browser.	`false`
`kroki-cache`	Whether fetched diagrams are kept in a persistent cache (see Persistent cache): `true` (or set with no value) — enabled `false` — disabled, always re-fetch `refresh` — enabled, but bypass a cached read and re-fetch + update the cache An invalid value falls back to `true` with a warning.	`true`
`kroki-cache-dir`	Directory used by the persistent cache (see Persistent cache).	XDG cache directory
`kroki-http-method`	How to retrieve images from the Kroki server: `get` — always use GET requests `post` — always use POST requests `adaptive` — use POST if the URI exceeds `kroki-max-uri-length` characters, otherwise use GET This attribute only applies when the extension downloads the diagram content itself: when `kroki-fetch-diagram` is enabled, when the image is embedded (data-URI mode or `inline` option), or when a text format is requested. Otherwise, the generated HTML references the image with a GET URL regardless of this attribute. An invalid value falls back to `adaptive` with a warning.	`adaptive`
`kroki-plantuml-include`	A file included at the top of every PlantUML diagram, as if `!include file` was used. Useful for defining a common skin. Accepts a path or a URL.
`kroki-plantuml-include-paths`	Additional search paths for resolving `!include file`, similar to PlantUML’s `plantuml.include.path`. Use `;` (Windows) or `:` (Unix) to separate multiple paths.
`kroki-max-uri-length`	Maximum URI length before switching to POST when using the `adaptive` HTTP method. With the `get` method, a warning is logged when the limit is exceeded.	`4000`

kroki-server-url

The URL of the Kroki server. See Self-Hosted Kroki.

kroki.io

kroki-data-uri

Embed images as data-URI elements in HTML so the file is completely self-contained. Only applies when kroki-fetch-diagram is enabled. The standard Asciidoctor data-uri attribute has the same effect. JavaScript only (see Feature parity (JavaScript vs Ruby)).

false

kroki-fetch-diagram

Download images from the Kroki server and save them to disk. Not available in the browser.

false

kroki-cache

Whether fetched diagrams are kept in a persistent cache (see Persistent cache):

true (or set with no value) — enabled
false — disabled, always re-fetch
refresh — enabled, but bypass a cached read and re-fetch + update the cache

An invalid value falls back to true with a warning.

true

kroki-cache-dir

Directory used by the persistent cache (see Persistent cache).

XDG cache directory

kroki-http-method

How to retrieve images from the Kroki server:

get — always use GET requests
post — always use POST requests
adaptive — use POST if the URI exceeds kroki-max-uri-length characters, otherwise use GET

This attribute only applies when the extension downloads the diagram content itself: when kroki-fetch-diagram is enabled, when the image is embedded (data-URI mode or inline option), or when a text format is requested. Otherwise, the generated HTML references the image with a GET URL regardless of this attribute. An invalid value falls back to adaptive with a warning.

adaptive

kroki-plantuml-include

A file included at the top of every PlantUML diagram, as if !include file was used. Useful for defining a common skin. Accepts a path or a URL.

kroki-plantuml-include-paths

Additional search paths for resolving !include file, similar to PlantUML’s plantuml.include.path. Use ; (Windows) or : (Unix) to separate multiple paths.

kroki-max-uri-length

Maximum URI length before switching to POST when using the adaptive HTTP method. With the get method, a warning is logged when the limit is exceeded.

4000

kroki-fetch-diagram, kroki-plantuml-include, and kroki-plantuml-include-paths are only available when safe mode is server or lower. See Asciidoctor safe modes.

Default format

By default, images are generated as SVG when possible. To change this, set the kroki-default-format attribute:

:kroki-default-format: png

Unset it with :kroki-default-format!: or restore the default with :kroki-default-format: svg.

An AsciiDoc attribute can be defined through the CLI or API, in the document header, or in the document body. If you are using Antora, you can define attributes in your playbook and/or component descriptor.

asciidoc:
  attributes:
    kroki-default-format: png@

The @ suffix allows the value to be overridden in individual documents.

References:

Default options

By default, Asciidoctor Kroki generates a link to the Kroki server or a local file for SVG diagrams. To change this default behavior, set the kroki-default-options attribute:

:kroki-default-options: inline

Unset it with :kroki-default-options: none, :kroki-default-options!:, or override it per block or macro using opts=none.

Generated file names

When kroki-fetch-diagram is set, diagrams are downloaded and saved to disk. Images are saved to the directory defined by the imagesoutdir attribute when set; otherwise to the output directory (the outdir attribute or the converter to_dir option, falling back to the base directory) combined with imagesdir.

The generated file name depends on whether you give the diagram a name:

Named diagram — the name is used as-is, so the link stays stable even when the diagram content changes:
```
[plantuml,my-diagram]
....
alice -> bob
....
```
generates my-diagram.svg.
Anonymous diagram — a content-addressed name such as diag-<checksum>.svg is generated so anonymous diagrams never collide. If a file with this name already exists in the output directory, it necessarily has the same content, so the diagram is not downloaded again.

If the same name is used for two diagrams with different content in the same document, the file is overwritten and a warning is logged. Use unique names to keep links stable.

A named diagram’s output file, unlike an anonymous one’s, cannot be trusted by name alone — the same name may exist from an earlier build with different (stale) content. The persistent cache described below is what lets a named diagram skip the download when its content hasn’t actually changed.

Persistent cache

Downloaded diagrams are also kept in a persistent cache, independent of the output directory. The cache key is derived from the actual request (server URL, diagram type, format, source, and options), not from the output file name, so:

A named diagram whose content hasn’t changed is served from the cache instead of being re-downloaded, even though its output file name stays the same across content changes.
The cache survives a clean or rebuilt output directory — useful for tools that wipe their output between runs, such as Antora.

By default, the cache lives in the platform’s XDG cache directory ($XDG_CACHE_HOME/kroki, or ~/.cache/kroki when XDG_CACHE_HOME is unset). Set kroki-cache-dir to use a different location — for example, to point it at a directory your CI pipeline already persists between runs:

:kroki-cache-dir: .cache/kroki

This is particularly useful for an Antora site: a full rebuild typically touches only a handful of pages, so most diagrams elsewhere in the site are unchanged, but Antora clears the output directory before every build. Pointing kroki-cache-dir at a directory your pipeline keeps between builds (a persisted CI cache, or a local directory outside build/ in a dev loop) avoids re-downloading those unchanged diagrams on every run:

asciidoc:
  attributes:
    kroki-fetch-diagram: true
    kroki-cache-dir: .cache/kroki

Disable the cache entirely with kroki-cache: false, or force a refresh (re-fetch and update the cache, bypassing any cached read) with kroki-cache: refresh:

:kroki-cache: refresh

The cache key includes the Kroki server URL (see kroki-server-url): the same diagram source fetched from two different servers is cached separately, since different servers are not guaranteed to run the same version of the underlying diagram libraries and so may not render identically. For the same reason, the cache does not know when a diagram library is upgraded on the server you use — if you rely on a self-hosted server and upgrade a diagram library, set kroki-cache: refresh (or clear kroki-cache-dir) to pick up the change.

The persistent cache is only used by the JavaScript/Node.js extension and the Ruby gem when kroki-fetch-diagram is set; it is not available in the browser.

Preprocessing

Some diagram libraries support referencing external entities by URL or accessing filesystem resources. For example, PlantUML supports the !include directive, and Vega-Lite can load data from a URL.

By default, the Kroki server runs in SECURE mode, which restricts access to the local file system and external network resources.

To work around this, Asciidoctor Kroki resolves and loads external resources before sending the request to the Kroki server. For PlantUML, the whole !include family is supported: !include, !include_many, !include_once, !includeurl, and !includesub. This feature is only available when Asciidoctor safe mode is server or lower.

PlantUML !include preprocessing is implemented in both the JavaScript/Node.js extension and the Ruby gem. Structurizr !include and Vega-Lite data.url preprocessing are implemented in the JavaScript/Node.js extension only; the Ruby gem relies on the Kroki server to resolve those (for example by running the server with KROKI_PLANTUML_ALLOW_INCLUDE=true for PlantUML-family diagrams it doesn’t preprocess itself). See Feature parity (JavaScript vs Ruby).

Feature parity (JavaScript vs Ruby)

The JavaScript/Node.js extension and the Ruby gem share the same version and are released together, but a few features are currently available in the JavaScript/Node.js extension only:

Feature JavaScript Ruby

Feature	JavaScript	Ruby
Preprocessing of PlantUML `!include` (local, remote and recursive)	Yes	Yes
Preprocessing of Structurizr `!include`	Yes	No (resolved by the Kroki server)
Preprocessing of Vega-Lite `data.url`	Yes	No (resolved by the Kroki server)
`kroki-plantuml-include-paths`	Yes	Yes
`kroki-plantuml-include` (single shared file)	Yes (`plantuml` and `c4plantuml`)	Yes (`plantuml` and `c4plantuml`)
`kroki-data-uri`	Yes	No
`kroki-default-options`	Yes	Yes

Preprocessing of PlantUML !include (local, remote and recursive)

Yes

Preprocessing of Structurizr !include

Yes

No (resolved by the Kroki server)

Preprocessing of Vega-Lite data.url

Yes

No (resolved by the Kroki server)

kroki-plantuml-include-paths

Yes

kroki-plantuml-include (single shared file)

Yes (plantuml and c4plantuml)

kroki-data-uri

Yes

kroki-default-options

Yes

Antora uses the JavaScript/Node.js extension, so preprocessing is fully available in an Antora pipeline.