stack-site-builder 1.24.0 → 1.25.0

package/CHANGELOG.md

@@ -11,6 +11,55 @@ 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 —
@@ -520,6 +569,7 @@ catalog sites from a thin content-only repository.
 - **Standalone development setup** — a devcontainer and a minimal `playground/`
   consuming site for developing and previewing the theme on its own.
 
+[1.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

package/README.md

@@ -218,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.24.0",
+  "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/layouts/BaseLayout.astro

@@ -1,5 +1,13 @@
 ---
 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, siteName, defaultLang, type Lang } from '../i18n/ui';

package/src/styles/global.css

@@ -866,6 +866,46 @@ summary {
   background: color-mix(in srgb, var(--aas-panel) 45%, transparent);
 }
 
+/* Math (`$$…$$`, rendered to HTML + MathML at build time by rehype-katex).
+   KaTeX draws everything in `currentColor`, so it picks up the theme — and the
+   dark/light swap — with no palette work here. What it does NOT do is stay
+   inside its column: a long derivation is one unbreakable line, so the same
+   argument as `.aas-table-scroll` applies and the display block takes the
+   scroll. The vertical padding is what makes that safe — `overflow-x: auto`
+   promotes `overflow-y` to `auto` unless it is pinned, and pinning it to
+   `hidden` would shave the top of a tall fraction or the tail of a descender. */
+.katex-display {
+  max-width: 100%;
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: contain;
+  padding: 0.5em 0;
+}
+/* Inline math sits in running text, so it must not introduce its own scrollbar
+   or stretch the line box; KaTeX's 1.21em default is a touch large next to our
+   body size. */
+.prose .katex {
+  font-size: 1.1em;
+}
+/* KaTeX's fonts carry no Hangul, kana or Han glyphs, so for `\text{처리량}` it
+   tags the run with `.hangul_fallback` (or `.cjk_fallback` / `.brahmic_fallback`)
+   and ships NO rule for them — the font is left to the site on purpose. Without
+   one the run falls through KaTeX_Main to whatever the browser picks next, which
+   renders Korean loose and letterform-mismatched beside the prose it sits in.
+   Hand it the site stack (Pretendard first) so math text matches body text. */
+.katex .hangul_fallback,
+.katex .cjk_fallback,
+.katex .brahmic_fallback {
+  font-family: var(--aas-sans);
+}
+/* A formula KaTeX could not parse. A production build fails on one (see
+   `rehypeMathErrors` in markdown.mjs), so this only ever shows in a dev server,
+   where being loud is exactly the point. */
+.katex-error {
+  color: var(--aas-role-guard);
+  border-bottom: 1px dotted currentColor;
+}
+
 /* ── Listing density: gallery (compact mini-cards) ───────────────────────────
    Toggled by [data-view='gallery'] on <html> (persisted in localStorage). A
    denser grid plus a stripped-down card — logo, name, stars, pricing, and a