The Kroki extension

The default diagram support on AsciidoctorJ has always been AsciidoctorJ Diagram, but it suffers from ensuring many other components needed to be managed locally. The Kroki extension is a great alternative and is recommended for most use cases.

Groovy
Kotlin

build.gradle

plugins {
    id 'org.asciidoctor.jvm.kroki' version '5.0.0-alpha.2'
}

build.gradle.kts

plugins {
    id("org.asciidoctor.jvm.kroki") version "5.0.0-alpha.2"
}

Kroki options

Groovy

import org.asciidoctor.gradle.model5.js.toolchains.AsciidoctorjsToolchain
import org.asciidoctor.gradle.model5.js.extensions.AsciidoctorjsKrokiExtension

asciidoc {
  toolchains {
    asciidoctorjs(AsciidoctorjsToolchain) {
      asciidocExtensions {
        kroki(AsciidoctorjsKrokiExtension) {
            useVersion('1.2.3') (1)
            serverUri = 'https://server.example/kroki' (2)
            fetchDiagrams = true (3)
            krokiMethod = 'adaptive' (4)
            maxUriLength = 4000 (5)
            plantUmlSearchPaths  '/foo', '/bar' (6)

            plantUmlIncludePath { (7)
                uri = 'https://server.example/path/to/plantuml/file'
                location = '/path/to/a/local/file'
                relativePath = 'relative/to/source/dir'
            }
        }
      }
    }
  }
}

1	Override the default version of Kroki. Anything lazy-evaluated to a string will do.
2	Override the server location. Anything lazy-evaluated to a URI will do. If not set the default at `kroki.io` will be used.
3	Whether to fetch diagrams and use them locally. When fetched, the diagrams will end up in the same folder as the converted document.
4	Set the Kroki fetch method. One of `get`, `post` or `adaptive`.
5	When using `adaptive`, this is the threshold for switching from `get` to `post`.
6	Search path(s) that will be used to resolve `!include` file additionally to current diagram directory. It is similar to PlantUML property `plantuml.include.path`. Items are lazy-evaluated to files, then their absolute paths are taken, before being joined by the path separator of the operating system. The combined string is the one that is sent to the Kroki extension.
7	A file that will be included at the top of all PlantUML diagrams as if `!include` file was used. Can be configured as a URI, a file or a relative path.

Handling missing Kroki options

Most of the options above simply provide a user-friendly conversion to AsciiDoc attributes. As Kroki evolves, it is possible that one might want to set other Kroki options that are not yet supported by this plugin. The way to do it is to set the attribute on the source set

Groovy

asciidoc {
  publications {
    main {
      sourceSet {
        attributes {
          add('kroki-default-format', 'png')
        }
      }
    }
  }
}

Then you can also, raise a feature request describing the Kroki options you would like to see added.

Using Kroki with EPUB and PDF

In order to you use Kroki images with EPUB and PDF you have one of two options to have the options downloaded.

Have Kroki download the images.
Set the allow-uri-read attribute on the source set.

Both of these options affect all the publications that use the specific toolchain. If this is not to your liking, you can create an additional asciidoctorj toolchain and set the Kroki setting only on that toolchain.

Using an additional toolchain

Groovy

build.gradle

import org.asciidoctor.gradle.model5.jvm.toolchains.AsciidoctorjToolchain
import org.asciidoctor.gradle.model5.jvm.extensions.AsciidoctorjKrokiExtension

asciidoc {
    toolchains {
        asciidoctorj2(AsciidoctorjToolchain) {
            asciidocExtensions {
                kroki(AsciidoctorjKrokiExtension) {
                    fetchDiagrams = true
                }
            }
        }
    }

    publications {
        main {
            output 'asciidoctorj', 'html' (1)
            output 'asciidoctorj2', 'epub' (2)
        }
    }
}

1	The HTML backend will use the links to the Kroki server.
2	The EPUB backend will use the images downloaded by the second `asciidoctorj` toolchain.

Setting the allow-uri-read for the source set

Groovy

build.gradle

import org.asciidoctor.gradle.model5.jvm.toolchains.AsciidoctorjToolchain
import org.asciidoctor.gradle.model5.jvm.extensions.AsciidoctorjKrokiExtension

asciidoc {
    publications {
        main {
            sourceSet {
                attributes {
                    add 'allow-uri-read', 1 (1)
                }
            }
        }
    }
}

1	Sets the attribute. You might consider caching the content, by adding a custom extension which uses the `open-uri-cached` GEM.

It might be better to only turn that on for PDF, which is the recommended approach if you have multiple outputs on the same source set.

Setting the allow-uri-read for the source set

Groovy

build.gradle

import org.asciidoctor.gradle.model5.jvm.formatters.AsciidoctorjPdf

asciidoc {
    toolchains {
        asciidoctorj {
            registeredOutputFormatters {
                pdf(AsciidoctorjPdf) {
                    allowUriRead = true (1)
                }
            }
        }
    }
}

1	Sets the attribute only on the PDF output formatter You might consider caching the content, by adding a custom extension which uses the `open-uri-cached` GEM.