Configuration

Attributes

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-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 on disk, 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.

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

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
Antora uses the JavaScript/Node.js extension, so preprocessing is fully available in an Antora pipeline.