Antora is an open-source, multi-repository documentation site generator built on AsciiDoc rather than Markdown. Its signature strength is pulling content from many separate git repositories and branches into one unified, versioned docs site. If you run a product with a dozen services, each with its own repo, Antora stitches those into a single site with a shared navigation and version selector. That is a different job from most static site generators, which assume one folder of files.
This review covers what Antora is, who builds it, how the content model works, setup, features, honest pros and cons, and who should pick something else. Because Antora leans on AsciiDoc, the AsciiDoc vs Markdown comparison is worth a read first if you are deciding on markup. For the versioning angle specifically, see our guide to documentation versioning, and for the workflow philosophy behind tools like this, docs as code explains the model Antora assumes you already follow.
What is Antora?
Antora is a documentation pipeline. You point it at a set of git repositories, and it aggregates the AsciiDoc files inside them, applies a theme, and produces a static HTML site. The project reached version 3.1 and is maintained by OpenDevise, the team behind the wider Asciidoctor ecosystem. It runs on Node.js, so the toolchain is npm install and a command-line generator.
The core idea sets Antora apart from Markdown-first tools like MkDocs Material or Sphinx. Those expect your docs to live in one place. Antora treats content as distributed by default. Each team owns the docs that sit next to their code, and Antora composes the pieces at build time. For large engineering orgs, that ownership model is the whole reason to use it.
How Antora works: the content model
Antora organizes content into four concepts. Once these click, the rest of the tool makes sense.
- Components are the top-level units, usually one product or service. A component gets its own section in the site navigation.
- Versions map to git branches or tags. A component can ship v1.0, v2.0, and a
mainbranch side by side, each a selectable version. - Modules group related pages inside a component. Think of them as subsections.
- Pages are the individual AsciiDoc files that hold the actual content.
A single configuration file, the playbook, lists every source repository, the branches to pull, the theme (called a UI bundle), and the output target. Run the generator against the playbook and Antora clones each source, reads the component descriptor in every repo, resolves cross-references between components, and builds one site. Cross-repo links survive because Antora uses a resource ID scheme instead of relative file paths.
Antora vs typical Markdown site generators
Most static site generators solve a narrower problem than Antora. This table shows where the lines fall.
| Factor | Antora | Docusaurus / MkDocs |
|---|---|---|
| Content source | Many git repos, aggregated | One repo, one docs folder |
| Versioning | Native, branch-based, built in | Plugin or manual folder copies |
| Markup | AsciiDoc | Markdown / MDX |
| Best for | Large multi-component technical docs | Single-product or app docs |
| Learning curve | Steep (playbook, UI bundles, AsciiDoc) | Moderate to gentle |
The pattern is clear. If your docs live in one repository and target one product, a Markdown generator gets you there with less setup. If your docs are scattered across many repos and you need versions of each, Antora is built for exactly that shape and the Markdown tools are not.
Setting up Antora: the short version
Getting a first Antora site running takes a few steps. You install the CLI and site generator, then write a playbook.
npm i -g @antora/cli @antora/site-generator
The playbook is a YAML file that names your sources and UI bundle:
site:
title: My Product Docs
start_page: component-a::index.adoc
content:
sources:
- url: https://gitlab.com/org/component-a.git
branches: [main, v2.0, v1.0]
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
Each source repo needs an antora.yml descriptor that declares its component name and version. Run antora antora-playbook.yml and the tool produces a build/site folder ready to host anywhere static files live. That last step is the same as any generator, but the front half, wiring up repos and descriptors, is more work than dropping Markdown into a folder.
Antora features worth knowing
Beyond aggregation and versioning, Antora ships several things that matter for serious technical documentation:
- Cross-repository references. Link to a page in another component with a stable resource ID. Move files around and the links still resolve.
- AsciiDoc power. Includes, conditionals, attributes, admonitions, and reusable snippets. AsciiDoc handles structured technical content that plain Markdown struggles with.
- Theming via UI bundles. The look is packaged as a separate, versioned zip. Design once, apply across every docs site your org builds.
- A built-in version selector. Readers switch between product versions from a dropdown without you managing duplicate folders.
- Content reuse. Shared partials can live in one repo and appear across many components, so you write a warning or a code sample once.
These features point at one audience: teams with a lot of documentation, spread across a lot of repositories, that changes across a lot of versions.
Pros and cons of Antora
No tool fits every team. Here is the honest split.
Pros
- Handles multi-repo, multi-version docs better than almost anything else open source.
- AsciiDoc is more capable than Markdown for structured, reusable technical content.
- Stable cross-references that survive file moves and restructures.
- Clean separation between content and presentation through UI bundles.
- Free and open source, with an active maintainer team.
Cons
- Steep learning curve. The playbook, component descriptors, and UI bundle system take time to understand.
- AsciiDoc is less common than Markdown, so contributors may need to learn new syntax.
- Overkill for a single-repo or single-product docs site.
- Theming through UI bundles is more involved than editing a config value.
- Not aimed at fast, simple sites or non-technical authors.
Who should use Antora, and who shouldn't
Antora is the right call for a specific profile: a large engineering organization with documentation split across many git repositories, multiple product versions in active support, and technical writers comfortable with AsciiDoc and a git-based workflow. Companies documenting a platform of many services, where each team owns its own docs next to its code, get real value from the aggregation model. Nothing else does that job as cleanly.
It is the wrong call if you are a small team or a solo founder who wants a docs site live this week. The playbook, the AsciiDoc syntax, the UI bundle system, and the Node toolchain add up to real setup time before a single page ships. If your docs live in one place and you do not need branch-based versioning, that machinery is cost without benefit.
Best Antora alternatives
If Antora feels heavier than your project needs, a few options cover different points on the spectrum:
- MkDocs Material for Python teams who want polished Markdown docs from a single repo with minimal config.
- Docusaurus for JavaScript teams who need MDX, React components, and a big plugin ecosystem.
- mdBook for lightweight Rust-friendly Markdown books and lean technical guides.
- Nextra for Next.js apps that want docs living inside the same codebase.
Those all share Antora's assumption that someone on the team will write and maintain the content by hand. For a SaaS founder who wants docs live without a Node toolchain, AsciiDoc, or multi-repo config, a managed platform is a closer fit. Docsio generates a branded documentation site from your product URL, renders Mermaid diagrams, and hosts it with SSL, so you skip the build pipeline entirely. Pricing is $60 per month per Pro site with unlimited AI editing. That solves the content and hosting problem, not just the rendering one, which is the actual gap for a small team.
The right tool depends on what you are optimizing for. Antora is excellent at composing distributed, versioned docs when you have the engineering muscle to run it. A managed AI platform is the better answer when you want the docs to exist without owning the machinery.
Should you choose Antora in 2026?
For a large org with many repos and many versions, yes. Antora solves a problem that few other tools even attempt, and the aggregation plus versioning model is genuinely strong once your team is past the learning curve. The AsciiDoc foundation pays off as your content grows in structure and reuse.
For a single-product docs site, a small team, or anyone who wants to publish this week, Antora is more tool than the job requires. Pick a Markdown generator or a managed platform, keep the setup light, and revisit Antora only if your docs actually spread across multiple repositories. Matching the tool to the shape of your documentation matters more than picking the most powerful option on the list.
Frequently asked questions
What is Antora used for?
Antora is used to build documentation sites that pull content from multiple git repositories and versions into one unified site. It suits large technical products with many components, where each team keeps docs next to its code. Antora aggregates those sources at build time and produces a single static site with shared navigation.
Does Antora use Markdown or AsciiDoc?
Antora uses AsciiDoc, not Markdown. AsciiDoc is a more capable markup language that supports includes, conditionals, attributes, and reusable content, which fits structured technical documentation. The trade-off is that AsciiDoc is less common than Markdown, so contributors used to Markdown may need time to learn the syntax before they can write pages.
Is Antora free?
Yes. Antora is open source and free to use, maintained by the OpenDevise team behind the wider Asciidoctor ecosystem. You install it through npm and run it from the command line. There is no paid tier or license fee for the generator itself. Your only costs are hosting the static output and the time to set up the pipeline.
What is the best Antora alternative?
It depends on your needs. For single-repo Markdown docs, MkDocs Material or Docusaurus are lighter choices. For a small team or founder who wants docs live without a Node toolchain, AsciiDoc, or multi-repo config, a managed AI platform like Docsio generates and hosts a branded site from your product URL in minutes.