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.

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: a repository that already has some or all of this in place (this repository, ai-catalog, already does) is left alone wherever it’s already correct, and only genuine gaps are filled — no page, config entry, or nav entry already present is overwritten or reordered. 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.

Purpose group

Repository Bootstrap

Invocation

/iru-setup-antora

Inputs

Argument Required Description Default

(none)

No

iru-setup-antora takes no explicit arguments. It derives the Antora component name/title/version, and whether Node.js/Antora/its extensions/the ROOT module/nav.adoc already exist, entirely 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 or corrected in place if some fields were already wrong.

  • 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).

  • 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 grouping what already existed versus what this run created or corrected, plus a reminder to review the generated starter pages.

Execution flow

flowchart TD A[Start /iru-setup-antora] --> 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 --> 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 --> 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: Report already-present\nvs newly created/corrected"]

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.

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.

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.