Install

Node.js

Install the dependencies:

npm i @asciidoctor/core asciidoctor-kroki

Create a file named kroki.js with the following content and run it:

import { convert, Extensions } from '@asciidoctor/core'
import { register } from 'asciidoctor-kroki'

const input = 'plantuml::hello.puml[svg,role=sequence]'

register(Extensions) (1)
console.log(await convert(input, { safe: 'safe' }))

const registry = Extensions.create()
register(registry) (2)
console.log(await convert(input, { safe: 'safe', extension_registry: registry }))
1 Register the extension in the global registry.
2 Register the extension in a dedicated registry.

CLI

If you are using the Asciidoctor.js CLI (the asciidoctor package), register the extension using the --extension option:

npm i asciidoctor asciidoctor-kroki
npx asciidoctor --extension asciidoctor-kroki doc.adoc

Unlike the Ruby CLI, the --require (or -r) option only loads a library; it does not register extensions. With the Asciidoctor.js CLI, you must use --extension.

Custom VFS

By default, the extension reads diagram files from the local file system. You can override this behavior by providing a custom Virtual File System (VFS) via the context parameter of the register function.

A VFS object can implement any combination of the following methods. Every method is asynchronous (returns a promise), whether or not the implementation actually needs to await anything:

Method Description

read(path, encoding)

Reads a file at path and resolves to its content as a string. encoding defaults to utf8; use binary for binary files.

exists(path)

Resolves to true if the file at path exists.

parse(resourceId)

Parses a resource identifier and returns an object with dir and path properties. The only synchronous method: it’s pure string manipulation, no I/O.

add(image)

Saves a diagram image. Called when kroki-fetch-diagram is enabled, except in the browser where images are embedded as data-URI elements. Receives an object with relative, basename, and contents properties.

Any method not provided falls back to the default Node.js file system implementation.

import { convert, Extensions } from '@asciidoctor/core'
import { register } from 'asciidoctor-kroki'

const vfs = {
  read: async (path, encoding = 'utf8') => { (1)
    // load from a custom source (e.g. a database, a ZIP archive, an S3 bucket...)
  },
  exists: async (path) => { (2)
    // check if the file exists in your custom source
  },
}

const registry = Extensions.create()
register(registry, { vfs }) (3)
console.log(await convert('plantuml::hello.puml[svg]', { safe: 'safe', extension_registry: registry }))
1 Override file reading to load content from a custom source.
2 Override file existence check.
3 Pass the custom VFS via the context argument.

HTTP limits

HTTP requests sent to Kroki, and remote includes (http:// and https:// URLs read by the default VFS), are limited in time and in response size (60 seconds and 25 MiB by default). The Ruby gem applies the same limits, which cannot be changed. The limits can be changed with the http option of the context argument:

register(registry, {
  http: {
    timeout: 120000,
    maxResponseSize: 50 * 1024 * 1024,
  },
})
Option Default Description

http.timeout

60000

Maximum time in milliseconds for a request, including the time needed to receive the complete response body.

http.maxResponseSize

26214400 (25 MiB)

Maximum size in bytes of a response body, enforced while the response is streamed (also when the server does not send a Content-Length header).
These limits do not apply to the read function of a custom VFS, nor to files read by the fetch-based VFS in the browser.

Browser

Install the dependencies:

npm i asciidoctor asciidoctor-kroki

Create a file named kroki.html with the following content and open it in your browser:

<html lang="en">
  <head>
    <title>Asciidoctor x Kroki</title>
    <meta charset="utf-8">
    <script type="importmap">
    {
      "imports": {
        "@asciidoctor/core": "./node_modules/@asciidoctor/core/build/browser/index.js",
        "asciidoctor-kroki": "./node_modules/asciidoctor-kroki/build/browser/index.js"
      }
    }
    </script>
  </head>
  <body>
    <div id="content"></div>
    <script type="module">
      import { convert, Extensions } from '@asciidoctor/core'
      import { register } from 'asciidoctor-kroki'

      const input = `Here is a _GraphViz_ "Hello World" example:

[graphviz]
....
digraph G {
  Hello->World
}
....`

      const registry = Extensions.create()
      register(registry) (1)
      const result = await convert(input, { safe: 'safe', extension_registry: registry })
      document.getElementById('content').innerHTML = result
    </script>
  </body>
</html>
1 Register the extension in a dedicated registry.

To reference a diagram file in a browser environment, define the base directory using the base_dir option. The extension will automatically use the Fetch API to read files:

const registry = Extensions.create()
register(registry)
const input = 'plantuml::hello.puml[svg,role=sequence]'
await convert(input, { safe: 'safe', base_dir: window.location.origin, extension_registry: registry })

Ruby

Install the dependency:

gem install asciidoctor-kroki

Require the library using the --require (or -r) option from the Asciidoctor CLI:

asciidoctor -r asciidoctor-kroki doc.adoc

Antora

If you are using Antora, you can integrate Kroki in your documentation site.

Version 1.0.0 and above requires Asciidoctor.js 4, which is not compatible with Antora 3 (Antora uses Asciidoctor.js 2). Use the latest-0 release line (currently 0.18.1) with Antora 3, as shown below. Some features described in this documentation, such as the persistent cache, are not available in this release line: see its documentation.

  1. Install the extension in your playbook project:

    npm i asciidoctor-kroki@latest-0

  2. Register the extension in your playbook file:

    asciidoc:
  extensions:
    - asciidoctor-kroki

Use the kroki-fetch-diagram attribute to download images from Kroki at build time. This way, page rendering no longer depends on the Kroki server at viewing time.

asciidoc:
  attributes:
    kroki-fetch-diagram: true