Support project specific configurations

Warning

This is an experimental feature starting with version 0.22.0. While it is experimental, names, conventions and functionality may change

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 parent document, all files that you includes will not have these settings.

Solution

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

Sample content:

// .asciidoctorconfig
:experimental:
:icons: font

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

Behavior

The order of processing will be 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. now 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 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[]