# Webmaster guide

## Local development
```bash
bash scripts/serve.sh
```
This generates event QR codes and starts Hugo at `http://localhost:1313`.

## Production build for Hostinger
```bash
bash scripts/build-hostinger.sh
```
This installs dependencies, generates QR codes, builds the site with Hugo, runs Pagefind, and leaves the uploadable site in `public/`. Upload the contents of `public/` to Hostinger `public_html`. The `.htaccess` file is included.

## Configuration
Edit `hugo.toml`:
- `baseURL` — must match the live domain (`https://cachegrows.org/`)
- `params.googleCalendarEmbed`, `googleCalendarIcs`, `googleCalendarSubscribe`
- `params.newsletterFormAction`
- `params.plausibleDomain` (optional analytics)
- Menu entries under `[menu.main]`

## Content management
Use Hugo archetypes:
```bash
hugo new events/YYYY-MM-DD-slug.md
hugo new partners/org-name.md
hugo new news/YYYY-MM-DD-recap.md
```
See `docs/CONTENT_GUIDE.md` for front matter fields.

## Theme and styling
- Theme lives in `themes/cachegrows`
- Colors: `assets/sass/_colors.sass`
- Layout: `assets/sass/_layout.sass` and `_sidebar.sass` (now header styles)
- Templates: `layouts/` (site overrides) and `themes/cachegrows/layouts/`

## Search
Pagefind indexes the built site. Run `npm run build` to regenerate. The search page is `/search/`.

## Testing and QA
- **Unit tests** (calendar rendering, poster canvas helpers, submit-event YAML generation):

  ```bash
  npm test
  ```
  Tests use Vitest + jsdom and live in `tests/`.

- **Smoke test** (build + key pages + JS syntax):

  ```bash
  bash scripts/smoke-test.sh
  ```

- **Poster print QA** (verifies letter + half-letter 2-up output in a real browser):

  ```bash
  npm i -g playwright && playwright install chromium
  hugo server -D -F &
  node scripts/poster-qa.js
  ```
  The script saves screenshots and PDFs to `/tmp/opencode/poster-qa/` and asserts the DOM/CSS state used when printing (one sheet per page for Letter; two sheets side-by-side on a landscape Letter page for half-letter). Check the screenshots for visual issues before releasing poster changes.

- **Accessibility**: `npx pa11y-ci --config .pa11yci.json` against a running local server (`hugo server -D -F`), or use the `Audit` GitHub workflow. If Chromium refuses to start in a sandboxed environment, add `--no-sandbox` (already set in `pa11y.json`/`.pa11yci.json`).

## Forms and integrations
- Newsletter form posts to `params.newsletterFormAction`
- RSVP links are per-event `rsvpUrl`
- Maps are generated from `location.address`
- Calendar embed and ICS links come from `hugo.toml`

## QR codes
- Site QR: `static/images/qr-cachegrows.png`
- Event QR codes: `static/images/qr-events/*.png`
- Regenerate with `scripts/make-event-qrs.sh`

## Backups
The entire site is in Git. Back up the repository and the shared Google Calendar/Sheets separately.

## Troubleshooting
- Missing events: Hugo excludes future-dated content by default; `buildFuture = true` is set in `hugo.toml`.
- Missing QR images: run `bash scripts/make-event-qrs.sh`.
- Broken styles: ensure Hugo extended and SASS compiles; check `layouts/_partials/styles.html`.
- 404s on Hostinger: ensure `.htaccess` uploaded and `baseURL` correct.