Asciidoctor Config File

To provide a common set of variables when rendering the preview, the plugin reads an .asciidoctorconfig configuration file. Use this to optimize the preview when the project contains a document that is split out to multiple include-files.

Situation

There are usually specific settings for each project that apply to all AsciiDoc sources: these might be the image directory or activating experimental options.

While documents have all the settings in the root document, files that it includes will not have these settings when they render in the IDE’s preview.

Solution

A file called .asciidoctorconfig will contain a snippet that will be pre-pended before rendering the AsciiDoc file.

The IntelliJ IDE provides a variable asciidoctorconfigdir that users can use to set base directory variables.

Sample content:

Example .asciidoctorconfig file
:experimental:
:icons: font
:myprojectbasedir: {asciidoctorconfigdir}

The handling will be a mixture of behaviors like .editorconfig and .gitconfig.

ifndef/ifdef macros will not work in a file called .asciidoctorconfig as they work only in files that have the extension .adoc. To work around this, rename the file to .asciidoctorconfig.adoc. This will work the same way as .asciidoctorconfig.

Behavior

The internal order of processing is as follows:

  1. load the .asciidoctorconfig (or .asciidoctorconfig.adoc) file from the root of the project tree (most general configuration)

  2. load the .asciidoctorconfig (or .asciidoctorconfig.adoc) files from the different directories leading to the specific file to be rendered

  3. load the .asciidoctorconfig (or .asciidoctorconfig.adoc) file from the current folder where the file to be rendered resides (most specific to the file opened)

  4. Prefix each file with :asciidoctorconfigdir: <absolute filename of the file>

  5. Prepend all the files found in the previous steps to the file to be rendered and render it in the preview.

Benefits

  • Project specific configuration is possible.

  • Hierarchical configuration is possible.

  • Use the AsciiDoc syntax the user is familiar with (even includes work).

Ecosystem

Support when using Eclipse as an IDE

The .asciidoctorconfig files are also supported by the Eclipse Asciidoctor Editor. See their wiki page for more information.

Generating a .asciidoctorconfig file during project build

For Gradle is an asciidoctorEditorConfig task available to create a .asciidoctorconfig via a build-task. See the docs for the 3.2+ release of the asciidoctor-gradle-plugin for more details.

Using the .asciidoctorconfig file for rendering regular AsciiDoc documents

While this is currently only supported by the IntelliJ plugin, users can use AsciiDoc’s include syntax to include the .asciidoctorconfig files in the root document and use it to render the document using for example command line tools.

// root.adoc

include::.asciidoctorconfig[]

= My Root Document

include::chapter01.adoc[]

include::chapter02.adoc[]