stack-site-builder 1.10.0 → 1.13.0

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to this project are recorded in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+`stack-site-builder` is the Astro theme behind the awesome-\*-stack catalog
+sites — it ships every route, component, style, the markdown pipeline and the
+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.13.0] - 2026-07-20
+
+### Added
+
+- **Optional sections** — a site can turn off any of the secondary sections
+  (concepts, articles, samples, slides, glossary, and the standalone `pages`
+  collection); the core catalog stays on. Disabling one removes both its routes
+  and its header-nav item. Declare `sections` in `src/data/site.ts` (hides the
+  nav item) and forward it to `aasTheme({ sections })` in astro.config (skips the
+  routes); the key type (`SectionKey`) is exported from the theme, so
+  `satisfies Partial<Record<SectionKey, boolean>>` gives autocomplete of the
+  valid keys. The playground drops `slides` to demonstrate.
+
+## [1.12.0] - 2026-07-20
+
+Locales are now **site-configurable**. The theme was wired to exactly two
+languages (English at the root, Korean under `/ko/`, plus a hand-written `ko/`
+copy of every route); a consuming site could not add a third. Now the theme
+reads the locales from the site's own astro.config `i18n` and renders every
+route for each of them from one source, so a site adds a language (e.g.
+Japanese) by editing its config and data — no theme changes, no per-locale route
+files. Existing en/ko sites are unaffected: the same URLs build, and the theme
+still defaults to en/ko when a site declares nothing.
+
+### Added
+
+- **Site-configurable locales** — the header language switcher, route
+  generation, date formatting, wikilink resolution and sitemap hreflang all
+  derive from the site's configured locales. A site declares them in
+  astro.config `i18n` (routing) and, optionally, `site.locales` in
+  `src/data/site.ts` (display name + date format per locale); it supplies each
+  extra locale's UI strings via `site.ui.<code>`, with any missing key falling
+  back to the default locale. The playground ships a third locale (`ja`) to
+  demonstrate the path.
+
+### Changed
+
+- **One route tree instead of a per-locale mirror** — the hand-maintained
+  `src/pages/ko/` copy of every page is gone; all pages now live once under
+  `src/pages/[...lang]/` and enumerate the site's locales in `getStaticPaths`.
+  This is internal to the theme, but it is what makes adding a locale free.
+- **`Lang` is now `string`** (was the `'en' | 'ko'` union) since locales are no
+  longer fixed at build time. Locale-keyed maps (`pricingLabels`, category
+  labels, …) resolve through helpers that fall back to the default locale rather
+  than assuming a key exists.
+
+## [1.11.0] - 2026-07-20
+
+The center of this release is **standalone pages**: a site can now add a
+first-class top-level section — an About/소개 page, contact, terms — that is
+just one Markdown file, rendered on its own and linked from the header
+navigation, without the listing and taxonomy of the catalog collections.
+Alongside it, the header collapses into a menu on phones, the language switcher
+becomes a globe icon, and two rendering bugs on the new pages are fixed.
+
+### Added
+
+- **Standalone `pages` collection** — author a top-level page as one MDX file
+  (`src/content/pages/{en,ko}/<slug>.mdx`); the theme renders it at `/<slug>/`
+  in both locales. Frontmatter drives a hero image, description, and header-nav
+  placement (`nav`, `navLabel`, `order`, `draft`). Ships the `PageDetail`
+  component, the `getPages` / `getNavPages` / `pageSlugOf` helpers, and a
+  per-locale route injected by the integration.
+- **Mobile navigation menu** — below the `sm` breakpoint the section links
+  collapse into a labelled dropdown menu (hamburger), so a phone header stays to
+  a few controls instead of a long icon run. The icon row (≥`sm`) and the menu
+  render from one `navItems` source, so they never drift, and nav pages appear
+  in both automatically.
+
+### Changed
+
+- **Globe icon for the language switcher** — the switcher shows a globe instead
+  of the locale code/name, and the dropdown chevrons are removed from both the
+  language and theme switchers, leaving a single clean control each. Adds
+  `nav.language` and `nav.menu` UI strings (en/ko).
+
+### Fixed
+
+- **In-locale wikilinks on standalone pages** — wikilink targets were emitted as
+  `../../glossary/` (and `../../stack/…`, etc.), which assumes the source sits
+  two levels deep within its locale, true for the collection detail routes
+  (`/ko/stack/<slug>/`) but not for a one-deep standalone page (`/ko/about/`).
+  The extra `../` overshot the locale prefix and linked to the default-locale
+  glossary; the depth is now derived from where the source actually sits.
+- **In-body images no longer force horizontal scroll** — content images had no
+  width cap and Astro's `<Image>` emits intrinsic `width`/`height`, so an image
+  wider than the viewport (e.g. a screenshot on a phone) stretched the body and
+  scrolled the whole page sideways. `.prose img` is now capped to
+  `max-width: 100%; height: auto`.
+
+## [1.10.0] - 2026-07-20
+
+First public release. The rendering engine of
+[awesome-ai-stack](https://github.com/codecompose7/awesome-ai-stack) — routes,
+components, styles, the markdown pipeline and the content schema — extracted
+into a reusable, MIT-licensed Astro theme so the same engine can drive other
+catalog sites from a thin content-only repository.
+
+### Added
+
+- **The awesome-\*-stack theme** — an integration that injects every route
+  (catalog, concepts, articles, slides, samples, glossary, tags, vendors, in
+  en/ko), the components and styles, the shared markdown pipeline
+  (`[[wikilink]]` glossary, slides, mermaid), and the content schema via
+  `defineAasCollections`. A consuming site provides content, taxonomy data
+  (`categories`, `glossary`, `site`) and config.
+- **Standalone development setup** — a devcontainer and a minimal `playground/`
+  consuming site for developing and previewing the theme on its own.
+
+[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
+[1.11.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.10.0...v1.11.0
+[1.10.0]: https://github.com/CodeCompose7/stack-site-builder/releases/tag/v1.10.0

package/README.md

@@ -34,12 +34,59 @@ export const collections = defineAasCollections({ categoryMap });
 
 | Where | What |
 | --- | --- |
-| `src/data/site.ts` | Site identity: name, repo URL, per-locale UI string overrides |
+| `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/glossary.mjs` | `[[Term]]` wikilink targets |
 | `src/content/{stacks,concepts,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 |
 
 The theme reaches the site's data through the `@aas-data/*` alias (set up by
 the integration), so everything above is swappable per site.
+
+## Locales
+
+The theme defaults to English (at the root) and Korean (under `/ko/`), but the
+locale set is the site's to choose — it renders every route for each configured
+locale from one source. To add a language (say Japanese):
+
+1. List it in astro.config `i18n.locales` (this drives routing):
+   `i18n: { locales: ['en', 'ko', 'ja'], defaultLocale: 'en', routing: { prefixDefaultLocale: false } }`.
+   The first/`defaultLocale` is served at the root; the others under `/<code>/`.
+2. Add it to `locales` in `src/data/site.ts` — `{ code, label, dateLocale? }` —
+   so it appears (named) in the language switcher and formats dates correctly.
+3. Supply its UI strings in `src/data/site.ts` under `site.ui.<code>`; any key
+   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.
+
+No theme files change — adding a locale is entirely site config and content.
+
+## Sections
+
+The core catalog (home, tool detail, categories, tags, vendors) is always on.
+The rest are opt-out — **concepts, articles, samples, slides, glossary** and the
+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.)
+
+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
+the theme so `satisfies` lists the valid keys as you type:
+
+```ts
+// src/data/site.ts
+import type { SectionKey } from 'stack-site-builder';
+export const site = {
+  /* … */
+  sections: { slides: false } satisfies Partial<Record<SectionKey, boolean>>,
+};
+```
+
+```js
+// astro.config.mjs
+import { site } from './src/data/site';
+integrations: [aasTheme({ glossary, sections: site.sections })];
+```

package/index.d.ts

@@ -1,8 +1,18 @@
 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';
+
 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.
+   */
+  sections?: Partial<Record<SectionKey, boolean>>;
 }
 
 /**

package/index.mjs

@@ -21,11 +21,14 @@ import tailwindcss from '@tailwindcss/vite';
 import { aasMarkdown } from './markdown.mjs';
 import { localSamples } from './dev/local-samples.mjs';
 
-// Every page the theme provides, as `src/pages/`-relative entrypoints. The
-// same tree is served at `/` (en) and under `/ko/` (physical mirrors, matching
-// prefixDefaultLocale: false).
+// Every page the theme provides, relative to the `src/pages/[...lang]/` tree.
+// Each is injected once at `/[...lang]/…`; its getStaticPaths enumerates the
+// site's locales, emitting the default at the root and others under `/<code>/`.
 const PAGES = [
   'index.astro',
+  // 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',
   'article/index.astro',
   'article/[...id].astro',
   'article/category/[id].astro',
@@ -43,43 +46,82 @@ const PAGES = [
   'vendors/[vendor].astro',
 ];
 
-/** `article/[...id].astro` → `/article/[...id]`, `index.astro` → `/` */
-/** @param {string} file @param {string} prefix */
-function patternOf(file, prefix) {
+/** `[...lang]/article/[...id].astro` → `/[...lang]/article/[...id]`,
+ *  `[...lang]/index.astro` → `/[...lang]` */
+/** @param {string} file */
+function patternOf(file) {
   const p = file.replace(/\.astro$/, '').replace(/\/?index$/, '');
-  const full = `/${prefix}${p}`.replace(/\/$/, '');
-  return full || '/';
+  return `/${p}`.replace(/\/$/, '') || '/';
+}
+
+// Which optional section each page belongs to (null = always-on core route).
+// Mirrors SectionKey in src/lib/sections.ts.
+/** @param {string} file @returns {string | null} */
+function sectionOf(file) {
+  if (file.startsWith('concept/')) return 'concepts';
+  if (file.startsWith('article/')) return 'articles';
+  if (file.startsWith('sample/')) return 'samples';
+  if (file.startsWith('slides/')) return 'slides';
+  if (file === 'glossary.astro') return 'glossary';
+  if (file === '[page].astro') return 'pages';
+  return null;
 }
 
 /**
  * @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.
+ *   Keep it in sync with `src/data/site.ts` `sections` (which hides the nav item).
  * @returns {import('astro').AstroIntegration[]}
  */
-export default function aasTheme({ glossary }) {
+export default function aasTheme({ glossary, sections = {} }) {
   /** @type {import('astro').AstroIntegration} */
   const core = {
     name: 'stack-site-builder',
     hooks: {
       'astro:config:setup': ({ config, injectRoute, updateConfig }) => {
-        for (const prefix of ['', 'ko/']) {
-          for (const file of PAGES) {
-            const entry = prefix === '' ? file : `ko/${file}`;
-            injectRoute({
-              pattern: patternOf(file, prefix),
-              entrypoint: `stack-site-builder/pages/${entry}`,
-            });
-          }
+        // Locales the site configured (astro.config `i18n`). Everything locale
+        // aware derives from here — route injection, wikilink detection, and the
+        // sitemap hreflang — so a site adds a language by editing its config, not
+        // the theme. `locales` entries may be strings or `{ path }` objects.
+        const rawLocales = config.i18n?.locales ?? ['en'];
+        const locales = rawLocales.map((l) => (typeof l === 'string' ? l : l.path));
+        const defaultLocale = config.i18n?.defaultLocale ?? locales[0];
+
+        // A single physical page tree under `[...lang]/` serves every locale: the
+        // default at the root, each other under `/<code>/`. Each page's
+        // getStaticPaths enumerates the locales, so adding one needs no new files.
+        // Skip a page whose optional section the site turned off (`{ slides: false }`).
+        for (const file of PAGES) {
+          const section = sectionOf(file);
+          if (section && sections[section] === false) continue;
+          injectRoute({
+            pattern: patternOf(`[...lang]/${file}`),
+            entrypoint: `stack-site-builder/pages/[...lang]/${file}`,
+          });
         }
 
         updateConfig({
-          markdown: aasMarkdown({ glossary }),
+          markdown: aasMarkdown({ glossary, locales, defaultLocale }),
 
           // Bind the dev server to 0.0.0.0 so it's reachable from a browser on
           // the host (outside the Docker container).
           server: { host: true },
 
+          // hreflang alternates so search engines pair each page with its twin in
+          // the other locales. Built from the site's configured locales (added
+          // here rather than in the returned array, where `config` isn't known).
+          integrations: [
+            sitemap({
+              i18n: {
+                defaultLocale,
+                locales: Object.fromEntries(locales.map((l) => [l, l])),
+              },
+            }),
+          ],
+
           vite: {
             plugins: [tailwindcss(), localSamples()],
 
@@ -109,16 +151,7 @@ export default function aasTheme({ glossary }) {
     },
   };
 
-  return [
-    core,
-    mdx(),
-    // i18n option emits hreflang alternates so search engines associate each
-    // page with its twin in the other locale (/stack/x/ ↔ /ko/stack/x/).
-    sitemap({
-      i18n: {
-        defaultLocale: 'en',
-        locales: { en: 'en', ko: 'ko' },
-      },
-    }),
-  ];
+  // The sitemap integration is added from the core hook's updateConfig (above),
+  // where the site's configured locales are known.
+  return [core, mdx()];
 }

package/markdown.mjs

@@ -230,12 +230,16 @@ 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 the `../../stack|concept/<slug>/` relative form (locale- and base-agnostic
-// on the depth-3 detail routes); external `href` entries pass through and get
+// emit a `../stack|concept/<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,
 // failing the build so a typo can't silently degrade to plain text. Code spans
 // and fenced blocks are untouched (mdast `inlineCode`/`code` carry no children).
-function remarkGlossary({ glossary }) {
+function remarkGlossary({ glossary, locales = ['en', 'ko'], defaultLocale = 'en' }) {
+  // Non-default locales carry a `/<code>/` segment in their content path; the
+  // default locale has none. Match the path against them to pick the locale.
+  const prefixed = locales.filter((l) => l !== defaultLocale);
   const RE = /\[\[\s*([^\]|]+?)\s*(?:\|\s*([^\]]+?)\s*)?\]\]/g;
   /** @param {string} s */
   const norm = (s) => s.trim().toLowerCase().replace(/\s+/g, '-');
@@ -262,7 +266,13 @@ function remarkGlossary({ glossary }) {
   /** @param {any} tree @param {any} file */
   return (tree, file) => {
     const path = (file && (file.path || (file.history && file.history[0]))) || '';
-    const lang = /[/\\]ko[/\\]/.test(path) ? 'ko' : 'en';
+    const lang = prefixed.find((l) => new RegExp(`[/\\\\]${l}[/\\\\]`).test(path)) ?? defaultLocale;
+    // How far the relative wikilink targets below must climb to reach the locale
+    // root. The collection detail routes sit two deep within their locale
+    // (/ko/stack/<slug>/), but a standalone `pages` entry is only one deep
+    // (/ko/about/). Using the wrong count overshoots the locale prefix — from
+    // /ko/about/ a `../../` lands on the default-locale glossary, not /ko/'s.
+    const up = /[/\\]content[/\\]pages[/\\]/.test(path) ? '../' : '../../';
     /** @param {any} l */
     const labelOf = (l) => (typeof l === 'string' ? l : l[lang]);
     // Same-document section links ([[#anchor]]) resolve their display text to
@@ -329,15 +339,15 @@ function remarkGlossary({ glossary }) {
             const def = entry.def ? labelOf(entry.def) : undefined;
             // A def-only term (no page) links to its entry on the glossary page.
             let url = entry.stack
-              ? `../../stack/${entry.stack}/`
+              ? `${up}stack/${entry.stack}/`
               : entry.concept
-                ? `../../concept/${entry.concept}/`
+                ? `${up}concept/${entry.concept}/`
                 : entry.article
-                  ? `../../article/${entry.article}/`
+                  ? `${up}article/${entry.article}/`
                   : entry.href
                     ? entry.href
                     : def
-                      ? `../../glossary/#${id}`
+                      ? `${up}glossary/#${id}`
                       : null;
             if (!url)
               throw new Error(
@@ -373,17 +383,19 @@ function remarkGlossary({ glossary }) {
 
 /**
  * The full markdown config for `defineConfig({ markdown })`.
- * @param {{ glossary: Record<string, any> }} opts — the site's glossary
- *   (wikilink targets); pass `{}` for a site without wikilinks.
+ * @param {{ glossary: Record<string, any>, locales?: string[], defaultLocale?: string }} 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).
  */
-export function aasMarkdown({ glossary }) {
+export function aasMarkdown({ glossary, locales = ['en', 'ko'], defaultLocale = 'en' }) {
   return {
     remarkPlugins: [
       remarkHeadingIds,
       remarkMermaid,
       remarkDirective,
       remarkSlideDirectives,
-      [remarkGlossary, { glossary }],
+      [remarkGlossary, { glossary, locales, defaultLocale }],
     ],
     rehypePlugins: [
       rehypeSlug,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.10.0",
+  "version": "1.13.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": {
@@ -13,7 +13,8 @@
     "index.d.ts",
     "markdown.mjs",
     "src",
-    "dev"
+    "dev",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -48,5 +49,10 @@
     "@types/markdown-it": "^14.1.2",
     "astro": "^5.7.0",
     "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "dev": "pnpm --filter playground dev",
+    "build": "pnpm --filter playground build",
+    "check": "pnpm --filter playground check"
   }
-}
+}

package/src/components/ArticleLink.astro

@@ -8,7 +8,7 @@
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import { getArticles, articleSlugOf, type ArticleEntry } from '../lib/articles';
 import { formatDate } from '../lib/dates';
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, defaultLang, type Lang } from '../i18n/ui';
 import { inlineMd } from '../lib/inline-md';
 
 interface Props {
@@ -16,7 +16,7 @@ interface Props {
 }
 
 const { slug } = Astro.props;
-const lang: Lang = Astro.currentLocale === 'ko' ? 'ko' : 'en';
+const lang: Lang = (Astro.currentLocale ?? defaultLang) as Lang;
 const t = useTranslations(lang);
 const articles = await getArticles(lang);
 const target = articles.find((a) => articleSlugOf(a) === slug) as ArticleEntry | undefined;

package/src/components/ConceptDetail.astro

@@ -5,7 +5,7 @@ import { getArticles, articleSlugOf, type ArticleEntry } from '../lib/articles';
 import { getConcepts, conceptSlugOf, conceptToolSlugs, type ConceptEntry } from '../lib/concepts';
 import { inlineMd } from '../lib/inline-md';
 import { Image } from 'astro:assets';
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, dateLocaleOf, type Lang } from '../i18n/ui';
 import MermaidLoader from './MermaidLoader.astro';
 import TocRail from './TocRail.astro';
 import Breadcrumb from './Breadcrumb.astro';
@@ -41,7 +41,7 @@ const relatedConcepts = data.related
   .filter(Boolean) as ConceptEntry[];
 
 const fmtDate = (d: Date) =>
-  new Intl.DateTimeFormat(lang === 'ko' ? 'ko-KR' : 'en-US', {
+  new Intl.DateTimeFormat(dateLocaleOf(lang), {
     year: 'numeric',
     month: 'long',
     day: 'numeric',

package/src/components/ConceptLink.astro

@@ -7,7 +7,7 @@
 // from the current page (concepts are served under /<lang>/...).
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import { getConcepts, conceptSlugOf, type ConceptEntry } from '../lib/concepts';
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, defaultLang, type Lang } from '../i18n/ui';
 import { inlineMd } from '../lib/inline-md';
 
 interface Props {
@@ -15,7 +15,7 @@ interface Props {
 }
 
 const { slug } = Astro.props;
-const lang: Lang = Astro.currentLocale === 'ko' ? 'ko' : 'en';
+const lang: Lang = (Astro.currentLocale ?? defaultLang) as Lang;
 const t = useTranslations(lang);
 const concepts = await getConcepts(lang);
 const target = concepts.find((c) => conceptSlugOf(c) === slug) as ConceptEntry | undefined;

package/src/components/ConceptTools.astro

@@ -7,7 +7,7 @@ import { getRelativeLocaleUrl } from 'astro:i18n';
 import { getStacks, slugOf, type StackEntry } from '../lib/stacks';
 import { categoryMap } from '@aas-data/categories';
 import ToolAvatar from './ToolAvatar.astro';
-import type { Lang } from '../i18n/ui';
+import { defaultLang, type Lang } from '../i18n/ui';
 
 interface Props {
   slugs: string[] | string;
@@ -21,7 +21,7 @@ const list = Array.isArray(slugs)
       .map((s) => s.trim())
       .filter(Boolean);
 
-const lang: Lang = Astro.currentLocale === 'ko' ? 'ko' : 'en';
+const lang: Lang = (Astro.currentLocale ?? defaultLang) as Lang;
 const stacks = await getStacks(lang);
 const bySlug = new Map(stacks.map((s) => [slugOf(s), s]));
 const tools = list.map((s) => bySlug.get(s)).filter(Boolean) as StackEntry[];

package/src/components/LanguageSwitcher.astro

@@ -1,7 +1,6 @@
 ---
 import { getRelativeLocaleUrl } from 'astro:i18n';
-import ChevronDown from './ChevronDown.astro';
-import { languages, type Lang } from '../i18n/ui';
+import { languages, useTranslations, type Lang } from '../i18n/ui';
 
 interface Props {
   lang: Lang;
@@ -10,17 +9,18 @@ interface Props {
 }
 
 const { lang, path } = Astro.props;
+const t = useTranslations(lang);
 const codes = Object.keys(languages) as Lang[];
 ---
 
 <details class="aas-lang">
   <summary
-    class="flex cursor-pointer list-none items-center gap-1 rounded-lg border border-[var(--aas-border)] px-2.5 py-1 whitespace-nowrap text-[var(--aas-text)] select-none"
+    class="flex cursor-pointer list-none items-center rounded-lg border border-[var(--aas-border)] px-2.5 py-1 text-[var(--aas-text)] select-none"
+    aria-label={t('nav.language')}
+    title={t('nav.language')}
   >
-    {/* Compact language code on mobile; full name from the `sm` breakpoint up. */}
-    <span class="sm:hidden">{lang.toUpperCase()}</span>
-    <span class="hidden sm:inline">{languages[lang]}</span>
-    <ChevronDown class="text-[var(--aas-muted)]" />
+    {/* A globe stands in for the current language; the dropdown lists names. */}
+    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><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"/></svg>
   </summary>
   <ul
     class="absolute right-0 z-10 mt-1 min-w-[8rem] overflow-hidden rounded-lg border border-[var(--aas-border)] bg-[var(--aas-panel)] py-1 shadow-lg"

package/src/components/PageDetail.astro

@@ -0,0 +1,52 @@
+---
+import { render } from 'astro:content';
+import { Image } from 'astro:assets';
+import type { PageEntry } from '../lib/pages';
+import type { Lang } from '../i18n/ui';
+import { inlineMd } from '../lib/inline-md';
+import TocRail from './TocRail.astro';
+import MermaidLoader from './MermaidLoader.astro';
+
+interface Props {
+  entry: PageEntry;
+  lang: Lang;
+}
+
+const { entry, lang } = Astro.props;
+const { Content, headings } = await render(entry);
+const data = entry.data;
+const tocItems = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+// A standalone page (and any <SampleProject/> README it embeds) may use Mermaid;
+// load the client renderer only when the body actually does.
+const bodyHasMermaid = (entry.body ?? '').includes('```mermaid');
+---
+
+<header class="pb-6">
+  <h1 class="text-3xl font-bold tracking-tight">{data.title}</h1>
+  {
+    data.description && (
+      <p
+        class="mt-2 aas-md text-lg whitespace-pre-line text-[var(--aas-muted)]"
+        set:html={inlineMd(data.description)}
+      />
+    )
+  }
+  {
+    data.image && (
+      <Image
+        src={data.image}
+        alt={data.imageAlt ?? data.title}
+        class="mt-5 aspect-[2/1] w-full rounded-2xl border border-[var(--aas-border)] object-cover"
+      />
+    )
+  }
+</header>
+
+<div class="mt-4 flex items-start gap-8">
+  <article class="prose max-w-none aas-reading min-w-0 flex-1">
+    <Content />
+  </article>
+  <TocRail lang={lang} items={tocItems} />
+</div>
+
+{bodyHasMermaid && <MermaidLoader />}

package/src/components/ProjectViewer.astro

@@ -1,5 +1,5 @@
 ---
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, dateLocaleOf, type Lang } from '../i18n/ui';
 import type { RenderedProject } from '../lib/project';
 import ChevronDown from './ChevronDown.astro';
 import ProjectFileList from './ProjectFileList.astro';
@@ -32,7 +32,7 @@ function splitReadme(html?: string): { titleInner?: string; body?: string } {
 function formatDate(iso: string): string {
   const [y, m, d] = iso.split('-').map(Number);
   if (!y || !m || !d) return iso;
-  return new Intl.DateTimeFormat(lang === 'ko' ? 'ko-KR' : 'en-US', {
+  return new Intl.DateTimeFormat(dateLocaleOf(lang), {
     year: 'numeric',
     month: 'long',
     day: 'numeric',

package/src/components/SampleIndex.astro

@@ -10,7 +10,7 @@ import ChevronDown from './ChevronDown.astro';
 import { listProjects } from '../lib/project';
 import { getStacks, slugOf } from '../lib/stacks';
 import { getArticles } from '../lib/articles';
-import { useTranslations, type Lang } from '../i18n/ui';
+import { useTranslations, dateLocaleOf, type Lang } from '../i18n/ui';
 
 interface Props {
   lang: Lang;
@@ -76,7 +76,7 @@ const scopeOptions = [
 function formatDate(iso: string): string {
   const [y, m, d] = iso.split('-').map(Number);
   if (!y || !m || !d) return iso;
-  return new Intl.DateTimeFormat(lang === 'ko' ? 'ko-KR' : 'en-US', {
+  return new Intl.DateTimeFormat(dateLocaleOf(lang), {
     year: 'numeric',
     month: 'long',
     day: 'numeric',