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.

Installing Graphviz dot to fix rendering problems in the preview

If a PlantUML diagram is rendered incorrectly in the preview window when using Asciidoctor Diagram as the diagram renderer, consider installing the Graphviz dot program and avoid using the PlantUML’s built-in Smetana render.

Use one of the following commands to install Graphviz dot:

macOS (using brew.sh): brew install graphviz
Linux (Debian, Ubuntu): sudo apt install graphviz
Linux (Fedora, Red Hat): sudo dnf install graphviz
Windows (using scoop.sh): scoop install graphviz

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.

.gitignore

**/.asciidoctor/images/*
**/.asciidoctor/diagram/*

Using Kroki

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

Use the plugin’s settings to enable Kroki:

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.

PlantUML includes with Kroki

The Kroki server has no access to the local file system, so the plugin resolves PlantUML !include, !includesub, !include_once, !include_many and !includeurl directives before the diagram is sent (plugin version 0.45.7+, using the include preprocessor of asciidoctor-kroki 2.0). Relative include paths resolve against the directory of the .puml file referenced by the block macro, then against each directory in the kroki-plantuml-include-paths attribute; http(s) includes are fetched and inlined as well, only <stdlib> includes are passed through to the server. Diagrams written inline in a [plantuml] block have no file location, so only absolute paths and the kroki-plantuml-include-paths directories work for their includes.

Antora resource ids as Kroki diagram targets

When editing inside an Antora module with Kroki enabled, a diagram source can be referenced by its Antora resource id, plantuml::example$order-model.puml[], and the plugin resolves it to the file in the module’s examples directory (plugin version 0.45.7+). This is the form the Antora site renders through the asciidoctor-kroki JavaScript extension, so page and preview agree. Includes inside the .puml file stay plain relative PlantUML includes (see above): resource ids belong in the AsciiDoc page, not in the diagram source, so every .puml remains a valid standalone diagram for the PlantUML CLI or the PlantUML integration plugin.

Placeholders for Kroki diagrams that cannot be rendered

A Kroki diagram can fail in the preview when the block macro’s target cannot be resolved or read, or when one of its !include files does not exist. In both cases the preview shows a placeholder box instead of an error paragraph or a silently incomplete diagram (the Kroki server drops an include it cannot read and renders the rest). The box names the diagram type and the reason, and offers an Open link that opens the diagram source in the IDE editor — where the PlantUML integration plugin, if installed, previews the file on its own.

To show placeholders for all Kroki diagrams without contacting the server, for example while editing a page with many diagrams, set the document attribute kroki-preview-placeholder (in the document header, via the plugin’s attribute settings, or via an .asciidoctorconfig file).

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
[plantuml,demo,svg,opts="inline",svg-type="inline"]
----
class Demo
note right
[[class-demo.html Link to class-demo.adoc]]
end note
----

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.

Using extensions to create links

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.matchFormat('short')
    this.positionalAttributes(['content'])
    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
  use_dsl
  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])
    else
      # no match, output the target as-is
      create_inline(parent, :quoted, target)
    end

  end
end

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
[plantuml,demo,svg,opts="{plantuml-opts}",svg-type="{plantuml-opts}"]
----
...
----