Working with Antora

Antora helps to write and publish documentation websites. 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

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

The plugin detects Antora playbooks by their name. The filename antora-playbook.yml would be detected as an Antora playbook, as well as any other file that ends with .yml and contains both words antora and playbook. For example, antora-playbook-author.yml would be treated as an Antora playbook as well, while antora-localpreview.yml would not be treated as an Antora playbook.

Support provided by the plugin

Antora stylesheet for the preview

Once the plugin detects that a page is part of an Antora module, it uses the Antora CSS theme for the preview (starting with plugin version 0.37.7). The preview will be in light or dark mode as configured in the plugin’s settings.

To configure an individual stylesheet from a remote site, users should create an .asciidoctorconfig file like the following in the root or documentation folder of their project:

:linkcss:
:stylesdir: https://docs.mysite.com/_/css/
:stylesheet: site.css
asciidoc

If the remote stylesheet is not available due to an unreachable server or a missing stylesheet, the preview will default to the standard stylesheet.

For more information see the chapter Custom stylesheets for the preview for details.

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

Using Antora page families and includes works in the preview only for trusted project and when IDE is running in the default UNSAFE mode. Otherwise, Asciidoctor will not be able to include files outside the document’s root folder.

The plugin validates all references to files within the same component, and also across components.

Antora component and module name validation

Validation of component and module names requires plugin version 0.37.23 or later.

The plugin validates the referenced component and module names. If they don’t exist, it will highlight this as an error in the editor window.

If a reference includes a version, the module name is only validated if the version and the component exist within the current project. If they don’t exist, it skips this reference for validation, as the plugin assumes this component to exist in a different branch that isn’t checked out in the current project.

For this to work, all components of the Antora site need to be opened in one IntelliJ project. If this isn’t suitable in a given setup, suppress the inspection for a given reference, or disable the inspection in the IDE’s setting for the given project.

Example how to disable the inspection for a single reference
// suppress inspection "AsciiDocUnresolvedAntoraModule"
xref:othercomponent:othermodule:index.adoc[]
asciidoc

To learn more about how to bundle multiple Git repositories as one IntelliJ project, see the chapter on multi-module projects for details.

Antora editor support

In the editor, the user can autocomplete filenames and references using Ctrl+Space ^ Space and can navigate to a folder or file using Ctrl+B ⌘ 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 a component descriptor (antora.yml) or playbook (antora-playbook.yml), 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.

Starting with release 0.35.2 of the plugin, it also picks up attributes from an Antora playbook if this is within the same project. If the playbook and the components are in different Git repositories, this requires a multi-module project.

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.

Antora Collector Extension support

This is new in plugin version 0.38.6.

Follow asciidoctor/asciidoctor-intellij-plugin#1177 for updates on this feature.

The Antora Collector Extension allows content that is not checked into a Git repository to be used as a source for an Antora generated site. The generated content has a higher priority than the checked-in content, so that it overrides and existing content at build-time. When the command generates an antora.yml file in the root folder the scanned directory, those properties overwrite the properties in the component descriptor.

From a writer’s point of view, the following features are supported:

  • Attributes and other information from a generated antora.yml file overwrites the component’s antora.yml settings.

  • Generated resources like pages, partials and images are available for auto-completion and validation. Filtering generated contents via the property scan.files is not supported, yet.

This table displays which properties are supported by the plugin:

Property Supported? Comment

run.*

no

The plugin won’t run the generators. Writers should run them from the command line as and when needed.

scan.dir

partially

The directory with the contents generated by the run command. To be supported by the plugin it must start with a ./ meaning this directory is relative to the antora.yml file.

scan.base

yes

The folder where the plugin places the contents of the scanned directory.

scan.files

no

At the moment, the plugin will scan files in the scan.dir folder. A future version of the plugin will support this. Follow the GitHub issue asciidoctor/asciidoctor-intellij-plugin#1177 for details.

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]
----
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]
asciidoc

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