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

Setup
npx antora -v
Print CLI and generator version. Verify your installation works.
npx antora --attribute key=value antora-playbook.yml
Pass AsciiDoc attributes at build time. Repeat the flag to set multiple.
Build
npx antora antora-playbook.yml
Standard build. Generates the site in the current directory.
npx antora --fetch antora-playbook.yml
Pull updates from remote content/UI repos, then build.
npx antora --clean antora-playbook.yml
Deletes previous output first. Use after reorganizing content or switching themes.
npx antora --fetch --clean antora-playbook.yml
Fetch latest sources and clean-build from scratch. Typical for CI pipelines.
Customize UI & Content
npx antora --ui-bundle-url ./ui-bundle.zip antora-playbook.yml
Preview a local UI bundle without pushing it to a remote repo.
npx antora --start-page component:module:page.adoc antora-playbook.yml
Temporarily override the site’s start page for local previews.
Output & Deployment
npx antora --to-dir public antora-playbook.yml
Write output to a custom folder (e.g. public/ for Netlify/Vercel).
npx antora --html-url-extension-style indexify antora-playbook.yml
Use clean, index-style URLs instead of .html file extensions.
npx antora --redirect-facility netlify antora-playbook.yml
Generate redirect rules for your hosting platform (nginx, netlify, gitlab, httpd, static).
npx antora --to-dir public --clean antora-playbook.yml
Clean-build directly into your deploy folder. Ready to ship.
Debugging
npx antora --log-level info antora-playbook.yml
Increase log verbosity. Levels: fatal, error, warn, info, debug.
npx antora --stacktrace antora-playbook.yml
Show full stacktrace on errors. Helpful for extension or UI issues.
npx antora --log-level debug --stacktrace antora-playbook.yml
Maximum debug output. Combine both flags when troubleshooting builds.
npx antora --ui-bundle-url ./ui.zip antora-playbook.yml
Test a local UI bundle to isolate theme issues from content problems.

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

Use a local install + npx, define a minimal playbook, add one component, generate.

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

The simpler alternative: adoc Studio’s Static Site Generator

If Antora’s multi-repo orchestration is more than you need, adoc Studio offers a radically simpler path from AsciiDoc to website.

Instead of managing playbooks, component descriptors, nav files, and a Node.js build pipeline, you work directly in your AsciiDoc document. The section structure of your document becomes your website navigation – no nav.adoc, no antora.yml, no config files at all.

What you skip entirely:

  • No package.json, npm install, or npx antora commands
  • No playbook YAML, no component descriptors
  • No separate nav.adoc files to keep in sync
  • No build pipeline or CI configuration for the site itself

What you get instead:

  • One-click export – hit export, pick a folder, done. All HTML files, styles, and navigation are generated automatically.
  • Section structure = sitemap – your document headings define pages and navigation. Choose how sections appear: topbar, sidebar, satellite navigation, or any combination.
  • Built-in multi-language – if your project has translations, adoc Studio builds a multi-language site with automatic language switcher, per-language navigation, and localized search index.
  • Consistent styling – the same CSS controls both your HTML website and PDF exports. Style once, use everywhere.

adoc Studio gives you the same results – versioned, navigable, multi-language documentation websites – without the toolchain overhead. No playbooks, no build pipeline, no manual configuration. Just your AsciiDoc content and a single click. Learn more about adoc Studio’s Static Site Generator.

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.

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.