Installing the plugin

List of prerequisites and a step-by-step guide to install the plugin.

For users already familiar with JetBrains IntelliJ, there’s a Quick Start documentation. For those new to IntelliJ, there is a Setup for technical writing with a step-by-step-guide installing IntelliJ for technical writing.

Prerequisites

To use this plugin, the user of the plugin needs to have one of the IntelliJ family of IDEs like IntelliJ IDEA, GoLand, WebStorm or PyCharm installed. See below for Android Studio and IntelliJ MPS.

Install the IDE with the JetBrains Toolbox. The Toolbox downloads the IDE with its pre-bundled JetBrains Runtime, a JDK that includes the JCEF browser. It also keeps the IDE up-to-date, so the IDE and the plugin stay compatible. See Installing IntelliJ for technical writing for a step-by-step guide.

Use the pre-bundled JetBrains Runtime to run the IDE, as it is the most stable and includes the JCEF browser that the plugin needs for its rich preview. The preview is based on an embedded Chrome browser with up-to-date JavaScript and CSS handling.

The JavaFX preview is no longer available. JetBrains removed JavaFX support for plugins from IntelliJ 2025.1, and the plugin removed the JavaFX preview in version 0.44.1. Use the JCEF preview instead.

If you’ve already installed the IDE and the plugin, continue to section Features of the IntelliJ AsciiDoc plugin.

If you have the IDE installed already, continue to the next section Installing the plugin.

If you are looking for a free version of the IDE, choose IntelliJ IDEA Community edition. All other IDEs require a paid subscription. You can still install them with the JetBrains Toolbox and use them with a free, time-limited evaluation subscription.

You can download the Toolbox from the JetBrains homepage: https://www.jetbrains.com/toolbox-app/

Google Android Studio

If you use Android Studio, go ahead and install the plugin.

Afterwards: Enable the JCEF preview by upgrading the bundled JDK.

IntelliJ MPS

To use MPS, go ahead and install the plugin.

Support will be limited as MPS doesn’t have all the APIs the plugin can hook into. Have a look at Troubleshooting problems when working with MPS. Open an issue on GitHub to contribute to making MPS support better.

More information on JDKs

The plugin’s preview needs a JetBrains Runtime with JCEF support. Install the IDE with the JetBrains Toolbox to get the matching JetBrains Runtime. Don’t replace the IDE’s runtime with a JDK from your Linux distribution or Oracle, as these don’t include JCEF and can make the IDE unstable. If the preview doesn’t show, see selecting a different JetBrains JDK.

Read more about choosing the JDK version of the IDE in the JetBrains knowledge base entry “Selecting the JDK version the IDE will run under”.

Installing the plugin

To activate the support for AsciiDoc in the IDE the plugin, you must install the plugin. There are several possibilities to install the plugin:

Installing from JetBrains marketplace with an Internet Connection:

  1. Via the IDE’s settings from JetBrains marketplace.

If your IDE doesn’t have internet access configured:

  1. Download the installation archive via your browser and install it from disk.

Installation via JetBrains Marketplace via the IDE’s settings

Prerequisite

This requires a working internet connection in your IDE.

Steps

  1. Open the IDE’s setting via File  Settings…​.
    This opens the following menu:

    Screenshot from settings menu when installing from JetBrains Marketplace
    Figure 1. Settings menu when installing from JetBrains Marketplace

  2. Select Plugins from the settings tree.

  3. Select Marketplace tab if it is not selected yet.

  4. Search for 'asciidoc'.

  5. Click on the button Install.

  6. Once the download is complete, press the button Apply and restart the IDE if there is a prompt to do so.

Now that the installation is complete, every AsciiDoc file opens in an editor with syntax highlighting and a preview. Continue to section Configuring the plugin to configure a user’s environment.

Installation by manually download and install-from-disk

Prerequisite

This requires a working internet connection when downloading the file with a browser. If the machine where the plugin should be installed doesn’t have direct internet access, download it on a different machine with Internet access and transfer the file internally via file transfer.

Steps

  1. Open the AsciiDoc plugin in the JetBrains Marketplace
    This opens a web page similar to the following screenshot:

    JetBrains Marketplace showing AsciiDoc plugin
    Figure 2. JetBrains Marketplace

  2. Choose the version tab if it isn’t pre-selected.

  3. Download the version compatible with your IDE’s version (usually the latest version if your IDE is up-to-date).

  4. Open the IDE’s setting via File  Settings…​.
    This opens the following menu:

    install from disk
    Figure 3. Settings menu when installing from disk

  5. Select Plugins from the settings tree.

  6. Click on small gear icon.

  7. Choose menu item Install Plugin from Disk…​.

  8. Pick this ZIP-file downloaded in step 3.

  9. Restart the IDE.

Now that the installation is complete, every AsciiDoc file opens in an editor with syntax highlighting and a preview. Continue to section Configuring the plugin to configure a user’s environment.