stack-site-builder 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -11,6 +11,54 @@ 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.16.0] - 2026-07-22
+
+### Added
+
+- **`apps` collection — product landings** — Things-style marketing pages
+  driven entirely by frontmatter (`template: 'landing'`): hero with app icon,
+  App Store / Google Play buttons (`"#"` renders disabled with a
+  "coming soon" label) and a Product Hunt badge; alternating feature rows
+  with optional device-frame screenshots and auto-rotating carousels; a
+  video "themes" showcase with tab switching; a highlights grid; pricing
+  tiers with a featured ribbon; a closing CTA; and legal links. Entries may
+  nest — `apps/<lang>/<slug>/privacy.mdx` renders at
+  `/apps/<slug>/privacy/` as a plain prose page (`template: 'page'`) — via
+  one catch-all route. Landing media (icons, screenshots, videos, frame art)
+  are `public/` paths. `nav: true` puts a landing in the header nav. The
+  section is on by default; an empty collection builds zero pages.
+- **Data-driven "cards" home** — a site that isn't a catalog can declare
+  `home: { template: 'cards', hero, cards, cta }` in `src/data/site.ts` and
+  get a hero + wide-card grid + CTA homepage instead of the stack catalog.
+  Localized strings use per-locale records (`{ ko: '…', en: '…' }`) with
+  default-locale fallback, like category labels. On a cards home the
+  header's catalog-anchored Browse link hides itself; the catalog routes
+  still build (empty without stacks).
+
+## [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 +186,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.16.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.15.0...v1.16.0
+[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,89 @@ 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>/`.
+
+## Apps (product landings)
+
+The `apps` collection renders Things-style marketing pages from frontmatter
+alone (`template: 'landing'`): hero with store buttons and an optional Product
+Hunt badge, alternating feature rows (device-frame screenshots, auto-rotating
+carousels), a video themes showcase, a highlights grid, pricing tiers, a
+closing CTA and legal links. Landing media are `public/` paths. Entries nest:
+`apps/<lang>/flowstate.mdx` → `/apps/flowstate/`, and
+`apps/<lang>/flowstate/privacy.mdx` → `/apps/flowstate/privacy/` (a plain
+prose page). `nav: true` adds a header link. See
+`playground/src/content/apps/` for a complete example.
+
+## Homepage
+
+The default home is the stack catalog. A site that isn't a catalog can swap in
+a data-driven home from `src/data/site.ts`:
+
+```ts
+home: {
+  template: 'cards',
+  hero: { icon: '/img/logo.png', subtitle: { ko: '…', en: '…' } },
+  cardsTitle: { ko: '앱', en: 'Apps' },
+  cards: [{ href: '/apps/flowstate/', name: 'FlowState', icon: '/img/icon.png',
+            rounded: true, description: { ko: '…', en: '…' }, tags: ['iOS'] }],
+  cta: { title: { … }, description: { … }, button: { label: { … }, href: '/course/' } },
+},
+```
+
+Localized values are either one string or a per-locale record with
+default-locale fallback. On a cards home the header's Browse link (which
+anchors into the catalog) hides itself.
+
+## 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,27 @@
 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'
+  | 'apps'
+  | '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,11 @@ 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',
+  // App/product pages (the `apps` collection): marketing landings and their
+  // nested subpages (privacy/terms) via one catch-all.
+  'apps/[...id].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 +41,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 +55,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 +69,28 @@ 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('apps/')) return 'apps';
   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 +115,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.16.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",