feat: archive substack posts

[rathermercurial]

Goal

Create a new content collection that imports Bread Co-op's Substack posts into an archive on the docs site.

Requirements

• New collection is read-only — not exposed in Keystatic.
• Populated from the Substack RSS feed.
• Resulting collection/pages are pre-rendered and static-only (no live collections).
• Use incremental builds if possible on the deploy target.

Recommended approach

Use Astro's Content Layer with a custom loader (built in on Astro 6 — no experimental flag needed):

• @ascorbic/feed-loader (RSS/Atom/RDF; maintained by Astro core maintainer Matt Kane). Define a build-time collection in src/content.config.ts:

  import { feedLoader } from '@ascorbic/feed-loader';
  
  substack: defineCollection({
    loader: feedLoader({ url: 'https://<publication>.substack.com/feed' }),
  }),

• "Read-only / not in Keystatic" is satisfied automatically — just don't add a Keystatic collection() for it.
• Static by default (current output: 'static').
• Render an archive index + per-post pages with getCollection('substack') inside getStaticPaths(), wrapped in <StarlightPage> for consistent layout.

Open questions / caveats

• ⚠️ Substack RSS only exposes ~the 20 most recent posts, not the full back-catalog. A complete archive needs a one-time bulk import (Substack export or a paginated scrape) seeded as markdown, with the feed loader keeping it current going forward. Decide whether "archive" means full history or rolling-recent.
• The original note said "incremental builds on vercel", but the site deploys to Netlify (netlify.toml, and @astrojs/netlify per feat: deploy Keystatic admin UI to Netlify (SSR adapter + GitHub App redirect) #12). The Netlify equivalent is on-demand/ISR via the adapter — wording to align.

References

• Community Loaders for Astro Content Layer
• Astro Content Loader API reference
• feed-loader readme
• Starlight custom pages / <StarlightPage>

[BreadrichEngels]

Preliminary research — substack archive collection

Requirements are clear; the open questions are how to ingest and how much of the archive is actually reachable.

Recommended approach — Astro Content Layer custom loader (built in on Astro 6, no experimental flag needed):

• Use @ascorbic/feed-loader (RSS/Atom/RDF; by Astro core maintainer Matt Kane). Build-time collection in src/content.config.ts:

  import { feedLoader } from '@ascorbic/feed-loader';
  substack: defineCollection({
    loader: feedLoader({ url: 'https://<publication>.substack.com/feed' }),
  }),

• This satisfies "read-only / not in Keystatic" automatically — just don't add a Keystatic collection(). Static by default (current output: 'static').
• Render an archive index + per-post pages with getCollection('substack') inside getStaticPaths(), wrapped in <StarlightPage> for consistent layout.

⚠️ Two things to settle before scoping:

1. Substack's RSS only exposes ~the 20 most recent posts, not the full back-catalog. A complete archive needs a one-time bulk import (Substack export or a paginated scrape) seeded as markdown, with the feed loader keeping it current going forward. Decide whether "archive" means full history or rolling-recent.
2. The issue says "incremental builds on vercel", but the site deploys to Netlify (netlify.toml, and @astrojs/netlify in feat: deploy Keystatic admin UI to Netlify (SSR adapter + GitHub App redirect) #12). Netlify's equivalent is on-demand/ISR via the adapter — worth aligning the wording.

Refs:

• Community Loaders for Astro Content Layer
• Astro Content Loader API reference
• feed-loader readme
• Starlight custom pages / <StarlightPage>