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 asciidoctorKroki from 'asciidoctor-kroki'

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

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

const registry = Extensions.create()
asciidoctorKroki.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.

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:

Method Description

Method	Description
`read(path, encoding)`	Reads a file at `path` and returns its content as a string. `encoding` defaults to `utf8`; use `binary` for binary files.
`exists(path)`	Returns `true` if the file at `path` exists.
`parse(resourceId)`	Parses a resource identifier and returns an object with `dir` and `path` properties.
`add(image)`	Saves a diagram image. Called when `kroki-fetch-diagram` is enabled. Receives an object with `relative`, `basename`, and `contents` properties.

read(path, encoding)

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

exists(path)

Returns true if the file at path exists.

parse(resourceId)

Parses a resource identifier and returns an object with dir and path properties.

add(image)

Saves a diagram image. Called when kroki-fetch-diagram is enabled. 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 asciidoctorKroki 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: (path) => { (2)
    // check if the file exists in your custom source
  },
}

const registry = Extensions.create()
asciidoctorKroki.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.

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 asciidoctorKroki from 'asciidoctor-kroki'

      const input = `Let's take an example with a _GraphViz_ "Hello World":

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

      const registry = Extensions.create()
      asciidoctorKroki.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.

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

const registry = Extensions.create()
asciidoctorKroki.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 version latest-0 (currently 0.18.1) with Antora 3:

npm i asciidoctor-kroki@latest-0

Install the extension in your playbook project:
```
npm i asciidoctor-kroki
```

asciidoc:
  extensions:
    - asciidoctor-kroki

Enjoy!

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