Docs deployment

Status: Scaffolded 2026-09-24

This site is a PokeDocs (Docusaurus) build published by AWS Amplify Hosting on every push to main, from the same AWS account and region (us-east-1) as the web app. The build spec is amplify.yml in the repo root; CI on pull requests stays on GitHub Actions.

Two pipelines

Trigger	Runs where	Does
Pull request to main	GitHub Actions, ci.yml	validate (Biome, tsc, pokedocs check, docusaurus build) and secrets (gitleaks). The ruleset requires validate green before merge.
Push to main	Amplify Hosting	Builds the static site from amplify.yml and publishes it. A failed build leaves the previous deploy live.

The Amplify build

preBuild:
  - nvm use 24
  - npm ci
  - sudo dnf install -y --setopt=strict=0 <chromium shared libraries>
  - npx playwright install chromium-headless-shell
build:
  - npm run build
artifacts: build/
cache: node_modules/, ~/.cache/ms-playwright/

Amplify's Amazon Linux 2023 image ships Node 22 by default and 24 through nvm, so the first line matches .nvmrc. The dnf line installs the shared libraries chromium needs, because Playwright's own --with-deps does not know Amazon Linux. The browser download is cached between builds.

Why a docs build installs a browser

Mermaid diagrams are rendered to SVG at build time in a headless chromium, so the published page carries no client-side Mermaid runtime and no diagram that fails to draw when a script is blocked. Locally, run npx playwright install chromium once.

POKEDOCS_STRICT_URL

docusaurus.config.ts reads url from POKEDOCS_URL, defaulting to https://docs.vegangrove.org, and baseUrl from POKEDOCS_BASE_URL. A production build with a placeholder URL only warns; setting POKEDOCS_STRICT_URL=true in the Amplify environment turns that into an error so a misconfigured environment cannot publish a sitemap and canonical links pointing at the wrong origin.

Custom domain

docs.vegangrove.org is attached to the app: Amplify issued the certificate and, because the zone lives in Route 53 in the same account, wrote the validation and alias records itself. HTTPS is enforced by Amplify, which is the step The Trick Book's docs site never took on its previous host. The default amplifyapp.com hostname keeps working as a fallback.

Local

npm run start       # dev server with hot reload, no Mermaid prerender
npm run validate    # exactly what CI runs
npm run serve       # serve build/ to check the production output

onBrokenLinks: 'throw' and the required description field mean a broken link or missing frontmatter fails validate locally before it fails CI. See testing.

Rollback

Amplify keeps every successful deploy; a bad page is fixed forward with a PR, and a build that fails never replaces the live site. The console can also redeploy any previous successful build in one click.