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 the extension Asciidoctor Diagram that depends on locally installed tools to generate images (i.e. executables available in the PATH environment variable).

The extension 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 the 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’s 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 a .gitignore file placed in the root of the project if the project uses Git as its 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.

Using a local Kroki instance

Users of the AsciiDoc plugin can run a local Kroki instance using containers to avoid sending diagram data to a public cloud instance.

If Docker is installed, it is possible to launch a local Kroki instance listening on port 8000 using the following command:

docker run --rm -p8000:8000 yuzutech/kroki:latest

To use this instance, open the AsciiDoc plugin’s settings and enter as URL of a local Kroki instance http://locahost:8000/.

Some diagrams (like bpmn, excalidraw, mermaid and diagramsnet) require running additional containers. See the Kroki installation documentation for details.

Creating PDFs with Kroki diagrams

In order for Kroki to embed diagrams in the PDF, the attribute allow-uri-read needs to be set in the plugin’s configuration. This allows Asciidoctor to retrieve the diagram and embed it in the PDF.

Starting with plugin release 0.38.13, the attribute is set automatically once Kroki for diagrams has been enabled and the plugin is running in the default UNSAFE mode.

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 while 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.

Using embedded Mermaid support

As an experimental option in plugin version 0.38.1+, there’s an embedded Mermaid support that is embedded in the plugin and will render Mermaid diagrams within the IDE without external helpers.

To enable the support, toggle the checkbox Enable built-in Mermaid Diagrams support in the plugin’s settings.

This is currently only supported for Mermaid diagrams, and only for the JCEF preview.

Advanced options

PNG-only JavaFX preview

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 such as 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 the Kroki plugin and the Asciidoctor Diagram plugin
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.

An extension with custom inline macro can create the links from an xref:[]. Use the JavaScript extension for example with Antora, and use the Ruby extension for IntelliJ as described in Asciidoctor Extensions.

JavaScript extension to add a custom inline macro linkinpuml:...[]
function register (registry, context) {
  registry.inlineMacro('linkinpuml', function () {
    this.process((parent, target, attrs) => {
      const anchor = parent.applySubstitutions(attrs.content, ['macros'])
      const [_, href, text] = anchor.match(/^<a href="(.+?)"[^>]*>(.*)<\/a>$/)
      const prefix = attrs.prefix
      return `[[${prefix ? [prefix, href].join('/') : href} ${text}]]`

module.exports.register = register
Ruby extension to add a custom inline macro linkinpuml:...[]
require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'

include ::Asciidoctor

class LinkInPumlMacro < Extensions::InlineMacroProcessor
  named :'link-in-puml'

  def process parent, target, attrs

    anchor = parent.apply_subs("xref:#{target}[]", [:macros])

    # parse the anchor
    matches = anchor.match(%r{^<a href="(?<href>.+?)"[^>]*>(?<text>.*)</a>$})

    if matches
      # matched, output the href
      create_inline(parent, :quoted, matches[:href])
      # no match, output the target as-is
      create_inline(parent, :quoted, target)

Example PlantUML code which substitutes the macro to create a link
[plantuml, format=svg, opts="inline",subs=+macros]
!include <C4/C4_Container>

System(systemAlias, "Label", "Optional Description", $link="linkinpuml:target.adoc[]")

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