Antora

Antora helps to write and publish documentation web sites. It allows combining documentation from multiple repositories into a single website.

Each documentation component contains an antora.yml file with a common directory structure with meta information about that component.

Pre-Requisites

You need to upgrade to version 0.30.31 or later of the plugin. Initial support has been added in issue #373.

Detection of Antora

The plugin will activate Antora support once it finds a file antora.yml and a sub-folder modules. Antora will be active for all AsciiDoc files located in folders below such a file. Once the plugin detects Antora, it activates its Antora features.

Support provided by the plugin

Antora references support

When using the Antora xref macro like xref:version@component:module:page.adoc[], the plugin will resolve links to the specific version, component and module with in the current projects. For this it searches all available antora.yaml files in the current project.

For include::[] macros the plugin supports the Antora families like partial$, example$ and page$.

Antora editor support

In the editor the user can autocomplete filenames and references using Ctrl+Space and can navigate to a folder or file using Ctrl+B.

Antora YAML schema support

When editing an antora.yml or antora-playbook.yml file, the plugin provides JSON-Schema support for validation, auto-completion and documentation. Press Ctrl+Q for quick help on each attribute.

Antora preview support

The preview renders images, includes and links. It also resolves reftext and navtitle in the preview (new in Antora 2.3). The user can click on links in the preview that will then open in the editor if they link to a local Antora page.

Users can customize the styling of the preview by referencing a stylesheet. See section Using a remote stylesheet for details.

Antora attributes support

The plugin reads all attributes defined in the module’s antora.yml file’s asciidoc.attributes section and uses this for the preview and auto-completion.

The plugin sets multiple attributes to allow referencing files with the current Antora module:

imagesdir: pointing to images of the current module (or assets/images, the Antora pre-2.1 style, if that folder exists)
partialsdir: pointing to partials of the current module (or pages/_partials, the Antora pre-1.1 style, if that folder exists)
attachmentsdir: pointing to attachments of the current module (or assets/attachments, the Antora pre-2.1 style, if that folder exists)
examplesdir: pointing to examples of the current module
page-*: These and several other intrinsic attributes are supported for the preview like page-component-version, page-module etc.

Any of these attributes is set only if the directory exists. While imagesdir and attachmentsdir use a relative path so that they work best with image and link macros, examplesdir and partialsdir use an absolute path that works best with includes macros.

Examples of supported Antora syntax

// images from the assets/images folder - no prefix necessary as imagesdir attribute is set
image::animage.png[some image]

// offer downloads
link:{attachmentsdir}/file.zip[Download]

// include content into a page
include::partial$some-recurring-content.adoc[]
include::{partialsdir}/some-recurring-content.adoc[]
include::component:module:partial$some-recurring-content.adoc[]

// include snippets from examples
[source,java]
----
include::example$test.java[tags=e1]
include::{examplesdir}/test.java[tags=e1]
include::component:module:example$test.java[tags=e1]
----

// reference documents in the same module
xref:mail-component.adoc[SMTP]

// reference documents in a different component and module
xref:component:module:mail-component.adoc[SMTP]

Example projects

Antora: Site: https://docs.antora.org/
Source code: https://gitlab.com/antora/antora/-/tree/master/docs
Apache Camel: Site: https://camel.apache.org/manual/latest/
Source code: https://github.com/apache/camel/tree/master/docs/user-manual
Apache Camel Kafka Connector: Site: https://camel.apache.org/camel-kafka-connector/latest/
Source code: https://github.com/apache/camel-kafka-connector/tree/master/docs
Debezium: Site: https://debezium.io/documentation/reference/index.html
Source code: https://github.com/debezium/debezium/tree/master/documentation
IntelliJ plugin for AsciiDoc: Site: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/index.html
Source code: https://github.com/asciidoctor/asciidoctor-intellij-plugin/tree/main/doc