Initial site setup

.ai-sessions/lessons.md

@@ -0,0 +1,23 @@
+# Lessons Learned
+
+## Recent
+<!-- 10 most recent lessons, newest first -->
+
+- When setting up a new year's conference site, check `git show <first-commit>:<file>` for the prior year's initial state, not the current state. The launch version is much simpler than the final version. (2026-04-08)
+- The initial 2026 site used a single simple color scheme with a placeholder PNG hero. The dual light/dark scheme with SVG logos came later. Start simple. (2026-04-08)
+- MkDocs Material `pytx-hero__image` class on an `<img>` tag directly (like 2026 initial) works better for placeholder PNGs than wrapping in flex divs with object-fit. (2026-04-08)
+- Ask about color scheme and dark mode preferences before writing CSS. Writing 490 lines that get replaced wastes time. (2026-04-08)
+- The schedule hook (hooks/schedule.py) gracefully skips when no data/schedule.yaml exists. Safe to include from day one. (2026-04-08)
+- `repo_name` in mkdocs.yml controls the text shown next to the git icon in the header. Easy to forget to update from the prior year. (2026-04-08)
+
+## Categories
+
+### MkDocs / Conference Site
+- When setting up a new year's conference site, check `git show <first-commit>:<file>` for the prior year's initial state, not the current state. The launch version is much simpler than the final version. (2026-04-08)
+- The initial 2026 site used a single simple color scheme with a placeholder PNG hero. The dual light/dark scheme with SVG logos came later. Start simple. (2026-04-08)
+- MkDocs Material `pytx-hero__image` class on an `<img>` tag directly (like 2026 initial) works better for placeholder PNGs than wrapping in flex divs with object-fit. (2026-04-08)
+- `repo_name` in mkdocs.yml controls the text shown next to the git icon in the header. Easy to forget to update from the prior year. (2026-04-08)
+- The schedule hook (hooks/schedule.py) gracefully skips when no data/schedule.yaml exists. Safe to include from day one. (2026-04-08)
+
+### Workflow
+- Ask about color scheme and dark mode preferences before writing CSS. Writing 490 lines that get replaced wastes time. (2026-04-08)

.ai-sessions/session-20260408-1602-initial-site-setup.md

@@ -0,0 +1,91 @@
+# Session Summary: PyTexas 2027 Initial Site Setup
+**Date**: 2026-04-08
+**Duration**: ~45 minutes
+**Conversation Turns**: ~25
+**Estimated Cost**: ~$15-20 (heavy file reads across 2025/2026 repos, many writes)
+**Model**: Claude Opus 4.6
+
+## Key Actions
+
+### Research Phase
+- Explored 2026 and 2025 repos in parallel (structure, git history, initial commits)
+- Identified what 2026 launched with in its first commit vs. what was added later
+- Read all key files from 2026: mkdocs.yml, content pages, CSS, workflows, hooks, templates
+
+### Site Creation
+- Created feature branch `initial-site-setup`
+- Built full directory structure for 2027
+- Copied and adapted all config files: mkdocs.yml, pyproject.toml, justfile, .gitignore, GitHub Actions workflows
+- Copied reusable binary assets from 2026 (favicon, parking map, prospectus SVGs, virtual images)
+- Created all content pages adapted for April 16-18, 2027 dates
+- Created placeholder pages for all commented-out nav items (schedule, speaking, virtual)
+- Set up schedule hook infrastructure (hooks/schedule.py with graceful skip when no data)
+- Verified site builds successfully
+
+### Styling & Theming
+- Initially copied 2026's dual light/dark color scheme (wrong approach)
+- Rewrote CSS to a single simplified scheme inspired by BBQ pit hero image
+- Removed dark mode toggle from mkdocs.yml
+- Colors: dark brown header, amber accents, green links, white background
+
+### Content Refinements
+- Updated hero image from broken SVG references to site-still-cooking.png placeholder
+- Commented out prospectus table (not ready for launch), added mailing list CTA
+- Updated homepage sponsor tile to point to sponsors mailing list
+- Enabled Speaking tab with CFP date (Oct 1, 2026), meetup CFP link, proposal help section
+- Fixed repo_name in both 2027 and 2026 mkdocs.yml (was "conference-site", now "pytexas/20XX")
+- Hunted and replaced all emdashes and sentence-level hyphens
+
+### Documentation
+- Created CLAUDE.md with architecture overview and dev guide
+- Wrote commit message to commit-msg.md
+
+## Prompt Inventory
+
+| Prompt/Command | Action Taken | Outcome |
+|---|---|---|
+| Set up 2027, look at 2026/2025 history | Parallel exploration of both repos, identified initial launch scope | Clear picture of what to build |
+| Python version should be 3.14 | Updated .python-version | Corrected before writing other files |
+| Do you have pages so I can turn on nav later? | Created 6 placeholder pages (schedule/*, speaking, virtual) | All nav entries backed by files |
+| Added site-still-cooking.png | Updated home.html hero to use the image | Image displayed (but stretched) |
+| Image is stretched terribly | Checked 2026 initial approach, simplified hero to use class not inline img div | Fixed with pytx-hero__image class |
+| White box around image, change to match BBQ pit, remove dark mode | Rewrote CSS to single scheme, BBQ colors, white bg, no toggle | Clean look matching the image |
+| Remove prospectus, update sponsor tile | Commented out prospectus like 2026 did, added mailing list CTA | Launch-ready sponsor pages |
+| repo_name wrong | Fixed in both 2027 and 2026 mkdocs.yml | Both repos corrected |
+| Links too brown, make them green | Changed link color to --pytx-green (#4A7C59) | Links stand out properly |
+| Was there a speaking tab on initial 2026? | Checked, there wasn't. Discussed adding one for 2027 | Added speaking with CFP info |
+| Add meetup CFP link, proposal help section | Added "Want Help Drafting Your CFP?" section with program@pytexas.org | Speaking page complete |
+| CFP opens 10/1/2026 | Updated speaking page and homepage | Dates consistent |
+| Kill all emdashes | Grep'd and replaced 2 instances | Clean prose |
+| Hyphens scream AI | Confirmed fix, saved feedback to memory | Will avoid in future |
+
+## Efficiency Insights
+
+### What went well
+- Parallel agent exploration of 2026 and 2025 repos saved significant time upfront
+- Checking the initial 2026 git commit (`git show 3133b06:`) was key to understanding what to launch with vs. what comes later
+- Copying the 2026 approach for commented-out prospectus, nav phasing, and placeholder images avoided reinventing patterns
+
+### What could have been more efficient
+- Initially copied the complex dual-scheme CSS from 2026's final state instead of its simpler initial state. Should have checked the initial commit CSS first.
+- The hero image went through 3 iterations (SVG divs -> inline style -> class) because I started with the final 2026 approach instead of the initial one
+- Could have asked about color scheme/dark mode preference before writing 490 lines of CSS that got replaced
+
+### Course corrections
+- User corrected Python version to 3.14 (I defaulted to 2026's 3.13)
+- User flagged stretched image, which led to checking initial 2026 approach
+- User flagged white box/wrong color scheme, leading to full CSS rewrite
+- User flagged brown links not looking like links
+
+## Process Improvements
+
+- When setting up a new year's conference site, always check the **initial commit** of the prior year, not just the current state. The initial launch is much simpler.
+- Ask about color scheme preferences before writing CSS. The "match the placeholder image" approach was the right call.
+- For conference sites that phase content in, start with the simplest possible styling and build up.
+
+## Observations
+
+- The PyTexas conference site follows a clear annual pattern: launch simple ~1 year out, add CFP/tickets in fall, add schedule/speakers in winter, final polish in spring.
+- The 2026 repo evolved from requirements.txt to pyproject.toml+uv mid-lifecycle. Starting 2027 with the modern stack from day one saves that migration.
+- The schedule hook (hooks/schedule.py) is a nice piece of infrastructure that was added mid-2026. Including it from the start in 2027 means one less thing to build later.
+- The "asking-for-sponsorship.md" advocacy guide with email templates is a unique and valuable piece of content that carries over well year to year.

.github/workflows/check.yml

@@ -0,0 +1,19 @@
+name: Dependency Review
+on:  # Triggers on PRs.
+  - pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 'Dependency Review'
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: always
+
+env:
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: ci
+on:
+  workflow_run:
+    workflows: ["Check Links"]
+    types:
+      - completed
+    branches: [ "main" ]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: sudo apt install libcairo2 zlib1g-dev libjpeg-dev
+      - run: uv sync
+      - run: uv run mkdocs gh-deploy --force

.github/workflows/link-check.yml

@@ -0,0 +1,49 @@
+name: Check Links
+
+on:
+  push:
+    branches: ['*']
+  pull_request:
+    branches: ['*']
+  workflow_dispatch:
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build site
+        run: uv run mkdocs build --strict
+
+      - name: Strip canonical and og:url meta tags
+        run: find site -name '*.html' -exec sed -i '/<link rel="canonical"/d;/<meta property="og:url"/d' {} +
+
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v2.2.0
+        with:
+          args: >
+            --verbose
+            --no-progress
+            --accept 200,204,206,301,302,307,308,429
+            'site/**/*.html'
+          fail: true
+
+      - name: Upload results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: lychee-report
+          path: lychee/out.md

.gitignore

@@ -1,3 +1,11 @@
+# PyTexas specific
+.lycheeignore
+.lycheecache
+.lycheecache/
+commit-msg.md
+.idea/*
+site/*
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

.python-version

@@ -0,0 +1 @@
+3.14

CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PyTexas 2027 Conference website — a static site built with MkDocs Material, deployed to GitHub Pages. Conference dates: **April 16-18, 2027** in Austin, TX at the Austin Central Library.
+
+## Build & Development Commands
+
+All commands use `just` (task runner) with `uv` (Python package manager):
+
+```bash
+just install          # Install dependencies (uv sync)
+just serve            # Local dev server on port 8000
+just serve-port 8001  # Dev server on specific port
+just build            # Build static site to site/
+just validate         # Build with --strict flag
+just link-check       # Build + check all links with lychee
+just check            # Run all quality checks (alias for link-check)
+just clean            # Remove site/, .lycheecache/, __pycache__/
+just deploy           # Deploy to GitHub Pages (production only)
+```
+
+**System prerequisite:** Cairo library (`brew install cairo` on macOS).
+
+## Architecture
+
+### Content Pipeline
+
+```
+docs/*.md  ──────────────────────────┐
+data/schedule.yaml ─→ hooks/schedule.py ─→ docs/schedule/index.md ──→ mkdocs build ──→ site/
+overrides/*.html ────────────────────┘
+docs/stylesheets/extra.css ──────────┘
+```
+
+- **`docs/`** — Markdown source files. MkDocs renders these into the static site.
+- **`hooks/schedule.py`** — MkDocs `on_pre_build` hook that reads `data/schedule.yaml` and auto-generates `docs/schedule/index.md`. Skips gracefully if no YAML exists yet.
+- **`overrides/`** — MkDocs Material template overrides:
+  - `home.html` — Hero section with placeholder image. When the 2027 logo is ready, uncomment the day/night SVG `<div>` blocks and remove the placeholder `<img>` tag. The logo SVGs go in `docs/assets/images/logos/pytexas2027_day_color.svg` and `pytexas2027_night_color.svg`.
+  - `main.html` — Site-wide announcement banner.
+- **`docs/stylesheets/extra.css`** — Custom color scheme (`pytx2027` / `pytx2027_light`). Colors are placeholders from 2026; update CSS custom properties when the 2027 logo palette is finalized. Also update `social.cards_layout_options` in `mkdocs.yml` to match.
+
+### Navigation Phasing
+
+Several nav sections in `mkdocs.yml` are commented out for later activation. The placeholder pages already exist — just uncomment when ready:
+
+- `Speaking` — uncomment when CFP opens (update dates/links in `docs/speaking.md`)
+- `Schedule` section — uncomment when schedule is published (populate `data/schedule.yaml`)
+- `Virtual Attendance` — uncomment when virtual event details are confirmed
+- `Our Sponsors` listing — uncomment when sponsors are signed (add logos to `docs/assets/images/sponsors/`)
+
+### CI/CD Pipeline (GitHub Actions)
+
+1. **link-check.yml** — Builds with `--strict`, runs lychee link checker. Triggers on all pushes/PRs.
+2. **ci.yml** — Deploys to GitHub Pages. Only runs on `main` after link-check succeeds.
+3. **check.yml** — Dependency vulnerability review on PRs.
+
+### Color Scheme
+
+Placeholder colors (from 2026 — update when 2027 logo is designed):
+
+| Color  | Hex     | CSS Variable    |
+|--------|---------|-----------------|
+| Green  | #204F3C | `--pytx-green`  |
+| Yellow | #C2B64A | `--pytx-yellow` |
+| Orange | #C73810 | `--pytx-orange` |
+| Brown  | #443229 | `--pytx-brown`  |
+| Blue   | #4B8EC2 | `--pytx-blue`   |
+| Cream  | #FAFAF8 | `--pytx-light-cream` |
+
+When updating colors: change both `pytx2027_light` and `pytx2027` (dark) scheme blocks in `extra.css`, gradient backgrounds in the `.pytx-container` rules, and `cards_layout_options` in `mkdocs.yml`.
+
+## Key Conventions
+
+- Conference content pages live in `docs/`. Venue, food, parking, hotel info carries over year-to-year.
+- Sponsor logos go in `docs/assets/images/sponsors/`, speaker photos in `docs/assets/images/speakers/`.
+- The schedule is data-driven: edit `data/schedule.yaml`, not `docs/schedule/index.md` (it gets overwritten on build).
+- Prospectus demographic data in `docs/sponsors/sponsor-us.md` uses Mermaid pie charts — update with post-conference survey data.
+- The `asking-for-sponsorship.md` page has email templates with year-specific dates that need updating.