Diagram integration

Diagram rendering is disabled by default (see Privacy). Set the asciidoc.extensions.enableKroki setting to true to enable it.

The first time you preview a document that contains a diagram Kroki can render while the extension is disabled, a one-time notification points it out and offers to enable Kroki (or to open this page). The notification is shown at most once; enabling Kroki always remains an explicit choice.

By default, diagrams are rendered by the public kroki.io server. To render them with your own instance instead, set the asciidoc.extensions.kroki.serverUrl setting to its URL (for example localhost:8000).

The setting is the lowest-precedence way to set the server URL: a kroki-server-url attribute set closer to the document still wins. You can therefore override the setting for a single document from its header, or for a directory tree from an .asciidoctorconfig file, using the same attribute:

The attribute can also be set in the asciidoc.preview.asciidoctorAttributes setting, which is useful when the server depends on the environment (for example in a Dev Container, where localhost is the container itself). Like any attribute passed through this setting, kroki-server-url is locked and cannot be overridden by the document, whereas kroki-server-url@ (with a trailing @) can.

The resolution order in the preview, from highest to lowest precedence, is therefore:

Exports (HTML, PDF and DocBook) do not read asciidoc.preview.asciidoctorAttributes, so only the document header, the nearest .asciidoctorconfig, the asciidoc.extensions.kroki.serverUrl setting and the public server apply to them, in that order.

Kroki diagrams also render in the web extension (for example on vscode.dev). The diagram is rendered by the browser, which loads it directly from the Kroki server, so the server must be reachable from the browser.

An HTTPS Kroki server — the public kroki.io or a self-hosted HTTPS instance — works everywhere.

An HTTP server is subject to the browser’s mixed content policy:

On the desktop (Node) extension there is no such restriction: an HTTP Kroki server, local or remote, works regardless of the server URL.

With the kroki-fetch-diagram attribute, diagrams are downloaded when the document is converted instead of being loaded from the Kroki server when it is displayed. On the desktop, the preview and the exports save each diagram as an image file in the images output directory, which defaults to the directory of the document.

To prevent the preview from writing these files into your workspace, set the data-uri attribute (or kroki-data-uri, which only applies to diagrams): the diagrams are then embedded in the preview as data URIs. In the web extension, diagrams are always embedded, since there is no disk to write to.

On the desktop, downloaded diagrams are also kept in a persistent cache, by default in ~/.cache/kroki, including the ones embedded as data URIs. Set kroki-cache to false to disable the cache, or kroki-cache-dir to use another directory.