Add calendar and event collection

[rathermercurial]

Goal

Add a calendar and gallery to display event listings (past and upcoming).

Decisions to make first

• Authoring: Keystatic-managed (editors add events in the CMS — recommended, matches the content workflow) vs. file-only.
• Display: a real month-grid calendar vs. a simpler upcoming / past list (gallery). Recommend starting with sorted upcoming/past lists — a grid calendar is a much bigger lift for little benefit on a docs site.
• Per-event pages (each event routable) vs. a single listing page only.

Recommended approach

• New events collection. If Keystatic-managed, add a collection() with fields.date(...) for start/end plus title, location, url, description, image.
  • ⚠️ Known Keystatic↔Astro gotcha: Keystatic stores dates as ISO strings, and an Astro z.date() schema can fail validation. Use z.coerce.date() (or z.string().transform(...)) in the collection schema. Background on the datetime-local quirk: Exploring Keystatic (armno).
• getCollection('events') ordering is non-deterministic — sort by date yourself, then partition upcoming = date >= now / past = date < now.
• Render via <StarlightPage> (splash layout) for the listing; getStaticPaths() for any per-event pages.

Caveat (ties to #18 / #19)

A standalone events page rendered with <StarlightPage> is not part of the docs collection and won't auto-appear in the docs sidebar. Integrating it into nav needs either a manual sidebar link or the topics plugin from #18 — sequence accordingly.

References

• Keystatic field types (incl. date)
• Astro × Keystatic guide
• Astro content collections — querying & sorting
• Starlight pages / <StarlightPage>

[BreadrichEngels]

Preliminary research — calendar & events collection

This is the thinnest of the open issues (one line), so most of the work is decisions, not code.

Decide first:

• Authoring: Keystatic-managed (editors add events in the CMS — recommended, matches the content workflow) vs. file-only.
• Display: a real month-grid calendar vs. a simpler upcoming / past list (gallery). Recommend starting with sorted upcoming/past lists — a grid calendar is a much bigger lift for little benefit on a docs site.
• Per-event pages (each event routable) vs. a single listing page only.

Suggested shape:

• New events collection. If Keystatic-managed, add a collection() with fields.date(...) for start/end plus title, location, url, description, image.
  • ⚠️ Known Keystatic↔Astro gotcha: Keystatic stores dates as ISO strings, and an Astro z.date() schema can fail validation. Use z.coerce.date() (or z.string().transform(...)). Background on the datetime-local quirk: Exploring Keystatic (armno).
• getCollection('events') ordering is non-deterministic — sort by date yourself, then partition upcoming = date >= now / past = date < now.
• Render via <StarlightPage> (splash layout) for the listing; getStaticPaths() for any per-event pages.

⚠️ Ties into #18/#19: a standalone events page rendered with <StarlightPage> is not part of the docs collection and won't auto-appear in the docs sidebar — see my note on #19.

Refs:

• Keystatic field types (incl. date)
• Astro × Keystatic guide
• Astro content collections — querying & sorting
• Starlight pages / <StarlightPage>