Antora
I had to try Antora after seeing its tagline: "The multi-repository documentation site generator for tech writers who love writing in AsciiDoc."
I was so please with it, I used it for this portfolio site! Compared to Flare and Hugo, it stands out with how it leverages Git and AsciiDoc to scale docs with ease.
Structured configuration
Antora’s project structure is strict, which is actually a strength. It requires you to have separate repositories for your content files, build configuration, and site’s theming. This enforces commits to occur in their own context, making complex projects easier to compartmentalize. Edits to your antora-playbook.yml, for example, won’t show up in a PR that updates feature docs. While there’s a slight learning curve to adopt Antora’s conventions, it’s worth it to have distinct separation of concerns.
Since Antora sources content from repo URLs, Git becomes a powerful tool in your deployment pipeline. For example, I’ve configured this project to deploy feature branches according to a pattern search for 'feature/*.
content:
sources:
- url: https://github.com/technicallyawriter/portfolio-docs.git
branches: [main, "feature/*"]New branches with the feature/ naming convention are generated in the next build. Deleted feature branches are removed.
👈 Click the version toolbar in the lower-left corner of the screen to display the feature-abc and feature-xyz branch prerelease content (-alpha).
Easy scaling
Want to add new projects to your docs site? Just add the Git repo to the sources block in your antora-playbook.yml, specify a branch, and add a nav.adoc file. Once configured, it’s included in the next build. This "hot-swapping" of repos lets you handle sources in a single configuration file.
AsciiDoc over traditional Markdown
AsciiDoc is the native syntax in Antora. In fact, Antora’s lead maintainer (Dan Allen) is also the Asciidoctor project lead!
Traditional Markdown is wonderful in its simplicity, but it’s underpowered for large documentation projects. AsciiDoc is as readable as Markdown but with a much richer feature set geared toward tech writing. Two of my favorite AsciiDoc features are directives that help with content reuse and single-sourcing docs, respectively: \includes::[] and ifdef[].
Includes
The \includes:: directive makes including other files a simple one-line call. This makes creating modular docs easy, as you can just include smaller files on a page. It’s my favorite AsciiDoc feature and changes the way I write my docs.
Antora builds on this feature with its family directories. Example, attachments, images, and partials are their own "family" which means they have their own default root locations. This make sourcing specific content intuitive and predictable. For example, relative paths can turn ugly at a certain port: \include::../../../../../feature-xyz/modular-xyz.adoc. With Antora’s family directories, you can reference the family’s root directory (in this case "example$") for a cleaner path: \include::example$/feature-xyz/modular-xyz.adoc.
Conditional directives
Conditional directives in AsciiDoc help filter content based on a defined (or not defined) attribute. This concept, first introduced in C programming, provides the ifdef and ifndef directives respectively. For tech writers, these commands help single-source docs that need to differentiate between online vs. print content or output for a specific audience.
Here are two common examples that use the ifdef directive to "hide" administrator and internal admonitions unless you specify the attribute explicitly.
== Feature xyz
Introduction to feature xyz...
ifdef::admin[]
[IMPORTANT]
.Administrator note
This information is relevant to administrators.
endif::admin[]
ifdef::internal[]
[IMPORTANT]
.Internal note
This section is for internal eyes only.
endif::internal[]To build output that includes these audiences, you can set the desired attribute in your antora-playbook.yml or with the --attribute option via the command line: npx antora --fetch --attribute=admin antora-playbook.yml
Versioning
Producing versioned docs can be tough. It can involve a lot of duplicated docs in nested folders and manual linking. With Antora, version is explicitly managed within the your antora.yml file and built out automatically. Since each repo referenced in your antora-playbook.yml contains an antora.yml file, delivering versions is a question of how you configure your antora-playbook.yml. This keeps your project size from ballooning and centralizes your management of version within a few files in the same tool.