Asciidoctor Extensions
Asciidoctor Extensions can provide features like additional custom macros or post-processing of the AsciiDoc AST. To see the rendered result in the preview, the plugin can use extensions while rendering it.
|
This is an experimental feature starting with version 0.23.0. While it is experimental, names, conventions and functionality may change. Support for AsciidoctorJ extensions is available from 0.31.19. |
Situation
When there are extensions for Asciidoctor used in a command line build, users want to see their effect on the preview rendered within their JetBrains IDE.
To find out more about extensions, have a look at the Asciidoctor Extensions Lab or the Asciidoctor Extensions List.
Solution
The plugin will search the directory .asciidoctor/lib in the root of the project and load all files with the extension “rb” as Asciidoctor extensions and all files with the extension “jar” as AsciidoctorJ extensions.
AsciidoctorJ extensions must use the service loader mechanism of AsciidoctorJ to register themselves.
If a user doesn’t want to store ruby or JAR files in their code repository, a user may choose to add a download or build-script that populates this folder.
Using a configuration file like .gitignore can ensure that the script is checked in to the repository, while the downloaded files are not checked in.
Behavior
The user working with the IDE needs to trust the Ruby or Java code of the extensions, as the code will run with the privileges of the user inside the IDE. When a developer runs a buildscript or other executable content in a repository, executing some else’s code is expected behavior. Running someone else’s code when viewing an Asciidoctor document is unexpected. Therefore, the user needs to confirm to enable Asciidoctor extensions once per project and IDE restart.
Caveats
|
Extensions run in the same JVM as the IDE. Errors in extensions might consume lots of memory, CPU and might crash the IDE. Changing extensions at runtime re-instantiates the Asciidoctor and JRuby runtime, which will lead to memory leaks. |
Example
The Arquillian Smart Testing project provides an example: https://github.com/arquillian/smart-testing/tree/master/.asciidoctor/lib