Antora: The Full 2025 Guide (Setup, Comparisons, i18n)

What Antora is (in one sentence)

Antora is a modular documentation pipeline that collects AsciiDoc content from one or more Git repositories, organizes it into components/versions, and renders a multi-page site with a themed UI.

Why teams pick it

• Built for multi-repo docs and versioning from day one.

• Uses AsciiDoc, which suits large, structured docs and reuse via includes/partials.

• Clean separation of content (in Git) and site UI (theme bundle).

Where adoc Studio helps: write faster with AsciiDoc-focused UX, keep content reusable, and style HTML/PDF with one CSS (see: Create custom CSS once, Templates & stylesheets).

Antora Cheat Sheet

Step-by-step: Install and run your first Antora site

1) Prerequisites

• Node.js (LTS)

• Git reachable from your shell

2) Create a playbook project and install Antora locally (recommended)

mkdir docs-site && cd docs-site
node -e "fs.writeFileSync('package.json','{}')"
npm i -D -E @antora/cli@3 @antora/site-generator@3
npx antora -v

3) Add a minimal antora-playbook.yml

site:
  title: "My Docs"
  url: https://example.com/docs
content:
  sources:
    - url: ./
      branches: HEAD
      start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/main/raw/build/ui-bundle.zip?job=build
  supplemental_files: ./supplemental-ui
output:
  dir: ./build/site

4) Create your first component

docs/                     # content source root
  antora.yml              # component version descriptor
  modules/
    ROOT/
      pages/
        index.adoc

antora.yml:

name: my-product
version: 1.0
title: My Product
nav:
  - modules/ROOT/nav.adoc

5) Author a page (docs/modules/ROOT/pages/index.adoc)

= Welcome to My Product Docs
:page-nav_order: 1

This is your first Antora page. See <<getting-started>> to continue.

If you’re new to AsciiDoc includes/reuse, keep this handy: Include directive tips.

6) Generate and preview

npx antora antora-playbook.yml
# open build/site/index.html

Structure your content the Antora way

• Components represent products/areas.

• Versions capture releases or tracks.

• Modules split content by purpose (e.g., ROOT, user, admin).

• Pages, partials, images, attachments live under modules.

Antora can stitch one component from multiple repos—use a primary antora.yml (with nav, title) and minimal descriptors in satellite repos.

Playbook content sources

content:
  sources:
    - url: https://git.example.com/my/product.git
      branches: [ main, v1.* ]
      start_path: docs
    - url: https://git.example.com/my/shared-docs.git
      start_path: docs

Versioning that won’t bite you later

• Keep semantic versions or named tracks (1.0, 2.0, next).

• Control how users see versions with display_version and routing.

• You can derive version from Git refs or set it in antora.yml.

Branching strategy

• Author on main (version next).

• Cut a release branch (release/2.1) and set version: 2.1 there.

• Backport fixes by cherry-pick.

UI, navigation, and branding

Antora ships a default UI; you can plug in your own UI bundle or supplemental files (logos, JS, CSS, partials).

• Keep navigation in one place (nav.adoc) to avoid drift.

• Add analytics, cookie banner, or dark mode via supplemental Handlebars/JS in your UI project.

• If you want a simpler path for PDF/HTML styling without a custom UI pipeline, style once in adoc Studio and export both HTML & PDF consistently: Design with CSS, Export AsciiDoc to PDF, ISO-ready admonitions.

CI/CD and hosting

• Antora produces a static site you can host anywhere (S3, GitHub/GitLab Pages, Netlify, your server).

• In CI: npm ci && npx antora antora-playbook.yml && rsync to your host.

• Build on merges to main, publish from tags for releases.

Antora vs. other tools (choose with eyes open)

Antora vs. MkDocs

• MkDocs is Markdown-first, fast, and has a thriving plugin/theme ecosystem (e.g., Material for MkDocs). Great for small-to-medium docs and Python-centric teams.

• Antora excels at multi-repo + versioned AsciiDoc sites and cross-component reuse. If you need component/versions at scale, Antora fits better.

Antora vs. Docusaurus

• Docusaurus is React/MDX-based, great for interactive docs, blogs, and marketing pages; it offers first-class versioning/i18n plugins.

• Antora is a multi-page static site focused on docs structure and AsciiDoc depth.

Antora vs. Sphinx

• Sphinx (reStructuredText/MyST) is powerful for Python ecosystems and API docs, with many builders and extensions.

• Antora’s strength is component/version orchestration across repos with AsciiDoc.

If your content is already in AsciiDoc or you need modular, versioned, multi-repo docs, choose Antora. If you need MDX widgets or a React SPA, consider Docusaurus. If your stack is Python/API-heavy, Sphinx/MkDocs make sense.

Using Antora with translations (multi-language)

There’s no turnkey i18n switcher; you implement languages via version-as-language (e.g., version: en, version: de) plus UI tweaks, or run separate playbooks/sites.

Pattern A — “Version-as-Language”

• Create parallel component versions named after languages: version: en, version: de.

• Duplicate the structure; translate pages under each locale.

• Tweak the UI to set <html lang> and add a language switcher.

Pattern B — Separate sites / playbooks

• Maintain one playbook per language (docs-site-en, docs-site-de), each building to its own output/URL.

• Add a language switcher in the header that points across sites.

Caveats & tips

• Keep resource IDs aligned so cross-links are deterministic across locales.

• Decide how to handle fallbacks: if a page isn’t translated, link to English.

• Automate string coverage in CI (simple counts by directory).

• If you want “batteries-included” i18n routing, Docusaurus or site frameworks like Astro offer that—but you trade off Antora’s component/version model.

Where adoc Studio helps: manage source AsciiDoc cleanly, keep includes and partials DRY across languages, and enforce consistent headings/terminology.

adoc Studio for Mac, iPad & iPhone

Create Technical Documentation
with AsciiDoc

Free 14-Day Trial →

Team best practices that scale

• Decide your coordinates early. Component names/versions become URLs and cross-refs. Write them down.

• One source of truth for nav. Keep nav.adoc in the primary repo; other repos have minimal antora.yml.

• Automate builds. CI runs npx antora … on merges; publish to a static host.

• Lint and style once. adoc Studio lets you write, lint, and apply one CSS for HTML/PDF so your Antora output looks on-brand from day one.

• Reusable content. Favor include::[] and partials for repeated sections (Include directive guide).

• Keep learning lightweight. New writers ramp faster with adoc Coach and a short product tutorial.

Troubleshooting & common pitfalls

• “It built, but the page is missing.” Check repo/branch/start path and that a content source root with antora.ymlexists.

• “Versions are in a weird order.” Set title/display_version consistently in antora.yml.

• “Global install permission errors.” Prefer local install + npx (works across machines/CI).

• “How do I preview a custom theme?” Build/serve the UI project and point your playbook’s ui.bundle.url to the built zip (or use --ui-bundle-url locally).

Quick reference: Copy-paste starters

Minimal antora.yml

name: my-product
version: 1.0
title: My Product
nav:
  - modules/ROOT/nav.adoc

Minimal playbook with one local source

site:
  title: "My Docs"
content:
  sources:
    - url: ./
      branches: HEAD
      start_path: docs
output:
  dir: ./build/site

Generate

npx antora antora-playbook.yml

Mini debug checklist

• Missing page after build? Confirm repo/branch/start path and that antora.yml sits beside modules/.

• Theme changes not visible? Use ui.bundle.snapshot: true or run with --ui-bundle-url pointing to your local bundle.

• Weird URLs? Try --html-url-extension-style indexify or set it under urls in the playbook.

• Version display/routing oddities? Check display_version and prerelease.

• No obvious error output? Re-run with --log-level debug --stacktrace.

Conclusion: When Antora is the right tool

Pick Antora when you need serious structure—components, versions, multi-repo content, and team workflows where docs behave like code. Combine it with a disciplined AsciiDoc practice and a small CI job and you’ll have a resilient docs stack that grows with your product.

If you want a faster start on the authoring/styling side, pair Antora with adoc Studio: write in AsciiDoc, reuse content, and style HTML/PDF once. See: Export to PDF, AsciiDoc Guide, and our short product tutorial.