Skip to content

Support project specific configurations

Jump to bottom
Alexander Schwartz edited this page Jul 5, 2019 · 21 revisions
Warning
 This is an experimental feature starting with version 0.22.0. While it is experimental, names, conventions and functionality may change. Development is tracked in ticket #220

Problem

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 you have all the settings in your root document, all files that you include will not have these settings when they render in your IDE in the preview.

Solution

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

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

Sample content:

// .asciidoctorconfig
:experimental:
:icons: font
:myprojectbasedir: {asciidoctorconfigdir}

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

Please note that ifndef/ifdef macros won’t work if you include them in a file called .asciidoctorconfig (they work only in files that have the extension .adoc)

To work around this, you can also name the file .asciidoctorconfig.adoc

Behavior

The internal order of processing is as follows:

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

  2. load the .asciidoctorconfig files from the different directories leading to the specific file to be rendered

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

  4. 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

  • you can use the Asciidoc syntax you are familiar with (you can even use includes and other elements as well)

Ecosystem

While this is currently only supported by the IntelliJ plugin, you can use Asciidoc’s include syntax to include the .asciidoctorconfig files in your root document and use the same settings to render your final document.

// root.adoc

include::.asciidoctorconfig[]

# My Root Document

include::chapter01.adoc[]

include::chapter01.adoc[]
Clone this wiki locally