Frequently asked questions (FAQ)

Missing an entry in the FAQ list? Please open an issue in the GitHub issues for this project.

General Troubles

I’m using MPS and see exceptions. How can I fix this?

There is an ad-tag-include template in all my files. Why?

See Special template ad-tag-include on how this works and how to disable it if you don’t need it.

There is an .asciidoctor folder appearing all over my project. Why?

This is a folder that holds temporary files that are created for dynamic diagrams when running in any other mode than UNSAFE.

Updating troubles

Updating the plugin via JetBrains Marketplace not working

Due to an error of the currently installed plugin version, the upgrade and download from the Marketplace might fail.

As a remedy, download the file from the Marketplace manually and install it as described in the installation chapter.

Editor Troubles

Pasting from clipboard removes leading spaces (aka indent). Why?

This is an automatic reformatting option in the IDE’s settings. Stripping leading spaces should not change your rendered output.

See Indent missing when pasting from clipboard for more information.

How to avoid scrolling left/right for long lines?

An AsciiDoc recommended practice is to have one sentence per line.

I’m editing a file that shows validation errors

The editor shows several validation warnings and errors, for example, for cross-references. This works the best if the IDE opens all files that belong together as a project.

See Validation of AsciiDoc files for details.

Interaction troubles

Whenever I run a code snippet from the editor, a new terminal tab opens

This might happen when a custom shell has been configured and the folder contains a blank.

Re-configure via File  Settings…​  Tools  Terminal  Shell path and add quotes around the path and executable.

Preview Troubles

The preview doesn’t show some remote images! Is this a proxy issue?

The JCEF preview doesn’t support the IDE’s proxy settings prior to IntelliJ 2021.1. Configuring a proxy for JCEF requires an IDE restart. See Proxy issues with the JCEF preview for more information.

The preview doesn’t show and in the notification I see “Errno::ENOENT message”.

This might be due to non-US-ASCII characters in folder names.

See Error Message Errno ENOENT and no preview for more information.

The preview could not find executable to render diagrams

Some diagram types need external helpers to render diagrams in the preview.

The preview is blurry!

This sometimes happens when using the JavaFX preview on high-resolution displays.

See Blurry preview when using JavaFX for more information.

The preview is ugly!

This sometimes happens when using Swing preview. This activates when neither JavaFX nor JCEF preview are available.

See chapters ‘JCEF Preview’ and ‘JavaFX Preview’ for more information.

Could not find the 'dot' (or other) executable. How to fix it?

Some diagram types need helper applications installed locally. Another alternative is to use a cloud-based renderer like Kroki.

PDF troubles

Creating a PDF with Kroki enabled shows URLs instead of 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.

Diagrams embedded in PDFs don’t show arrows or text properly

Some SVG diagrams embed HTML to show text or arrows, for example, Mermaid or This is not supported by Asciidoctor PDF.

Other Troubles

Something is not working as I expect it to work, where can I get help?

Please open an issue in the GitHub issues for this project.

Supporting the project

I’m a user of the plugin, where can I show my support?

Please consider adding a rating for the plugin in the JetBrains Marketplace.

This plugin is based on Asciidoctor and a lot of ideas from its community. To support Asciidoctor, please consider contributing funds via Open Collective.