# Agent Guidelines for Lindsay Brunner Website

This document provides context for AI assistants working on this Hugo static site project.

## Project Overview

This is a personal website built with **Hugo** (v0.149.2+), deployed on **Netlify**. The site showcases thought leadership content and recipes with a custom dark theme design.

## Critical Protected Elements ⚠️

**NEVER modify these without explicit user permission:**

1. **Hero H1 Gradient** (`layouts/index.html`):
   - Must use `background-size: 80% 100%` (not 100%)
   - Gradient: `linear-gradient(135deg, var(--color-red) 0%, var(--color-pink) 50%, var(--color-yellow) 100%)`
   - Changing this breaks the visual match with the header logo

2. **Typography**:
   - `h1` and `.site-logo` must use `font-family: 'Inter'` (not Space Grotesk)
   - Required for gradient rendering consistency

3. **Button Hover States**:
   - White text must be explicitly maintained for readability
   - Don't change hover text colors on gradient buttons

## Project Structure

```
content/
  ├── thoughts/          # Thought leadership posts
  │   ├── _index.md      # Section index
  │   └── *.md           # Individual posts
  ├── recipes/           # Recipe posts
  │   ├── _index.md      # Section index
  │   └── recipe-*.md    # Individual recipes
  ├── about/
  │   └── index.md       # About page
  └── _index.md          # Homepage content

layouts/
  ├── index.html         # Homepage template
  ├── 404.html          # Error page
  ├── _default/          # Default templates
  ├── thoughts/          # Thoughts section layouts
  ├── recipes/           # Recipes section layouts
  └── partials/          # Reusable components

static/
  ├── css/               # Stylesheets (main.css, custom.css)
  ├── favicons/          # All favicon files
  ├── images/
  │   └── social/        # Open Graph images
  ├── _headers           # Netlify headers
  └── _redirects         # Netlify redirects
```

## Writing Style and Voice

**IMPORTANT:** When creating or editing content, always follow the guidelines in `CONTENT_STYLE_GUIDE.md`. This document defines:

- Tone and voice (wry, plainspoken, pragmatic)
- Sentence structure and rhythm
- Style of argumentation
- Formatting rules (no em dashes, title case H1s, sentence case other headers)
- Content clarity principles
- How to write in Lindsay's voice

**Key rules:**
- ❌ Absolutely no em dashes (use parentheses, commas, or break sentences)
- Title case for H1s, sentence case for all other headers
- Avoid corporate/LinkedIn sludge
- Write for builders and practitioners as peers
- Lead with lived experience, not abstractions

## Content Creation Patterns

### Thoughts Posts

**📋 For complete thoughts guidelines, see [`docs/thoughts-template.md`](./docs/thoughts-template.md)**

The template includes:
- Complete front matter template with all required and optional fields
- Content structure guidelines (flexible, unlike recipes)
- Formatting rules (headers, links, emphasis, etc.)
- OG image workflow (manual creation)
- Scheduling instructions
- Complete examples

**Quick reference:**

**Required front matter fields:**
- `title` (string)
- `date` (YYYY-MM-DD format)
- `description` (string)
- `subtitle` (string)
- `draft` (true/false)

**Optional fields:**
- `slug` (string)
- `og_image` or `social_image` (path to image in `/images/social/`)

**Permalink pattern:** `/thoughts/:year-:month-:day/:slug/`

**File naming for drafts:**
- Prefix draft thoughts files with `draft-` for easy identification (e.g., `draft-my-post.md`)
- The `slug` field in front matter determines the URL, so "draft" won't appear in production URLs
- This naming convention only applies to thoughts posts, not recipes

**Example:**
```yaml
---
title: "My Thought Title"
date: 2025-01-15
description: "A compelling description"
subtitle: "Brief subtitle for homepage"
draft: false
slug: "my-thought-title"  # This determines the URL, not the filename
social_image: "/images/social/my-image.png"
---
```

### Recipe Posts

**📋 For complete recipe guidelines, see [`docs/recipe-template.md`](./docs/recipe-template.md)**

The template includes:
- Complete front matter template with all required and optional fields
- Content structure guidelines (snapshot, ingredients, method, notes)
- Formatting rules (temperatures, measurements, section separators)
- OG image workflow
- Scheduling instructions
- Complete examples

**Quick reference:**

**Required front matter fields:**
- `title`, `date`, `description`, `subtitle`, `draft` (same as thoughts)
- `prepTime` (ISO 8601 duration, e.g., "PT30M")
- `cookTime` (ISO 8601 duration, e.g., "PT45M")
- `totalTime` (ISO 8601 duration, e.g., "PT75M")
- `recipeYield` (string, e.g., "6-8 servings")
- `recipeCategory` (string, e.g., "Main Course")
- `recipeCuisine` (string, e.g., "Japanese-American")
- `dietary` (optional array) — see **Dietary labels** below. Used for filter chips and title icons.
- `recipeIngredient` (array of strings)
- `recipeInstructions` (array of strings)

**Permalink pattern:** `/recipes/:year-:month-:day/:slug/`

**File naming:** Use `recipe-` prefix (e.g., `recipe-bachan-pulled-pork.md`)

**Section separators:** Use `---` (three dashes) as horizontal rules to separate major sections within recipe content. Do not use `⸻` (triple em dash) or other separator characters.

**Dietary labels (optional):** Labels apply to the **base recipe only** (main Ingredients and Method). Use exactly these values (lowercase, hyphenated). If a note or variation would change a classification, explicitly call that out in the note.
- **dairy-free** — Base recipe has no milk, cream, butter, cheese, or other dairy.
- **vegetarian** — Base recipe has no meat, poultry, or fish. Eggs and dairy allowed.
- **vegan** — Base recipe has no animal products (no meat, fish, eggs, dairy, honey, etc.).
- **gluten-free** — Base recipe has no wheat, barley, rye, or ingredients derived from them.

**Temperature formatting:**
- Always use degree symbols: `°F` and `°C`
- Standard format: `200°F (93°C)` (Fahrenheit first, Celsius in parentheses)
- For ranges: `160–165°F (71–74°C)`
- Do not use slash format (`350°F / 175°C`) — use parentheses instead

**Volume and measurement formatting:**
- **Always capitalize abbreviations:** `Tbsp`, `Tsp`, `Cup`, `Cups` (not `tbsp`, `tsp`, `cup`, `cups`)
- **Acceptable abbreviations:**
  - `Tbsp` / `Tbsp` (tablespoon) — always abbreviate
  - `Tsp` / `Tsp` (teaspoon) — always abbreviate
  - `cup` / `cups` — can abbreviate in lists, spell out in narrative text
  - `oz` (ounce) — always abbreviate
  - `lb` (pound) — always abbreviate
  - `g` (gram) — always abbreviate
  - `ml` (milliliter) — always abbreviate
  - `in` (inch) — can abbreviate in measurements like `1½-inch chunks`
- **Always spell out:**
  - `minutes` / `minute` (not `min`)
  - `hours` / `hour` (not `hr`)
  - `seconds` / `second` (not `sec`)
- **Metric conversions:** Optional but helpful. Include when it adds clarity: `1 cup (240 ml)`, `2 Tbsp (30 g)`
- **Fractions:** Use Unicode fractions when available: `½`, `⅓`, `¼`, `¾`; otherwise use `1/2`, `1/3`, etc.

## Testing

**Always run tests after making changes:**

```bash
npm run build      # Build the site first
npm run test:content  # Run content validation tests
npm test           # Run all tests (HTML, links, content, spell check, OG images, scheduling, search JSON, recipe template)
```

**Available test commands:**
- `npm run test:content` - Content validation tests
- `npm run test:html` - HTML validation
- `npm run test:links` - Broken link detection (starts dev server, waits for ready, runs check, stops server)
- `npm run test:spell` - Spell check modified content files (git diff)
- `npm run test:spell:all` - Spell check all content files
- `npm run test:og-images` - OG image generation validation
- `npm run test:schedule` - Scheduled posts workflow validation
- `npm run test:search-json` - Recipe search JSON index validation
- `npm run test:recipe-template` - Recipe template structure validation
- `npm test` - Run all tests (includes pretest build step)

**Test coverage includes:**
- Front matter validation (thoughts & recipes)
- Dietary labels: only `dairy-free`, `vegetarian`, `vegan`, `gluten-free` allowed; no duplicates; labels apply to base recipe only (see docs)
- No duplicate recipe page content (identical body in multiple files)
- Social image existence
- Static asset checks (CSS, favicons, default images)
- RSS feed structure
- Sitemap validation
- Homepage content structure
- About page validation
- 404 page validation
- Permalink structure
- Spell checking (content files)
- OG image generation and structure
- Scheduled posts workflow
- Recipe search JSON index structure and validity
- Recipe template compliance
- Recipe print functionality (print buttons, stylesheet, email links)

## Configuration Details

**Key config settings (`config.toml`):**
- Site title: "LB"
- Base URL: `https://lindsaybrunner.com`
- Markup: `unsafe = true` (allows raw HTML in content)
- Default social image: `/images/social/default-og.png`
- Recent posts number: 4

**Permalink patterns:**
- Thoughts: `/thoughts/:year-:month-:day/:slug/`
- Recipes: `/recipes/:year-:month-:day/:slug/`

**Output formats:**
- HTML (default)
- RSS feed (`/index.xml`)
- RecipeSearch JSON (`/recipes/index.json`) - JSON index for recipe search functionality

## Brand Guidelines

See `BRAND.md` for complete brand guidelines. Key points:

**Colors:**
- Gradient: Red (#ff0037) → Pink (#ff1b8d) → Yellow (#ffdd00)
- Primary brand: Pink (#ff1b8d)
- Dark theme: Black background (#000000) with dark surfaces (#0f0f0f)

**Typography:**
- Primary: Space Grotesk (body, navigation, headers h2-h6)
- Protected: Inter (h1 and logo only)
- Mono: SF Mono / system monospace

## Common Tasks

### Adding a New Thought Post

1. Create file in `content/thoughts/` (lowercase, hyphens)
   - For drafts, use `draft-` prefix: `draft-my-post.md` (helps with organization)
   - The `slug` field in front matter determines the URL, so "draft" won't appear in production URLs
2. Use the complete template from `docs/thoughts-template.md`
3. Add required front matter (see template for complete details)
4. Optionally create and add social image to `static/images/social/` (manual creation, unlike recipes)
5. Reference image in front matter: `social_image: "/images/social/my-image.png"`
6. **For diagram images in thoughts posts**: If adding PNG diagram images (e.g., flowcharts, system diagrams) to thoughts post content, place them in `static/images/` and ensure their backgrounds match the site's true black (#000000). Run `node scripts/fix-diagram-backgrounds.js` to automatically fix background colors. Add new diagram filenames to the `diagramFiles` array in the script before running. **Note**: This script is specifically for diagrams in thoughts posts, not for other types of images or other page types.
7. Run `npm run build && npm run test:content`

**To schedule for future publication:**
- Set `draft: true` and a future `date` in front matter
- The GitHub Actions workflow will automatically publish when the date arrives
- Test locally with `npm run schedule-posts` to see what would be published

### Adding a New Recipe

1. Create file `content/recipes/recipe-*.md`
2. Use the complete template from `docs/recipe-template.md`
3. Follow the content structure (description, snapshot, ingredients, method, notes)
4. Generate and review OG image: `npm run generate:og-images`
   - This generates SVG files in `static/images/social/working-files/` for editing
   - After editing the SVG, convert to PNG: `npm run generate:png -- static/images/social/working-files/recipe-xxx-og.svg`
   - The PNG will be saved in `static/images/social/` for use as the OG image
5. Add `social_image` to front matter: `social_image: "/images/social/recipe-xxx-og.png"`
6. Run `npm run build && npm run test:content`

**Print functionality:**
- Recipe pages automatically include print icon button (top-right) and print/email buttons (bottom)
- Print stylesheet is automatically applied via `@media print` rules in `static/css/custom.css`
- Print and email actions are tracked in Plausible Analytics
- No additional configuration needed - works out of the box for all recipes

**To schedule for future publication:**
- Set `draft: true` and a future `date` in front matter
- **Important**: Scheduled recipes must have `social_image` set before the publish date, or they will be skipped
- The GitHub Actions workflow will automatically publish when the date arrives
- Test locally with `npm run schedule-posts` to see what would be published

### Modifying Styles

- Main styles: `static/css/main.css`
- Custom overrides: `static/css/custom.css`
  - Includes print stylesheet (`@media print`) for recipe pages
  - Print styles hide navigation, use serif fonts, optimize for paper
- Use CSS custom properties from brand system
- Test responsive breakpoints: 768px, 480px

### Updating Homepage

- Edit `content/_index.md` for content
- Edit `layouts/index.html` for structure
- Recent Thoughts section shows 3 most recent (or placeholders if < 3)

## Important Notes

- **Drafts**: Set `draft: true` to hide from production
- **Draft file naming (thoughts only)**: Prefix draft thoughts files with `draft-` for easy identification (e.g., `draft-my-post.md`). The `slug` field in front matter determines the URL, so "draft" won't appear in production URLs.
- **Dates**: Use YYYY-MM-DD format (Hugo sorts by date)
- **Social Images**: Place in `static/images/social/`, reference with leading slash
- **Raw HTML**: Allowed in content (config has `unsafe = true`)
- **Build**: Always run `npm run build` before testing
- **Deployment**: Automatic via Netlify on push to master
- **Scheduled Posts**: Posts with `draft: true` and future dates will auto-publish via GitHub Actions (runs twice daily at 13:00 and 14:00 UTC to cover both PDT and PST). See README.md for details.
- **Recipe Search JSON**: A JSON index is automatically generated at `/recipes/index.json` for client-side recipe search functionality. The index includes recipe metadata and is validated by tests.
- **Recipe Print Functionality**: Recipe pages include print icon button (top-right) and print/email buttons (bottom). Print stylesheet automatically optimizes layout for printing. Print and email actions are tracked in Plausible Analytics. See README.md for details.
- **Spell Checking**: Use `npm run test:spell` to check modified content files, or `npm run test:spell:all` to check all content files. Add valid words to `cspell.json` if needed.
- **Hugo Version Checking**: Periodically check Hugo version and security status with `npm run check:hugo`. This checks for known CVEs and available updates. Recommended: check monthly or when security advisories are published.
- **Dependency Security Checking**: Run `npm run check:dependencies` to check all npm packages, Node.js version, and GitHub Actions for security vulnerabilities and updates. This runs automatically via GitHub Actions monthly and creates issues if problems are found.

## References

- **README.md**: Setup, scripts, content management guide, scheduling posts
- **docs/thoughts-template.md**: Complete thoughts template with front matter, structure, and formatting guidelines
- **docs/recipe-template.md**: Complete recipe template with front matter, structure, and formatting guidelines
- **docs/recipe-snapshot-template.md**: Snapshot section format and field definitions
- **BRAND.md**: Complete brand guidelines and protected elements
- **CONTENT_STYLE_GUIDE.md**: Writing principles, tone, voice, and style guidelines
- **config.toml**: Hugo configuration
- **tests/content-checks.js**: Main test orchestrator (modular structure in `tests/content-checks/` directory)
- **tests/spell-check.js**: Spell checking script for content files
- **tests/og-image-generation.test.js**: OG image generation validation
- **tests/schedule-posts.test.js**: Scheduled posts workflow validation
- **tests/recipe-search-json.test.js**: Recipe search JSON index validation
- **tests/recipe-template.test.js**: Recipe template structure validation
- **tests/dietary-labels.test.js**: Dietary label validation (allowed values only; base recipe only)
- **scripts/schedule-posts.js**: Auto-publish scheduled posts script
- **scripts/generate-og-images.js**: Generate OG images for recipes
- **scripts/generate-png-from-svg.js**: Convert SVG to PNG for social media compatibility
- **scripts/fix-diagram-backgrounds.js**: Fix diagram image background colors to match site black (#000000). Processes PNG files listed in the `diagramFiles` array, replacing dark pixels with pure black to ensure seamless integration with the dark theme. **Note**: Currently only relevant for diagrams placed in thoughts posts, not other types of images or other page types.
- **scripts/check-hugo-version.js**: Check Hugo version, security status, and available updates
- **scripts/check-dependencies.js**: Check all dependencies (npm packages, Node.js, GitHub Actions) for security issues and updates
- **.github/workflows/security-check.yml**: Monthly automated security and dependency check workflow
- **.github/workflows/schedule-posts.yml**: GitHub Actions workflow for scheduled publishing
- **layouts/recipes/list.json**: Template for recipe search JSON index
- **layouts/recipes/single.html**: Recipe page template with print functionality (print icon, print/email buttons)
- **static/css/custom.css**: Print stylesheet (`@media print`) for optimized recipe printing

## When in Doubt

1. Check existing content files for patterns
2. Run tests to verify changes
3. Check BRAND.md for design constraints
4. Check CONTENT_STYLE_GUIDE.md for writing style and voice guidelines
5. Preserve existing conventions unless explicitly asked to change them