See all blog posts
Moving to Antora, an open source solution for Open Liberty docs
Open Liberty recently moved to the open source Antora framework to generate and manage our docs. This post looks at the motivating factors behind this move: navigation, versioning, and community support.
What is Antora?
Antora is a multi-repository documentation site generator that offers unique solutions for some of the most prevalent challenges of writing, hosting, and maintaining meaningful docs. Docs in Antora are written in Asciidoc, a lightweight markup language that is similar to Markdown, but more flexible and better suited for technical documentation. Antora is designed on the premiss that writers want to spend their time writing, not fussing around with complex formatting or elaborate content management systems (CMS). The underlying simplicity of this framework appealed to our team and addressed some specific issues that we faced as our docs evolved along with the rest of the Open Liberty project.
New docs, new framework
Before our move to Antora, our doc site generator was a custom implementation based around Jekyll. We started with a relatively small doc set that consisted of a handful of concept topics and a streamlined reference section for features and configuration elements. The docs navigation was a simple alphabetical list that was autogenerated by the site build. At that time, the Open Liberty project was on a quarterly release cycle.
To provide faster updates for our users, Open Liberty soon accelerated to a four-week release cycle. As the pace of development increased, so did the volume of the documentation. Within the space of a year, the number of topics almost tripled and we enhanced our reference documentation with a collection of concise grab-and-go configuration examples. Before we knew it, our documentation family had outgrown its quaint apartment and was ready to move into a modern home.
Reaping the benefits
This faster release cycle resulted in the need to host and maintain a distinct version of the documentation for each release. And the larger collection of docs meant that our users needed better navigation. We also had to address some requirements that were specific to the structure and design of Open Liberty. We needed the flexibility to inject our own customizations into whatever framework we used. On each of these accounts, Antora presented novel solutions.
Meaningful navigation
Antora treats navigation as content. Site navigation is defined in a simple Asciidoc list that requires no special formatting. This approach makes it easy to update and maintain the navigation and to experiment with different navigation strategies. With Antora, breaking the navigation into meaningful sections and providing helpful cross-references to other areas of the Open Liberty site, such as our blogs and guides, was simple to configure. We were able to test different ideas and change them quickly when we found a better option. We modeled our updated navigation categories on the existing categories in our guides, with which many of our users were already familiar. As our docs continue to evolve, creating new categories or editing existing ones is as simple as adding and removing items from a list.
As our docs continue to grow, we need the flexibility to update their structure and organization. As with any doc set, we have to balance our efforts against our users habits and expectations. If we change the URL for a page, will we ruin someone’s bookmark to helpful information? The Antora page-aliases attribute provides a quick and easy way to set up page redirects. This was especially important for us when we moved to Antora. We needed a way to update our URL structure across the docs without disrupting our users' existing links. Page aliases were an elegant solution to the problem.
Versatile versioning
With a 4-week release cycle, new functions are constantly being developed, and with them, new documentation. The Open Liberty commitment to zero migration means our users must be able to move easily across runtime versions, mixing and matching features according to the needs of their applications. The documentation must support this flexibility by making it easy to find the relevant docs for any version.
Antora treats each version of the docs as a distinct branch in Git. Each new branch is created from the existing reference of the previous version so that only the updated content changes when a new branch is added. This approach makes it easy for our team to compare and manage the different versions of a doc. And for our users, moving between doc versions is as simple as selecting the relevant version from the version picker at the beginning of our sidebar navigation. Furthermore, the Antora framework provides flexibility with how different parts of the doc are versioned. We can easily integrate content that is not versioned with each release, such as Javadoc.
Flexible customizations
Another big draw for Antora is the ability to customize the framework to meet the needs of our documentation. Our docs mix together concept and task topics that aren written by our team with Javadoc and reference pages that are generated directly from the Open Liberty source code. The line between these two types of content is not always definite. We enhance our generated content with manually written examples and explanations. Content from multiple repositories can appear in the same section of our navigation, such as the overview topics in our reference section. The Antora multi-repository framework was flexible enough for us to design our own solution for integrating all this content, without having to build everything from scratch.
Antora supports a Docs as Code approach to documentation, wherein documentation is written with the same tools as code and managed from the same repositories. This framework means you can build your docs from multiple sources that are maintained in the same repositories as the code, rather than isolated in a content management system.
For Open Liberty, this was an important capability because it enabled us to manage different sections of our documentation, such as concept topics, Javadoc, and feature reference material, in a loosely coupled way. We can make changes and improvements to different aspects of the docs without having to overhaul the entire collection. It also enables us to build some of this content directly out of the source code files into its own repo, which makes troubleshooting and maintenance more straightforward. We can mix together content from these largely independent sources as we see fit.
A vibrant community
Thanks to the vibrant and helpful Antora community, we’ve received plenty of help along our journey and look forward to contributing back, whether with code or by answering other users' questions. The beauty of an open source project like Antora (and Open Liberty) is that nothing happens in a bubble and all participants can benefit from the network effect. New capabilities and bug fixes are added with each Antora release. We are happy to pass these benefits along to our users and share our own experience with the Antora community.
If you’d like to learn more about the specifics of the Antora framework, check this in-depth analysis from Matthew Setter: Antora 101: The Three Core Concepts You Need To Know To Use It Fully.
Thanks for joining us on our Antora journey, and for checking out our docs site. As always, if you have any questions or feedback, we’d love to hear from you.
