antora generate: Build a Multi-Repo Docs Site
antora generate site.yml aggregates AsciiDoc from one or more git repositories into a single versioned documentation site.
Antora is built for docs that live across many repos and versions. A playbook YAML lists the content sources; antora generate clones or reads them and produces the site.
What it does
antora generate reads a playbook (commonly antora-playbook.yml) that declares content sources (git URLs and branches), a UI bundle, and output settings. It collects the AsciiDoc, resolves cross-references across components and versions, and writes a static site (default build/site).
Common usage
antora generate antora-playbook.yml
# fetch the latest from remote content sources
antora generate --fetch antora-playbook.yml
# fail on any broken xref or missing target
antora --log-failure-level=warn generate antora-playbook.ymlOptions
| Flag | What it does |
|---|---|
| --fetch | Update remote content sources before building |
| --to-dir <dir> | Output directory for the generated site |
| --log-failure-level <lvl> | Exit non-zero at warn or error |
| --stacktrace | Print stack traces on error |
| --clean | Clean the output directory first |
In CI
Pass --fetch so the build pulls current branches instead of a stale cache, and set --log-failure-level=warn so a broken xref fails the pipeline. Provide git credentials for private content sources via the playbook or environment. Deploy the build/site directory.
Common errors in CI
Content source has no branches or tags means a source pattern matched nothing; check the branch globs in the playbook. target of xref not found: page.adoc fails the build under --log-failure-level=warn. not a git repository or clone errors mean a wrong URL or missing credentials for a private source.