stack-site-builder 1.13.0 → 1.15.0

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/components/SlidesIndex.astro

@@ -32,8 +32,14 @@ const decks = await getDecks(lang);
           <p class="text-xs font-medium tracking-wide text-[var(--aas-muted)] uppercase">
             {t('slides.deck')}
           </p>
-          <h2 class="mt-1 text-xl font-semibold text-[var(--aas-text)]">{deck.data.title}</h2>
-          <p class="mt-2 text-sm leading-relaxed text-[var(--aas-muted)]">{deck.data.description}</p>
+          <h2 class="mt-1 text-xl font-semibold text-[var(--aas-text)]">
+            {deck.data.private && (
+              <span aria-label={t('private.badge')} title={t('private.badge')}>🔒 </span>
+            )}{deck.data.title}
+          </h2>
+          <p class="mt-2 text-sm leading-relaxed text-[var(--aas-muted)]">
+            {deck.data.private ? (deck.data.teaser ?? '') : deck.data.description}
+          </p>
           <span class="mt-4 inline-flex items-center gap-1 text-sm font-medium text-[var(--aas-text)]">
             {t('slides.open')}
             <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">

package/src/components/StackCard.astro

@@ -26,9 +26,12 @@ interface Props {
   repo?: string;
   version?: string;
   deprecated?: boolean;
+  /** Private entry: show a lock and the (public) `teaser` instead of the description. */
+  isPrivate?: boolean;
+  teaser?: string;
 }
 
-const { slug, lang, name, formerNames = [], vendor, description, tags, pricing, license, language, category, logo, logoDark, repo, version, deprecated } =
+const { slug, lang, name, formerNames = [], vendor, description, tags, pricing, license, language, category, logo, logoDark, repo, version, deprecated, isPrivate = false, teaser } =
   Astro.props;
 const t = useTranslations(lang);
 const href = getRelativeLocaleUrl(lang, `stack/${slug}/`);
@@ -54,7 +57,11 @@ const langTokens = (language ?? '')
   .split('/')
   .map((s) => s.trim())
   .filter(Boolean);
-const searchText = `${name} ${description} ${tags.join(' ')}`.toLowerCase();
+// Private entries: the card carries only public copy — the title and the
+// authored `teaser` (description stays inside the encrypted detail page), and
+// the search index must not include the hidden description either.
+const shownDesc = isPrivate ? (teaser ?? '') : description;
+const searchText = `${name} ${shownDesc} ${tags.join(' ')}`.toLowerCase();
 ---
 
 {/* The card is a container, not a link: the name is the stretched primary link
@@ -85,6 +92,11 @@ const searchText = `${name} ${description} ${tags.join(' ')}`.toLowerCase();
       <div class="min-w-0">
         <h3 class="truncate text-base font-semibold text-[var(--aas-text)]">
           <a href={href} class="no-underline after:absolute after:inset-0 after:content-['']">
+            {isPrivate && (
+              <span aria-label={t('private.badge')} title={t('private.badge')}>
+                🔒{' '}
+              </span>
+            )}
             {name}
           </a>
         </h3>
@@ -100,7 +112,7 @@ const searchText = `${name} ${description} ${tags.join(' ')}`.toLowerCase();
     <p
       class="aas-md mt-2 text-sm leading-relaxed text-[var(--aas-muted)]"
       data-card-desc
-      set:html={inlineMd(description)}
+      set:html={inlineMd(shownDesc)}
     />
 
     {/* Secondary facts: version · release date · language · license.

package/src/components/StackDetail.astro

@@ -402,8 +402,16 @@ const relatedToolsByFolder = new Map(projectRail.map((p) => [p.folder, p.tools])
 
 <script>
   import { startScrollSpy, initBackToTop, initReveals } from '../lib/toc-rail-client';
+  import { initOnReady } from '../lib/reinit';
 
+  // Wrapped in initOnReady: on a private tool page all of this DOM sits inside
+  // the encrypted body, so the load-time run wires nothing (null rail, empty
+  // lists — its document listeners are inert) and the post-decryption run does
+  // the real wiring against the injected DOM.
+  initOnReady(() => {
   const rail = document.querySelector<HTMLElement>('[data-toc-rail]');
+  if (rail?.dataset.aasInit) return;
+  if (rail) rail.dataset.aasInit = '1';
   // Scroll-spy + back-to-top + prose-<details> persistence, shared with
   // TocRail.astro. The tab/version/example handlers below re-run the spy after
   // changing which headings are visible.
@@ -481,6 +489,7 @@ const relatedToolsByFolder = new Map(projectRail.map((p) => [p.folder, p.tools])
       });
     }),
   );
+  });
 </script>
 
 {

package/src/components/TagIndex.astro

@@ -45,6 +45,8 @@ const entries = (await getStacksByTag(lang, tag)).sort((a, b) =>
         repo={e.data.repo}
         version={e.data.version}
         deprecated={e.data.deprecated}
+        isPrivate={e.data.private}
+        teaser={e.data.teaser}
       />
     ))
   }

package/src/components/TocRail.astro

@@ -64,11 +64,17 @@ const hasContent = items.length > 0 || relatedTools.length > 0 || Boolean(projec
 
 <script>
   import { startScrollSpy, initBackToTop, initReveals } from '../lib/toc-rail-client';
+  import { initOnReady } from '../lib/reinit';
 
-  const rail = document.querySelector<HTMLElement>('[data-toc-rail]');
-  if (rail) {
-    startScrollSpy(rail);
-    initBackToTop(rail);
-    initReveals(rail);
-  }
+  // Re-runs after private-content decryption (the rail ships inside the
+  // encrypted body); the dataset flag keeps a live rail from double-wiring.
+  initOnReady(() => {
+    const rail = document.querySelector<HTMLElement>('[data-toc-rail]');
+    if (rail && !rail.dataset.aasInit) {
+      rail.dataset.aasInit = '1';
+      startScrollSpy(rail);
+      initBackToTop(rail);
+      initReveals(rail);
+    }
+  });
 </script>

package/src/components/VendorIndex.astro

@@ -45,6 +45,8 @@ const vendorName = entries[0]?.data.vendor ?? vendor;
         repo={e.data.repo}
         version={e.data.version}
         deprecated={e.data.deprecated}
+        isPrivate={e.data.private}
+        teaser={e.data.teaser}
       />
     ))
   }

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
@@ -107,6 +116,11 @@ export function defineAasCollections({ categoryMap }: { categoryMap: Map<string,
         )
         .default([]),
       featured: z.boolean().default(false),
+      // Login-gated entry: the body ships encrypted and listings show only the
+      // title (+ `teaser`, an explicitly PUBLIC one-liner written for the gate).
+      // See docs/private-content-design.md. Requires the AAS_PRIVATE_* env vars.
+      private: z.boolean().default(false),
+      teaser: z.string().optional(),
     }),
   });
 
@@ -147,6 +161,10 @@ export function defineAasCollections({ categoryMap }: { categoryMap: Map<string,
           .optional(),
         tags: z.array(z.string()).default([]),
         draft: z.boolean().default(false),
+        // Login-gated entry (encrypted body; listings show title + optional
+        // PUBLIC `teaser`). See docs/private-content-design.md.
+        private: z.boolean().default(false),
+        teaser: z.string().optional(),
       }),
   });
 
@@ -181,6 +199,66 @@ export function defineAasCollections({ categoryMap }: { categoryMap: Map<string,
         tags: z.array(z.string()).default([]),
         order: z.number().optional(), // manual sort on the index (lower first)
         draft: z.boolean().default(false),
+        // Login-gated entry (encrypted body; listings show title + optional
+        // PUBLIC `teaser`). See docs/private-content-design.md.
+        private: z.boolean().default(false),
+        teaser: z.string().optional(),
+      }),
+  });
+
+  /**
+   * 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(),
       }),
   });
 
@@ -221,6 +299,10 @@ export function defineAasCollections({ categoryMap }: { categoryMap: Map<string,
       toc_level: z.number().int().min(2).max(4).default(2),
       toc_open: z.boolean().default(true),
       draft: z.boolean().default(false),
+      // Login-gated deck (encrypted body; the slides index shows title +
+      // optional PUBLIC `teaser`). See docs/private-content-design.md.
+      private: z.boolean().default(false),
+      teaser: z.string().optional(),
     }),
   });
 
@@ -249,8 +331,12 @@ export function defineAasCollections({ categoryMap }: { categoryMap: Map<string,
         navLabel: z.string().optional(),
         order: z.number().default(0),
         draft: z.boolean().default(false),
+        // Login-gated page (encrypted body; the nav/meta show title + optional
+        // PUBLIC `teaser`). See docs/private-content-design.md.
+        private: z.boolean().default(false),
+        teaser: z.string().optional(),
       }),
   });
 
-  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',
@@ -67,6 +68,13 @@ export const ui = {
     'nav.menu': 'Menu',
     'code.copy': 'Copy code',
     'code.copied': 'Copied',
+    'private.badge': 'Private',
+    'private.locked': 'This content is private. Log in to view it.',
+    'private.id': 'ID',
+    'private.password': 'Password',
+    'private.submit': 'Unlock',
+    'private.error': 'Wrong ID or password.',
+    'private.logout': 'Log out',
     'slides.title': 'Slides',
     'slides.tagline': 'Concept decks — the same ideas as the concept pages, in slide form.',
     'slides.deck': 'Deck',
@@ -110,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',
@@ -200,6 +217,7 @@ export const ui = {
       'AI 시스템을 만들 때 실제로 쓰는 도구와 서비스를 모았습니다 — 각 항목마다 상세 페이지와 바로 실행 가능한 샘플 코드를 제공합니다.',
     'nav.browse': '둘러보기',
     'nav.concepts': '개념',
+    'nav.courses': '강의',
     'nav.blog': '글',
     'nav.samples': '샘플',
     'nav.slides': '슬라이드',
@@ -209,6 +227,13 @@ export const ui = {
     'nav.menu': '메뉴',
     'code.copy': '코드 복사',
     'code.copied': '복사됨',
+    'private.badge': '비공개',
+    'private.locked': '비공개 콘텐츠입니다. 로그인 후 볼 수 있습니다.',
+    'private.id': '아이디',
+    'private.password': '비밀번호',
+    'private.submit': '잠금 해제',
+    'private.error': '아이디 또는 비밀번호가 올바르지 않습니다.',
+    'private.logout': '로그아웃',
     'slides.title': '슬라이드',
     'slides.tagline': '개념 덱 — 개념 페이지와 같은 내용을 슬라이드로 옮겼습니다.',
     'slides.deck': '덱',
@@ -251,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': '이름순',
@@ -384,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

@@ -17,9 +17,11 @@ interface Props {
   path: string;
   /** Wider container — used by detail pages that have a right-rail TOC. */
   wide?: boolean;
+  /** Private entries: ask crawlers not to index the gate page. */
+  noindex?: boolean;
 }
 
-const { title, lang, path, wide = false } = Astro.props;
+const { title, lang, path, wide = false, noindex = false } = Astro.props;
 const t = useTranslations(lang);
 // Collapse any authored line breaks (used for on-page wrapping) to a single
 // space so the SEO meta description stays one clean line.
@@ -58,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'),
@@ -113,7 +121,18 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
     <meta name="generator" content={Astro.generator} />
     <title>{title}</title>
     <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. */}
@@ -262,6 +281,8 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
     <BackToTop lang={lang} />
 
     <script>
+      import { initOnReady } from '../lib/reinit';
+
       // Clicking a heading's "#" anchor copies that section's URL to the
       // clipboard (and updates the address bar) instead of just navigating.
       document.addEventListener('click', (e) => {
@@ -279,8 +300,9 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
       // Mount a copy-to-clipboard button on every code block: README/overview
       // prose (.prose pre), the file viewer (.aas-projfile), and the Code tab
       // (.aas-code). The button is pinned to a non-scrolling host so it stays in
-      // place on long, horizontally-scrolling code.
-      (function mountCopyButtons() {
+      // place on long, horizontally-scrolling code. Re-runs after private-content
+      // decryption (mount() skips hosts that already have a button).
+      initOnReady(function mountCopyButtons() {
         const LABEL = document.documentElement.dataset.copyLabel || 'Copy code';
         const DONE = document.documentElement.dataset.copiedLabel || 'Copied';
         const COPY_ICON =
@@ -334,7 +356,7 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
           const fig = el.closest('figure');
           mount(el, (fig as HTMLElement) ?? wrap(el));
         });
-      })();
+      });
 
       // Close any open <details> dropdown when clicking outside it (or on Esc).
       // Only nav dropdowns — leave file-tree folders (.aas-tree-dir) and prose

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),
+    );
+}