stack-site-builder 1.14.0 → 1.16.0

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

@@ -7,6 +7,8 @@ import LanguageSwitcher from '../components/LanguageSwitcher.astro';
 import ThemeToggle from '../components/ThemeToggle.astro';
 import BackToTop from '../components/BackToTop.astro';
 import { getNavPages, pageSlugOf } from '../lib/pages';
+import { getNavApps, appSlugOf } from '../lib/apps';
+import { homeTemplate } from '../lib/home';
 import { sectionEnabled, type SectionKey } from '../lib/sections';
 
 interface Props {
@@ -41,6 +43,8 @@ const isDefaultHome = path === '' && lang === 'en';
 // e.g. an About/소개 page. Rendered as their own nav items alongside the
 // built-in sections; the accessible label comes from the page's own frontmatter.
 const navPages = await getNavPages(lang);
+// App landings that opt into a header link (the `apps` collection's `nav`).
+const navApps = await getNavApps(lang);
 
 // The header sections, as data — rendered twice from one source so the two
 // layouts never drift: an icon-only row (≥sm) and a labelled dropdown menu
@@ -54,11 +58,23 @@ const allNavItems: {
   keepFilters?: boolean;
   section?: SectionKey;
 }[] = [
+  // Browse anchors into the catalog home's category sections — it only makes
+  // sense when the site keeps the catalog home template.
+  ...(homeTemplate === 'catalog'
+    ? [
+        {
+          href: `${home}#categories`,
+          label: t('nav.browse'),
+          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: `${home}#categories`,
-    label: t('nav.browse'),
-    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/'),
@@ -90,6 +106,12 @@ const allNavItems: {
     section: 'glossary',
     svg: '<path d="M12 7v14"/><path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z"/>',
   },
+  ...navApps.map((a) => ({
+    href: getRelativeLocaleUrl(lang, `apps/${appSlugOf(a)}/`),
+    label: a.data.navLabel ?? a.data.title,
+    section: 'apps' as SectionKey,
+    svg: '<rect width="14" height="20" x="5" y="2" rx="2" ry="2"/><path d="M12 18h.01"/>',
+  })),
   ...navPages.map((p) => ({
     href: getRelativeLocaleUrl(lang, `${pageSlugOf(p)}/`),
     label: p.data.navLabel ?? p.data.title,
@@ -117,6 +139,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/apps.ts

@@ -0,0 +1,24 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import type { Lang } from '../i18n/ui';
+
+export type AppEntry = CollectionEntry<'apps'>;
+
+/** The url slug of an app page — its id minus the `<lang>/` prefix. May be
+ *  nested (`flowstate-ai/privacy`), which the catch-all route renders at the
+ *  matching subpath. */
+export function appSlugOf(entry: AppEntry): string {
+  return entry.id.replace(/^[a-z]{2}\//, '');
+}
+
+/** Published app pages for one locale, in `order` (then title) order. */
+export async function getApps(lang: Lang): Promise<AppEntry[]> {
+  const all = await getCollection('apps');
+  return all
+    .filter((e) => e.id.startsWith(`${lang}/`) && !e.data.draft)
+    .sort((a, b) => a.data.order - b.data.order || a.data.title.localeCompare(b.data.title));
+}
+
+/** The subset of {@link getApps} that opts into a header-nav link. */
+export async function getNavApps(lang: Lang): Promise<AppEntry[]> {
+  return (await getApps(lang)).filter((e) => e.data.nav);
+}

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/home.ts

@@ -0,0 +1,61 @@
+import { site } from '@aas-data/site';
+import { defaultLang, type Lang } from '../i18n/ui';
+
+/**
+ * The data-driven "cards" homepage. By default the theme home is the stack
+ * catalog; a site that isn't a catalog (a studio/product site) declares
+ * `home: { template: 'cards', … }` in `src/data/site.ts` and gets a
+ * hero + card grid + CTA home instead. The catalog routes still build (they
+ * are simply empty when the site has no stacks), and the header's Browse
+ * link — which anchors into the catalog home — hides itself.
+ *
+ * Strings are `Localized`: either one string for every locale, or a
+ * per-locale record (`{ ko: '…', en: '…' }`) that falls back to the default
+ * locale, matching how category labels work.
+ */
+export type Localized = string | Record<string, string>;
+
+export interface HomeCard {
+  href: string;
+  external?: boolean;
+  name: Localized;
+  description?: Localized;
+  icon?: string; // public/ path
+  rounded?: boolean; // app-icon style rounding for the icon
+  tags?: string[] | Record<string, string[]>;
+}
+
+export interface HomeConfig {
+  template: 'cards';
+  hero?: {
+    icon?: string; // public/ path, shown above the title
+    title?: Localized; // defaults to site.name
+    subtitle?: Localized; // defaults to the site.tagline UI string
+  };
+  cardsTitle?: Localized;
+  cards?: HomeCard[];
+  cta?: {
+    title?: Localized;
+    description?: Localized;
+    button?: { label: Localized; href: string; external?: boolean };
+  };
+}
+
+export const home: HomeConfig | undefined = (site as { home?: HomeConfig }).home;
+
+/** Which homepage the site gets: the catalog (default) or the cards home. */
+export const homeTemplate: 'catalog' | 'cards' = home?.template === 'cards' ? 'cards' : 'catalog';
+
+/** Resolve a Localized string for `lang` (default locale, then any, as fallback). */
+export function loc(v: Localized | undefined, lang: Lang): string | undefined {
+  if (v == null) return undefined;
+  if (typeof v === 'string') return v;
+  return v[lang] ?? v[defaultLang] ?? Object.values(v)[0];
+}
+
+/** Resolve a per-locale (or shared) string list for `lang`. */
+export function locList(v: string[] | Record<string, string[]> | undefined, lang: Lang): string[] {
+  if (v == null) return [];
+  if (Array.isArray(v)) return v;
+  return v[lang] ?? v[defaultLang] ?? Object.values(v)[0] ?? [];
+}

package/src/lib/sections.ts

@@ -11,13 +11,26 @@ 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'
+  | 'apps'
+  | '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
+  apps: true, // no site data needed; an empty collection builds zero pages
   samples: true,
   slides: true,
   glossary: true,

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

@@ -0,0 +1,67 @@
+---
+import { site } from '@aas-data/site';
+import { render } from 'astro:content';
+import type { GetStaticPaths } from 'astro';
+import BaseLayout from '../../../layouts/BaseLayout.astro';
+import AppLanding from '../../../components/AppLanding.astro';
+import PrivateGate from '../../../components/PrivateGate.astro';
+import TocRail from '../../../components/TocRail.astro';
+import MermaidLoader from '../../../components/MermaidLoader.astro';
+import { getApps, appSlugOf } from '../../../lib/apps';
+import { allLocales, langParam } from '../../../lib/locales';
+import { inlineMd } from '../../../lib/inline-md';
+
+export const getStaticPaths = (async () => {
+  const paths: Awaited<ReturnType<GetStaticPaths>> = [];
+  for (const lang of allLocales) {
+    for (const entry of await getApps(lang)) {
+      paths.push({ params: { lang: langParam(lang), id: appSlugOf(entry) }, props: { lang, entry } });
+    }
+  }
+  return paths;
+}) satisfies GetStaticPaths;
+
+const { lang, entry } = Astro.props;
+const slug = appSlugOf(entry);
+const priv = entry.data.private;
+const isLanding = entry.data.template === 'landing';
+// Plain 'page' template (privacy/terms subpages) renders the markdown body.
+const { Content, headings } = await render(entry);
+const tocItems = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+const bodyHasMermaid = (entry.body ?? '').includes('```mermaid');
+---
+
+<BaseLayout
+  title={`${entry.data.title} — ${site.name}`}
+  description={priv ? entry.data.teaser : (entry.data.description ?? entry.data.subtitle)}
+  lang={lang}
+  path={`apps/${slug}/`}
+  noindex={priv}
+>
+  <PrivateGate enabled={priv} lang={lang} title={entry.data.title} teaser={entry.data.teaser}>
+    {
+      isLanding ? (
+        <AppLanding entry={entry} lang={lang} />
+      ) : (
+        <>
+          <header class="pb-6">
+            <h1 class="text-3xl font-bold tracking-tight">{entry.data.title}</h1>
+            {entry.data.description && (
+              <p
+                class="mt-2 aas-md text-lg whitespace-pre-line text-[var(--aas-muted)]"
+                set:html={inlineMd(entry.data.description)}
+              />
+            )}
+          </header>
+          <div class="mt-4 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 />}
+        </>
+      )
+    }
+  </PrivateGate>
+</BaseLayout>

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]/index.astro

@@ -3,6 +3,8 @@ import { site } from '@aas-data/site';
 import type { GetStaticPaths } from 'astro';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import Home from '../../components/Home.astro';
+import CardsHome from '../../components/CardsHome.astro';
+import { homeTemplate } from '../../lib/home';
 import { allLocales, langParam } from '../../lib/locales';
 
 export const getStaticPaths = (() =>
@@ -12,5 +14,5 @@ const { lang } = Astro.props;
 ---
 
 <BaseLayout title={site.name} lang={lang} path="">
-  <Home lang={lang} />
+  {homeTemplate === 'cards' ? <CardsHome lang={lang} /> : <Home 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)}/`),
+    })),
+  });
+}