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.	`false`
`kroki-fetch-diagram`	Download images from the Kroki server and save them to disk. In the browser, there is no disk: images are always embedded as data-URI elements.	`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). In `safe` and `server` modes, a value set in the document must be inside the base directory or the output directory.	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 (relative to the document’s base directory) or a URL (read only if `allow-uri-read` is set).
`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.

false

kroki-fetch-diagram

Download images from the Kroki server and save them to disk. In the browser, there is no disk: images are always embedded as data-URI elements.

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). In safe and server modes, a value set in the document must be inside the base directory or the output directory.

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 (relative to the document’s base directory) or a URL (read only if allow-uri-read is set).

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 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.

In safe and server modes, a document cannot write outside of the base directory or the output directory: when imagesoutdir, imagesdir or outdir set in the document resolve to another location, a warning is logged and the diagram is embedded as a data URI instead. This does not apply to values set from the API or the CLI, as a document cannot change them, nor when a custom virtual file system provides the add function. An attribute with the @ suffix (for example in an Antora playbook) can be changed by the document, so it follows the same rule.

An existing output file is never trusted: a named diagram’s file may exist from an earlier build with different (stale) content, and even an anonymous diagram’s file may have been rendered by an earlier version of the Kroki server. The persistent cache described below is what lets a diagram skip the download when its content hasn’t actually changed, and kroki-cache: refresh downloads it again and overwrites its output file.

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.

This also applies to images embedded using data-uri or kroki-data-uri with kroki-fetch-diagram enabled. Embedded and linked images share the same cache entries: unchanged diagrams can be embedded in a single-file HTML document without contacting Kroki, even when the server is unavailable. The cached image bytes are encoded directly into the data URI; no separate output image is written. The same cache directory, invalidation rules, and false / refresh modes apply. Cache misses and refreshes still require the server, and preprocessing external source includes may require network access even on a diagram cache hit.

The cache is best-effort: when the cache directory cannot be read or written (for example on a read-only file system), diagrams are fetched from the Kroki server and a warning is logged once per document.

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). On Windows, ~ is the user’s profile directory (for example C:\Users\name\.cache\kroki).

The cache is never purged automatically, so it grows as diagrams change. You can safely delete the cache directory, or any file in it, at any time: a diagram that is no longer cached is downloaded again the next time it is needed, which requires the Kroki server to be reachable.

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

A relative path is resolved from the current working directory. In safe and server modes, a value set in the document must be inside the base directory or the output directory; otherwise, a warning is logged and the default location is used. This does not apply to a value set from the API or the CLI.

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

Antora 3 is not yet compatible with this version (see Compatibility), and the persistent cache is not available in the latest-0 release line.

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.

Asciidoctor Kroki applies the same rules as the include:: directive when it reads a resource referenced by a document (!include, kroki-plantuml-include, kroki-plantuml-include-paths, Vega-Lite data.url):

A local file is only read if it is inside the document’s base directory, unless the safe mode is unsafe.
A URL is only read if the allow-uri-read attribute is set.

A resource that is not allowed is not read, and a warning is logged. The !include directive is left in the diagram source, so that the Kroki server can resolve it, if it’s allowed to. A Vega-Lite diagram that references a local data file that is not allowed is replaced by an error block.

Like the include:: directive, a relative path is resolved from the directory of the file that contains it, that is to say the document’s base directory for a diagram written in the document. It is then searched in kroki-plantuml-include-paths and in the base directory, and finally in the current working directory.

These rules do not apply in the browser, where everything is fetched by the browser, or when a custom virtual file system provides the read function (as with Antora): it is then responsible for what it reads.

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	Yes
`kroki-default-options`	Yes	Yes
`inline` option without `allow-uri-read`	Yes (requires Asciidoctor.js 4.0.2 or later)	No (fixed in Asciidoctor by asciidoctor#3791, but not released yet; the image is rendered as a blank placeholder)
Image path when `imagesoutdir` differs from `imagesdir`	Yes	No (waiting for a release that contains asciidoctor#3660; the image path does not include the output directory)

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

inline option without allow-uri-read

Yes (requires Asciidoctor.js 4.0.2 or later)

No (fixed in Asciidoctor by asciidoctor#3791, but not released yet; the image is rendered as a blank placeholder)

Image path when imagesoutdir differs from imagesdir

Yes

No (waiting for a release that contains asciidoctor#3660; the image path does not include the output directory)

Antora uses the JavaScript/Node.js extension, so preprocessing is also available in an Antora pipeline, with the latest-0 release line (see Compatibility).