stack-site-builder 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -11,6 +11,30 @@ content schema, while a consuming site supplies only content, taxonomy data and
 config. Sites track the theme with `pnpm up stack-site-builder`, so each release
 here is a plain version bump they pull in.
 
+## [1.15.0] - 2026-07-22
+
+### Added
+
+- **`courses` collection** — an opt-in section (`sections: { courses: true }`)
+  for sites that teach rather than catalog: course cards with difficulty stars
+  (`level` 1–5, localized labels), duration (`hours`), a manual sort key
+  (`order`, highest first — e.g. `"2601-01"` cohort keys), a `type` tag, linked
+  slide decks (`slides`), related courses, and the usual draft/private/teaser
+  flags. Routes mirror concepts (`/course/`, `/course/<id>/`,
+  `/course/category/<id>/`); an enabling site adds
+  `src/data/course-categories.ts` (exporting `courseTree` / `courseCatOf`) and
+  may pass `courseCategoryMap` to `defineAasCollections` for build-time
+  category validation. Because the section needs that site data, it stays off
+  until a site explicitly opts in — a theme upgrade alone changes nothing.
+- **Body components** — `Bookmark` (link-preview card), `Embed` (responsive
+  iframe wrapper for demos/videos, with `ratio`/`height`/`sandbox`), and
+  `Lead` (intro paragraph), importable from
+  `stack-site-builder/components/*` in any MDX body.
+- **RSS feed** — a per-locale feed of the articles collection at `/rss.xml`
+  (default locale) and `/<code>/rss.xml`, injected with the `articles` section
+  and advertised via `<link rel="alternate">`. Drafts and private entries stay
+  out, mirroring the sitemap.
+
 ## [1.14.0] - 2026-07-21
 
 ### Added
@@ -138,6 +162,7 @@ catalog sites from a thin content-only repository.
 - **Standalone development setup** — a devcontainer and a minimal `playground/`
   consuming site for developing and previewing the theme on its own.
 
+[1.15.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.13.0...v1.14.0
 [1.13.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.12.0...v1.13.0
 [1.12.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.11.0...v1.12.0

package/README.md

@@ -38,9 +38,9 @@ export const collections = defineAasCollections({ categoryMap });
 | --- | --- |
 | `src/data/site.ts` | Site identity: name, repo URL, the `locales` it ships, optional `sections` toggles, per-locale UI string overrides |
 | `src/data/categories.ts` | The tool-catalog category tree (validated against content) |
-| `src/data/concept-categories.ts` · `article-categories.ts` | Taxonomies for concepts / articles |
+| `src/data/concept-categories.ts` · `article-categories.ts` · `course-categories.ts` (opt-in) | Taxonomies for concepts / articles / courses |
 | `src/data/glossary.mjs` | `[[Term]]` wikilink targets |
-| `src/content/{stacks,concepts,articles,slides}/` | The content, one MDX file per locale |
+| `src/content/{stacks,concepts,courses,articles,slides}/` | The content, one MDX file per locale |
 | `src/content/pages/` | Standalone top-level pages (e.g. an About/소개), rendered at `/<slug>/` and optionally linked in the header nav |
 | `public/` · `samples/` | Logos/favicons and runnable sample projects |
 
@@ -72,7 +72,7 @@ The rest are opt-out — **concepts, articles, samples, slides, glossary** and t
 standalone **pages** collection (About/소개, …) — so a site can ship only what it
 needs. Turning one off removes both its routes and its header-nav item. (`pages`
 also has finer control: each page's `nav` / `draft` frontmatter, or simply not
-authoring it.)
+authoring it.) **courses** is the one opt-IN section — see below.
 
 Declare the toggles once in `src/data/site.ts` and forward them to the theme in
 astro.config (which needs them to skip route injection). Import `SectionKey` from
@@ -93,6 +93,57 @@ import { site } from './src/data/site';
 integrations: [aasTheme({ glossary, sections: site.sections })];
 ```
 
+## Courses (opt-in)
+
+A course section for sites that teach: cards with difficulty stars and
+duration, cohort ordering, category browse pages, and paid courses gated by
+the same private-content machinery. It stays off until a site opts in, because
+it needs site data:
+
+1. `sections: { courses: true }` in `src/data/site.ts` (forwarded to
+   `aasTheme` as above).
+2. `src/data/course-categories.ts` exporting `courseTree` / `courseCatOf`
+   (copy `playground/src/data/course-categories.ts` and edit the tree).
+3. Optionally pass the map to
+   `defineAasCollections({ categoryMap, courseCategoryMap })` so course
+   category ids are validated at build time.
+
+Then author `src/content/courses/<lang>/<slug>.mdx`:
+
+```yaml
+title: Getting Started with AI Agents
+description: A hands-on introduction.
+date: 2026-06-01
+category: ai-basics # id from course-categories.ts
+level: 2 # difficulty 1–5, shown as stars
+hours: "1:30" # duration, shown verbatim
+order: "2601-01" # manual sort key, highest first (optional)
+slides: [deck-id] # decks in the slides collection (optional)
+private: true # paid course — body ships encrypted
+teaser: A public one-liner for the login gate.
+```
+
+Routes mirror concepts: `/course/`, `/course/<slug>/`, `/course/category/<id>/`.
+
+## Body components
+
+Reusable MDX-body components, importable from any collection's content:
+`Bookmark` (link-preview card), `Embed` (responsive iframe for demos/videos —
+`ratio`, `height`, `sandbox`), `Lead` (intro paragraph).
+
+```mdx
+import Bookmark from 'stack-site-builder/components/Bookmark.astro';
+
+<Bookmark url="https://…" title="…" description="…" />
+```
+
+## RSS
+
+The articles collection feeds `/rss.xml` (default locale) and
+`/<code>/rss.xml`, advertised with `<link rel="alternate">`. Drafts and
+private entries stay out (mirroring the sitemap); the feed is injected only
+while the `articles` section is on.
+
 ## Private content
 
 Any entry (tools, concepts, articles, slides, pages) can require login:

package/index.d.ts

@@ -1,16 +1,26 @@
 import type { AstroIntegration } from 'astro';
 
 /** Optional content sections that a site can turn off. `pages` is the
- *  standalone-pages collection (About/소개, …). */
-export type SectionKey = 'concepts' | 'articles' | 'samples' | 'slides' | 'glossary' | 'pages';
+ *  standalone-pages collection (About/소개, …); `courses` is opt-IN
+ *  (default off — enabling it requires site-side course data). */
+export type SectionKey =
+  | 'concepts'
+  | 'articles'
+  | 'courses'
+  | 'samples'
+  | 'slides'
+  | 'glossary'
+  | 'pages';
 
 export interface AasThemeOptions {
   /** The site's glossary (`src/data/glossary.mjs`) — `[[wikilink]]` targets. */
   glossary: Record<string, unknown>;
   /**
-   * Turn optional sections off (all on by default), e.g. `{ slides: false }`.
-   * A disabled section's routes aren't injected; pass the same object to
-   * `src/data/site.ts` `sections` so its header-nav item is hidden too.
+   * Section toggles, e.g. `{ slides: false }`. Every section is on by default
+   * except `courses`, which is opt-in (`{ courses: true }`) and additionally
+   * requires `src/data/course-categories.ts` on the site. A disabled section's
+   * routes aren't injected; pass the same object to `src/data/site.ts`
+   * `sections` so its header-nav item is hidden too.
    */
   sections?: Partial<Record<SectionKey, boolean>>;
 }

package/index.mjs

@@ -29,6 +29,8 @@ const PAGES = [
   // Standalone top-level pages (the `pages` collection), e.g. an About/소개
   // page. A single dynamic route per locale renders every entry at `/<slug>/`.
   '[page].astro',
+  // Per-locale RSS feed of the articles collection (an endpoint, not a page).
+  'rss.xml.ts',
   'article/index.astro',
   'article/[...id].astro',
   'article/category/[id].astro',
@@ -36,6 +38,9 @@ const PAGES = [
   'concept/index.astro',
   'concept/[...id].astro',
   'concept/category/[id].astro',
+  'course/index.astro',
+  'course/[...id].astro',
+  'course/category/[id].astro',
   'glossary.astro',
   'sample/index.astro',
   'sample/[folder].astro',
@@ -47,10 +52,11 @@ const PAGES = [
 ];
 
 /** `[...lang]/article/[...id].astro` → `/[...lang]/article/[...id]`,
- *  `[...lang]/index.astro` → `/[...lang]` */
+ *  `[...lang]/index.astro` → `/[...lang]`,
+ *  `[...lang]/rss.xml.ts` → `/[...lang]/rss.xml` (endpoints keep their name). */
 /** @param {string} file */
 function patternOf(file) {
-  const p = file.replace(/\.astro$/, '').replace(/\/?index$/, '');
+  const p = file.replace(/\.(astro|ts)$/, '').replace(/\/?index$/, '');
   return `/${p}`.replace(/\/$/, '') || '/';
 }
 
@@ -60,19 +66,27 @@ function patternOf(file) {
 function sectionOf(file) {
   if (file.startsWith('concept/')) return 'concepts';
   if (file.startsWith('article/')) return 'articles';
+  if (file.startsWith('course/')) return 'courses';
   if (file.startsWith('sample/')) return 'samples';
   if (file.startsWith('slides/')) return 'slides';
   if (file === 'glossary.astro') return 'glossary';
   if (file === '[page].astro') return 'pages';
+  if (file === 'rss.xml.ts') return 'articles'; // the feed is the blog's
   return null;
 }
 
+// Sections that are opt-IN rather than opt-out: their routes are injected only
+// when the site passes `{ <key>: true }`. `courses` needs site-side data
+// (src/data/course-categories.ts), so a theme upgrade alone must not enable it.
+const OPT_IN_SECTIONS = new Set(['courses']);
+
 /**
  * @param {object} opts
  * @param {Record<string, any>} opts.glossary — the site's glossary
  *   (`src/data/glossary.mjs`), used by `[[wikilink]]` resolution.
  * @param {Partial<Record<string, boolean>>} [opts.sections] — optional-section
  *   toggles (`{ slides: false }`); a disabled section's routes are not injected.
+ *   `courses` is opt-IN (`{ courses: true }`) — it needs site-side course data.
  *   Keep it in sync with `src/data/site.ts` `sections` (which hides the nav item).
  * @returns {import('astro').AstroIntegration[]}
  */
@@ -97,6 +111,7 @@ export default function aasTheme({ glossary, sections = {} }) {
         for (const file of PAGES) {
           const section = sectionOf(file);
           if (section && sections[section] === false) continue;
+          if (section && OPT_IN_SECTIONS.has(section) && sections[section] !== true) continue;
           injectRoute({
             pattern: patternOf(`[...lang]/${file}`),
             entrypoint: `stack-site-builder/pages/[...lang]/${file}`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "license": "MIT",
   "description": "The engine behind the awesome-*-stack catalog sites: an Astro theme with the catalog/concepts/articles/slides/samples routes, components, styles and markdown pipeline. Sites provide content, taxonomy data and config.",
   "repository": {
@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@astrojs/mdx": "^4.2.0",
+    "@astrojs/rss": "^4.0.0",
     "@astrojs/sitemap": "^3.3.0",
     "@tailwindcss/vite": "^4.1.0",
     "markdown-it": "^14.2.0",

package/src/components/Bookmark.astro

@@ -0,0 +1,37 @@
+---
+// Link-preview card for MDX bodies (a Hugo `bookmark` shortcode successor):
+//   <Bookmark url="https://…" title="…" description="…" />
+import ArrowUpRight from './ArrowUpRight.astro';
+
+interface Props {
+  url: string;
+  title: string;
+  description?: string;
+  /** Host label under the title; derived from `url` when omitted. */
+  host?: string;
+}
+
+const { url, title, description, host = new URL(url).host } = Astro.props;
+---
+
+<a
+  href={url}
+  target="_blank"
+  rel="noopener noreferrer"
+  class="not-prose aas-lift my-4 block rounded-2xl border border-[var(--aas-border)] bg-[var(--aas-panel)] p-4 no-underline"
+>
+  <span class="flex items-center justify-between gap-3">
+    <span class="min-w-0">
+      <span class="block truncate font-semibold text-[var(--aas-text)]">{title}</span>
+      {
+        description && (
+          <span class="mt-1 line-clamp-2 block text-sm leading-relaxed text-[var(--aas-muted)]">
+            {description}
+          </span>
+        )
+      }
+      <span class="mt-1.5 block text-xs text-[var(--aas-muted)] opacity-75">{host}</span>
+    </span>
+    <ArrowUpRight size={18} class="shrink-0 text-[var(--aas-muted)]" />
+  </span>
+</a>

package/src/components/CourseCard.astro

@@ -0,0 +1,97 @@
+---
+import { Image } from 'astro:assets';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { formatDate, isoDate } from '../lib/dates';
+import { inlineMd } from '../lib/inline-md';
+import DifficultyStars from './DifficultyStars.astro';
+import type { ImageMetadata } from 'astro';
+
+interface Props {
+  lang: Lang;
+  slug: string;
+  title: string;
+  description: string;
+  tags: string[];
+  image?: ImageMetadata;
+  imageAlt?: string;
+  level?: number;
+  hours?: string;
+  version?: string;
+  date: Date;
+  updated?: Date;
+  /** Manual sort key (`order` frontmatter) — beats date recency in the list sort. */
+  order?: string;
+  /** Private entry: show a lock and the (public) `teaser` instead of the description. */
+  isPrivate?: boolean;
+  teaser?: string;
+}
+
+const {
+  lang,
+  slug,
+  title,
+  description,
+  tags,
+  image,
+  imageAlt,
+  level,
+  hours,
+  version,
+  date,
+  updated,
+  order,
+  isPrivate = false,
+  teaser,
+} = Astro.props;
+const t = useTranslations(lang);
+const shownDesc = isPrivate ? (teaser ?? '') : description;
+// ListControls' "recent" sort compares data-date strings descending. Putting
+// `order` in the key keeps the manual curation working client-side too: order
+// keys ("2601-01") outrank ISO dates ("20…") lexicographically, matching the
+// server-side getCourses() order — so the on-load sort causes no reflow.
+const sortKey = order ?? isoDate(updated ?? date);
+const shownDate = updated ?? date;
+---
+
+<a
+  href={getRelativeLocaleUrl(lang, `course/${slug}/`)}
+  data-name={title.toLowerCase()}
+  data-date={sortKey}
+  class="aas-lift block overflow-hidden rounded-3xl border border-[var(--aas-border)] bg-[var(--aas-panel)] no-underline"
+>
+  {image && <Image src={image} alt={imageAlt ?? title} class="aspect-[16/9] w-full object-cover" />}
+  <div class="p-5">
+    <p class="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-[var(--aas-muted)]">
+      {level && <DifficultyStars lang={lang} level={level} />}
+      {
+        hours && (
+          <span class="inline-flex items-center gap-1" title={t('course.hours')}>
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>
+            {hours}
+          </span>
+        )
+      }
+      <time datetime={isoDate(shownDate)}>{formatDate(shownDate, lang)}</time>
+      {version && <span>{t('meta.docVersion')} {version}</span>}
+    </p>
+    <h3 class="mt-1 text-lg font-semibold text-[var(--aas-text)]">
+      {isPrivate && <span aria-label={t('private.badge')} title={t('private.badge')}>🔒 </span>}{title}
+    </h3>
+    <p
+      class="aas-md mt-2 text-sm leading-relaxed text-[var(--aas-muted)]"
+      set:html={inlineMd(shownDesc)}
+    />
+    {
+      tags.length > 0 && (
+        <div class="mt-3 flex flex-wrap gap-1.5">
+          {tags.slice(0, 4).map((tag) => (
+            <span class="rounded-full border border-[var(--aas-border)] px-2 py-0.5 text-xs text-[var(--aas-muted)]">
+              {tag}
+            </span>
+          ))}
+        </div>
+      )
+    }
+  </div>
+</a>

package/src/components/CourseDetail.astro

@@ -0,0 +1,116 @@
+---
+import { render, getCollection } from 'astro:content';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { getCourses, courseSlugOf, type CourseEntry } from '../lib/courses';
+import { inlineMd } from '../lib/inline-md';
+import { Image } from 'astro:assets';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { formatDate } from '../lib/dates';
+import { sectionEnabled } from '../lib/sections';
+import MermaidLoader from './MermaidLoader.astro';
+import TocRail from './TocRail.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import DifficultyStars from './DifficultyStars.astro';
+import { courseTree, courseCatOf } from '@aas-data/course-categories';
+import RelatedCourses from './RelatedCourses.astro';
+
+interface Props {
+  entry: CourseEntry;
+  lang: Lang;
+}
+
+const { entry, lang } = Astro.props;
+const t = useTranslations(lang);
+const { Content, headings } = await render(entry);
+const data = entry.data;
+const tocItems = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+const bodyHasMermaid = (entry.body ?? '').includes('```mermaid');
+
+// Sibling courses linked from frontmatter (mutual cross-links, like concepts).
+const courses = await getCourses(lang);
+const courseBySlug = new Map(courses.map((c) => [courseSlugOf(c), c]));
+const relatedCourses = data.related
+  .map((sl) => courseBySlug.get(sl))
+  .filter(Boolean) as CourseEntry[];
+
+// Decks in the `slides` collection that belong to this course. Only linked when
+// the slides section is enabled (otherwise its routes don't exist) and the deck
+// id actually resolves — a typo just drops the chip instead of a dead link.
+const slideDecks = sectionEnabled('slides') && data.slides.length > 0
+  ? (await getCollection('slides')).filter(
+      (d) => data.slides.includes(d.id) && !d.data.draft,
+    )
+  : [];
+
+// Breadcrumb: All courses › category › subcategory… (each segment linked).
+const crumbs = [
+  { label: t('course.backToCourses'), href: getRelativeLocaleUrl(lang, 'course/') },
+  ...courseTree.pathOf(courseCatOf(data.category)).map((c) => ({
+    label: c.label[lang],
+    href: getRelativeLocaleUrl(lang, `course/category/${c.id}/`),
+  })),
+];
+---
+
+<Breadcrumb segments={crumbs} />
+
+<header class="mt-4 pb-6">
+  <h1 class="text-3xl font-bold tracking-tight">{data.title}</h1>
+  <p class="mt-2 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-[var(--aas-muted)]">
+    {data.level && <DifficultyStars lang={lang} level={data.level} size={14} />}
+    {
+      data.hours && (
+        <span class="inline-flex items-center gap-1" title={t('course.hours')}>
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>
+          {data.hours}
+        </span>
+      )
+    }
+    {data.version && <span>{t('meta.docVersion')} {data.version}</span>}
+    {
+      data.updated && (
+        <span>
+          {t('course.updated')} {formatDate(data.updated, lang)}
+        </span>
+      )
+    }
+  </p>
+  <p class="mt-2 aas-md text-lg whitespace-pre-line text-[var(--aas-muted)]" set:html={inlineMd(data.description)} />
+  {
+    slideDecks.length > 0 && (
+      <p class="mt-3 flex flex-wrap items-center gap-2">
+        <span class="text-xs font-semibold tracking-wide text-[var(--aas-muted)] uppercase">
+          {t('course.slides')}
+        </span>
+        {slideDecks.map((d) => (
+          <a
+            href={getRelativeLocaleUrl(lang, `slides/${d.id}/`)}
+            class="rounded-full border border-[var(--aas-border)] bg-[var(--aas-panel)] px-3 py-1 text-sm text-[var(--aas-text)] no-underline hover:bg-[var(--aas-tint)]"
+          >
+            {d.data.title}
+          </a>
+        ))}
+      </p>
+    )
+  }
+  {
+    data.image && (
+      <Image
+        src={data.image}
+        alt={data.imageAlt ?? data.title}
+        class="mt-5 aspect-[2/1] w-full rounded-2xl border border-[var(--aas-border)] object-cover"
+      />
+    )
+  }
+</header>
+
+<RelatedCourses lang={lang} courses={relatedCourses} />
+
+<div class="mt-8 flex items-start gap-8">
+  <article class="prose max-w-none aas-reading min-w-0 flex-1">
+    <Content />
+  </article>
+  <TocRail lang={lang} items={tocItems} />
+</div>
+
+{bodyHasMermaid && <MermaidLoader />}

package/src/components/CourseIndex.astro

@@ -0,0 +1,145 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import CourseCard from './CourseCard.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import ListControls from './ListControls.astro';
+import ArrowUpRight from './ArrowUpRight.astro';
+
+const PAGE = 12;
+import { courseTree, courseCatOf } from '@aas-data/course-categories';
+import { getCourses, courseSlugOf, type CourseEntry } from '../lib/courses';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+// Doubles as the course index (no `categoryId` → all courses, grouped by
+// category) and a category browse page (`categoryId` → that category, with a
+// breadcrumb, its direct courses, and a section per subcategory).
+interface Props {
+  lang: Lang;
+  categoryId?: string;
+}
+
+const { lang, categoryId } = Astro.props;
+const t = useTranslations(lang);
+// getCourses() order (manual `order` desc, then date) agrees with the client
+// "recent" comparator over CourseCard's data-date keys — no reflow on load.
+const all = await getCourses(lang);
+const catUrl = (cid: string) => getRelativeLocaleUrl(lang, `course/category/${cid}/`);
+
+const itemsIn = (cid: string): CourseEntry[] => {
+  const ids = new Set(courseTree.descendantIds(cid));
+  return all.filter((c) => ids.has(courseCatOf(c.data.category)));
+};
+
+const node = categoryId ? courseTree.map.get(categoryId) : undefined;
+const sections = node ? courseTree.childrenOf(node.id) : courseTree.roots;
+const direct = node ? all.filter((c) => courseCatOf(c.data.category) === node.id) : [];
+
+// A leaf category page shows one flat list — that grid gets ?page= pagination.
+// Index and parent-category pages stay grouped overviews: each section is
+// capped to PAGE cards with a "see all" link to the fuller list.
+const isLeaf = !!node && sections.length === 0;
+
+const path = node ? courseTree.pathOf(node.id) : [];
+const crumbs = node
+  ? [
+      { label: t('course.backToCourses'), href: getRelativeLocaleUrl(lang, 'course/') },
+      ...path.map((c, i) => ({
+        label: c.label[lang],
+        href: i === path.length - 1 ? undefined : catUrl(c.id),
+      })),
+    ]
+  : [];
+
+const card = (c: CourseEntry) => ({
+  lang,
+  slug: courseSlugOf(c),
+  title: c.data.title,
+  description: c.data.summary ?? c.data.description,
+  tags: c.data.tags,
+  image: c.data.image,
+  imageAlt: c.data.imageAlt,
+  level: c.data.level,
+  hours: c.data.hours,
+  version: c.data.version,
+  date: c.data.date,
+  updated: c.data.updated,
+  order: c.data.order,
+  isPrivate: c.data.private,
+  teaser: c.data.teaser,
+});
+---
+
+{
+  node ? (
+    <>
+      <Breadcrumb segments={crumbs} />
+      <header class="mt-4">
+        <h1 class="text-3xl font-bold tracking-tight">{node.label[lang]}</h1>
+        <p class="mt-2 max-w-2xl text-lg text-[var(--aas-muted)]">
+          {node.detail?.[lang] ?? node.description[lang]}
+        </p>
+      </header>
+    </>
+  ) : (
+    <section class="py-6">
+      <h1 class="text-4xl font-bold tracking-tight">{t('course.title')}</h1>
+      <p class="mt-3 max-w-2xl text-lg text-[var(--aas-muted)]">{t('course.tagline')}</p>
+    </section>
+  )
+}
+
+{all.length === 0 && <p class="mt-8 text-[var(--aas-muted)]">{t('course.empty')}</p>}
+
+{all.length > 0 && <div class="mt-6"><ListControls lang={lang} /></div>}
+
+{
+  direct.length > 0 && (
+    <div
+      class="mt-4 grid gap-5 sm:grid-cols-2 lg:grid-cols-3"
+      data-sortgrid
+      data-paginate={isLeaf ? true : undefined}
+      data-page-size={isLeaf ? PAGE : undefined}
+    >
+      {direct.map((c) => (
+        <CourseCard {...card(c)} />
+      ))}
+    </div>
+  )
+}
+
+{
+  sections.map((cat) => {
+    const items = itemsIn(cat.id);
+    return (
+      items.length > 0 && (
+        <section class="mt-8">
+          <h2 class="text-2xl font-semibold">
+            <a
+              href={catUrl(cat.id)}
+              class="text-[var(--aas-text)] no-underline hover:text-[var(--aas-accent)]"
+            >
+              {cat.label[lang]}
+              <ArrowUpRight size={20} class="ml-1 text-[var(--aas-muted)]" />
+            </a>
+          </h2>
+          <p class="mt-1 text-sm text-[var(--aas-muted)]">{cat.description[lang]}</p>
+          <div class="mt-4 grid gap-5 sm:grid-cols-2 lg:grid-cols-3" data-sortgrid>
+            {items.slice(0, PAGE).map((c) => (
+              <CourseCard {...card(c)} />
+            ))}
+          </div>
+          {items.length > PAGE && (
+            <a
+              href={catUrl(cat.id)}
+              class="mt-3 inline-block text-sm font-medium text-[var(--aas-accent)] no-underline"
+            >
+              {t('list.seeAll').replace('{n}', String(items.length))} &rarr;
+            </a>
+          )}
+        </section>
+      )
+    );
+  })
+}
+
+{isLeaf && <nav data-pager aria-label="Pagination" class="mt-8 flex flex-wrap items-center justify-center gap-1.5" />}

package/src/components/DifficultyStars.astro

@@ -0,0 +1,34 @@
+---
+import StarIcon from './StarIcon.astro';
+import { useTranslations, difficultyLabel, type Lang } from '../i18n/ui';
+
+// Course difficulty as a 5-star row (filled up to `level`). The visual is
+// decorative; the level + localized label live in the aria-label/tooltip.
+interface Props {
+  lang: Lang;
+  /** 1 (beginner) … 5 (expert). */
+  level: number;
+  size?: number;
+  class?: string;
+}
+
+const { lang, level, size = 12, class: className } = Astro.props;
+const t = useTranslations(lang);
+const label = `${t('course.level')}: ${difficultyLabel(lang, level)}`;
+---
+
+<span
+  class:list={['inline-flex items-center gap-0.5', className]}
+  role="img"
+  aria-label={label}
+  title={label}
+>
+  {
+    [1, 2, 3, 4, 5].map((i) => (
+      <StarIcon
+        size={size}
+        class={i <= level ? 'text-[var(--aas-accent)]' : 'text-[var(--aas-border)]'}
+      />
+    ))
+  }
+</span>

package/src/components/Embed.astro

@@ -0,0 +1,36 @@
+---
+// Responsive iframe wrapper for MDX bodies (a Hugo `iframe` shortcode
+// successor) — interactive demos, videos, and other embeds:
+//   <Embed src="/demos/foo/index.html" title="Foo demo" ratio="4:3" />
+interface Props {
+  src: string;
+  /** Accessible name for the iframe — required; it is the only label. */
+  title: string;
+  /** Aspect ratio ("16:9" default, "4:3", …), or "auto" paired with `height`. */
+  ratio?: string;
+  /** CSS height, used when `ratio` is "auto" (e.g. "32rem"). */
+  height?: string;
+  /** `sandbox` attribute passthrough (omit = unsandboxed, same-origin demos). */
+  sandbox?: string;
+  allowFullscreen?: boolean;
+}
+
+const { src, title, ratio = '16:9', height, sandbox, allowFullscreen = true } = Astro.props;
+const style =
+  ratio === 'auto'
+    ? height
+      ? `height: ${height};`
+      : undefined
+    : `aspect-ratio: ${ratio.replace(':', ' / ')};`;
+---
+
+<div class="not-prose my-4" style={style}>
+  <iframe
+    src={src}
+    title={title}
+    loading="lazy"
+    class="h-full w-full rounded-2xl border border-[var(--aas-border)] bg-[var(--aas-panel)]"
+    {...(sandbox !== undefined ? { sandbox } : {})}
+    {...(allowFullscreen ? { allowfullscreen: true } : {})}
+  ></iframe>
+</div>

package/src/components/Lead.astro

@@ -0,0 +1,8 @@
+---
+// Lead/intro paragraph for MDX bodies (a Hugo `lead` shortcode successor):
+//   <Lead>One-sentence framing of the page.</Lead>
+---
+
+<p class="not-prose my-5 text-xl leading-relaxed text-[var(--aas-muted)]">
+  <slot />
+</p>

package/src/components/RelatedCourses.astro

@@ -0,0 +1,64 @@
+---
+// "Related courses" card section on a course detail page, mirroring
+// RelatedConcepts so course links present the same way (image + title +
+// level/duration meta + description, in a collapsible grid).
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { Image } from 'astro:assets';
+import { courseSlugOf, type CourseEntry } from '../lib/courses';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { formatDate } from '../lib/dates';
+import { inlineMd } from '../lib/inline-md';
+import CollapsibleGrid from './CollapsibleGrid.astro';
+import DifficultyStars from './DifficultyStars.astro';
+
+interface Props {
+  lang: Lang;
+  courses: CourseEntry[];
+}
+
+const { lang, courses } = Astro.props;
+const t = useTranslations(lang);
+---
+
+{
+  courses.length > 0 && (
+    <section class="mt-8">
+      <h2 class="text-xs font-semibold tracking-wide text-[var(--aas-muted)] uppercase">
+        {t('course.relatedCourses')}
+      </h2>
+      <CollapsibleGrid lang={lang} count={courses.length}>
+        {courses.map((c) => (
+          <a
+            href={getRelativeLocaleUrl(lang, `course/${courseSlugOf(c)}/`)}
+            class="aas-lift flex items-stretch overflow-hidden rounded-2xl border border-[var(--aas-border)] bg-[var(--aas-panel)] no-underline"
+          >
+            {c.data.image && (
+              <Image src={c.data.image} alt="" class="w-28 shrink-0 self-stretch object-cover" />
+            )}
+            <div class="min-w-0 p-4">
+              <span class="block font-semibold text-[var(--aas-text)]">
+                {c.data.private && (
+                  <span aria-label={t('private.badge')} title={t('private.badge')}>🔒 </span>
+                )}
+                {c.data.title}
+              </span>
+              <span class="mt-0.5 flex flex-wrap items-center gap-x-2 gap-y-0.5 text-xs text-[var(--aas-muted)]">
+                {c.data.level && <DifficultyStars lang={lang} level={c.data.level} size={10} />}
+                {c.data.hours && <span>{c.data.hours}</span>}
+                {c.data.updated && (
+                  <span>
+                    {t('course.updated')} {formatDate(c.data.updated, lang)}
+                  </span>
+                )}
+              </span>
+              <span
+                class="aas-md mt-1.5 line-clamp-2 text-xs leading-relaxed text-[var(--aas-muted)] opacity-75"
+                set:html={inlineMd(c.data.private ? (c.data.teaser ?? '') : c.data.description)}
+              />
+            </div>
+          </a>
+        ))}
+      </CollapsibleGrid>
+    </section>
+  )
+}

package/src/content.ts

@@ -3,8 +3,8 @@ import { glob } from 'astro/loaders';
 
 /**
  * The shared content model for awesome-*-stack sites: `stacks` (the tool
- * catalog), `articles`, `concepts` and `slides`. A site's content.config.ts
- * stays thin:
+ * catalog), `articles`, `concepts`, `courses` (opt-in), `slides` and `pages`.
+ * A site's content.config.ts stays thin:
  *
  *   import { defineAasCollections } from 'stack-site-builder/content';
  *   import { categoryMap } from './data/categories';
@@ -15,7 +15,16 @@ import { glob } from 'astro/loaders';
  * tree — stack entries are validated against it so an unknown category id
  * fails the build instead of silently dropping the entry from every listing.
  */
-export function defineAasCollections({ categoryMap }: { categoryMap: Map<string, unknown> }) {
+export function defineAasCollections({
+  categoryMap,
+  courseCategoryMap,
+}: {
+  categoryMap: Map<string, unknown>;
+  /** The site's course category tree (`src/data/course-categories.ts`). Optional
+   *  because `courses` is an opt-in section; when provided, course `category`
+   *  ids are validated against it at build time (like stacks). */
+  courseCategoryMap?: Map<string, unknown>;
+}) {
   /**
    * The `stacks` collection holds one entry per tool/service used to build
    * AI agents. Each entry is an MDX file: frontmatter powers the listing and
@@ -197,6 +206,62 @@ export function defineAasCollections({ categoryMap }: { categoryMap: Map<string,
       }),
   });
 
+  /**
+   * The `courses` collection holds structured lessons/lectures — an opt-in
+   * section (`sections: { courses: true }`) for sites that teach rather than
+   * catalog. Each course is one MDX file: frontmatter powers the course cards
+   * (difficulty, duration, category), the body is the course page itself. Paid
+   * courses use `private` + `teaser` like every other collection.
+   *
+   * Locale-partitioned like the others: `courses/<lang>/<slug>.mdx`.
+   */
+  const courses = defineCollection({
+    loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/courses' }),
+    schema: ({ image }) =>
+      z.object({
+        title: z.string(),
+        description: z.string(),
+        // Short one-liner for tight card layouts; falls back to `description`.
+        summary: z.string().optional(),
+        date: z.coerce.date(), // first published
+        // Living-doc metadata, mirroring concepts: bump on meaningful edits.
+        version: z.string().optional(), // e.g. "1.0"
+        updated: z.coerce.date().optional(), // last meaningful update (YYYY-MM-DD)
+        image: image().optional(), // hero / card image (optimized; relative to the file)
+        imageAlt: z.string().optional(),
+        // Leaf id from the site's src/data/course-categories.ts. Validated when the
+        // site passes `courseCategoryMap` (strict, like stacks); otherwise resolved
+        // at render time with an uncategorized fallback (loose, like concepts).
+        category: (courseCategoryMap
+          ? z.string().refine((id) => courseCategoryMap.has(id), {
+              message:
+                'unknown course category id — must match a node in the site data course category tree',
+            })
+          : z.string()
+        ).optional(),
+        tags: z.array(z.string()).default([]),
+        // Difficulty, 1 (beginner) … 5 (expert) — rendered as stars on cards
+        // and the detail header; localized labels live in src/i18n/ui.ts.
+        level: z.number().int().min(1).max(5).optional(),
+        // Human-readable duration, e.g. "1:30" or "8주" — displayed verbatim.
+        hours: z.string().optional(),
+        // Manual sort key, highest first (e.g. "2601-01" = YYMM-seq, so newer
+        // cohorts lead). Courses without one sort by `date`, newest first.
+        order: z.string().optional(),
+        // Free-form kind tag a site can style/filter on (e.g. "special-lecture").
+        type: z.string().optional(),
+        related: z.array(z.string()).default([]), // related course slugs
+        // Decks in the `slides` collection that belong to this course
+        // (linked from the course detail header).
+        slides: z.array(z.string()).default([]),
+        draft: z.boolean().default(false),
+        // Login-gated course (encrypted body; listings show title + optional
+        // PUBLIC `teaser`). See docs/private-content-design.md.
+        private: z.boolean().default(false),
+        teaser: z.string().optional(),
+      }),
+  });
+
   /**
    * The `slides` collection holds presentation decks — one MDX file per deck, with
    * each slide wrapped in a <Slide> component (see src/components/Slide.astro). The
@@ -273,5 +338,5 @@ export function defineAasCollections({ categoryMap }: { categoryMap: Map<string,
       }),
   });
 
-  return { stacks, articles, concepts, slides, pages };
+  return { stacks, articles, concepts, courses, slides, pages };
 }

package/src/i18n/ui.ts

@@ -58,6 +58,7 @@ export const ui = {
       'A curated stack of the tools and services you actually use to build AI systems — each with a detail page and runnable sample code.',
     'nav.browse': 'Browse',
     'nav.concepts': 'Concepts',
+    'nav.courses': 'Courses',
     'nav.blog': 'Writing',
     'nav.samples': 'Samples',
     'nav.slides': 'Slides',
@@ -117,6 +118,15 @@ export const ui = {
     'concept.learnMore': 'Learn more',
     'concept.backToConcepts': 'All concepts',
     'concept.updated': 'Updated',
+    'course.title': 'Courses',
+    'course.tagline': 'Structured lessons and lectures — from fundamentals to hands-on practice.',
+    'course.empty': 'No courses yet.',
+    'course.backToCourses': 'All courses',
+    'course.level': 'Level',
+    'course.hours': 'Duration',
+    'course.updated': 'Updated',
+    'course.relatedCourses': 'Related courses',
+    'course.slides': 'Slides',
     'detail.usedInConcepts': 'Used in concepts',
     'sort.label': 'Sort',
     'sort.alpha': 'A–Z',
@@ -207,6 +217,7 @@ export const ui = {
       'AI 시스템을 만들 때 실제로 쓰는 도구와 서비스를 모았습니다 — 각 항목마다 상세 페이지와 바로 실행 가능한 샘플 코드를 제공합니다.',
     'nav.browse': '둘러보기',
     'nav.concepts': '개념',
+    'nav.courses': '강의',
     'nav.blog': '글',
     'nav.samples': '샘플',
     'nav.slides': '슬라이드',
@@ -265,6 +276,15 @@ export const ui = {
     'concept.learnMore': '더 알아보기',
     'concept.backToConcepts': '개념 전체',
     'concept.updated': '업데이트',
+    'course.title': '강의',
+    'course.tagline': '기초부터 실습까지, 체계적으로 구성한 강의.',
+    'course.empty': '아직 강의가 없습니다.',
+    'course.backToCourses': '강의 전체',
+    'course.level': '난이도',
+    'course.hours': '수강 시간',
+    'course.updated': '업데이트',
+    'course.relatedCourses': '관련 강의',
+    'course.slides': '슬라이드',
     'detail.usedInConcepts': '이 도구가 쓰이는 개념',
     'sort.label': '정렬',
     'sort.alpha': '이름순',
@@ -398,6 +418,19 @@ export const pricingLabels: Record<string, Record<string, string>> = {
   },
 };
 
+/** Localized label for a course `level` (1–5), falling back to the default
+ *  locale then the bare number (so a site-added locale never crashes). */
+export function difficultyLabel(lang: Lang, level: number): string {
+  const key = String(level);
+  return difficultyLabels[lang]?.[key] ?? difficultyLabels[defaultLang]?.[key] ?? key;
+}
+
+/** Human labels for the course `level` frontmatter (1–5), per locale. */
+export const difficultyLabels: Record<string, Record<string, string>> = {
+  en: { '1': 'Beginner', '2': 'Elementary', '3': 'Intermediate', '4': 'Advanced', '5': 'Expert' },
+  ko: { '1': '입문', '2': '초급', '3': '중급', '4': '고급', '5': '전문가' },
+};
+
 /** Descriptive (non-name) licenses get localized; real license names pass through. */
 const licenseLabels: Record<string, Record<string, string>> = {
   en: { proprietary: 'Proprietary' },

package/src/layouts/BaseLayout.astro

@@ -60,6 +60,12 @@ const allNavItems: {
     keepFilters: true,
     svg: '<rect width="7" height="7" x="3" y="3" rx="1"/><rect width="7" height="7" x="14" y="3" rx="1"/><rect width="7" height="7" x="14" y="14" rx="1"/><rect width="7" height="7" x="3" y="14" rx="1"/>',
   },
+  {
+    href: getRelativeLocaleUrl(lang, 'course/'),
+    label: t('nav.courses'),
+    section: 'courses',
+    svg: '<path d="M21.42 10.922a1 1 0 0 0-.019-1.838L12.83 5.18a2 2 0 0 0-1.66 0L2.6 9.08a1 1 0 0 0 0 1.832l8.57 3.908a2 2 0 0 0 1.66 0z"/><path d="M22 10v6"/><path d="M6 12.5V16a6 3 0 0 0 12 0v-3.5"/>',
+  },
   {
     href: getRelativeLocaleUrl(lang, 'concept/'),
     label: t('nav.concepts'),
@@ -117,6 +123,16 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
     <meta name="description" content={description} />
     {noindex && <meta name="robots" content="noindex" />}
     <link rel="icon" type="image/svg+xml" href={`${base.replace(/\/$/, '')}/favicon.svg`} />
+    {
+      sectionEnabled('articles') && (
+        <link
+          rel="alternate"
+          type="application/rss+xml"
+          title={`${site.name} — ${t('blog.title')}`}
+          href={getRelativeLocaleUrl(lang, 'rss.xml')}
+        />
+      )
+    }
     {/* On the root (default-locale) home, send first-time visitors to the
         locale matching their browser — unless they've already picked one (the
         language switcher stores `aas:lang`). Runs before paint, no history entry. */}

package/src/lib/courses.ts

@@ -0,0 +1,26 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import type { Lang } from '../i18n/ui';
+
+export type CourseEntry = CollectionEntry<'courses'>;
+
+/** The url slug of a course, i.e. its id with the `<lang>/` prefix removed. */
+export function courseSlugOf(entry: CourseEntry): string {
+  return entry.id.replace(/^[a-z]{2}\//, '');
+}
+
+/**
+ * Published courses for one locale. `order` keys sort highest-first (newer
+ * cohorts lead, e.g. "2601-01" before "2512-02") and beat order-less entries;
+ * ties fall back to `date` (newest first), then title.
+ */
+export async function getCourses(lang: Lang): Promise<CourseEntry[]> {
+  const all = await getCollection('courses');
+  return all
+    .filter((e) => e.id.startsWith(`${lang}/`) && !e.data.draft)
+    .sort(
+      (a, b) =>
+        (b.data.order ?? '').localeCompare(a.data.order ?? '') ||
+        b.data.date.valueOf() - a.data.date.valueOf() ||
+        a.data.title.localeCompare(b.data.title),
+    );
+}

package/src/lib/sections.ts

@@ -11,13 +11,24 @@ import { site } from '@aas-data/site';
  * the `nav` / `draft` frontmatter, or by not authoring the page.
  *
  * A site sets overrides in `src/data/site.ts` (`sections`), which astro.config
- * also forwards to the theme integration for route filtering. Omitted = enabled.
+ * also forwards to the theme integration for route filtering. Omitted = enabled —
+ * except `courses`, which is opt-IN (`{ courses: true }`): enabling it requires
+ * site-side data (`src/data/course-categories.ts`), so it must never switch on
+ * by a theme upgrade alone.
  */
-export type SectionKey = 'concepts' | 'articles' | 'samples' | 'slides' | 'glossary' | 'pages';
+export type SectionKey =
+  | 'concepts'
+  | 'articles'
+  | 'courses'
+  | 'samples'
+  | 'slides'
+  | 'glossary'
+  | 'pages';
 
 const DEFAULTS: Record<SectionKey, boolean> = {
   concepts: true,
   articles: true,
+  courses: false, // opt-in: needs src/data/course-categories.ts on the site
   samples: true,
   slides: true,
   glossary: true,

package/src/pages/[...lang]/course/[...id].astro

@@ -0,0 +1,35 @@
+---
+import { site } from '@aas-data/site';
+import type { GetStaticPaths } from 'astro';
+import BaseLayout from '../../../layouts/BaseLayout.astro';
+import CourseDetail from '../../../components/CourseDetail.astro';
+import PrivateGate from '../../../components/PrivateGate.astro';
+import { getCourses, courseSlugOf } from '../../../lib/courses';
+import { allLocales, langParam } from '../../../lib/locales';
+
+export const getStaticPaths = (async () => {
+  const paths: Awaited<ReturnType<GetStaticPaths>> = [];
+  for (const lang of allLocales) {
+    for (const entry of await getCourses(lang)) {
+      paths.push({ params: { lang: langParam(lang), id: courseSlugOf(entry) }, props: { lang, entry } });
+    }
+  }
+  return paths;
+}) satisfies GetStaticPaths;
+
+const { lang, entry } = Astro.props;
+const slug = courseSlugOf(entry);
+const priv = entry.data.private;
+---
+
+<BaseLayout
+  title={`${entry.data.title} — ${site.name}`}
+  description={priv ? entry.data.teaser : entry.data.description}
+  lang={lang}
+  path={`course/${slug}/`}
+  noindex={priv}
+>
+  <PrivateGate enabled={priv} lang={lang} title={entry.data.title} teaser={entry.data.teaser}>
+    <CourseDetail entry={entry} lang={lang} />
+  </PrivateGate>
+</BaseLayout>

package/src/pages/[...lang]/course/category/[id].astro

@@ -0,0 +1,25 @@
+---
+import { site } from '@aas-data/site';
+import type { GetStaticPaths } from 'astro';
+import BaseLayout from '../../../../layouts/BaseLayout.astro';
+import CourseIndex from '../../../../components/CourseIndex.astro';
+import { courseTree } from '@aas-data/course-categories';
+import { allLocales, langParam } from '../../../../lib/locales';
+
+export const getStaticPaths = (() => {
+  const paths: Awaited<ReturnType<GetStaticPaths>> = [];
+  for (const lang of allLocales) {
+    for (const id of courseTree.allIds) {
+      paths.push({ params: { lang: langParam(lang), id }, props: { lang, id } });
+    }
+  }
+  return paths;
+}) satisfies GetStaticPaths;
+
+const { lang, id } = Astro.props as { lang: string; id: string };
+const node = courseTree.map.get(id)!;
+---
+
+<BaseLayout title={`${node.label[lang]} — ${site.name}`} lang={lang} path={`course/category/${id}/`}>
+  <CourseIndex lang={lang} categoryId={id} />
+</BaseLayout>

package/src/pages/[...lang]/course/index.astro

@@ -0,0 +1,18 @@
+---
+import { site } from '@aas-data/site';
+import type { GetStaticPaths } from 'astro';
+import BaseLayout from '../../../layouts/BaseLayout.astro';
+import CourseIndex from '../../../components/CourseIndex.astro';
+import { useTranslations } from '../../../i18n/ui';
+import { allLocales, langParam } from '../../../lib/locales';
+
+export const getStaticPaths = (() =>
+  allLocales.map((lang) => ({ params: { lang: langParam(lang) }, props: { lang } }))) satisfies GetStaticPaths;
+
+const { lang } = Astro.props;
+const t = useTranslations(lang);
+---
+
+<BaseLayout title={`${t('course.title')} — ${site.name}`} lang={lang} path="course/">
+  <CourseIndex lang={lang} />
+</BaseLayout>

package/src/pages/[...lang]/rss.xml.ts

@@ -0,0 +1,40 @@
+import rss from '@astrojs/rss';
+import type { APIContext, GetStaticPaths } from 'astro';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { site } from '@aas-data/site';
+import { getArticles, articleSlugOf } from '../../lib/articles';
+import { allLocales, langParam } from '../../lib/locales';
+import { useTranslations } from '../../i18n/ui';
+
+// Per-locale RSS feed of the articles collection: /rss.xml (default locale)
+// and /<code>/rss.xml. Injected with the `articles` section, so a site that
+// turns the blog off has no feed either.
+export const getStaticPaths = (() =>
+  allLocales.map((lang) => ({
+    params: { lang: langParam(lang) },
+    props: { lang },
+  }))) satisfies GetStaticPaths;
+
+export async function GET(context: APIContext) {
+  const { lang } = context.props as { lang: string };
+  const t = useTranslations(lang);
+  if (!context.site) {
+    throw new Error('RSS needs `site` set in astro.config (it already powers the sitemap).');
+  }
+  // getArticles drops drafts; private entries stay out of the feed entirely,
+  // mirroring the sitemap's private-page filter.
+  const articles = (await getArticles(lang)).filter((a) => !a.data.private);
+  return rss({
+    title: `${site.name} — ${t('blog.title')}`,
+    description: t('blog.tagline'),
+    site: context.site,
+    customData: `<language>${lang}</language>`,
+    items: articles.map((a) => ({
+      title: a.data.title,
+      description: a.data.description,
+      pubDate: a.data.date,
+      // Locale-relative and base-aware; rss() resolves it against `site`.
+      link: getRelativeLocaleUrl(lang, `article/${articleSlugOf(a)}/`),
+    })),
+  });
+}