Services / Antora

Antora and Docusaurus Static Documentation Sites

I build, migrate and maintain documentation sites using static site generators, and can analyse which is the best fit for your documentation needs. These sites are built from static files, generated using AsciiDoc or Markdown. This way they load fast and are cheap to host, with no need to worry about complex software.

Antora or Docusaurus?

  • Antora is better suited to larger projects, where documentation spans several repositories and may need to be adapted for multiple product versions. Based in AsciiDoc, this is my primary tool.
  • Docusaurus is a Markdown-based builder that suits lighter projects more. Having previously built Docusaurus sites of my own, I know this process too, and it is very similar.

The Process

  • I establish the structure of documentation you need, and choose the tool based on that.
  • I build the initial structure. For example, writing your Antora playbook, or your Docusaurus config.
  • Working with your designer, I use CSS to adapt the site's UI to seamlessly match your branding.
  • I add search and navigation tools, such as Lunr search for an Antora site.
  • I write the CI/CD publishing pipeline, to create the self-generating site.
  • I write AsciiDoc conventions and templates for engineers and maintainers to use after the project is finished.
  • I fit the pipeline into your existing web hosting system.

After I'm done, you will have a build system that any developer or engineer can run themselves.

Multiple versions from one site

Antora can publish several product versions side by side, and your site can include a switcher so readers can choose the docs that match their version. Each version lives in its own Git branch, and can be added from the Antora playbook:

content:
  sources:
  - url: https://example.com/your-org/docs.git
    branches: [main, v2.0]

I became familiar with this at GraphAware, which is also where I first learned Antora.

Example: a multi-repo Antora site at Kaptio

At Kaptio, I used Antora to build a new public-facing documentation site. I wrote the playbook, which pulled from four repositories, including the landing page, release notes and metadata, bringing them together for one site. It also used Lunr for search. My manager and I updated the UI, with input from marketing, and the company's System Architect handled the final deployment step.

In the end we created an easily navigated static documentation site, built automatically from Git. You can read more about the pipeline behind it here.

A cohesive docs-as-code site

No matter the tool, the result is a clear, navigable website. The landing page and content are wrapped in a UI that fits your brand design, and the site is fast, lightweight and responsive.

Related: Docs-as-code CI/CD pipelines · Confluence to AsciiDoc migration

Want to discuss an Antora project? Contact me here!

Email All services