Option: Diagrams Extension

On this page you will learn:

  • about the diagrams extension

  • about Kroki

  • how to configure the extension option Diagrams extension

  • a simple example

For a more complex example, see the Diagrams Extension Quickstart page.

Use Kroki via the diagrams extension

With the extension option Diagrams extension you can embed diagrams in your AsciiDoc files as text based descriptions using the Kroki.io online service.

The Kroki server (default or custom) converts the text to its corresponding image with no extra software installed on your machine or browser.

To learn more about diagrams from text based descriptions and "diagrams like code", visit kroki.io.

Diagrams extension options

The two options of the diagrams extension are:

  • Enabled or disabled

  • Kroki Server URL

Enable the diagrams extension

Enable or disable the diagrams extension with this option.

When enabled, the diagrams extension is sending the text diagrams to an instance of Kroki to display them as images in the preview. Kroki is a free open-source project.

When you enable the diagrams extension without changing the default server URL, you agree to the diagrams extension sending your diagrams to the free public cloud instance kroki.io for conversion.

Server URL

The Server URL defines the URL of a Kroki diagram server.

By default, the diagrams extension sends your diagrams to the free public cloud instance kroki.io, but you can install Kroki on your own infrastructure. Once you’ve installed Kroki, make sure to update the server URL to point to your instance.

Learn more about installing Kroki at kroki.io

Benefits

The diagrams extension allows you to take further advantage of the "docs like code" approach for faster and more effective manually created diagrams from text.

Diagrams from text in general enables further documentation automation.

Benefits of the diagrams extension

  • Manage diagram assets related to the document, with the documents

  • Manage change quickly, as the diagram can be updated by editing text

  • Accept changes faster, as for many small diagrams, the change is evident in the text and does not require the rendered image to be present

  • More expressive documents, as writers are able to make quick diagrams to convey concepts that would otherwise take too much time

  • Less storage volume, as the images are only present in the final output

  • Faster git operations, as it is not managing large numbers of image artifacts that increase the size of the repository

Benefits of installing Kroki

The benefits of running Kroki locally, or installing it on your own infrastructure are:

  • Diagram conversion traffic remains inside your organization

  • Depending on the diagram generator used, you may standardise diagram themes for consistency across your organization without changing source diagrams

Security, diagrams and Kroki

Using Kroki via the diagrams extension removes the need to install and maintain diagramming software on individual machines, centralising their deployment to a central Kroki server.

To satisfy security policies, organizations may choose to deploy a Kroki service within their own network.

Learn more Kroki

Learn more about installing Kroki at kroki.io

Example diagram

Below is a three-step process diagram using the GraphViz dot language.

three step process
Figure 1. Three-step process

The AsciiDoc and embedded diagram text to produce the above diagram is below.

[graphviz]
....
digraph { rankdir=LR a -> b -> c}
....

For more information about embedding diagrams as text and GraphViz diagrams, visit kroki.io and graphviz.org.

Quickstart

To try it your yourself, visit the Diagrams Extension Quickstart page.