The Static Site Generator for Tech Writers
|Antora 1.0.0-beta.2 is now available! See the CHANGELOG for details.|
Antora is designed to make it easy for tech writers to publish documentation to the web. As a tech writer, you simply author content in AsciiDoc, Antora’s preferred markup language, then save those files under a standard project structure in one or more content repositories. Antora picks up your content from there and transforms it into a website. That’s all there is to it!
Antora’s generator pipeline is a complete end-to-end solution for publishing. While it can be extended, no additional scripts are needed.
Antora’s generator pipeline kicks off by aggregating files from a variety of sources. Currently, these sources can be branches of one or more git repositories and a UI bundle.
Next, Antora organizes the files into catalogs. It then uses Asciidoctor to convert all content files to embeddable HTML and resolve links between pages.
Once conversion is complete, Antora passes the embeddable HTML as part of a UI data model to Handlebars templates provided by the UI bundle to create the web pages.
Finally, it publishes the pages and supporting content and UI assets to one or more local or remote destinations, where they can be viewed as a website.
Antora’s built-in orchestration makes it very CI-friendly. All the CI job has to do is prepare the environment and launch a single command, and out comes your site!
While it’s considered a best practice to split source code into discrete, well-defined modules, documentation for that code often gets lumped together into one massive book. This situation has brought many documentation projects to a grinding halt.
By treating docs as code, the documentation process can benefit from the best practices that produce successful software. Antora helps you incorporate these practices into your documentation workflow.
Antora’s generator pipeline favors a modular approach to managing documentation. It consists of a playbook project, content repositories, a UI bundle, and the generator software, all of which are discrete parts. The playbook project controls how Antora generates and publishes your site, but it does not own any content itself.
The separation of these parts keeps the configuration separate from content. The content repositories just contain content. They can be enlisted, per branch, into the site generation process.
This strategy makes it possible for content branches to be reused, substituted, deactivated, or archived. This is a sharp contrast to many other site generators, which intermix all these concerns, making the documentation difficult to manage, maintain, and enhance.
If you’re ready to set up a new documentation project or migrate an existing one to use with Antora, start by organizing your documentation for Antora.
If you want to dive deeper into the details of the generator pipeline, check out how Antora works.