Plugin installation

Prerequisites

To use this plugin, you need 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.

All default download packages include the JetBrains Runtime 11, a pre-bundled OpenJDK runtime environment. Please use the pre-bundled JetBrains Runtime to run the IDE as it proves to be the most stable.

Up to and including IntelliJ IDEA 2020.1 the pre-bundled OpenJDK includes JavaFX, which is required for a rich preview in 2020.1 and earlier.

From IntelliJ 2020.2 onward the plugin supports the JCEF browser preview that is pre-bundled in the JetBrains runtime that pre-bundled with 2020.2 and later. It uses and embedded Chrome browser with up-to-date JavaScript and CSS handling.

Starting with IDEA 2020.2 the JavaFX preview is only available after installing the plugin “JavaFX for plugins”.

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 download them and use them with a free, time-limited evaluation subscription.

You can download them from the JetBrains homepage: https://www.jetbrains.com/idea/download/

Google Android Studio

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

Afterwards: For Android Studio 4.0+, enable JavaFX preview by upgrading the bundled JDK. For Android Studio 4.2+, enable JCEF preview by upgrading the bundled JDK.

IntelliJ MPS

If you 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. Please open an issue on GitHub if you want to contribute to make MPS support better.

More information on JDKs

To use the JavaFX preview instead of the Swing preview, you’ll need to run IntelliJ with 64bit Java and JavaFX installed. Starting with IntelliJ 2020.3, the JetBrains platform requires JDK 11 to run. Oracle JDK installations include JavaFX, but can make the IDE unstable and crash. OpenJDK included with for example an Linux distribution usually don’t include JavaFX.

The event more advanced JCEF preview will only work with JetBrains OpenJDK runtime.

Therefore, JetBrains OpenJDK pre-bundled with your IDE is recommended.

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 Ccnnection:

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 Install

  6. Once the download is complete, restart your IDE

Now that the installation is complete, every AsciiDoc file will open in an editor with syntax highlighting and a preview. Continue to section Recommended settings to configure your environment.

Installation by manually download and install-from-disk

Prerequisite

This requires a working internet connection when downloading the file with a browser. You can then distribute the file internally to the IDE by regular file transfer.

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

    JetBrains Marketplace showing AsciiDoc plugin
    Figure 2. JetBrains Marketplace
  2. Choose the version tab

  3. Download version matching 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 Install Plugin from Disk…​

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

  9. Restart the IDE

Now that the installation is complete, every AsciiDoc file will open in an editor with syntax highlighting and a preview. Continue to section Recommended settings to configure your environment.