Docs as code with AsciiDoc and Antora

Documentation rots for a predictable reason: it lives somewhere engineers don't. When the docs sit in a wiki and the code sits in git, every release creates a gap that someone has to remember to close. Under deadline pressure, nobody does.

Docs as code closes that gap by moving documentation into the same workflow as the software it describes. The docs live in git, right next to the code when that's useful. Changes arrive as pull requests and get reviewed like code. A CI pipeline builds and publishes the site, so the published docs are exactly what's on main, not what someone last remembered to paste into a wiki.

This documentation set is the playbook we wish every team had when they made that move, built on two tools that are made for it:

AsciiDoc: a plain-text writing format with the features technical documentation actually needs, including content reuse through includes, single-sourcing through attributes, and cross-references the toolchain can validate.
Antora: a static site generator designed for multi-repository, multi-version documentation. It pulls content straight from your git branches and assembles one coherent site, so "document version 2.0 and 3.0 side by side" stops being a copy-paste problem.

Who this documentation is for

This documentation is for you if:

You own documentation for a product that ships versions, such as a server, a library, an API, or an appliance.
Your docs currently live in a wiki, a shared drive, or a SaaS editor, and keeping them current is a recurring failure.
Your contributors are comfortable with git, or sit next to people who are.
You want a documentation platform you can review, diff, automate, and leave without an export ticket.

What you'll find here

When to adopt docs as code: a decision-maker's overview. What the workflow buys you, what it costs, and how it compares to the wiki and SaaS alternatives.
Your first Antora site: a tutorial that takes you from an empty directory to a built documentation site in about 45 minutes, with the standard layout you'll keep forever.
Publish the site with GitHub Actions: the automation how-to. Every merge to main rebuilds and republishes the site, with broken cross-references failing the build instead of shipping.
Version your docs with branches: how to publish several product versions from git branches without copying files, and how to backport a fix with a cherry-pick.
antora.yml and playbook keys, annotated: the configuration surface (component descriptor, playbook, and resource IDs) with the behavior each key actually controls.
How Antora assembles a site: the aggregation model underneath it all, why it's built that way, and where the model creaks.

How to read this information

We've written these pages using the Diátaxis style, which consists of the following types of information:

Tutorials: you learn by doing
How-tos: you solve a specific problem
References: you look something up
Explanations: you understand the why

Every page tells you, in its opening sentence, what type of document it is.

If you're evaluating the approach, start with the overview. If you've already decided and want working software, the tutorial is the fastest path. If your team adopted Antora before you arrived and you need to know what start_path does, the reference has you covered.