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.

Auto-complete in antora.yml files was implemented starting with plugin version 0.32.54.

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.yml 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.

To allow auto-completion for components that reside in different Git repositories, consider using a multi-module project.

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.

For the keys nav and start_page in antora.yml, the plugin provides auto-completion.

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