The easiest way to install the extension is to use the Jamal command line tool. The command line version can be installed using the platform-specific installation kit downloadable from the GitHub release page.

https://github.com/verhas/jamal/releases/tag/v2.8.2

Download the installation kit and start it up. The installation kit will install the command line version of Jamal into the system. This installation will install the command line version of Jamal with all the dependencies, including a tailored JDK.

Having a command line executable Jamal, you can open a terminal (MacOs) or a command prompt (Windows) and type the command:

in the root directory of your project.

This command will install the extension into the .Asciidoctor/lib directory, where the Asciidoctor plugin is looking for its extensions. Unfortunately, there is no simple way to install Jamal globally for all the projects.

If you want to use a different version of the extension, you can specify the version number as a parameter to the jamalize command:

If you omit the version parameter, then the version of the installing command line version Jamal will be used.

The -jamalize option with the command line version can also be used if you installed the command line version in some different way, for example, using jbang or manually relying on the already installed JDK.

You can install the extension manually. You may want to do this installation if you do not have and do not intend to use the command line version of Jamal. The manual installation described below is exactly what the automated installation does.

To install the extension together with the IntelliJ AsciiDoc plugin, you need the file jamal-AsciiDoc-2.8.2-jamal-AsciiDoc-distribution.zip.

You can download this file from the central Maven repository using the URLs:

• https://repo.maven.apache.org/maven2/com/javax0/jamal/jamal-AsciiDoc/2.8.2/jamal-AsciiDoc-2.8.2-jamal-AsciiDoc-distribution.zip

  Is the ZIP file. This is the only file you really need. The other files are checksum files.

• https://repo.maven.apache.org/maven2/com/javax0/jamal/jamal-AsciiDoc/2.8.2/jamal-AsciiDoc-2.8.2-jamal-AsciiDoc-distribution.zip.asc

  This is the PGP signature of the ZIP file. Using this file, you can ensure that the downloaded ZIP file is really from the original author.

• https://repo.maven.apache.org/maven2/com/javax0/jamal/jamal-AsciiDoc/2.8.2/jamal-AsciiDoc-2.8.2-jamal-AsciiDoc-distribution.zip.md5

  This is the MD5 checksum of the ZIP file.

• https://repo.maven.apache.org/maven2/com/javax0/jamal/jamal-AsciiDoc/2.8.2/jamal-AsciiDoc-2.8.2-jamal-AsciiDoc-distribution.zip.sha1

  This is the SHA1 checksum of the ZIP file.

The ZIP file contains all the JAR files, the .asc, .md5 and .sha1 files are standard checksum files to check the integrity of the archive.

Extract the content of this zip file into your projects .Asciidoctor/lib folder.

To use the extension with the IntelliJ Asciidoctor plugin, you have to configure IntelliJ to recognize the .jam extension as an AsciiDoc file.

Open the Preferences window of IntelliJ and select Editor and File Types. Under the recognized file types, select AsciiDoc files. Under the File name patterns: click on the plus sign and add *.jam

It will associate the Asciidoctor plugin with the files with the .jam extension. The Jamal extension does not start the processing when you look at files that do not have the .jam ending.

Start editing the .jam file and look at the right pane at the rendered document.

You may need to restart IntelliJ.

As soon as you open a file configured as AsciiDoc, IntelliJ will ask you:

This project contains Asciidoctor Extensions in .asciidoctor/lib that can be executed to render the preview. As this Ruby code runs as your local user, don’t run this code unchecked.

You have to click on the first link that says

I’ve checked the code and trust it, enable them!

When you edit an AsciiDoc file the extension is adoc.jam. The plugin converts the Jamal macros and passes the pure AsciiDoc document to the IntelliJ Asciidoctor plugin. You edit the file and see the result instantly in the other editor pane.

When you edit a Markdown file, the extension is either md.jam or markdown.jam. The plugin first converts the Jamal macros and then converts the markdown to AsciiDoc. The Jamal processed markdown file is saved into the output, but the converted AsciiDoc is passed to the IntelliJ Asciidoctor plugin. That way you edit the markdown and see the result instantly in the other editor pane.

In IntelliJ, there is a plugin to display Markdown files. In this case, it is not invoked. The preview of the document may look slightly different from the Markdown preview. If you are interested how the Markdown plugin renders the same document, you can open any times the saves .md file.

The xml conversion happens the same way as any text format. It is handled separately to add the xml formatting after the source as [source,xml] in the case of pom.jam files.

The editor will treat a file as plain text when the extension is not recognized by any of the extension converters. The details about converters you can plug into the process are covered in the next section "Other formats". In this case, the plugin first converts the Jamal macros and then converts the text to AsciiDoc plain text. That way it adds

in front of the text and adds

at the end of the file. The characters xxx in the actual conversion will be the internal extension that stands before the final .jam extension. For example editing my_gorgeous.xml.jam will start with [source,xml]. That way you edit the text and see the result instantly in the other editor pane.

The conversion of different formats is not hardwired into the preprocessor. You do not need, but can create Java classes doing conversion from different formats to AsciiDoc. The preprocessor defines the interface javax0.jamal.AsciiDoc.Converter and uses all converters available. The interface implementations are loaded using the service loader as defined in the Java 9 module systems.

There are two converters supplied inside the JAR file of the preprocessor itself:

• AsciiDoc → AsciiDoc converter (javax0.jamal.AsciiDoc.AsciiDocConverter)

• Markdown → AsciiDoc converter (javax0.jamal.AsciiDoc.MarkdownConverter)

The first one is fairly obvious, it just leaves the text as it is after the Jamal processing. The markdown conversion converts from markdown to AsciiDoc.

If there are other implementations in some JAR files copied into the .asciidoctor/lib properly exposed to the service loader then they will also be consulted. The method canConvert(name) is consulted for each converter passing the file name. If any of the converters' method returns true, stating that the specific converter can convert the file then the convert(lines) will be invoked. Only one converter is invoked for an input.

If none of the converters can convert the input, then it is converted using the built-in text converter.

The default macro opening and closing strings are {% and %}. It is the usual convention when editing AsciiDoc files with Jamal preprocessor. The reason for this is that these documents many times include sample code snippets that frequently may have { and } in them. AsciiDoc also uses the { and } to denote attributes. If you want to use { and } as macro opening and closing strings, then start your file with the line:

When the first two characters of the document are {@, then the macro opening and closing strings will be { and }. It is what the core built-in macro import also does. The back-slash following the macro closing string escapes the new line, thus this comment is truly an empty string.

It is a frequent mistake to start the document with some macro other than an empty comment. Sometimes the macro start changes from {@ to {# to pre-evaluate the macro input. With that, all of a sudden the macros are not recognized anymore. It is safer to use the empty comment as a "shebang" line.

When you use Jamal in the IntelliJ Asciidoctor plugin, you can separately install IntelliJ live templates. These templates help you to write macros. The template names all start with the prefix jm-. If you start typing it, IntelliJ will automatically offer the templates that you can select from:

To install the live templates, download the ZIP file

• https://raw.githubusercontent.com/verhas/jamal/master/jamal-AsciiDoc/live-templates.zip

When you have this file downloaded, you have to use the IntelliJ menu:

• File → Manage IDE Settings > → Import Settings…​

This menu brings up a file selector. You have to navigate to the downloaded ZIP file and select it.

On the modal dialog:

ensure that the checkboxes are selected and then press OK. The next dialog will need your confirmation to restart the IDE:

Click`Import and Restart`.

After the IDE restarted you will have your live templates at your disposal.

You can configure the extension using the Jamal built-in configuration mechanism, which uses

• environment variables,

• system variables, or

• properties files.

The configuration uses the exact mechanism that Jamal uses when searching for configuration options. The search order and key name translations are described in the documentation of the macro env.

When looking for a configuration value X_Y_Z, then the following search order is used:

• First, the code looks at the Java system properties for x.y.z.

• If there is no system property with that name, it looks at the environment variable X_Y_Z.

• Finally, it tries to look up the configuration value x.y.z from the ~/.jamal/setting.properties or ~/.jamal/setting.xml file.

The following configuration values are supported:

• ASCIIDOC_EXTENSION_OPEN can define the macro opening string. The default value is {%.

• ASCIIDOC_EXTENSION_CLOSE can define the macro closing string. The default value is %}.

• ASCIIDOC_EXTENSION_NOSAVE can be true or false, and it defines whether the extension should save the rendered document to the file system. The default value is false, meaning that the rendered document is saved to the file system.

• ASCIIDOC_EXTENSION_LOG can be true or false, defining whether the extension should log the rendering. The default value is false, meaning no logging by default.

• ASCIIDOC_EXTENSION_EXTERNAL can instruct the extension to start Jamal as an external process, convert the input to the output and then read the lines of the generated file and return it for the AsciiDoc plugin. The external command to be executed can be configured using the next, ASCIIDOC_EXTENSION_EXTERNAL_COMMAND configuration. Note that starting an external process may need significant resource and may significantly slow down the rendering.

• ASCIIDOC_EXTENSION_EXTERNAL_COMMAND can specify the command to execute when the preprocessing is done using an external process.

• ASCIIDOC_EXTENSION_NO_DEPENDENCIES can be true or false defining whether the extension should consider the included files change when caching. The option is false by default, which means that the caching examines all the included, imported and other files that were used during the processing.

• ASCIIDOC_EXTENSION_FROM_FILE instructs the Jamal preprocessor to read the content of the saved file instead of the lines provided by the Asciidoctor plugin to preprocess. It will result in less processing along with the use of the in-memory cache. The user has to press Control-S (or Command-S on Mac) to refresh the formatted AsciiDoc output. It is also to note that Asciidoctor already processes the lines before invoking the Jamal preprocessor. If this variable is true, reading from a file will eliminate the effects of these processes. The output in some special cases may be different. The default value is false, meaning that the content provided by the IntelliJ plugin is used.

• ASCIIDOC_EXTENSION_KEEP_FRONT_MATTER instructs Jamal to remove the front-matter, like

  ---
  publish_date: 2022-01-13
  ---

  These lines are usually used by site builder tools, like Jekyll, and they are ignored by Asciidoctor. Asciidoctor removes these lines before starting Jamal. Jamal puts these lines back; thus you can have Jamal macros even in the front-end. You can also have macros in front of the front-matter assumed they do not produce any output. However, since Asciidoctor has removed these lines, it also expects that they are not present when the lines are processed by Jamal. The default behaviour is to remove the front-matter after Jamal has finished.

  Note	The front-matter is removed only from the lines, which are passed to the Asciidoctor plugin. They are never removed from the output saved into the output file.

  Using this option, you can instruct Jamal to keep the front matter.

  This option is only consulted when the file is formatted as AsciiDoc, having the file extension .adoc.jam. For other files, any font-matter is kept as it is, and becomes part of the preformatted source AsciiDoc text.

  Note

  The input text provided by as a list of lines does not contain the front matter when Jamal is started. Jamal fetches the front matter calling final var frontMatter = document.getAttribute("front-matter", null); The result contains the front matter as a string omitting the last new-line character. Because the last new-line character is missing, Asciidoctor passes an empty string when the front matter is empty, but also when the front matter is an empty line. This should not cause any problem. If this is really a problem in your application, you can use the ASCIIDOC_EXTENSION_FROM_FILE, fromFile option.

Note that these names should be translated to a lower case and use . as separator instead of _ when using the ~/.jamal/setting.properties or ~/.jamal/setting.xml file. For example, in the ~/.jamal/setting.properties file you should write

instead of ASCIIDOC_EXTENSION_LOG.

The plugin defines the following macro before starting the preprocessing:

• asciidoctorj:version is the version of the AsciidoctorJ library used by the IntelliJ plugin. It is . If you see no version number, then the AsciiDoc file was created by Jamal running in a different installation and not AsciidoctorJ integration.

• failfast option is defined true by this application at the start of the processing. It means that the processing stops when an error occurs and does not try to recover. When processing the document interactively, it is more important to finish faster than to discover all the errors in single processing. When the user fixes the first error, the next one will immediately be shown as preprocessing runs again on each key press. What is more, a long error list may even be confusing the user. It is better to stop at the first error.

Consider the possibility that the macros may not be defined when running the conversion outside of IntelliJ or other AsciidoctorJ integration. To avoid error use the {?…​} format when referencing the macro.

The system property intellij.asciidoctor.plugin and asciidocfx.asciidoctor.plugin are defined by the embedding environment. You can use this via the env macro to decide if the Jamal processor is running as an asciidoctor preprocessor.

will result in

You should use this macro only for very special purposes. Using this macro will result different output based on the different Jamal processor environment. Currently, there is no support to distinguish between IntelliJ and AsciidocFX environment.

The use case for the environment variable is executing external processors or retrieving expensive resources. Examples:

• A macro executing Mermaid or some other processing as an external tool may execute the external tool in an asynchronous way when running inside an editor. The external processing may finish later than Jamal finishes. In this case, the preview of the document will show a broken image until the processing is finished. The next time the preview is refreshed, the image will be shown.

  When the same code runs out of the editor, the external processing will be executed synchronously. The execution time of Jamal may be longer, but it does not affect an interactive user. On the other hand, it is guaranteed that the generated picture is there.

• Another example is retrieving a response from ChatGPT. Getting the response may take a few seconds or even minutes. When running inside an editor, the response will be retrieved asynchronously, and the preview will be available. This preview will show a message about the ongoing processing. This is better than freezing the rendering for long seconds.

  When running outside of the editor, the response will be retrieved synchronously, same as in the previous example.

You can alter the auxiliary functions of the extension using options. You can place these options into the document’s first line into a comment. If an option is defined for something controllable by configuration, then the option will take precedence.

or

You can place any of the options listed in the above example separated by spaces in any order.