Using Antora with IntelliJ
How to set up IntelliJ for writing content for Antora, the static site generator for AsciiDoc content.
This is part of the step-by-step series to set up a technical writing environment with IntelliJ and the AsciiDoc plugin. See the page Setup for technical writing for an overview of all steps.
Why to use Antora
Antora is a static site generator that pulls AsciiDoc content from multiple Git repositories, converts it to HTML, and applies a custom multi-page theme to the output. The result can be hosted on any web server. All content is grouped into components which have a name an optional version identifier. The user of the published site can then choose the component with the version they are interested in, navigate from page to page and use an optional full-text index.
This documentation of the AsciiDoc plugin for IntelliJ is maintained in an Antora structure and published using Antora, so it can serve as one possible example what the result can look like. To find out more about Antora, visit the Antora homepage and read the Antora docs.
There’s a 20-minute summary about Antora’s concepts plus a demo of IntelliJ in a talk at the conference FOSDEM 2020 by the author of this plugin: Creating a documentation site for users with AsciiDoc and Antora.
What to learn on this page
This page describes how to:
Using Antora with one or multiple content repositories with IntelliJ.
Enabling navigation between components in different repositories.
Configuring the preview to use a stylesheet that makes it look like the published site.
This assumes that IntelliJ IDEA is already installed on the PC and a project is open. See Installing IntelliJ for technical writing and Opening a project in IntelliJ IDEA.
The following sections assume that the reader knows about the concepts of Antora. Use the links in the previous section to learn about the concepts.
For those new to Antora, it would be good practice to start with the Antora Quickstart to try out Antora on the command line before continuing with this page.
To set up the playbook repository, basic knowledge of Node and npm is required. If such a setup already exists, such a project can be added to the local IntelliJ development environment without knowledge about Node and npm.
With the long list of prerequisites, this is an advanced topic. To set up these features, some proficiency with IntelliJ and the command line is beneficial. After the setup is complete and each file has been committed and pushed to the repository, those features will work for all other contributors with minimal additional setup.
Users new to IntelliJ and Antora should consider trying out these features with another IntelliJ user.
Basic structure of an Antora setup
A standard setup consists of one or more repositories storing content in Antora components plus one repository with an Antora playbook and the theme.
The following sections give a high-level overview of these repositories to the extent needed to describe the IntelliJ setup later on this page. They also provide pointers to best practices.
Outline of an Antora content repository
Each component has at least an
antora.yml file with the name of the component, plus a module folder.
The default module is named
📒 my-content-repo └─📒 docs (1) ├─📄 .asciidoctorconfig (2) └─📒 my-component ├─📄 antora.yml (3) └─📂 modules ├─📂 ROOT │ ├─📂 attachments │ ├─📂 examples │ ├─📂 images │ ├─📂 pages │ │ └─📄 index.adoc (4) │ ├─📂 partials │ └─📄 nav.adoc └─📂 a-named-module └─📂 pages
|1||The components can be located in one or more sub-folders in the content repository as defined in the playbook.|
|2||Configure additional attributes for the preview in the IDE in an
|4||Each page is a single AsciiDoc file in the
antora.yml file defines at a minimum the name of the component.
title: My component name (1) name: my-component version: '1.0' (2) nav: - modules/ROOT/nav.adoc (3) asciidoc: attributes: (4) my-attribute: 'my-value' another-attribute: 'another-value'
|1||The title is optional and defaults to the name of the component.|
|2||The version is optional and can be determined by rules specified in the Antora playbook from the branch or tag name.|
|3||Zero or more navigation files determine the navigation outline for the component.|
|4||For each component, attributes can be defined. Site attributes are defined in the Antora playbook which is described in the next section.|
Some of this can be seen in action in this project’s GitHub repository.
Outline of an Antora playbook repository
This outline lists common files and their purpose in a playbook repository. Depending on the setup, there might be additional files, and some of them might have other names.
The following assumes that the version of Antora and its plugins are managed via a
package.json file and the npm package manager.
📒 my-playbook-repo ├─📄 antora-playbook.yml (1) ├─📄 antora-playbook-author.yml (2) ├─📄 package.json (3) ├─📄 package-lock.json (4) ├─📄 ui-bundle.zip (5) ├─📄 README.adoc (6) └─📂 supplemental_ui (7) ├─📂 css │ └─📄 preview.css (8) └─📂 partials ├─📄 footer-content.hbs └─📄 header-content.hbs
|3||As Antora is based on Node, a
|4||For the packages specified in
|5||The standard theme for the site can be stored in a ZIP archive in the repository, or in a remote location specified in the playbook.|
|8||A CSS file for the preview in the IDE is optional, and can be added via the supplemental UI. See Using the site’s CSS in the preview for details.|
An example playbook file could look as follows:
site: title: My example site url: https://example.com (1) start_page: my-component::index.adoc content: sources: - url: https://github.com/example/conent start_paths: - doc/my-component - doc/other-component branches: - 'main' ui: bundle: url: ui-bundle.zip snapshot: true supplemental_files: supplemental_ui output_dir: antora runtime: fetch: true cache_dir: ./.cache/antora log: failure_level: error (2) output: clean: true dir: _site/docs asciidoc: attributes: (3) global-attribute: 'global-value'
|1||The 404, site-map, and canonical urls are only generated when am URL is defined.|
|2||This option ensures that the build-process exits with an error code if, for example, cross-references are broken. This will make a continuous integration build fail, which usually triggers a notification to the technical writer.|
|3||Global AsciiDoc attributes used across all components.|
To generate an author’s preview, the file is similar. The only difference is that instead of pointing to a remote Git repository, it points to a local relative URL instead.
site: # ... content: sources: - url: ../my-content-repo (1) start_paths: - doc/my-component - doc/other-component branches: - 'HEAD' (2) # ...
|1||Use a relative path to point to a local checked-out Git repository with the author’s modifications checked out.|
|2||Instead of specifying a branch or tag, only list
Some of this can be seen in action in this project’s GitHub repository for the playbook, although it contains a lot more than this.
Using IntelliJ to work with an Antora setup
As described above, the setup contains multiple Git repositories.
The recommended setup is to check to create one parent folder and then check out all Git repositories as sub-folders of the newly created folder.
📒 parent-folder ├─📒 my-playbook-repo │ ├─📄 antora-playbook.yml │ └─📄 ... ├─📒 my-content-repo │ └─📒 docs │ └─📒 my-component │ ├─📄 antora.yml │ └─📂 modules │ └─📂 ... └─📒 other-content-repo └─📂 ...
To render the preview and allow navigation between components, the IDE would need to know about all components, and also the playbook to know about attributes defined there.
Depending on how many content repositories exist and how many attributes are defined in the playbook, there are two different setups:
Single content repository and only a few AsciiDoc attributes in the playbook
This is a simple scenario, and it allows the user to open only the single content repository in IntelliJ. The folder structure described above is still recommended for generating the author’s preview, so that the author’s playbook can use a relative path to the local sandbox of the content repository.
When the user opens only the content repository, the IDE doesn’t know about the attributes defined in the Antora playbook.
To let the IDE know about the attributes in the playbook and to show a preview similar to the real site, add an
.asciidoctorconfigfile in the content repository as outlined in Outline of an Antora content repository and duplicate the attributes of the Antora playbook in this file. See Provide hints for the preview with
.asciidoctorconfigfor more details.
If there is more than one content repository, the downside of this approach it that the IDE can’t follow navigation links to components outside the repository. Also, the page titles of those navigation links won’t be rendered in the preview. See the next section on how to avoid this.
Multiple content repositories or a lot of AsciiDoc attributes in the playbook
To avoid duplicating the attributes from the Antora playbook in multiple content repositories, the content repositories can be opened together with the playbook repository in one project.
Here the user opens the parent repository.
In this setup, the IDE can read all AsciiDoc attributes from the playbook, and they don’t need to be duplicated in an
.asciidoctorconfigfile. The IDE also knows about all components, so auto-completion and validation for cross-references work as expected. All page titles for those cross-references are also correctly rendered in the preview.
In this scenario, the Git toolbox window shows the history of all Git repositories in the sub-folders of the parent folder.
See Multi-module Projects for an alternative setup without a parent folder.
The tradeoff: Users might struggle with this approach, and would want to open only a single repository as they usually do. Such a scenario might be where the Antora content is stored side-by-side with source code or other information stored in the repository. If there are only few cross-references between the components, checking out other content repositories is seen as an unnecessary overhead, and checking out the playbook repository is a nuisance.
In such a situation, it might be simpler to duplicate the playbook’s attributes in an
.asciidoctorconfigfile, and authors would rely on the IDE’s preview to prepare their changes. See Author preview in the IDE for details.
Using the site’s CSS in the preview
To use the site’s CSS in the preview, perform two steps:
preview.cssfile in the published site. This can be added via the
supplemental_uias described in the Outline of an Antora playbook repository.
preview.cssfile in the
.asciidoctorconfigfile as an external CSS file as described in the Outline of an Antora content repository.
This can be seen in action for the documentation of this plugin in the
preview.css file in the playbook repository and the
.asciidoctorconfig file in the content repository.
See Custom styling for the preview for details on how to do this.
To read more about Antora, continue with Decisions around Antora which describes areas for decisions and different solutions for different scenarios.
Continue to Recommended Plugins for Technical Writing for the next step of this series.