stack-site-builder 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -11,6 +11,48 @@ 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
+
+- **Private (login-gated) content** — mark any entry in any collection
+  (stacks, concepts, articles, slides, pages) with `private: true`. The
+  rendered body ships AES-256-GCM-encrypted and is decrypted in the browser
+  after login, so it works on any static host with no server; the users
+  (`AAS_PRIVATE_USERS`, `id:password` pairs) and the master secret
+  (`AAS_PRIVATE_MASTER_SECRET` — rotate to force every device to log in again)
+  come from env vars, with sessions cached per device for
+  `AAS_PRIVATE_SESSION_DAYS` (default 30). Listings show only the title + 🔒
+  plus an optional public `teaser`; private pages are `noindex` and excluded
+  from the sitemap; the client re-initializes embedded behaviors (TOC,
+  mermaid, tabs, copy buttons, the slide deck engine) after decryption. The
+  source repo must be private — `.mdx` files stay plaintext; see
+  docs/private-content-design.md.
+
 ## [1.13.0] - 2026-07-20
 
 ### Added
@@ -120,6 +162,8 @@ 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
 [1.11.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.10.0...v1.11.0

package/README.md

@@ -1,5 +1,7 @@
 # stack-site-builder
 
+> 한국어: [docs/readme.ko.md](docs/readme.ko.md)
+
 An [Astro](https://astro.build) theme for curated "awesome stack" catalog
 sites — a tool catalog with per-entry detail pages, concepts, articles,
 presentation slides, runnable samples, a `[[wikilink]]` glossary, and full
@@ -36,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 |
 
@@ -70,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
@@ -90,3 +92,103 @@ export const site = {
 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:
+
+```yaml
+private: true
+teaser: A public one-liner shown on cards and above the login form. # optional
+```
+
+The body ships **encrypted** (AES-256-GCM, key wrapped per user with PBKDF2) and
+is decrypted in the browser after login — no server needed, works on any static
+host. Listings show only the title + 🔒 (+ teaser); private URLs get `noindex`
+and stay out of the sitemap. Users and keys come from env vars (see
+`playground/.env.sample`): `AAS_PRIVATE_USERS` (`id:password,…`),
+`AAS_PRIVATE_MASTER_SECRET` (rotate it to log every device out) and
+`AAS_PRIVATE_SESSION_DAYS`. Set them in `.env` locally or as CI secrets.
+
+Two rules: the **source repo must be private** (the `.mdx` files are plaintext —
+only the built output is encrypted), and when you remove a user, also rotate the
+master secret. Full design: `docs/private-content-design.md`.
+
+## Deploying (and where the secrets live)
+
+Encryption happens wherever `astro build` runs, reading `process.env` — the
+values just come from a different place per environment:
+
+| Where you build | Where the `AAS_PRIVATE_*` values live |
+| --- | --- |
+| Your machine (`pnpm build`, `firebase deploy`) | `.env` file (gitignored — copy `.env.sample`) |
+| GitHub Actions (deploy on push) | **Repository secrets**: Settings → Secrets and variables → Actions |
+
+`.env` never reaches GitHub; in CI the workflow maps repository secrets to env
+vars on the build step:
+
+```yaml
+- name: Build
+  run: pnpm install && pnpm build # encryption happens here
+  env:
+    AAS_PRIVATE_USERS: ${{ secrets.AAS_PRIVATE_USERS }}
+    AAS_PRIVATE_MASTER_SECRET: ${{ secrets.AAS_PRIVATE_MASTER_SECRET }}
+    AAS_PRIVATE_SESSION_DAYS: '30'
+```
+
+A complete GitHub Pages workflow a site can copy is in
+[`playground/.github/workflows/deploy.yml`](playground/.github/workflows/deploy.yml)
+(inert inside the playground — workflows only run from a repo's root
+`.github/`). Managing users/keys then never touches git: edit the secrets and
+re-run the workflow. Sites without private content need none of this.

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}`,
@@ -119,6 +134,15 @@ export default function aasTheme({ glossary, sections = {} }) {
                 defaultLocale,
                 locales: Object.fromEntries(locales.map((l) => [l, l])),
               },
+              // Private entries stay out of the sitemap. PrivateGate records each
+              // private pathname (via globalThis — it lives in a different module
+              // graph) while pages render; @astrojs/sitemap runs this after.
+              filter: (page) => {
+                const paths = globalThis.__aasPrivatePaths;
+                if (!paths) return true;
+                const p = new URL(page).pathname.replace(/\/?$/, '/');
+                return !paths.has(p);
+              },
             }),
           ],
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.13.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/ArticleCard.astro

@@ -16,10 +16,14 @@ interface Props {
   image?: ImageMetadata;
   imageAlt?: string;
   version?: string;
+  /** Private entry: show a lock and the (public) `teaser` instead of the description. */
+  isPrivate?: boolean;
+  teaser?: string;
 }
 
-const { slug, lang, title, description, date, tags, image, imageAlt, version } = Astro.props;
+const { slug, lang, title, description, date, tags, image, imageAlt, version, isPrivate = false, teaser } = Astro.props;
 const t = useTranslations(lang);
+const shownDesc = isPrivate ? (teaser ?? '') : description;
 const href = getRelativeLocaleUrl(lang, `article/${slug}/`);
 const dateStr = date.toISOString().slice(0, 10);
 ---
@@ -36,10 +40,12 @@ const dateStr = date.toISOString().slice(0, 10);
       <time datetime={dateStr}>{formatDate(date, lang)}</time>
       {version && <span> · {t('meta.docVersion')} {version}</span>}
     </p>
-    <h3 class="mt-1 line-clamp-2 text-base font-semibold text-[var(--aas-text)]">{title}</h3>
+    <h3 class="mt-1 line-clamp-2 text-base 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-1.5 line-clamp-2 text-sm leading-relaxed text-[var(--aas-muted)]"
-      set:html={inlineMd(description)}
+      set:html={inlineMd(shownDesc)}
     />
     {
       tags.length > 0 && (

package/src/components/ArticleLink.astro

@@ -33,8 +33,13 @@ const target = articles.find((a) => articleSlugOf(a) === slug) as ArticleEntry |
         <span class="block text-xs font-semibold tracking-wide text-[var(--aas-accent)] uppercase">
           {t('detail.relatedWriting')}
         </span>
-        <span class="mt-0.5 block font-semibold text-[var(--aas-text)]">{target.data.title}</span>
-        <span class="aas-md mt-1 block text-sm text-[var(--aas-muted)]" set:html={inlineMd(target.data.description)} />
+        <span class="mt-0.5 block font-semibold text-[var(--aas-text)]">
+          {target.data.private && <span aria-label={t('private.badge')} title={t('private.badge')}>🔒 </span>}{target.data.title}
+        </span>
+        <span
+          class="aas-md mt-1 block text-sm text-[var(--aas-muted)]"
+          set:html={inlineMd(target.data.private ? (target.data.teaser ?? '') : target.data.description)}
+        />
         <span class="mt-1.5 block text-xs text-[var(--aas-muted)]">
           {formatDate(target.data.date, lang)}
         </span>

package/src/components/BlogIndex.astro

@@ -58,6 +58,8 @@ const card = (a: ArticleEntry) => ({
   tags: a.data.tags,
   image: a.data.image,
   imageAlt: a.data.imageAlt,
+  isPrivate: a.data.private,
+  teaser: a.data.teaser,
 });
 ---
 

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/CategoryIndex.astro

@@ -59,6 +59,8 @@ const cardProps = (e: StackEntry) => ({
   repo: e.data.repo,
   version: e.data.version,
   deprecated: e.data.deprecated,
+  isPrivate: e.data.private,
+  teaser: e.data.teaser,
 });
 ---
 

package/src/components/CodeSamples.astro

@@ -90,7 +90,12 @@ const t = useTranslations(lang);
 </style>
 
 <script>
+  import { initOnReady } from '../lib/reinit';
+  // Re-runs after private-content decryption; the dataset flag guards each root.
+  initOnReady(() =>
   document.querySelectorAll<HTMLElement>('[data-samples]').forEach((root) => {
+    if (root.dataset.aasInit) return;
+    root.dataset.aasInit = '1';
     const dd = root.querySelector<HTMLDetailsElement>('[data-samples-dd]');
     const current = root.querySelector<HTMLElement>('[data-sample-current]');
     const options = Array.from(root.querySelectorAll<HTMLButtonElement>('[data-sample-option]'));
@@ -137,5 +142,5 @@ const t = useTranslations(lang);
       const cur = options.find((o) => o.getAttribute('aria-current') === 'true');
       if (cur) writeV(cur.dataset.sampleOption!);
     });
-  });
+  }));
 </script>

package/src/components/ConceptCard.astro

@@ -16,10 +16,14 @@ interface Props {
   imageAlt?: string;
   version?: string;
   updated?: Date;
+  /** 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, version, updated } = Astro.props;
+const { lang, slug, title, description, tags, image, imageAlt, version, updated, isPrivate = false, teaser } = Astro.props;
 const t = useTranslations(lang);
+const shownDesc = isPrivate ? (teaser ?? '') : description;
 ---
 
 <a
@@ -39,10 +43,12 @@ const t = useTranslations(lang);
         </p>
       )
     }
-    <h3 class="mt-1 text-lg font-semibold text-[var(--aas-text)]">{title}</h3>
+    <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(description)}
+      set:html={inlineMd(shownDesc)}
     />
     {
       tags.length > 0 && (

package/src/components/ConceptIndex.astro

@@ -64,6 +64,8 @@ const card = (c: ConceptEntry) => ({
   imageAlt: c.data.imageAlt,
   version: c.data.version,
   updated: c.data.updated,
+  isPrivate: c.data.private,
+  teaser: c.data.teaser,
 });
 ---
 

package/src/components/ConceptLink.astro

@@ -32,8 +32,13 @@ const target = concepts.find((c) => conceptSlugOf(c) === slug) as ConceptEntry |
         <span class="block text-xs font-semibold tracking-wide text-[var(--aas-accent)] uppercase">
           {t('concept.learnMore')}
         </span>
-        <span class="mt-0.5 block font-semibold text-[var(--aas-text)]">{target.data.title}</span>
-        <span class="aas-md mt-1 block text-sm text-[var(--aas-muted)]" set:html={inlineMd(target.data.description)} />
+        <span class="mt-0.5 block font-semibold text-[var(--aas-text)]">
+          {target.data.private && <span aria-label={t('private.badge')} title={t('private.badge')}>🔒 </span>}{target.data.title}
+        </span>
+        <span
+          class="aas-md mt-1 block text-sm text-[var(--aas-muted)]"
+          set:html={inlineMd(target.data.private ? (target.data.teaser ?? '') : target.data.description)}
+        />
       </div>
       <span aria-hidden="true" class="shrink-0 text-xl text-[var(--aas-accent)]">
         &rarr;

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>