stack-site-builder 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -11,6 +11,31 @@ 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.23.0] - 2026-07-27
+
+### Added
+
+- **Wikilink `course` / `paper` targets** — glossary entries can now point at
+  the opt-in sections' detail pages: `{ label: '…', course: '<slug>' }` links
+  `[[Term]]` to `/course/<slug>/`, `paper: '<id>'` to `/paper/<id>/` (relative,
+  so locale- and base-path-agnostic like the existing stack/concept/article
+  targets). The glossary page lists them under new Courses/Papers sections
+  (flat — no dependency on the sites' opt-in course/paper category data), with
+  graduation-cap / scroll fallback glyphs.
+
+## [1.22.0] - 2026-07-25
+
+### Added
+
+- **Cards-home catalog Browse nav** — `home.browse = { href, label?, external? }`:
+  on a cards home the stacks catalog Browse nav is hidden (it anchors into the
+  catalog home's `#categories` section, which a cards home doesn't have). Set
+  `home.browse` to add a header nav item (the same grid icon) that links to a
+  separate catalog page instead — e.g. a category browse at `/categories/tools/`.
+  `href` is a locale-less internal path (prefixed per locale) or an external URL;
+  `label` falls back to the theme's "Browse" string. The catalog home is
+  unaffected — it keeps its built-in `#categories` Browse.
+
 ## [1.21.0] - 2026-07-24
 
 ### Added
@@ -396,6 +421,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.23.0]: https://github.com/CodeComposeStudio/stack-site-builder/compare/v1.22.0...v1.23.0
 [1.19.3]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.19.2...v1.19.3
 [1.19.2]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.19.1...v1.19.2
 [1.19.1]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.19.0...v1.19.1

package/README.md

@@ -39,7 +39,7 @@ export const collections = defineAasCollections({ categoryMap });
 | `src/data/site.ts` | Site identity: name, repo URL (`repoNav: false` hides the header's GitHub link), the `locales` it ships, optional `sections` toggles, browser icons (`icons: { favicon, appleTouch, manifest }`), the `home` template, 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` · `course-categories.ts` · `product-categories.ts` · `paper-categories.ts` (opt-in) | Taxonomies for concepts / articles / courses / products / papers |
-| `src/data/glossary.mjs` | `[[Term]]` wikilink targets |
+| `src/data/glossary.mjs` | `[[Term]]` wikilink targets — each entry links a term to a `stack` / `concept` / `article` / `course` / `paper` page, an external `href`, or is a definition-only term (`def`) |
 | `src/content/{stacks,concepts,courses,products,papers,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 |
@@ -165,7 +165,20 @@ home: {
 
 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.
+anchors into the catalog home's `#categories` section) hides itself — set
+`home.browse` to add it back, pointing at a separate catalog page instead:
+
+```ts
+home: {
+  template: 'cards',
+  // …
+  // Header nav item (grid icon) → a standalone catalog page. Use this when the
+  // catalog lives at a category browse rather than on the home. `href` is a
+  // locale-less internal path (or an external URL with `external: true`);
+  // `label` defaults to the theme's "Browse" string.
+  browse: { href: '/categories/tools/', label: { ko: '사용 도구', en: 'Tools' } },
+},
+```
 
 ## Papers (opt-in)
 

package/markdown.mjs

@@ -230,7 +230,8 @@ function remarkSlideDirectives() {
 
 // Turn `[[Term]]` (and `[[Term|display text]]`) wikilinks into links, resolving
 // each against the site's central glossary (passed as an option). Internal targets
-// emit a `../stack|concept/<slug>/` relative form (locale- and base-agnostic), with
+// (stack/concept/article/course/paper) emit a `../<kind>/<slug>/` relative form
+// (locale- and base-agnostic), with
 // the number of `../` set by how deep the source page sits in its locale (see `up`
 // below); external `href` entries pass through and get
 // target="_blank" from rehype-external-links downstream. An unknown term throws,
@@ -344,19 +345,23 @@ function remarkGlossary({ glossary, locales = ['en', 'ko'], defaultLocale = 'en'
                 ? `${up}concept/${entry.concept}/`
                 : entry.article
                   ? `${up}article/${entry.article}/`
-                  : entry.href
-                    ? entry.href
-                    : def
-                      ? `${up}glossary/#${id}`
-                      : null;
+                  : entry.course
+                    ? `${up}course/${entry.course}/`
+                    : entry.paper
+                      ? `${up}paper/${entry.paper}/`
+                      : entry.href
+                        ? entry.href
+                        : def
+                          ? `${up}glossary/#${id}`
+                          : null;
             if (!url)
               throw new Error(
-                `[glossary] term "[[${m[1]}]]" needs one of stack/concept/article/href/def`,
+                `[glossary] term "[[${m[1]}]]" needs one of stack/concept/article/course/paper/href/def`,
               );
             if (anchor) {
               // A def-only target already carries its own hash — an extra
               // anchor is a mistake, so fail the build like an unknown term.
-              if (!entry.stack && !entry.concept && !entry.article && !entry.href)
+              if (!entry.stack && !entry.concept && !entry.article && !entry.course && !entry.paper && !entry.href)
                 throw new Error(
                   `[glossary] "[[${m[1]}]]" — a definition-only term can't take a #anchor`,
                 );

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.21.0",
+  "version": "1.23.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": {
     "type": "git",
-    "url": "git+https://github.com/CodeCompose7/stack-site-builder.git"
+    "url": "git+https://github.com/CodeComposeStudio/stack-site-builder.git"
   },
   "files": [
     "index.mjs",

package/src/components/Glossary.astro

@@ -19,6 +19,8 @@ type Entry = {
   stack?: string;
   concept?: string;
   article?: string;
+  course?: string;
+  paper?: string;
   href?: string;
   def?: string | { ko: string; en: string };
 };
@@ -54,6 +56,11 @@ const articleBySlug = new Map(articles.map((a) => [articleSlugOf(a), a]));
 const tools: Term[] = [];
 const conceptTerms: Term[] = [];
 const articleTerms: Term[] = [];
+// Courses/papers are opt-in sections whose category data a site may not have,
+// so their terms render as flat groups (no @aas-data/{course,paper}-categories
+// import — that would break sites that don't supply those files).
+const courseTerms: Term[] = [];
+const paperTerms: Term[] = [];
 const defTerms: Term[] = [];
 const external: Term[] = [];
 
@@ -110,6 +117,30 @@ for (const [id, e] of Object.entries(map)) {
       catLabel: top?.label[lang] ?? '',
       search: `${label} ${leaf?.label[lang] ?? ''} ${top?.label[lang] ?? ''}`.toLowerCase(),
     });
+  } else if (e.course) {
+    courseTerms.push({
+      id,
+      label,
+      href: getRelativeLocaleUrl(lang, `course/${e.course}/`),
+      subtitle: def,
+      external: false,
+      icon: { name: label, fallback: 'course' },
+      catId: '',
+      catLabel: '',
+      search: `${label} ${def}`.toLowerCase(),
+    });
+  } else if (e.paper) {
+    paperTerms.push({
+      id,
+      label,
+      href: getRelativeLocaleUrl(lang, `paper/${e.paper}/`),
+      subtitle: def,
+      external: false,
+      icon: { name: label, fallback: 'paper' },
+      catId: '',
+      catLabel: '',
+      search: `${label} ${def}`.toLowerCase(),
+    });
   } else if (e.href) {
     external.push({
       id,
@@ -162,6 +193,8 @@ const kinds = [
   { key: 'tool', title: t('glossary.tool'), groups: groupBy(tools, rootCategories.map((c) => c.id)) },
   { key: 'concept', title: t('glossary.concept'), groups: groupBy(conceptTerms, conceptTree.roots.map((c) => c.id)) },
   { key: 'article', title: t('glossary.article'), groups: groupBy(articleTerms, articleTree.roots.map((c) => c.id)) },
+  { key: 'course', title: t('glossary.course'), groups: flat(courseTerms) },
+  { key: 'paper', title: t('glossary.paper'), groups: flat(paperTerms) },
   { key: 'term', title: t('glossary.term'), groups: flat(defTerms) },
   { key: 'external', title: t('glossary.external'), groups: flat(external) },
 ].filter((k) => k.groups.length > 0);

package/src/components/ToolAvatar.astro

@@ -30,12 +30,17 @@ const icons: Record<string, string> = {
     '<ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5V19A9 3 0 0 0 21 19V5"/><path d="M3 12A9 3 0 0 0 21 12"/>',
   observability: '<path d="M22 12h-4l-3 9L9 3l-3 9H2"/>',
   // A concept/idea (lightbulb), an article (file-text, matching the Writing nav
-  // icon), an external link (globe), and a plain term (book) — glossary
-  // fallbacks for avatars without a logo.
+  // icon), a course (graduation cap), a paper (scroll), an external link
+  // (globe), and a plain term (book) — glossary fallbacks for avatars without
+  // a logo.
   concept:
     '<path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
   article:
     '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M16 13H8"/><path d="M16 17H8"/><path d="M10 9H8"/>',
+  course:
+    '<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"/>',
+  paper:
+    '<path d="M15 12h-5"/><path d="M15 8h-5"/><path d="M19 17V5a2 2 0 0 0-2-2H4"/><path d="M8 21h12a2 2 0 0 0 2-2v-1a1 1 0 0 0-1-1H11a1 1 0 0 0-1 1v1a2 2 0 1 1-4 0V5a2 2 0 1 0-4 0v2a1 1 0 0 0 1 1h3"/>',
   external:
     '<circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/>',
   term: '<path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H20v20H6.5a2.5 2.5 0 0 1 0-5H20"/>',

package/src/i18n/ui.ts

@@ -110,6 +110,8 @@ export const ui = {
     'glossary.tool': 'Tools',
     'glossary.concept': 'Concepts',
     'glossary.article': 'Writing',
+    'glossary.course': 'Courses',
+    'glossary.paper': 'Papers',
     'glossary.term': 'Terms',
     'glossary.external': 'External',
     'glossary.search': 'Search terms…',
@@ -287,6 +289,8 @@ export const ui = {
     'glossary.tool': '도구',
     'glossary.concept': '개념',
     'glossary.article': '글',
+    'glossary.course': '강의',
+    'glossary.paper': '논문',
     'glossary.term': '용어',
     'glossary.external': '외부',
     'glossary.search': '용어 검색…',

package/src/layouts/BaseLayout.astro

@@ -12,7 +12,7 @@ import BackToTop from '../components/BackToTop.astro';
 import Footer from '@aas-footer';
 import { getNavPages, pageSlugOf } from '../lib/pages';
 import { getNavProducts, getTopProducts, productSlugOf } from '../lib/products';
-import { homeTemplate } from '../lib/home';
+import { homeTemplate, home as homeConfig, loc } from '../lib/home';
 import { sectionEnabled, type SectionKey } from '../lib/sections';
 import { siteIcons } from '../lib/icons';
 import { privateClientData } from '../lib/private';
@@ -84,6 +84,10 @@ const showRepoLink =
 // layouts never drift: an icon-only row (≥sm) and a labelled dropdown menu
 // (<sm, so a phone header stays to a few controls instead of a long icon run).
 // `svg` is the icon's inner markup (drawn into a shared <svg> shell below).
+// Shared 2×2 grid icon for the catalog Browse nav (catalog home + cards-home
+// `home.browse`).
+const CATALOG_ICON =
+  '<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"/>';
 const allNavItems: {
   href: string;
   label: string;
@@ -92,18 +96,30 @@ 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.
+  // Browse (grid icon): on the catalog home it anchors into the #categories
+  // section; on a cards home it's off unless the site sets `home.browse` to
+  // point at a separate catalog page (e.g. a category browse).
   ...(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"/>',
+          svg: CATALOG_ICON,
         },
       ]
-    : []),
+    : homeConfig?.browse
+      ? [
+          {
+            href: homeConfig.browse.external
+              ? homeConfig.browse.href
+              : getRelativeLocaleUrl(lang, homeConfig.browse.href.replace(/^\//, '')),
+            label: loc(homeConfig.browse.label, lang) ?? t('nav.browse'),
+            external: homeConfig.browse.external,
+            svg: CATALOG_ICON,
+          },
+        ]
+      : []),
   ...(hasProducts
     ? [
         {

package/src/lib/home.ts

@@ -45,6 +45,15 @@ export interface HomeConfig {
     description?: Localized;
     button?: { label: Localized; href: string; external?: boolean };
   };
+  /** Catalog "Browse" nav link for the cards home. The stacks catalog Browse
+   *  nav anchors into the catalog home's #categories section, so it's hidden on
+   *  a cards home — set this to add a header nav item that points at a separate
+   *  catalog page instead (e.g. a category browse at `/categories/tools/`, or a
+   *  tag/vendor page). `href` is a locale-less internal path (prefixed per
+   *  locale at render) or an external URL (`external: true`); `label` defaults
+   *  to the theme's "Browse" string. Ignored on the catalog home, which keeps
+   *  its built-in #categories Browse. */
+  browse?: { href: string; label?: Localized; external?: boolean };
 }
 
 export const home: HomeConfig | undefined = (site as { home?: HomeConfig }).home;