Initial commit - but way too late.

openspec/changes/archive/2026-02-10-fix-sub-pages/design.md

@@ -0,0 +1,40 @@
+## Context
+
+The site is statically generated (Astro) and deployed behind nginx in Docker. Users can browse to `/videos`, `/podcast`, and `/about`, but direct navigation to these paths is currently resulting in a 404 in the deployed environment.
+
+The static output contains directory-based pages (`/videos/index.html`, `/podcast/index.html`, `/about/index.html`). Some nginx configurations resolve directory indexes only for requests ending with `/` (e.g., `/videos/`) and may 404 for the no-trailing-slash path (`/videos`) unless explicitly handled.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Ensure `/videos`, `/podcast`, and `/about` resolve successfully (200) in the nginx/Docker deployment.
+- Ensure requests to both the trailing slash and non-trailing slash forms work predictably.
+- Keep behavior consistent with the SEO spec (indexable pages remain distinct; no SPA-style fallback masking real 404s).
+
+**Non-Goals:**
+- Changing site IA or page content.
+- Introducing a client-side router fallback (SPA rewrite) that would hide missing pages.
+
+## Decisions
+
+### 1) Fix nginx static routing for directory index pages
+
+**Decision:** Update nginx `try_files` to include `$uri/index.html` so requests like `/videos` resolve to `/videos/index.html` when present.
+
+**Rationale:** This explicitly supports directory index pages without requiring a redirect, and prevents the common 404 case when the request does not include a trailing slash.
+
+**Alternatives considered:**
+- Redirect `/videos` -> `/videos/`: acceptable, but adds an extra hop and needs per-route rules or more complex logic.
+- Rewrite all unknown paths to `/index.html`: not acceptable; would mask real 404s and break the semantics of distinct indexable pages.
+
+### 2) Add a small verification step as part of deployment
+
+**Decision:** Validate the deployed container serves `/videos`, `/podcast`, and `/about` as 200 in addition to verifying the build output includes the expected `index.html` files.
+
+**Rationale:** This catches config regressions and ensures the fix applies to the real serving stack.
+
+## Risks / Trade-offs
+
+- [Path collisions] -> Using `$uri/index.html` could cause unexpected resolution if both a file and a directory exist. Mitigation: keep route structure simple and prefer one form.
+- [Platform differences] -> Non-nginx deployments might still behave differently. Mitigation: document that the Docker/nginx deploy is canonical and ensure other hosts use equivalent rules.
+