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
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. |
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 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 (orassets/images
, the Antora pre-2.1 style if that folder exists) - partialsdir
-
pointing to
partials
of the current module (orpages/_partials
, the Antora pre-1.1 style if that folder exists) - attachmentsdir
-
pointing to
attachments
of the current module (orassets/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]
----
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