Frequently asked questions (FAQ)

See Troubleshooting problems when working with MPS for more information.

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

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

Read more in Temporary folder .asciidoctor appearing in several places.

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.

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.

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

See section “Configuring editor” in chapter “Configuring the plugin” on how to enable soft-wrap.

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.

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.

See Running shell commands from the same terminal for more details.

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.

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

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

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

See Could not render diagrams with external helpers for more information.

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

See Blurry preview when using JavaFX for more information.

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.

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

See Could not render diagrams with external helpers for more information.

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.

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

See Diagrams embedded in PDFs don’t show properly for more details.

To use a theme when creating PDFs in the IDE, always specify an absolute directory pointing to the folders with the themes and the fonts.

When specifying the folder in a regular AsciiDoc file, use the modules/ROOT/pages attribute as a prefix to point to a folder relative to the current document:

When specifying a theme relative in an .asciidoctorconfig file, use the folder of that file by prefixing {asciidoctorconfigdir}:

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

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.