stack-site-builder 1.23.0 → 1.23.2

package/CHANGELOG.md

@@ -11,6 +11,50 @@ 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.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
+
+- **Prose blockquote styling** — `>` blockquotes in reading content (courses,
+  articles, concepts, stacks and standalone pages) rendered with the browser
+  default and were nearly indistinguishable from a normal paragraph. They now
+  get a left accent rail and a faint neutral fill so a pulled-out passage reads
+  as set apart. Light/dark-aware (theme tokens), and no italic so it renders
+  cleanly on Korean prose. Two-trailing-space hard breaks inside the quote are
+  preserved as before.
+
 ## [1.23.0] - 2026-07-27
 
 ### Added
@@ -421,6 +465,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.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
 [1.19.2]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.19.1...v1.19.2

package/README.md

@@ -202,6 +202,9 @@ import Bookmark from 'stack-site-builder/components/Bookmark.astro';
 <Bookmark url="https://…" title="…" description="…" />
 ```
 
+Markdown/MDX authoring gotchas (nested-list indentation, blockquotes, hard
+breaks, wikilinks): `docs/content-authoring.md`.
+
 ## RSS
 
 The articles collection feeds `/rss.xml` (default locale) and

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.0",
+  "version": "1.23.2",
   "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/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/project.ts

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { createHighlighter, type Highlighter } from 'shiki';
 import MarkdownIt from 'markdown-it';
+import { withTableScroll } from './md-tables';
 import { site } from '@aas-data/site';
 
 const SAMPLES_DIR = 'samples';
@@ -240,17 +241,19 @@ export async function renderProjects(folders: string[], lang: string): Promise<R
   const hl = await getHighlighter();
   const escapeHtml = (s: string) =>
     s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-  const md = new MarkdownIt({
-    html: false,
-    linkify: true,
-    highlight: (code, info) => {
-      const lang = (info || '').trim() || 'text';
-      // Hand mermaid blocks to the client-side MermaidLoader instead of Shiki,
-      // so README diagrams render as graphics rather than highlighted text.
-      if (lang === 'mermaid') return `<pre class="mermaid">${escapeHtml(code)}</pre>`;
-      return highlight(hl, code, lang);
-    },
-  });
+  const md = withTableScroll(
+    new MarkdownIt({
+      html: false,
+      linkify: true,
+      highlight: (code, info) => {
+        const lang = (info || '').trim() || 'text';
+        // Hand mermaid blocks to the client-side MermaidLoader instead of Shiki,
+        // so README diagrams render as graphics rather than highlighted text.
+        if (lang === 'mermaid') return `<pre class="mermaid">${escapeHtml(code)}</pre>`;
+        return highlight(hl, code, lang);
+      },
+    }),
+  );
   // README links open in a new tab.
   const baseLink = md.renderer.rules.link_open ?? ((t, i, o, _e, s) => s.renderToken(t, i, o));
   md.renderer.rules.link_open = (tokens, idx, opts, env, self) => {

package/src/lib/samples.ts

@@ -1,7 +1,8 @@
 import { codeToHtml } from 'shiki';
 import MarkdownIt from 'markdown-it';
+import { withTableScroll } from './md-tables';
 
-const md = new MarkdownIt({ html: false, linkify: true });
+const md = withTableScroll(new MarkdownIt({ html: false, linkify: true }));
 
 export interface SampleHeading {
   slug: string;

package/src/styles/global.css

@@ -379,8 +379,9 @@ html[lang='ko'] h1 {
 }
 /* Doc tables: a touch larger, centered (shrink-to-content), roomier cells, and
    a full-row hover highlight. `fit-content` + `margin-inline: auto` centers the
-   table block while `max-width`/overflow (from the base .prose rule) keep it
-   scrollable if it ever outgrows the column. */
+   table block. When the table sits in a `.aas-table-scroll` wrapper (the normal
+   case — see below) the centering moves to the wrapper and the table keeps its
+   natural column widths instead. */
 .aas-reading.aas-reading :where(table) {
   display: table;
   width: fit-content;
@@ -581,6 +582,24 @@ summary {
   list-style: decimal;
   padding-left: 1.25rem;
 }
+/* Blockquotes — a quiet left-accent rail with a faint neutral fill, so a
+   pulled-out passage reads as set apart from the running text. No italic: it
+   renders on Korean prose too, where slanted CJK looks wrong. First/last child
+   margins collapse so the quote hugs its own padding. */
+.prose :where(blockquote) {
+  margin: 1.25rem 0;
+  padding: 0.75rem 1.15rem;
+  border-left: 3px solid var(--aas-accent);
+  border-radius: 0 0.5rem 0.5rem 0;
+  background: var(--aas-tint);
+  color: color-mix(in srgb, var(--aas-text) 88%, transparent);
+}
+.prose :where(blockquote > :first-child) {
+  margin-top: 0;
+}
+.prose :where(blockquote > :last-child) {
+  margin-bottom: 0;
+}
 .prose :where(a) {
   color: var(--aas-accent);
   text-decoration: none;
@@ -709,6 +728,18 @@ summary {
   margin-inline: auto;
 }
 
+/* Mermaid draws its labels as real HTML inside <foreignObject> and sizes nodes
+   and subgraph frames from the measured box. Mermaid 11 wraps label text in a
+   <p>, which then inherits the PAGE's paragraph typography — on a slide that is
+   26px/41px, while mermaid only reserves ~25px for a subgraph title, so every
+   subgraph title overlapped the first node inside it by ~16px. Pin label
+   typography back to mermaid's own so its measurements hold. */
+.mermaid foreignObject p {
+  margin: 0;
+  font-size: inherit;
+  line-height: inherit;
+}
+
 /* Mermaid theme: rounded corners + soft pastel fills, derived from the site
    accent so it adapts to light/dark. `!important` overrides Mermaid's own
    id-scoped <style> block. Applies wherever a diagram renders (prose + samples). */
@@ -776,7 +807,10 @@ summary {
 }
 
 
-/* Markdown tables — without these, columns collapse together. */
+/* Markdown tables — without these, columns collapse together. This is also the
+   fallback for a table that reaches the page WITHOUT the scroll wrapper below
+   (raw HTML in MDX, say): `display: block` + `overflow-x` at least keeps it
+   from pushing the page sideways. */
 .prose :where(table) {
   width: 100%;
   border-collapse: collapse;
@@ -785,6 +819,39 @@ summary {
   display: block;
   overflow-x: auto;
 }
+
+/* Horizontal scroll box wrapped around every rendered table — by
+   `rehypeTableScroll` (markdown.mjs) for content collections, and by
+   `withTableScroll` (lib/md-tables.ts) for READMEs and sample descriptions.
+   A table cannot scroll itself: it needs `display: table` for real column
+   sizing, which makes `overflow-x` on the table a no-op, so a table wider than
+   its column had no escape but to wrap every cell — a 120px-tall table became
+   430px of cramped text. The wrapper takes the scrolling; the table gets its
+   natural column widths back (`max-content`, floored at the column width so a
+   narrow table still fills it). */
+.aas-table-scroll {
+  max-width: 100%;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  margin: 1.25rem 0;
+}
+.aas-table-scroll > table {
+  display: table;
+  width: max-content;
+  min-width: 100%;
+  margin: 0;
+}
+/* In a reading column the wrapper shrinks to the table and centers, so a table
+   narrower than the column keeps its own width rather than being stretched. */
+.aas-reading.aas-reading .aas-table-scroll {
+  width: fit-content;
+  margin-inline: auto;
+}
+.aas-reading.aas-reading .aas-table-scroll > table {
+  min-width: 0;
+  max-width: none;
+  margin-inline: 0;
+}
 .prose :where(th, td) {
   border: 1px solid var(--aas-border);
   padding: 0.55rem 0.85rem;
@@ -1253,13 +1320,25 @@ summary {
   color: var(--aas-muted);
 }
 
-/* Tables */
+/* Tables. Same deal as prose tables: the `.aas-table-scroll` wrapper does the
+   scrolling, so a wide table slides sideways instead of cramming its cells. */
+.aas-slide-inner .aas-table-scroll {
+  width: 100%;
+  margin: 0.5em 0;
+}
 .aas-slide-inner table {
   width: 100%;
   border-collapse: collapse;
   font-size: clamp(0.9rem, 1.5vw, 1.25rem);
   margin: 0.5em 0;
 }
+/* Declared after `.aas-slide-inner table` so the wrapped form wins: full column
+   width normally, natural width (scrolling) once the table outgrows the slide. */
+.aas-slide-inner .aas-table-scroll > table {
+  width: max-content;
+  min-width: 100%;
+  margin: 0;
+}
 .aas-slide-inner th,
 .aas-slide-inner td {
   text-align: left;
@@ -1510,6 +1589,38 @@ summary {
 /* 3b) Code stays pinned to the top of its filled box — that's the default block
        flow of a tall <pre>, so nothing extra is needed. */
 
+/* 3c) Size the diagram against the box it was just given, not a fixed viewport
+       fraction. The generic caps (`pre` 62vh, svg 52vh) don't know how much room
+       the fill rules actually handed over — on a full-height slide that box is
+       ~78vh, so a tall flowchart rendered at a THIRD of its size with the unused
+       height letterboxed as empty margins either side. The box already has a
+       definite height here, so `100%` resolves against it; the svg's viewBox
+       does the rest (it scales to fit and centers itself). Excludes the layouts
+       that deliberately manage their own overflow: `compact` (natural size),
+       `.aas-split.scroll` (vertical scroll box) and `scroll-x` (horizontal). */
+.aas-slide:not(.compact):not(.scroll-x) .aas-slide-inner > .aas-diagram > pre.mermaid,
+.aas-slide:not(.compact):not(.scroll-x)
+  .aas-slide-inner
+  > .aas-split:not(.scroll)
+  > .aas-diagram
+  > pre.mermaid {
+  flex: 1 1 0;
+  min-height: 0;
+  max-height: 100%;
+  width: 100%;
+}
+.aas-slide:not(.compact):not(.scroll-x) .aas-slide-inner > .aas-diagram > pre.mermaid > svg,
+.aas-slide:not(.compact):not(.scroll-x)
+  .aas-slide-inner
+  > .aas-split:not(.scroll)
+  > .aas-diagram
+  > pre.mermaid
+  > svg {
+  width: 100%;
+  height: 100%;
+  max-height: 100%;
+}
+
 /* Scrollable diagram (`<div class="aas-split scroll">`): the diagram column is a
    fixed-height scroll box (opted out of the fill rules above) and the diagram
    fits the column width, so a tall/complex flowchart scrolls vertically next to