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

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.