iru-build-docs

name	iru-build-docs
description	Build a repository's existing Antora documentation site, setting it up first (via `iru-setup-antora`) if it doesn't exist yet. Invoke as `/iru-build-docs`. Does no code exploration and makes no content edits to any existing page — it only ensures the toolchain/module exist and runs the Antora build, unlike `iru-update-docs`, which edits pages to reflect codebase changes. Use whenever the user just wants the docs site built/verified (e.g. to check it compiles, or to get the built HTML output) instead of updating its content.
model	haiku

Build Docs

Build a repository's Antora documentation site as-is. This skill never edits page content, nav.adoc, or antora.yml beyond what bootstrapping requires — if the docs need to be updated to reflect code changes, that's iru-update-docs, not this skill.

Step 1 — Locate the documentation module

Find antora.yml file(s) in the repository (find . -name antora.yml -not -path '*/node_modules/*').

• None found: there is no documentation module yet to build. Ask the user whether Antora documentation should be set up now (via the iru-setup-antora skill) before continuing — don't assume either way.
  • User agrees: run the iru-setup-antora skill (via the Agent tool, or directly via Skill if already in this context) to scaffold the module. If it reports it stopped short (e.g. Node.js isn't installed), relay that blocker to the user and stop — there's nothing to build yet.
  • User declines: stop this skill entirely — there is nothing for it to build.
• One or more found: continue to Step 2 for each one.

Step 2 — Locate the playbook and toolchain

For the docs module found in Step 1, locate its Antora playbook file (commonly antora-playbook.yml or site.yml, usually next to antora.yml or at the docs module root) — don't assume a fixed name, check docs/package.json scripts or the repository's CI config (e.g. .github/workflows/docs.yml) if it isn't obvious.

Check Node.js is usable (node -v / npm -v). If either fails, stop and point the user at iru-setup-antora's Step 1 install instructions rather than attempting to install Node.js yourself.

Step 3 — Install dependencies and build

From the docs module's directory:

npm ci
npx antora <playbook-file>

Use npm ci when a lockfile is present (matching CI); fall back to npm install only if there's no lockfile yet.

• Build succeeds: the static site lands at the module's build output directory (e.g. docs/build/site). Note the path to its index.html.
• Build fails: read the Antora/Asciidoctor error (broken xref:, bad YAML, malformed AsciiDoc table, invalid Mermaid/MathJax syntax) and report it verbatim to the user along with the offending file — do not fix page content yourself; that's iru-update-docs's job, not this skill's.

Step 4 — Report

State whether the module already existed or was just set up via iru-setup-antora, whether the build succeeded or failed, and the path to the built index.html (or the build error) — nothing else.