FTN Antora Setup vs. Antora Supplemental Reference

This page compares FoodTruckNerdz’s Antora documentation setup with the canonical reference maintained by the Antora Supplemental organization. Use it to align FTN’s approach with recommended practices and to find the authoritative documentation.

Reference Documentation

Key Comparisons

Playbook location (root layout)

| Aspect | FTN (current) | Antora Supplemental (reference) | |--------|---------------|----------------------------------| | Playbook | antora-playbook.yml at the repository root | antora-playbook.yml at repository root (root strategy) | | Local playbook | antora-playbook-local.yml at root (copy from antora-playbook-local.example.yml; entry git-ignored) | Same idea: local path sources, local file often git-ignored | | CI | Default job working directory; pnpm exec antora antora-playbook.yml | antora from repo root; no working-directory under a site/ subfolder |

Alignment: The playbooks and package.json live at the root of the docs repository. The Antora Deployment guide (root vs. subfolder, CI, GitHub Pages) matches this layout. Custom UI and scripts still sit under site/ (e.g. site/supplemental-ui/, site/scripts/), not the playbooks.

Private Repo Authentication

| Aspect | FTN | Antora Supplemental | |--------|-----|---------------------| | Method | GIT_CREDENTIALS env var with x-access-token | Same; also documents git config --global url as Option A | | PAT storage | FTN_GITHUB_TOKEN (or org-specific name) | ANTORA_READ_TOKEN or REPO_ACCESS_TOKEN | | Gotcha coverage | Documents GITHUB_TOKEN vs PAT, x-access-token | Same; see Antora Deployment (private repos) |

Alignment: FTN’s github-actions-antora-setup is aligned with antora-supplemental guidance. Both correctly document PAT requirement for private content sources.

GitHub Pages Deployment

| Aspect | FTN | Antora Supplemental | |--------|-----|---------------------| | Pattern | Actions-based (upload-pages-artifact + deploy-pages) | Same (recommended) | | Build action | Inline pnpm exec antora in workflow | Recommends antora-build-action or inline | | Package manager | pnpm, package.json at repo root | pnpm; antora-build-action can use pnpm dlx antora without a project package.json |

Note: antora-supplemental’s antora-build-action simplifies the build step. FTN uses a manual install + run; both are valid.

Package Manager Commands

FTN uses npx antora in building-docs; antora-supplemental recommends pnpm dlx antora for one-off runs or pnpm exec antora when Antora is in package.json. See Antora Deployment (package manager run commands) for pnpm vs npm vs yarn.

Inconsistencies to resolve

  1. npx vs pnpm: Some older snippets use npx antora; CI and package.json use pnpm exec antora / pnpm run build. Prefer pnpm exec or pnpm dlx for one-off runs to match the lockfile and org standards.

  2. Local playbook extension: antora-supplemental’s “Best of Both Worlds” uses extends: ./antora-playbook.yml for local overrides. FTN’s antora-playbook-local.yml could be refactored to extend the main playbook if source lists drift.

Related FTN Pages