Setup Antora

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Bootstrap a minimal, working Antora documentation site for a repository: verify/install the Node.js toolchain, install Antora plus its extensions, scaffold antora.yml/antora-playbook.yml and a ROOT module with three starter pages, and confirm the site actually builds. The component name is derived from the project identifier (Maven artifactId, npm package name, pyproject.toml [project].name, the root Cargo.toml [package] name, the last element of the go.mod module path (a /vN suffix skipped), a Swift package’s executable product name, a .NET solution’s .slnx/.sln file name, or an XcodeGen project.yml’s `name:), a Python .dev0 or .NET/PHP -dev pre-release suffix is stripped from the starting version like -SNAPSHOT (for an Apple app the version comes from MARKETING_VERSION in project.yml/Project.swift/*.xcconfig; for a command-line tool from Cargo.toml, internal/version/version.go, Version.swift or Directory.Build.props), and for Python projects the optional API-docs entry in the starter pages points at the Sphinx build (docs/api/, published under the site’s api/).

Purpose

iru-setup-antora gets a repository from "no documentation site" (or a partially set-up one) to a building Antora site with a minimal, useful ROOT module — without assuming any particular language or build system. It is additive by default, and it says up front which of two things the run is doing: creating the site from scratch or updating an existing one. When docs/antora.yml, the playbook, or the ROOT module already exists (this repository, ai-catalog, already does), it warns and asks whether to Update (fill gaps only — no page, config entry, or nav entry already present is overwritten or reordered), Keep as is (touch nothing; only the .gitignore check and the build verification still run), Replace (rewrite antora.yml and the playbook from its template; existing pages and nav.adoc are kept unless the user separately confirms otherwise), or Stop. A scripted caller can pre-answer that question with on-existing. It also copies its own bundled ui-bundle.zip into docs/, so the generated antora-playbook.yml points ui.bundle.url at that local file instead of depending on the upstream GitLab CI artifact URL at build time. For a repository with a user interface it also creates a small User interface skeleton (Step 9b, following its bundled reference/ui-docs.md; see Building user interfaces); the per-screen and per-component pages and every screenshot are left to Update Docs.

Purpose group

Repository Bootstrap

Plugin

Shipped by the iru-core plugin of the ai-catalog marketplace (install with /plugin install iru-core@ai-catalog; see Plugins).

Invocation

/iru-setup-antora

Optionally followed by an args line, e.g. on-existing: update, when called by an orchestrator.

Inputs

Argument Required Description Default

Argument	Required	Description	Default
`on-existing`	No	`ask`, `keep`, `update`, or `replace` — how to treat an Antora site that already exists. For scripted runs: Step 2 still prints its warning but applies the value without asking. `mode: existing` alone does not mean "update silently"; Step 2 still asks unless `on-existing` says otherwise.	`ask`
other `key: value` lines	No	Ignored (e.g. `sonar`, `mode`, `visibility`) — this skill only owns the docs site. The Antora component `name`/`title`/`version`, and whether Node.js/Antora/its extensions/the `ROOT` module/`nav.adoc` already exist, are derived by surveying the repository itself (README, project manifest such as `pom.xml`, git tags, GitHub releases, and the current `docs/` layout).	N/A

on-existing

ask, keep, update, or replace — how to treat an Antora site that already exists. For scripted runs: Step 2 still prints its warning but applies the value without asking. mode: existing alone does not mean "update silently"; Step 2 still asks unless on-existing says otherwise.

ask

other key: value lines

Ignored (e.g. sonar, mode, visibility) — this skill only owns the docs site. The Antora component name/title/version, and whether Node.js/Antora/its extensions/the ROOT module/nav.adoc already exist, are derived by surveying the repository itself (README, project manifest such as pom.xml, git tags, GitHub releases, and the current docs/ layout).

N/A

Outputs

docs/antora.yml and docs/antora-playbook.yml, written fresh, corrected in place if some fields were already wrong (Update), rewritten from the template (Replace), or untouched (Keep as is).
docs/ui-bundle.zip copied in from this skill’s own directory (unless already present), so antora-playbook.yml’s `ui.bundle.url: ui-bundle.zip resolves to a local file instead of the upstream GitLab CI artifact URL.
docs/modules/ROOT/nav.adoc and a ROOT module skeleton at docs/modules/ROOT/pages/ containing index.adoc (repository overview), installation.adoc (install guide), and reference.adoc (links to generated reports/dashboards) — skipped for any of the three roles already covered by an existing page under a different name.
Antora, @antora/lunr-extension, @sntke/antora-mermaid-extension, and @djencks/asciidoctor-mathjax installed under docs/ (as dev/regular dependencies in docs/package.json).
For a repository with a UI (Step 9b): pages/ui/index.adoc (screens and components tables from a quick inventory), pages/ui/navigation.adoc (a Mermaid navigation graph, no screenshots yet), images/ui/.gitkeep, and a User interface section in nav.adoc. Existing ui/ pages are kept as is on Update; the user is told to run /iru-update-docs once the UI tests have produced .ui-screenshots/.
A docs/build/ entry added to the root .gitignore if missing.
A built static site at docs/build/site (from npx antora antora-playbook.yml), or a fixed build error if one occurred — this skill does not report success on a broken build.
A report that starts by restating the mode ("created from scratch" or "updated an existing site"), the option applied (updated / kept as is / replaced, and whether it came from the user or from on-existing, or that the user chose Stop), and, under Keep as is, every gap left unfilled. It then groups what already existed versus what this run created or corrected, plus a reminder to review the generated starter pages.
For a command-line tool repository, nothing extra: the generated cli-reference.adoc page and its nav entry are added afterwards by Setup CLI Repository, and an existing one is kept as is on Update.

Execution flow

flowchart TD A[Start /iru-setup-antora] --> A0["Step 0: Resolve on-existing from args\n(default ask)"] A0 --> B{"Step 1: node -v / npm -v work?"} B -- no --> C["Show install instructions;\nstop and ask user to install Node.js"] B -- yes --> D["Step 2: Survey existing docs/,\nantora.yml, playbook, ROOT module,\nnav.adoc, package.json deps"] D -- nothing exists --> D1["Announce: creating from scratch"] D1 --> E D -- something exists --> D2["Announce: updating existing site;\nwarn and ask Update / Keep / Replace / Stop\n(or apply on-existing)"] D2 -- Stop --> Z["End without changes"] D2 -- Keep as is --> M D2 -- Update or Replace --> E["Step 3: Install Antora + lunr/mermaid/\nmathjax extensions under docs/"] E --> F["Step 4: Write or correct docs/antora.yml"] F --> G["Step 5: Write or fill docs/antora-playbook.yml;\ncopy ui-bundle.zip into docs/"] G --> H["Step 6: Create ROOT module skeleton\n(nav.adoc, pages/)"] H --> I["Step 7: Write index.adoc\n(repository overview, via Explore agent)"] I --> J["Step 8: Write installation.adoc\n(install guide)"] J --> K["Step 9: Write reference.adoc\n(links of interest)"] K --> K2["Step 9b: UI skeleton (ui/index, ui/navigation,\nimages/ui/.gitkeep) when the repository has a UI"] K2 --> L["Step 10: Update nav.adoc\nwith new page entries"] L --> M["Step 11: Add docs/build/\nto .gitignore if missing"] M --> N["Step 12: Build site via\nnpx antora antora-playbook.yml"] N -- build fails --> O[Fix offending file before finishing] O --> N N -- build succeeds --> P["Step 13: Restate mode and option applied;\nreport already-present vs created/corrected\n(and gaps left under Keep as is)"]

Dependencies

Invokes

None — iru-setup-antora is a leaf skill; it does not call any other skill in this catalog.

Invoked by

Setup Java Library Repository — Step 4 runs iru-setup-antora with no args, deriving the component name/title/version straight from the pom.xml that Setup Java Library just wrote, and runs it before the CI-workflow step so that step’s own survey finds the docs already in place.
Update Docs — conditionally, only when no Antora module exists anywhere in the repository yet, and only after asking the user; run via a sub-agent so iru-update-docs can keep running afterward instead of blocking on it.
Setup TypeScript Repository — Step 6, Antora docs site, via the iru-isolated-skill-executor agent.
Setup Android Repository (Step 5) — runs it via the iru-isolated-skill-executor agent right after the flavor’s scaffold and deliberately before the workflows skill so the workflows survey finds docs already in place.
Setup Swift Repository (Step 6) — runs it via the iru-isolated-skill-executor agent right after the flavor’s scaffold and deliberately before the workflows skill so the workflows survey finds docs already in place.
Setup PHP Repository — Step 6, Antora docs site, via the iru-isolated-skill-executor agent.
Setup Quarkus Repository — Step 4, Antora documentation site, via the iru-isolated-skill-executor agent.
Setup KMP Repository — Step 5, Antora docs site, via the iru-isolated-skill-executor agent, right after the KMP app scaffold and before the workflows step.
Setup CLI Repository — Step 5, Antora docs site, via the iru-isolated-skill-executor agent, right after the Rust/Go/Swift/.NET CLI scaffold and before the gitignore step; the CLI reference page is added afterwards.
Setup macOS Repository — Step 5, Antora docs site, via the iru-isolated-skill-executor agent.
Setup Windows Repository — Step 5, Antora docs site, via the iru-isolated-skill-executor agent.
Update Java Spring Boot Documentation — Step 1, bootstraps the Antora site if docs/antora.yml is absent, via a general-purpose sub-agent.
Build Docs — Step 1, conditionally: only when no antora.yml is found anywhere in the repository, and only after asking the user whether to bootstrap Antora documentation now.

Related agents

Explore (see Agents) — used in Step 7 to build a picture of the top-level source layout and main public entry points before writing index.adoc’s overview, rather than reading the whole source tree directly — the same agent the `iru-explore skill itself uses for this kind of broad structural search. Step 9b uses it again for the quick screens/components inventory of a UI repository.

When Update Docs invokes iru-setup-antora conditionally, it does so through a sub-agent it manages, not one this skill spawns itself.

Source

SKILL.md on GitHub — the file this page was generated from.