npm - stack-site-builder - Versions diffs - 1.24.0 → 1.25.1 - Mend

stack-site-builder 1.24.0 → 1.25.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md +67 -0
package/README.md +1 -1
package/index.d.ts +8 -0
package/index.mjs +6 -2
package/markdown.mjs +61 -6
package/package.json +4 -1
package/src/components/DeckView.astro +6 -0
package/src/layouts/BaseLayout.astro +11 -0
package/src/styles/global.css +42 -0

package/CHANGELOG.md CHANGED Viewed

@@ -11,6 +11,72 @@ 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.1] - 2026-08-31
+### Fixed
+- **Math in a slide deck rendered twice** — a deck is the one route that does
+  not go through `BaseLayout`; `DeckView.astro` renders the whole `<html>`
+  itself, so it never picked up the layout's `katex.min.css` import. Without
+  that stylesheet the MathML copy rehype-katex emits for screen readers loses
+  the rule that clips it out of view, and every formula showed up twice: once
+  as unstyled MathML source and once as the real KaTeX drawing beside it. The
+  deck now imports the stylesheet too, and `sample-layouts` gained a Math
+  section so the deck path is covered the way the article path already was.
+- **Inline math in a slide was oversized** — the `font-size: 1.1em` that trims
+  KaTeX's 1.21em default was scoped to `.prose`, which a slide is not. It now
+  applies under `.aas-slide-inner` as well, so a formula mid-sentence matches
+  the text around it on a slide the same as in an article.
+## [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 +586,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.24.0",
+  "version": "1.25.1",
   "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/DeckView.astro CHANGED Viewed

@@ -1,5 +1,11 @@
 ---
 import '../styles/global.css';
+// A deck is its own document root (this component renders the whole <html>), so
+// it does not inherit BaseLayout's stylesheet imports and needs KaTeX's own
+// stylesheet here as well. Without it the MathML copy that rehype-katex emits
+// for screen readers loses the rule that hides it and renders as a second,
+// unstyled formula beside the real one.
+import 'katex/dist/katex.min.css';
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import { render, type CollectionEntry } from 'astro:content';
 import MermaidLoader from './MermaidLoader.astro';

package/src/layouts/BaseLayout.astro CHANGED Viewed

@@ -1,5 +1,16 @@
 ---
 import '../styles/global.css';
+// KaTeX's stylesheet, loaded for every page under this layout 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. DeckView.astro is the one route that bypasses this layout
+// (a deck renders its own <html>), so it repeats the import.
+// 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 CHANGED Viewed

@@ -866,6 +866,48 @@ 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. A slide is not `.prose` — it carries its own type scale — but the
+   same mismatch shows up there, so both roots get the rule. */
+.prose .katex,
+.aas-slide-inner .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