stack-site-builder 1.23.1 → 1.24.0

package/CHANGELOG.md

@@ -11,6 +11,93 @@ 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.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
+
+- **Wide tables scroll instead of cramming their cells** — a table wider than its
+  column had no way out: it needs `display: table` for real column sizing, which
+  makes `overflow-x` on the table itself a no-op, so every cell was squeezed into
+  a stack of wrapped lines (a 3-column table with 1561px of natural content
+  rendered 920px wide and 3.6x its natural height, breaking code samples
+  mid-token). Every rendered table now sits in a `.aas-table-scroll` box that
+  takes the scrolling while the table keeps its natural widths — on both render
+  paths: `rehypeTableScroll` for content collections, `withTableScroll`
+  (`lib/md-tables.ts`) for the MarkdownIt paths behind READMEs and sample
+  descriptions. In a reading column the wrapper shrinks to the table and centers,
+  so a narrow table keeps its own width instead of being stretched; on slides a
+  wide table slides sideways. A table that arrives without a wrapper (raw HTML in
+  MDX, say) still behaves exactly as before.
+- **Slide diagrams render full-size** — the generic caps (`pre` 62vh, svg 52vh)
+  don't know how much room the slide fill rules actually handed the diagram — on
+  a full-height slide that box is ~78vh — so a tall flowchart was scaled to fit
+  52vh and the unused width was letterboxed as empty margins either side.
+  Diagrams now size against the box they were given (measured on a 1958x2000
+  flowchart: 0.34 -> 0.75 scale). `compact`, `.aas-split.scroll` and `scroll-x`
+  manage their own overflow and are excluded, so they render exactly as before.
+- **Mermaid subgraph titles stop overlapping** — mermaid draws labels as real
+  HTML in a `<foreignObject>` and sizes nodes and cluster frames from the
+  measured box; mermaid 11 wraps label text in a `<p>`, which inherited the
+  page's paragraph typography (26px/41px on a slide) while mermaid reserves only
+  ~25px for a cluster title, so every subgraph title overlapped the first node
+  inside it by ~16px. Label typography is pinned back to mermaid's own so its
+  measurements hold.
+
 ## [1.23.1] - 2026-07-29
 
 ### Fixed
@@ -433,6 +520,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.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
 [1.19.3]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.19.2...v1.19.3

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.
 

package/markdown.mjs

@@ -94,6 +94,32 @@ function remarkMermaid() {
   return (/** @type {any} */ tree) => walk(tree);
 }
 
+// Wrap every table in a horizontal scroll box. A table can't scroll itself: the
+// moment it needs `display: table` for real column sizing (and a rounded frame),
+// `overflow-x` on the table is dead, so a table wider than its column has no way
+// out but to squeeze every cell into a stack of wrapped lines — a 120px-tall
+// table becomes 430px of cramped text. The wrapper takes the scrolling, the
+// table keeps its natural widths (see `.aas-table-scroll` in global.css).
+function rehypeTableScroll() {
+  /** @param {any} node */
+  const walk = (node) => {
+    if (!node.children) return;
+    node.children.forEach((/** @type {any} */ child, /** @type {number} */ i) => {
+      if (child.type === 'element' && child.tagName === 'table') {
+        node.children[i] = {
+          type: 'element',
+          tagName: 'div',
+          properties: { className: ['aas-table-scroll'] },
+          children: [child],
+        };
+      } else {
+        walk(child);
+      }
+    });
+  };
+  return (/** @type {any} */ tree) => walk(tree);
+}
+
 // Slide directives (needs remarkDirective, which runs first). Two are handled:
 //
 //   :::cols          columns, separated by `---`:
@@ -405,6 +431,7 @@ export function aasMarkdown({ glossary, locales = ['en', 'ko'], defaultLocale =
     rehypePlugins: [
       rehypeSlug,
       rehypeHeadingAnchors,
+      rehypeTableScroll,
       [rehypeExternalLinks, { target: '_blank', rel: ['noopener', 'noreferrer'] }],
     ],
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.23.1",
+  "version": "1.24.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": {

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

@@ -2,7 +2,7 @@
 import '../styles/global.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 +55,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 +65,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 +220,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 +291,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 +306,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 ?? '') ||

package/src/lib/locales.ts

@@ -14,3 +14,33 @@ export const allLocales = Object.keys(languages) as Lang[];
 /** The `[...lang]` param for a locale: `undefined` for the default, else the code. */
 export const langParam = (lang: Lang): string | undefined =>
   lang === defaultLang ? undefined : lang;
+
+/**
+ * Content-id helpers. Every collection is locale-partitioned by folder
+ * (`stacks/<code>/<slug>.mdx`), so an entry's id carries a `<code>/` prefix
+ * that listings filter on and slugs strip.
+ *
+ * Two details make the prefix worth deriving instead of hardcoding: Astro's
+ * glob loader runs every path segment through github-slugger, which
+ * LOWERCASES it, so a `zh-CN` folder yields the id `zh-cn/…`; and a locale
+ * code isn't necessarily two bare letters (`zh-CN`, `pt-BR`). Both are handled
+ * here once, so adding such a locale stays a site-config change.
+ */
+
+/** The `<locale>/` prefix an entry id carries for `lang`. */
+export const contentPrefix = (lang: Lang): string => `${lang.toLowerCase()}/`;
+
+/** Whether a content id belongs to `lang`. */
+export const inLocale = (id: string, lang: Lang): boolean => id.startsWith(contentPrefix(lang));
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// Longest code first, so `zh` can't shadow `zh-cn` on a site shipping both.
+const localePrefixRe = new RegExp(
+  `^(?:${allLocales
+    .map((l) => escapeRe(l.toLowerCase()))
+    .sort((a, b) => b.length - a.length)
+    .join('|')})/`,
+);
+
+/** An entry id with its `<locale>/` prefix removed — the basis of every slug. */
+export const stripLocale = (id: string): string => id.replace(localePrefixRe, '');

package/src/lib/md-tables.ts

@@ -0,0 +1,21 @@
+import type MarkdownIt from 'markdown-it';
+
+/**
+ * Wrap every rendered table in a `.aas-table-scroll` box, matching what
+ * `rehypeTableScroll` (markdown.mjs) does for content collections. A table
+ * cannot scroll itself — it needs `display: table` for real column sizing,
+ * which makes `overflow-x` on the table a no-op — so without the wrapper a
+ * README table wider than its column has no escape but to wrap every cell.
+ *
+ * Only needed on MarkdownIt instances that RENDER (READMEs, sample
+ * descriptions); the ones that merely `parse()` for metadata can skip it.
+ */
+export function withTableScroll(md: MarkdownIt): MarkdownIt {
+  const base = md.renderer.rules.table_open ?? ((t, i, o, _e, s) => s.renderToken(t, i, o));
+  md.renderer.rules.table_open = (tokens, idx, opts, env, self) =>
+    `<div class="aas-table-scroll">${base(tokens, idx, opts, env, self)}`;
+  const baseClose = md.renderer.rules.table_close ?? ((t, i, o, _e, s) => s.renderToken(t, i, o));
+  md.renderer.rules.table_close = (tokens, idx, opts, env, self) =>
+    `${baseClose(tokens, idx, opts, env, self)}</div>`;
+  return md;
+}

package/src/lib/pages.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 PageEntry = CollectionEntry<'pages'>;
 
 /** The url slug of a page, i.e. its id with the `<lang>/` prefix removed. */
 export function pageSlugOf(entry: PageEntry): string {
-  return entry.id.replace(/^[a-z]{2}\//, '');
+  return stripLocale(entry.id);
 }
 
 /** Standalone pages for one locale, in `order` (then title) order. */
 export async function getPages(lang: Lang): Promise<PageEntry[]> {
   const all = await getCollection('pages');
   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 - b.data.order || a.data.title.localeCompare(b.data.title),
     );

package/src/lib/papers.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 PaperEntry = CollectionEntry<'papers'>;
 
 /** The url slug of a paper, i.e. its id with the `<lang>/` prefix removed. */
 export function paperSlugOf(entry: PaperEntry): string {
-  return entry.id.replace(/^[a-z]{2}\//, '');
+  return stripLocale(entry.id);
 }
 
 /** Published papers for one locale — newest publication year first, then title. */
 export async function getPapers(lang: Lang): Promise<PaperEntry[]> {
   const all = await getCollection('papers');
   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.year ?? 0) - (a.data.year ?? 0) || a.data.title.localeCompare(b.data.title),
     );

package/src/lib/products.ts

@@ -1,5 +1,6 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import type { Lang } from '../i18n/ui';
+import { inLocale, stripLocale } from './locales';
 
 export type ProductEntry = CollectionEntry<'products'>;
 
@@ -7,14 +8,14 @@ export type ProductEntry = CollectionEntry<'products'>;
  *  nested (`flowstate-ai/privacy`), which the catch-all route renders at the
  *  matching subpath. */
 export function productSlugOf(entry: ProductEntry): string {
-  return entry.id.replace(/^[a-z]{2}\//, '');
+  return stripLocale(entry.id);
 }
 
 /** Published product pages for one locale, in `order` (then title) order. */
 export async function getProducts(lang: Lang): Promise<ProductEntry[]> {
   const all = await getCollection('products');
   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 - b.data.order || a.data.title.localeCompare(b.data.title));
 }