stack-site-builder 1.23.2 → 1.25.0

package/CHANGELOG.md

@@ -11,6 +11,110 @@ 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.25.0] - 2026-08-31
+
+Papers and courses routinely carry formulas, and until now a site's only
+option was to drop in a screenshot or fake it with Unicode. This release adds
+LaTeX math to the markdown pipeline, rendered by KaTeX at build time, with the
+theme's existing dollar-sign prices left alone by default.
+
+### Added
+
+- **LaTeX math in the markdown pipeline** — `$$…$$` renders as math: inline
+  when it sits mid-line, a centered display block when the fence stands alone
+  on its own lines. A longer run of dollars (`$$$…$$$`) opens an equivalent
+  fence for a formula that itself contains `$$`. Single `$…$` is deliberately
+  left as plain text — these are catalog sites full of prices, and "plans
+  start at $8 and go to $20" would otherwise silently become an equation — so
+  a site opts in explicitly with `math: { singleDollar: true }`, now
+  available on both `aasMarkdown()` and, newly, `aasTheme()`, which previously
+  had no way to forward the option at all. KaTeX runs at build time via
+  rehype-katex, so pages ship plain HTML + MathML with no math runtime on the
+  client, and `\text{}` renders unicode text (`\text{처리량}`) without
+  KaTeX's usual strict-mode warning, since that's the normal case in
+  bilingual content rather than a mistake.
+- **A formula KaTeX can't parse fails the build** — rehype-katex's own answer
+  to unparsable LaTeX is a vfile warning nobody reads plus red error text
+  baked into the published page, the same silent degradation this pipeline
+  already refuses for an unknown wikilink. `rehypeMathErrors` turns each such
+  warning into a thrown build error naming the file and the `line:column`
+  alongside KaTeX's own diagnostic.
+- **KaTeX ships themed and scrollable** — its stylesheet and fonts load
+  site-wide (~7 kB gzipped added to the shared bundle; the 20 font faces are
+  only fetched by a page that actually renders math) and draw in
+  `currentColor`, so math follows the light/dark theme with no palette work
+  needed. A display block wider than its column scrolls horizontally instead
+  of squeezing, matching how wide tables already behave, and inline math is
+  sized to 1.1em to match body text. KaTeX's Hangul/kana/Han fallback
+  classes, which ship with no font by design, now point at the site's own
+  sans, so `\text{처리량}` renders in the site font instead of falling
+  through to a mismatched system pick.
+
+### Changed
+
+- **The playground's Attention paper demonstrates the math syntax**, in both
+  locales — inline math, a `$$` display fence, a `$$$` fence, prices left
+  untouched, and `\text{처리량}` rendering warning-free.
+  `docs/content-authoring.md` gains a matching Math section covering both
+  fence forms, the single-dollar opt-in, the build-fails-on-error behavior,
+  and the one MDX escaping rule that does not apply inside math (braces need
+  no `\{`).
+
+## [1.24.0] - 2026-08-25
+
+Adding a locale was already meant to be site config only — the README said so —
+but four strings never got the memo, so a site shipping a language beyond the
+theme's en/ko had no way to translate its pricing chips, difficulty tooltips or
+license labels, and no way to give the site itself a per-language name. This
+release closes those, along with two hardcodings that assumed the default locale
+is `en` and that a locale code is two bare letters.
+
+### Added
+
+- **Sites supply the enum label tables** — `site.pricingLabels` (the `pricing`
+  frontmatter enum), `site.difficultyLabels` (course `level` 1–5) and
+  `site.licenseLabels` (descriptive licenses like `proprietary`) now feed
+  `pricingLabel()` / `difficultyLabel()` / `licenseLabel()` with the same
+  precedence `useTranslations` already used: the site's table for this locale,
+  the theme's, then both again for the default locale. Each is
+  `{ <code>: { <key>: <label> } }`, merged per key, so a site lists only what it
+  needs — and a site can retranslate a locale the theme ships, since the site's
+  entry wins. Previously these three read en/ko literals with no override point,
+  which left a third locale's chips and tooltips rendering in the default
+  locale's language with nothing a site could do about it.
+- **`site.name` can be per-locale** — either one string for every locale (as
+  before, unchanged) or a record like
+  `{ en: 'Advanced Algorithms', ko: '고급 알고리즘' }`, resolved through the new
+  `siteName(lang)` export and falling back to the default locale then any entry.
+  Every place the name appears — page titles, the header wordmark and its
+  aria-label, the RSS channel title, the catalog and cards homepages, the deck
+  view — now goes through it.
+
+### Fixed
+
+- **The language auto-detect redirect works on non-`en`-default sites** — the
+  root home gated its redirect script on `lang === 'en'` instead of
+  `lang === defaultLang`, so a site whose first locale is anything else (a
+  ko-default lecture site, say) shipped the script on no page at all and never
+  auto-detected. The redirect now lands on whichever locale's home is served
+  without a prefix.
+- **Locale codes that aren't two bare letters** — every collection derived its
+  slugs with a copy of `/^[a-z]{2}\//` and filtered its listings with
+  `id.startsWith(`${lang}/`)`, so a `zh-CN` or `pt-BR` locale produced slugs
+  with the locale still glued on and listings that matched nothing. Both now go
+  through `stripLocale()` / `inLocale()` in `lib/locales.ts`, built from the
+  site's own locale codes. The prefix is compared lowercased because Astro's
+  glob loader lowercases every path segment when it derives content ids, so the
+  content folder may be cased either way (`stacks/zh-CN/` or `stacks/zh-cn/`).
+
+### Changed
+
+- **The playground demos a fourth locale, `zh-CN`** — deliberately a code that
+  is neither two letters nor all-lowercase, with its own `pricingLabels`,
+  `difficultyLabels`, `licenseLabels`, a per-locale `site.name` and a partial
+  `site.ui` table, so the fallbacks and the slug derivation stay covered by the
+  build.
+
 ## [1.23.2] - 2026-08-06
 
 ### Fixed
@@ -465,6 +569,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.25.0]: https://github.com/CodeComposeStudio/stack-site-builder/compare/v1.24.0...v1.25.0
+[1.24.0]: https://github.com/CodeComposeStudio/stack-site-builder/compare/v1.23.2...v1.24.0
 [1.23.2]: https://github.com/CodeComposeStudio/stack-site-builder/compare/v1.23.1...v1.23.2
 [1.23.1]: https://github.com/CodeComposeStudio/stack-site-builder/compare/v1.23.0...v1.23.1
 [1.23.0]: https://github.com/CodeComposeStudio/stack-site-builder/compare/v1.22.0...v1.23.0

package/README.md

@@ -36,7 +36,7 @@ export const collections = defineAasCollections({ categoryMap });
 
 | Where | What |
 | --- | --- |
-| `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/site.ts` | Site identity: name (one string, or per-locale), 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 and enum label tables (`pricingLabels`, `difficultyLabels`, `licenseLabels`) |
 | `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 — each entry links a term to a `stack` / `concept` / `article` / `course` / `paper` page, an external `href`, or is a definition-only term (`def`) |
@@ -63,6 +63,21 @@ locale from one source. To add a language (say Japanese):
    you omit falls back to the default locale. Add the `<code>` translations to
    your content (`src/content/<collection>/<code>/…`), glossary and category
    labels the same way you did for the built-in locales.
+4. Supply the enum labels the theme only ships in en/ko, under the same
+   per-locale shape: `site.pricingLabels` (the `pricing` frontmatter enum),
+   `site.difficultyLabels` (course `level` 1–5) and `site.licenseLabels`
+   (descriptive licenses like `proprietary`; real license names pass through).
+   Each is `{ <code>: { <key>: <label> } }`, merged per key over the theme's
+   table, so you list only what you need. A site can also retranslate a locale
+   the theme ships — the site's entry wins.
+5. If the site's own name differs per language, make `site.name` a per-locale
+   record — `name: { en: 'Advanced Algorithms', ko: '고급 알고리즘' }` — instead of
+   one string. A locale it omits falls back to the default locale.
+
+A locale code doesn't have to be two letters: `zh-CN` and `pt-BR` work, and the
+content folder may be cased either way (`stacks/zh-CN/` or `stacks/zh-cn/`) —
+Astro lowercases the path segment when it derives content ids, which the theme
+accounts for.
 
 No theme files change — adding a locale is entirely site config and content.
 
@@ -203,7 +218,7 @@ import Bookmark from 'stack-site-builder/components/Bookmark.astro';
 ```
 
 Markdown/MDX authoring gotchas (nested-list indentation, blockquotes, hard
-breaks, wikilinks): `docs/content-authoring.md`.
+breaks, wikilinks, math): `docs/content-authoring.md`.
 
 ## RSS
 

package/index.d.ts

@@ -25,6 +25,14 @@ export interface AasThemeOptions {
    * `sections` so its header-nav item is hidden too.
    */
   sections?: Partial<Record<SectionKey, boolean>>;
+  /**
+   * Math syntax. `$$…$$` (inline, or a fence on its own lines for a display
+   * block) is always on. `singleDollar` additionally reads `$…$` as inline
+   * math; it is off by default because these are catalog sites whose prose is
+   * full of prices, and "plans start at $8 and go to $20" would otherwise
+   * silently render as an equation.
+   */
+  math?: { singleDollar?: boolean };
 }
 
 /**

package/index.mjs

@@ -100,9 +100,13 @@ const OPT_IN_SECTIONS = new Set(['courses', 'products', 'papers']);
  *   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).
+ * @param {{ singleDollar?: boolean }} [opts.math] — math syntax. `$$…$$` is
+ *   always on; `{ singleDollar: true }` additionally reads `$…$` as inline math.
+ *   Off by default because a catalog site's prose is full of prices — see
+ *   MATH_SYNTAX in markdown.mjs.
  * @returns {import('astro').AstroIntegration[]}
  */
-export default function aasTheme({ glossary, sections = {} }) {
+export default function aasTheme({ glossary, sections = {}, math = {} }) {
   /** @type {import('astro').AstroIntegration} */
   const core = {
     name: 'stack-site-builder',
@@ -138,7 +142,7 @@ export default function aasTheme({ glossary, sections = {} }) {
         });
 
         updateConfig({
-          markdown: aasMarkdown({ glossary, locales, defaultLocale }),
+          markdown: aasMarkdown({ glossary, locales, defaultLocale, math }),
 
           // Bind the dev server to 0.0.0.0 so it's reachable from a browser on
           // the host (outside the Docker container).

package/markdown.mjs

@@ -1,12 +1,14 @@
 // @ts-check
 // The shared Markdown/MDX pipeline for awesome-*-stack sites: heading ids +
-// copy-link anchors, mermaid fences, slide directives, and [[wikilink]]
-// resolution against the site's glossary. Sites get the whole pipeline from
-// the theme integration (index.mjs); `aasMarkdown({ glossary })` is also
-// exported for direct use.
+// copy-link anchors, mermaid fences, slide directives, LaTeX math, and
+// [[wikilink]] resolution against the site's glossary. Sites get the whole
+// pipeline from the theme integration (index.mjs); `aasMarkdown({ glossary })`
+// is also exported for direct use.
 import rehypeExternalLinks from 'rehype-external-links';
+import rehypeKatex from 'rehype-katex';
 import rehypeSlug from 'rehype-slug';
 import remarkDirective from 'remark-directive';
+import remarkMath from 'remark-math';
 
 // Prepend a "#" copy-link anchor to h2/h3/h4 headings (a global click handler
 // in BaseLayout copies the section URL). The "#" count per level is drawn via
@@ -412,25 +414,78 @@ function remarkGlossary({ glossary, locales = ['en', 'ko'], defaultLocale = 'en'
   };
 }
 
+// KaTeX cannot parse everything, and rehype-katex's answer to a formula it
+// chokes on is a warning nobody reads plus red text in the published page. That
+// is the silent-degradation failure mode this pipeline already refuses for
+// wikilinks, so promote it the same way: fail the build. Runs immediately after
+// rehypeKatex, which records each failure on the vfile.
+function rehypeMathErrors() {
+  return (/** @type {any} */ _tree, /** @type {any} */ file) => {
+    /** @type {any[]} */
+    const messages = file.messages || [];
+    const bad = messages.filter((m) => m.source === 'rehype-katex');
+    if (!bad.length) return;
+    // Drop them from the vfile so the thrown error is the only report.
+    file.messages = messages.filter((m) => m.source !== 'rehype-katex');
+    const where = file.path || (file.history && file.history[0]) || 'unknown file';
+    const detail = bad
+      .map((m) => {
+        const at = m.place && m.place.start ? `${m.place.start.line}:${m.place.start.column} ` : '';
+        return `  - ${at}${(m.cause && m.cause.message) || m.reason}`;
+      })
+      .join('\n');
+    throw new Error(`[math] KaTeX could not parse ${bad.length} formula(s) in ${where}:\n${detail}`);
+  };
+}
+
+// Math is written with DOUBLE dollars — `$$E = mc^2$$` inline, or a `$$` fence
+// on its own lines for a display block (three or more dollars work the same, so
+// `$$$ … $$$` is a valid fence too, as long as the closing run is at least as
+// long as the opening one). Single `$…$` is deliberately OFF: these are catalog
+// sites full of prices, and "plans start at $8 and go to $20" would otherwise
+// silently turn into math. A site that wants single-dollar math can opt in with
+// `aasMarkdown({ math: { singleDollar: true } })`.
+const MATH_SYNTAX = { singleDollarTextMath: false };
+
+// KaTeX renders at BUILD time (rehype-katex), so pages ship plain HTML + MathML
+// with no client-side math runtime; the stylesheet is pulled in by BaseLayout.
+const KATEX_OPTIONS = {
+  // KaTeX's `strict` mode warns about non-Latin characters inside `\text{…}`,
+  // which for bilingual ko/en content is the normal case, not a mistake
+  // (`\text{처리량}`). Silence just that rule and keep the rest of the warnings.
+  /** @param {string} code */
+  strict: (/** @type {string} */ code) => (code === 'unicodeTextInMathMode' ? 'ignore' : 'warn'),
+};
+
 /**
  * The full markdown config for `defineConfig({ markdown })`.
- * @param {{ glossary: Record<string, any>, locales?: string[], defaultLocale?: string }} opts
+ * @param {{ glossary: Record<string, any>, locales?: string[], defaultLocale?: string,
+ *          math?: { singleDollar?: boolean } }} opts
  *   `glossary` — the site's wikilink targets (pass `{}` for none). `locales` /
  *   `defaultLocale` come from the site's astro.config `i18n` so wikilink locale
  *   detection matches whatever locales the site ships (defaults to en/ko).
+ *   `math.singleDollar` opts into `$…$` inline math (see MATH_SYNTAX).
  */
-export function aasMarkdown({ glossary, locales = ['en', 'ko'], defaultLocale = 'en' }) {
+export function aasMarkdown({ glossary, locales = ['en', 'ko'], defaultLocale = 'en', math = {} }) {
   return {
     remarkPlugins: [
       remarkHeadingIds,
+      // Before remarkMermaid/remarkDirective only for readability — all three
+      // are micromark syntax extensions, so the parser applies them together.
+      [remarkMath, { ...MATH_SYNTAX, singleDollarTextMath: math.singleDollar === true }],
       remarkMermaid,
       remarkDirective,
       remarkSlideDirectives,
       [remarkGlossary, { glossary, locales, defaultLocale }],
     ],
     rehypePlugins: [
+      // rehypeSlug runs first so a heading with math slugs from the SOURCE
+      // (`## $$x^2$$` → "x2"); after KaTeX the heading's text content is the
+      // whole rendered glyph soup and the id would be unusable.
       rehypeSlug,
       rehypeHeadingAnchors,
+      [rehypeKatex, KATEX_OPTIONS],
+      rehypeMathErrors,
       rehypeTableScroll,
       [rehypeExternalLinks, { target: '_blank', rel: ['noopener', 'noreferrer'] }],
     ],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.23.2",
+  "version": "1.25.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": {
@@ -38,11 +38,14 @@
     "@astrojs/rss": "^4.0.0",
     "@astrojs/sitemap": "^3.3.0",
     "@tailwindcss/vite": "^4.1.0",
+    "katex": "^0.16.47",
     "markdown-it": "^14.2.0",
     "mermaid": "^11.15.0",
     "rehype-external-links": "^3.0.0",
+    "rehype-katex": "^7.0.1",
     "rehype-slug": "^6.0.0",
     "remark-directive": "^4.0.0",
+    "remark-math": "^6.0.0",
     "shiki": "^4.2.0",
     "tailwindcss": "^4.1.0"
   },

package/src/components/CardsHome.astro

@@ -6,7 +6,7 @@
 import { site } from '@aas-data/site';
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import { home, loc, locList } from '../lib/home';
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, siteName, type Lang } from '../i18n/ui';
 
 interface Props {
   lang: Lang;
@@ -18,7 +18,7 @@ const h = home;
 const base = import.meta.env.BASE_URL.replace(/\/$/, '');
 const withBase = (p?: string) => (p && p.startsWith('/') ? base + p : p);
 
-const heroTitle = loc(h?.hero?.title, lang) ?? site.name;
+const heroTitle = loc(h?.hero?.title, lang) ?? siteName(lang);
 const heroSubtitle = loc(h?.hero?.subtitle, lang) ?? t('site.tagline');
 const extAttrs = (external?: boolean) =>
   external ? { target: '_blank', rel: 'noopener noreferrer' } : {};

package/src/components/DeckView.astro

@@ -1,11 +1,10 @@
 ---
-import { site } from '@aas-data/site';
 import '../styles/global.css';
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import { render, type CollectionEntry } from 'astro:content';
 import MermaidLoader from './MermaidLoader.astro';
 import PrivateGate from './PrivateGate.astro';
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, siteName, type Lang } from '../i18n/ui';
 import { siteIcons } from '../lib/icons';
 
 // Renders a full-screen slide deck as a horizontal scroll-snap presentation.
@@ -31,7 +30,7 @@ const priv = entry.data.private;
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>{entry.data.title} — {site.name}</title>
+    <title>{entry.data.title} — {siteName(lang)}</title>
     <meta name="description" content={(priv ? entry.data.teaser : entry.data.description) ?? ''} />
     {priv && <meta name="robots" content="noindex" />}
     <link rel="icon" {...(siteIcons.faviconType ? { type: siteIcons.faviconType } : {})} href={`${base}${siteIcons.favicon}`} />

package/src/components/Home.astro

@@ -8,7 +8,7 @@ import { getStacks, slugOf } from '../lib/stacks';
 import { site } from '@aas-data/site';
 import { deriveFacets } from '../lib/facets';
 import { memberOnlyInIndex } from '../lib/listing';
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, siteName, type Lang } from '../i18n/ui';
 
 interface Props {
   lang: Lang;
@@ -33,7 +33,7 @@ const facets = deriveFacets(entries, lang);
 ---
 
 <section class="py-6">
-  <h1 class="text-4xl font-bold tracking-tight">{site.name}</h1>
+  <h1 class="text-4xl font-bold tracking-tight">{siteName(lang)}</h1>
   <p class="mt-3 max-w-2xl text-lg text-[var(--aas-muted)]">{t('site.tagline')}</p>
 </section>
 

package/src/i18n/ui.ts

@@ -25,9 +25,23 @@ const themeLocales: LocaleDef[] = [
   { code: 'en', label: 'English', dateLocale: 'en-US' },
   { code: 'ko', label: '한국어', dateLocale: 'ko-KR' },
 ];
-// Read defensively: a site that hasn't opted into custom locales simply has no
-// `locales` field, and should keep the theme's en/ko default (not a type error).
-const siteLocales = (site as { locales?: LocaleDef[] }).locales;
+/** A per-locale label table: `{ <locale>: { <key>: <label> } }`. Sites supply
+ *  these for locales the theme doesn't ship (see {@link pricingLabels}). */
+export type LabelTable = Record<string, Record<string, string>>;
+
+// Read defensively: every field below is optional, and a site that declares
+// none of them must not be a type error — the `@aas-data/site` alias points at
+// the site's own object, whose exact shape the theme can't know.
+const siteCfg = site as {
+  name?: string | Record<string, string>;
+  locales?: LocaleDef[];
+  pricingLabels?: LabelTable;
+  difficultyLabels?: LabelTable;
+  licenseLabels?: LabelTable;
+};
+// A site that hasn't opted into custom locales simply has no `locales` field,
+// and should keep the theme's en/ko default.
+const siteLocales = siteCfg.locales;
 const localeList: LocaleDef[] =
   Array.isArray(siteLocales) && siteLocales.length ? siteLocales : themeLocales;
 
@@ -51,6 +65,20 @@ export function dateLocaleOf(lang: Lang): string {
   );
 }
 
+/**
+ * The site's name in `lang`. `site.name` is either one string used for every
+ * locale (the common case) or a per-locale record — `{ ko: '고급 알고리즘', en:
+ * 'Advanced Algorithms' }` — which falls back to the default locale, then to
+ * any entry. Same rule as `loc()` in lib/home.ts, inlined here because that
+ * module imports this one.
+ */
+export function siteName(lang: Lang): string {
+  const n = siteCfg.name;
+  if (n == null) return '';
+  if (typeof n === 'string') return n;
+  return n[lang] ?? n[defaultLang] ?? Object.values(n)[0] ?? '';
+}
+
 /** UI chrome strings, keyed by a dotted id. */
 export const ui = {
   en: {
@@ -436,14 +464,35 @@ export function useTranslations(lang: Lang) {
   };
 }
 
+/**
+ * Look one label up with the same precedence `useTranslations` uses: the site's
+ * table for this locale, the theme's, then both again for the default locale.
+ * The site-first order lets a site retranslate a locale the theme ships; the
+ * default-locale fallback keeps a site-added locale from rendering a bare key.
+ */
+function lookupLabel(
+  siteTable: LabelTable | undefined,
+  themeTable: LabelTable,
+  lang: Lang,
+  key: string,
+): string | undefined {
+  return (
+    siteTable?.[lang]?.[key] ??
+    themeTable[lang]?.[key] ??
+    siteTable?.[defaultLang]?.[key] ??
+    themeTable[defaultLang]?.[key]
+  );
+}
+
 /** Localized label for a `pricing` enum value, falling back to the default
  *  locale then the raw value (so a site-added locale never crashes). */
 export function pricingLabel(lang: Lang, value: string): string {
-  return pricingLabels[lang]?.[value] ?? pricingLabels[defaultLang]?.[value] ?? value;
+  return lookupLabel(siteCfg.pricingLabels, pricingLabels, lang, value) ?? value;
 }
 
-/** Human labels for the `pricing` frontmatter enum, per locale. */
-export const pricingLabels: Record<string, Record<string, string>> = {
+/** Human labels for the `pricing` frontmatter enum, per locale. A site adds its
+ *  own locales via `site.pricingLabels` — same shape, merged per-key. */
+export const pricingLabels: LabelTable = {
   en: {
     'completely-free': 'Completely free',
     'open-source': 'Open source',
@@ -464,20 +513,22 @@ export const pricingLabels: Record<string, Record<string, string>> = {
  *  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;
+  return lookupLabel(siteCfg.difficultyLabels, difficultyLabels, lang, key) ?? key;
 }
 
-/** Human labels for the course `level` frontmatter (1–5), per locale. */
-export const difficultyLabels: Record<string, Record<string, string>> = {
+/** Human labels for the course `level` frontmatter (1–5), per locale. A site
+ *  adds its own locales via `site.difficultyLabels`. */
+export const difficultyLabels: LabelTable = {
   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>> = {
+/** Descriptive (non-name) licenses get localized; real license names pass
+ *  through. A site adds its own locales via `site.licenseLabels`. */
+const licenseLabels: LabelTable = {
   en: { proprietary: 'Proprietary' },
   ko: { proprietary: '독점' },
 };
 export function licenseLabel(lang: Lang, value: string): string {
-  return licenseLabels[lang]?.[value] ?? licenseLabels[defaultLang]?.[value] ?? value;
+  return lookupLabel(siteCfg.licenseLabels, licenseLabels, lang, value) ?? value;
 }

package/src/layouts/BaseLayout.astro

@@ -1,8 +1,16 @@
 ---
 import '../styles/global.css';
+// KaTeX's stylesheet, loaded site-wide rather than per-page. An Astro `import`
+// is resolved statically, so a runtime `{hasMath && …}` guard (the trick that
+// keeps the Mermaid loader off pages without diagrams) would not actually keep
+// it out of the bundle. Site-wide is also the cheaper end of the trade: it
+// merges into the one global stylesheet every page already downloads and
+// caches, ~7 kB gzipped, and the font files are only fetched by a browser that
+// has math to draw. See markdown.mjs for the pipeline that produces the markup.
+import 'katex/dist/katex.min.css';
 import { site } from '@aas-data/site';
 import { getRelativeLocaleUrl } from 'astro:i18n';
-import { useTranslations, languages, type Lang } from '../i18n/ui';
+import { useTranslations, languages, siteName, defaultLang, type Lang } from '../i18n/ui';
 import LanguageSwitcher from '../components/LanguageSwitcher.astro';
 import ThemeToggle from '../components/ThemeToggle.astro';
 import BackToTop from '../components/BackToTop.astro';
@@ -55,7 +63,7 @@ const baseNoSlash = base.replace(/\/$/, '');
 
 // Header brand: `site.header = { logo?: '/path.png', logoInvert?: bool,
 // name?: bool }`. A logo replaces the ⚡ bolt; `name: false` drops the
-// wordmark (logo-only brand — the link keeps site.name as its aria-label).
+// wordmark (logo-only brand — the link keeps siteName(lang) as its aria-label).
 const header = (site as { header?: { logo?: string; logoInvert?: boolean; name?: boolean } })
   .header;
 const brandLogo = header?.logo;
@@ -65,7 +73,11 @@ const brandName = header?.name !== false;
 const localeHomes = Object.fromEntries(
   (Object.keys(languages) as Lang[]).map((c) => [c, getRelativeLocaleUrl(c, '')]),
 );
-const isDefaultHome = path === '' && lang === 'en';
+// The auto-detect redirect belongs on the ROOT home — the one page served
+// without a locale prefix — which is the default locale's, whatever it is. This
+// read 'en' until 1.24.0, so a ko-default (or any non-en-default) site never
+// redirected at all.
+const isDefaultHome = path === '' && lang === defaultLang;
 
 // Standalone pages (the `pages` collection) that opt into a header-nav link,
 // e.g. an About/소개 page. Rendered as their own nav items alongside the
@@ -216,7 +228,7 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
         <link
           rel="alternate"
           type="application/rss+xml"
-          title={`${site.name} — ${t('blog.title')}`}
+          title={`${siteName(lang)} — ${t('blog.title')}`}
           href={getRelativeLocaleUrl(lang, 'rss.xml')}
         />
       )
@@ -287,7 +299,7 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
         <a
           href={home}
           data-keep-filters
-          aria-label={site.name}
+          aria-label={siteName(lang)}
           class="flex min-w-0 items-center gap-1.5 text-base font-bold tracking-tight whitespace-nowrap no-underline sm:text-lg"
         >
           {
@@ -302,7 +314,7 @@ const navItems = allNavItems.filter((item) => !item.section || sectionEnabled(it
             )
           }
           {/* Below 600px only the mark remains, so the narrow header never truncates the wordmark. */}
-          {brandName && <span class="hidden truncate min-[600px]:inline">{site.name}</span>}
+          {brandName && <span class="hidden truncate min-[600px]:inline">{siteName(lang)}</span>}
         </a>
         {/* Section links are icon-only (labels live in aria-label). On phones
             (<sm) they collapse into the labelled dropdown menu below, so the

package/src/lib/articles.ts

@@ -1,18 +1,19 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import type { Lang } from '../i18n/ui';
+import { inLocale, stripLocale } from './locales';
 
 export type ArticleEntry = CollectionEntry<'articles'>;
 
 /** The url slug of an article, i.e. its id with the `<lang>/` prefix removed. */
 export function articleSlugOf(entry: ArticleEntry): string {
-  return entry.id.replace(/^[a-z]{2}\//, '');
+  return stripLocale(entry.id);
 }
 
 /** Published articles for one locale, newest first. */
 export async function getArticles(lang: Lang): Promise<ArticleEntry[]> {
   const all = await getCollection('articles');
   return all
-    .filter((e) => e.id.startsWith(`${lang}/`) && !e.data.draft)
+    .filter((e) => inLocale(e.id, lang) && !e.data.draft)
     .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
 }
 

package/src/lib/concepts.ts

@@ -1,18 +1,19 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import type { Lang } from '../i18n/ui';
+import { inLocale, stripLocale } from './locales';
 
 export type ConceptEntry = CollectionEntry<'concepts'>;
 
 /** The url slug of a concept, i.e. its id with the `<lang>/` prefix removed. */
 export function conceptSlugOf(entry: ConceptEntry): string {
-  return entry.id.replace(/^[a-z]{2}\//, '');
+  return stripLocale(entry.id);
 }
 
 /** Published concepts for one locale, by `order` then title. */
 export async function getConcepts(lang: Lang): Promise<ConceptEntry[]> {
   const all = await getCollection('concepts');
   return all
-    .filter((e) => e.id.startsWith(`${lang}/`) && !e.data.draft)
+    .filter((e) => inLocale(e.id, lang) && !e.data.draft)
     .sort(
       (a, b) =>
         (a.data.order ?? 999) - (b.data.order ?? 999) ||

package/src/lib/courses.ts

@@ -1,11 +1,12 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import type { Lang } from '../i18n/ui';
+import { inLocale, stripLocale } from './locales';
 
 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}\//, '');
+  return stripLocale(entry.id);
 }
 
 /**
@@ -16,7 +17,7 @@ export function courseSlugOf(entry: CourseEntry): string {
 export async function getCourses(lang: Lang): Promise<CourseEntry[]> {
   const all = await getCollection('courses');
   return all
-    .filter((e) => e.id.startsWith(`${lang}/`) && !e.data.draft)
+    .filter((e) => inLocale(e.id, lang) && !e.data.draft)
     .sort(
       (a, b) =>
         (b.data.order ?? '').localeCompare(a.data.order ?? '') ||