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.	`false`
`kroki-fetch-diagram`	Download images from the Kroki server and save them to disk. Not available in the browser.	`false`
`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	`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. JavaScript only (see Feature parity (JavaScript vs Ruby)).
`kroki-max-uri-length`	Maximum URI length before switching to POST when using the `adaptive` HTTP method.	`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.

false

kroki-fetch-diagram

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

false

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

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. JavaScript only (see Feature parity (JavaScript vs Ruby)).

kroki-max-uri-length

Maximum URI length before switching to POST when using the adaptive HTTP method.

4000

kroki-fetch-diagram and kroki-plantuml-include 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. 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.

Preprocessing

Some diagram libraries support referencing external entities by URL or accessing filesystem resources. For example, PlantUML supports the !import 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. This feature is only available when Asciidoctor safe mode is server or lower.

Preprocessing is implemented in the JavaScript/Node.js extension only. The Ruby gem does not resolve includes locally and instead relies on the Kroki server to resolve them (for example by running the server with KROKI_PLANTUML_ALLOW_INCLUDE=true). 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	No (resolved by the Kroki server)
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	No
`kroki-plantuml-include` (single shared file)	Yes	Yes
`kroki-default-options`	Yes	Yes

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

Yes

No (resolved by the Kroki server)

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

kroki-default-options

Yes

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