How Antora Can Help You and Your Team

Automate the assembly of your secure, nimble static site as changes happen instead of wrestling with a CMS giant.

Rebuild and deploy your site automatically in a matter of seconds in response to any change. Never have to worry about patching security holes in your deployed CMS application since you don’t have one. All pages are static—​in the JAMstack style. Need to migrate your site to a different domain? Just rebuild the site and relaunch it on the new host.

Adapt your site to fit seamlessly with your other web properties.

No site is an island. Sites must play nice with others to maintain a consistent brand and user experiences. Static sites generated by Antora are well-suited for this role. With page templates and a little help from an automated process, you can blend your documentation pages into existing sites, giving the impression it’s all part of a single uniform site.

Use a git-based CI workflow to manage documentation changes, contributions, and initiatives.

Go where the development is. Whether it’s GitHub, GitLab, Bitbucket, or another code hosting service, you can tap into these platforms to develop Docs as Code. Not only does a git-based CI workflow give you collaboration and review tools for free, it also encourages collaboration to happen across teams. As a result, the docs become part of the software development process. And that means many more people feel ready to support the effort to improve the docs.

Manage teams and permissions by leveraging existing development infrastructure.

Chances are, your software product already has a well-defined team, permission structure, and contributor community. You can use the same organization or build on it to manage your docs team. These platforms can serve as an administrative and management interface for your docs, whether it’s to monitor activity or grant access to perform certain actions.

Describe what you want to make and Antora takes it from there.

Antora was built for writers first. Writers want to write, not fiddle with reconfiguring software. That’s where Antora’s playbook comes in. A playbook is a concise way to describe the site you want to produce. This description boils down to a) where to get the content, b) what UI to apply to the pages, and c) where to publish it. That’s all Antora needs to know to do its job. Only when you’re looking for additional customization do you need to dive deeper.

Offline first.

A site generated using Antora can be viewed entirely offline. All the references in the site are self-contained (i.e., relative), so you don’t need to run a web server to view it. Just open one of the generated HTML files in your browser and from there you can navigate to all the pages from the UI. Even redirects work offline by default. If a web server is available, you can pass additional configuration to tell Antora to take advantage of its capabilities.

Use a single build to aggregate documentation that spans repository boundaries and branches.

Most site generators are confined to a single branch of a single repository. Antora, on the other hand, knows how to speak git. It goes out and gathers up all the content the site needs using its built-in git client. It then sorts through the files by separating them into versions of components. This allows you to store the documentation in a way that works best for your organization, whether it means keeping content with code or using separate repositories. Antora can round up all those disparate projects and repositories and create an integrated site.

Pick and choose content to handcraft your site.

You won’t always want to include everything in the site. Sometimes, you just want to build a “microsite” that includes a reduced selection of products or versions. Or perhaps you just need to preview the documentation for the product you’re currently working on. The playbook lets you produce multiple variations of a site from the same content sources simply by tuning which sources you draw from.

Build each version of the product as part of one site.

Since software is versioned, the documentation for it needs to be versioned too. Otherwise, users won’t know which version of the software the documentation they’re reading covers. Confusion ensues. Like with software, you can use branches and tags to manage versions of the documentation. This content can even be stored with the software itself. Antora happily gathers all this content and organizes it so users can access each version of the documentation, all under a single site.

Explore different product versions or navigate between pages across versions.

With multiple versions of documentation available, the user needs a way to navigate to them. Antora provides a catalog of documentation components and versions that are presented to the reader as a menu. The reader can scan the menu and jump right to the version of the documentation they need. Additionally, each page can self identify as being part of a version sequence, allowing the user to quickly visit older or newer versions of the content on the page.

Document using an intuitive syntax designed specifically for technical documentation that’s lightweight, yet comprehensive.

When you write documentation, the last thing you want getting in your way is the markup syntax. To create the best content, you need to be able to see what you’re writing, but still be able to represent different content types appropriately. That’s exactly what AsciiDoc affords. Its line-oriented, left-aligned syntax is easy to browse and leaves room for applying just enough metadata to build a semantic structure. AsciiDoc is a documentation writer’s best friend.

Keep your content DRY using reusable attributes, includes, and syntax extensions.

Every time you type something you’ve typed before, you’re losing efficiency and introducing the risk of divergent content. AsciiDoc provides several tools to keep you from having to repeat yourself. You can use attributes to avoid having to type URLs, product names, or definitions multiple times. You can use includes to extract whole paragraphs, sections, and other reusable content to common files. And you can introduce extensions to the syntax to reduce commonly repeated patterns, such as references to an issue tracker, or new types of content, such as equations and charts, to shorthand.

Pages are simply AsciiDoc documents that can be edited in any text editor.

Creating a page in the documentation is as simple as creating an AsciiDoc document. The document can be opened and previewed in a text editor, or it can be viewed in the context of the site. Antora assigns the page an implicit ID so it can be referenced from other pages, and it can reference other pages using the implicit ID of those pages. Features such as section titles, admonition blocks, and highlighted source listings are styled appropriately.

Create references between pages and other resources using a source-to-source xref system that’s concise and easy to construct.

Instead of relying on generated filenames or URLs, you create references between pages and other resources using the location of the target in the source system. This makes reasoning about references easy since you only have to think about where the source file is located, not how it gets processed. In other words, you stay in the source coordinate system. And you get the benefit of the context of the current source file, so you only need to specify the traits of the target that differ from the current context.

Source-to-source references provide the necessary information to decouple the site from the filesystem and publishing environment.

By expressing a reference using a resource ID, Antora can intelligently create a link to the resource in the published output that isn’t coupled with the filesystem or publishing environment. That means the generated site can be viewed anywhere, including offline.

Describe the documentation navigation using AsciiDoc lists.

Writers using Antora can feel right at home when defining navigation. Why? Because, like pages, the navigation is just another AsciiDoc document. But instead of free-form content, the navigation file contains a list hierarchy that gets translated into the navigation trees you see in the navigation menu sidebar. To add another navigation tree, you simply add an additional list.

Create navigation links using the same xref system that’s used in the main content.

So how do you create a link to a page from the navigation? Using an xref, of course. Since the navigation file is just content, it can use the same xref system that’s used by the main content to create links between pages. Think of a navigation file as a page that doesn’t get published. And since the file is stored with the content, the xrefs can be contextual, meaning you only have to specify the traits of the target that differ from the current context.

The site’s user interface and theme is maintained separately from the content.

A key theme in Antora is separation of content and presentation. This is prominently seen in the UI. Antora interfaces with a site UI that is stored and managed as a separate project. It passes a UI model to a Handlebars template that the UI provided. The template then decides what to display from the model, giving the UI full control over the page layout. The template also decides what CSS and JavaScript to include.

Iterate on the UI independently from the content.

Since the UI and content are maintained separately, they can follow different release cycles. And no toes get stepped on. The work done on the UI does not interfere with the work done on the content. When Antora runs, it fuses the latest content and the latest UI together. This means it’s easy to swap one UI and theme with another, which can be useful for redesigns, A/B testing, or campaigns. You have maximum freedom to tailor the UI and its theme(s) to your needs.

Retain URLs of old pages in a transparent way by storing the information in the target document.

Change happens. You just need to be ready to deal with it. One of the most frequent changes in a documentation site are the URLs of pages, which change as the pages get renamed or reorganized. Antora provides a way to retain the URLs of old pages by declaring page aliases. Like other features in Antora, this information is stored with the content, in this case in the header of the target AsciiDoc document.

Redirects are described using aliases, which are simply inbound xrefs; not coupled to URLs.

As you might expect, a page alias is a source reference, which allows Antora to take care of creating the redirect from the correct URL. Since not all hosting environments are the same, the facility for performing a redirect isn’t either. Antora generates the appropriate configuration for the redirect facility that the hosting environment provides, falling back to good old-fashioned static bounce pages if no other mechanism is supported.

Publish anywhere, whether local or remote.

Sites are meant to be published. Antora helps with that. Whether the destination is local or remote Antora streams the content there using a built-in or custom provider. And yet, no matter where the site is published, the site is not coupled to the host environment. Antora supports as many output streams as you want, which could be a local directory, a local archive, a directory on a remote SSH server, or a web service endpoint like S3, or a combination of destinations. You can be sure Antora gets the files where they need to go for publishing. All in a single build.

No need for a separate step, tool or script in the pipeline.

Antora’s site publisher saves you a step in the pipeline. Most site generators write the output to a local directory, which you then have to turn around and publish. Antora sends the output directly to the destinations you specify. And since the references in the site are not coupled to the publishing environment, you can even preview the site offline by publishing it to a local directory.

Start with the default.

Antora offers an opinionated site generator and UI out of the box so you can get up and running quickly. You interface with the site generator using the antora CLI command, which you can install yourself or invoke using the Docker container. Just point the command at your playbook and Antora kicks out a multi-component, multi-version documentation site for you. Once you’ve had a chance to set up or migrate your documentation for use with Antora, you can graduate from the defaults and start tailoring Antora to fit advanced requirements.

Tailor Antora just for you.

Antora features an open architecture. What does that mean? It means you have the ability to teach Antora new tricks. Perhaps you need to incorporate additional content into Antora’s catalog. Or maybe you want to perform custom processing somewhere along the line. You can even introduce your own behavior to reconfigure Antora to fit your needs. Antora was designed so you can use it as a foundation when the default site generator pipeline doesn’t suit you.