Diagram integration

The extension supports a wide range of diagrams — from BPMN to Graphviz, PlantUML, and Vega — through Kroki and asciidoctor-kroki.

You can see the full range of supported diagram types on the Kroki website.

Enable diagrams

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.

Use your own Kroki server

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:

:kroki-server-url: https://kroki.example.org

The resolution order, from highest to lowest precedence, is therefore: the document header, then the nearest .asciidoctorconfig, then the asciidoc.extensions.kroki.serverUrl setting, and finally the public kroki.io server.

VS Code for the Web

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:

  • When the web editor is served over HTTPS (as vscode.dev is), the browser blocks diagrams loaded over plain HTTP — including from localhost — so an HTTP Kroki server cannot be used there. Point the extension at an HTTPS server instead.

  • When the web editor is itself served over HTTP (some self-hosted or development setups), an HTTP Kroki server works.

Lowering the preview security level (AsciiDoc: Change Preview Security Settings) relaxes the extension’s own Content Security Policy, but it does not bypass the browser’s mixed content blocking — it therefore does not help load an HTTP diagram on an HTTPS page.

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

Privacy

By default, diagram source is sent to kroki.io to be rendered.

If this is a concern, you can run your own Kroki instance and point the extension to it (see Use your own Kroki server). See also the asciidoctor-kroki instructions for details.