AI Village Website

Static Astro site for aivillage.org.

Requirements

• Node.js 24 (see .nvmrc)
• pnpm as the canonical package manager, pinned by packageManager in package.json

Quick Start

corepack enable
pnpm install --frozen-lockfile
pnpm dev
pnpm build
pnpm preview

Before pushing or opening a PR, run:

pnpm validate

pnpm build runs Astro/type checks, content-identity and Markdown heading checks, offline social-image generation, the Astro static build, redirect verification, internal-link verification, and emitted social-image verification.

pnpm validate runs the production build plus lint, formatting, contrast checks, and all regression suites. GitHub Actions runs that validation surface, audits dependencies, and builds the development container for every pull request and every push to master.

Development Environments

Nix and direnv

The committed flake provides the same Node.js and pnpm major versions used by the repository on x86-64 Linux, ARM64 Linux, and Apple Silicon macOS:

nix develop
pnpm install --frozen-lockfile
pnpm dev

If direnv is installed, direnv allow activates the flake automatically when entering the repository.

Docker

The development container runs Astro on container port 4321 and maps it to host port 4000 by default:

docker compose up --build

Open http://localhost:4000. Set AIV_SITE_PORT to use a different host port, for example AIV_SITE_PORT=4321 docker compose up --build.

The Compose service bind-mounts the repository for live Astro updates and keeps container dependencies in a named volume. Stop it with docker compose down.

Adding Content

Blog Posts

Add posts to src/content/blog/ with front matter including title, date, author, and category.

Canonical blog URLs use:

/blog/<slug>/

Use slug or canonicalSlug to set the canonical slug. The build fails on slug collisions.

The migration redirect set is complete. New Astro-native posts should not receive fabricated Jekyll-style legacy URLs. If a real historical URL needs to be preserved, add it explicitly to public/_redirects; redirect front matter is not used to generate redirects.

Events

Add events to src/content/events/ with title, date, and optional description and location. Event detail pages build at /events/<slug>/. Real legacy aliases are handled explicitly in public/_redirects.

Schedule and talk pages are mapped in src/data/schedules.ts and rendered from src/content/schedules/.

Volunteers

Add volunteer profiles to src/content/volunteers/ with first_name, last_name, a required stable slug, optional role fields, an explicit order, and an optional profile image filename from public/assets/images/profiles/. Person links use /about/#<slug>; keep an existing slug unchanged when correcting or updating a display name.

Sponsors

Add sponsors to src/content/sponsors/ with name, required status (current or past), and optional logo, url, and tier. Current sponsors appear on the homepage and /sponsors/; past sponsors appear in the past sponsors section. Each sponsor also gets a detail page at /sponsors/<slug>/.

Workshops

The /learn/ page links to the public AI Village workshops repository. Keep workshop claims limited to that repository's README files and top-level workshop documentation.

Content schemas strictly validate front matter at build time. Missing required fields, misspelled keys, and obsolete Jekyll metadata fail the build with a clear error.

Redirects

Redirects are manually maintained in public/_redirects. Treat that file as the source of truth for Cloudflare Pages redirects now that the migration is complete.

Cloudflare Pages applies _redirects as host-level redirects. Local Astro preview does not prove true 301 behavior. True redirect status verification requires a Cloudflare Pages preview or production deployment.

pnpm build copies public/_redirects into dist/_redirects and validates that the committed redirect file is well-formed, has no chains, and points at built routes. It does not regenerate or rewrite public/_redirects.

When adding a redirect:

• Add only real historical or manually verified inbound paths.
• Do not add fabricated Jekyll-style redirects for new Astro-native posts.
• Point source content at canonical URLs, not redirect sources.

Useful local checks:

pnpm run verify:redirects
pnpm run check:internal-links
pnpm run audit:dependencies

Kiosk

Open /kiosk/ on the display. The slideshow starts automatically. Edit src/data/kiosk.ts to add, remove, or reorder slides; poster entries use slugs from hosted records in src/data/posters.ts. Right Arrow or Space advances, Left Arrow goes back, and P pauses or resumes.

Deployment

Cloudflare Pages is the production target.

Configure deployment through the Cloudflare dashboard or Git integration:

• Connect the GitHub repository in Cloudflare Pages.
• Production branch: master
• Build command: pnpm run build
• Build output directory: dist
• Preview deployments: enabled
• Custom domain: aivillage.org
• Redirect rules: manually maintained at public/_redirects and applied by Cloudflare Pages

No GitHub Pages workflow is used because strict server-side 301 redirects require host-level redirect support.

The active custom domain and DNS configuration are managed in Cloudflare Pages/DNS; GitHub Pages files such as CNAME and .nojekyll are not used.