Asciidoctor configfiles

Origins and compatibilty with IntellJ plugin

The asciidoc config file idea comes from the IntelliJ asciidoc plugin. You can read their description at https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html

Video

You will find a video about the feature at https://youtu.be/sCQai1q_TPg

Details

Supported filenames:

• .asciidoctorconfig (origin filename but does not handle ifndef etc.)
• .asciidoctorconfig.adoc. This will work the same way like .asciidoctorconfig but supports preprocessor macros like ifndef

Internal processing

(Adopted from intellij documentation page mentioned before)

The internal order of processing is as follows:

• load the .asciidoctorconfig/.asciidoctorconfig.adoc
  • file from the root of the project tree (most general configuration)
  • files from the different directories leading to the specific file to be rendered
  • file from current folder where the file to be rendered resides (most specific to the file opened)
• Prepend all the files found in the previous steps to the file to be rendered and render it in the preview.

Provide special variable

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

// .asciidoctorconfig
:experimental:
:icons: font

:myprojectbasedir: {asciidoctorconfigdir}

When looking at https://github.com/asciidoctor/asciidoctor-intellij-plugin/blob/3a1adacbec4831fb68759c79d1c2bdf95d32dde0/doc/users-guide/modules/ROOT/pages/features/advanced/stylesheets.adoc as an example of usage, there is described:

As this uses {asciidoctorconfigdir}, the folder is relative to the .asciidoctorconfig file.

So the variable asciidoctorconfigdir has to be replaced at rendering time with the folder where there current asciidoctorconfig file is located! The last location wins!

An example:

$myProjectRoot/
           .asciidoctorconfig.adoc
           main.adoc  -->  {asciidoctorconfigdir} points to $myProjectRoot
           subfolder1/
               .asciidoctorconfig.adoc  
               sub1.adoc -->  {asciidoctorconfigdir} points to $myProjectRoot/subfolder1
               sub1subfolder2/
                      .asciidoctorconfig
                      sub1sub2.adoc  -->  {asciidoctorconfigdir} points to $myProjectRoot/subfolder1/sub1subfolder2/
               sub1subfolder3/
                     sub1sub3.adoc  -->  {asciidoctorconfigdir} points to $myProjectRoot/subfolder1
$myProject

Example

Having a file /home/user1/testproject/.asciidoctorconfig.adoc with

:imagesdir: {asciidoctorconfigdir}/images

the asciidoc images directory attribute would be set to /home/user1/testproject/images