Diagrams in the preview

The preview of the AsciiDoc plugin supports rendering the diagrams in the preview. Two different types of diagram renderer are supported: Asciidoctor Diagram and Kroki.

Using Asciidoctor Diagram

By default, the plugin uses Asciidoctor Diagram that depends on locally installed tools to generate images (i.e. executables available in the PATH environment variable).

Asciidoctor Diagram renders the content of the editor including all referenced includes, images and diagrams like PlantUML on the fly.

Downloading Asciidoctor Diagram

As of AsciiDoc Plugin version 0.31.14+ Asciidoctor Diagram is no longer included in the plugin as default as it adds approximately 15 MB to the download of the installation and each update.

When the preview includes a diagram, the plugin shows an editor notification asking the user to download the necessary dependency.

The download requires a working internet connection. When the download fails the IDE prompts to check proxy settings or to retry the download. The IDE’s event log contains instructions for a manual download of the file.

The dependencies will be cached locally. A new download will only be necessary when the AsciiDoc plugin requires a newer version.

Users can force the download by selecting “Download AsciiDoc dependencies for diagrams and PDF creation” in the settings of the plugin.

Temporary folder .asciidoctor appearing in several places

This is a folder that holds temporary files that are created for example for dynamic diagrams.

When running in Asciidoctor UNSAFE mode, the plugin creates a temporary folder outside the project. When running in any other mode, Asciidoctor needs to have this folder them relative to the document’s folder.

Diagrams in the preview when running in any mode other than UNSAFE will only work starting with version 0.33.8.

To avoid checking in these files, consider adding a file path to the ignore file of your version control system.

See below for example .gitignore file placed in the root of the project if the project uses Git as version control system.


Using Kroki

Alternatively, the plugin supports Kroki instead of Asciidoctor Diagram to render diagrams.

Use the plugin’s settings to enable Kroki:

kroki settings

When Kroki is enabled, the plugin sends the text diagrams to an instance of Kroki to display them as images in the preview. By default, it sends the diagrams to the free public cloud instance kroki.io, but users can install Kroki on their own infrastructure. Once the custom instance is set up, update the server URL in the plugin’s settings to point to it.

Inline diagrams with Kroki

When using the diagram option inline, users will need to set the attribute allow-uri-read in the plugin’s settings to allow the download of the diagrams at render time.

As Kroki will in inline-mode fetch the diagrams synchronously when preparing the preview, a slow or unavailable internet connection to the user’s Kroki server can slow down or break the preview.

To avoid this, consider using interactive for Kroki diagrams as an alternative. See Interactive vs inlined SVGs and Avoid flicker in preview on refresh for a discussion of tradeoffs.

Advanced options

PNG-only JavaFX preview

As JavaFX has a problem displaying SVG files correctly. Therefore, the plugin displays all diagrams in the JavaFX preview as PNGs, even when the user specifies SVG as the diagram format.

When using IntelliJ 2020.2+ and plugin version 0.31.25+, the JCEF preview will show diagrams as SVGs when the user specifies SVG as the diagram format.

Interactive vs inlined SVGs

SVGs support interactions with the user, for example hovering or links. This is only available when the user adds the option interactive or inline to diagrams or SVG images. Only when an SVG or diagram is inlined, the plugin will redirect clicks on links in the preview to local AsciiDoc files. See section “Taming SVGs” in the Asciidoctor manual.

  • When using existing SVGs images in Asciidoctor, use opts=inline to inline existing SVGs

  • When using Kroki, use opts=inline and set allow-uri-read in the plugin’s settings

  • When using Asciidoctor Diagram, use svg-type=inline to inline generated SVG

  • As this requires SVG support in the preview, this only works with the JCEF preview.

The following PlantUML example renders a diagram in the preview showing a note “Link to class-demo.adoc” with a link. When the user clicks on the note, the plugin resolves the link class-demo.html to the workspace file class-demo.adoc.

Source code for diagram
// setting both opts and svg-type to make it work with both Kroki and Asciidoctor Diagram
class Demo
note right
[[class-demo.html Link to class-demo.adoc]]
end note
Diagram as displayed in the preview
Figure 1. Diagram as displayed in the preview

In this documentation the image above is non-interactive, as the target link of the note would not resolve.

Avoid flicker in preview on refresh

Using inlined diagrams instead of interactive diagrams in the preview prevents flickering on refreshed content. If inlining should be used only for IntelliJ preview, consider a conditional attribute like in the following listing.

ifdef::env-idea[:plantuml-opts: inline]

// setting both opts and svg-type to make it work with both Kroki and Asciidoctor Diagram