@brandon_m_behring/book-scaffold-astro 4.8.0 → 4.9.0

package/CLAUDE.md

@@ -25,6 +25,8 @@ When in doubt, run `grep BOOK_PROFILE .env astro.config.mjs src/content.config.t
 
 ## Frontmatter schemas
 
+**Universal field (v4.9.0):** every profile accepts an optional `slug:` string that overrides the URL. A file `99-appendix.mdx` with `slug: appendix` is served at `/chapters/appendix/` — Astro's glob loader maps frontmatter `slug` → `entry.id`, and cross-references (`<XRef>`, via `build-labels`) resolve to the same path. Omit it and the URL falls back to the filename. Use it to keep numbered filenames for ordering while publishing clean URLs.
+
 ### Academic profile (`src/content.config.ts:academicChapterSchema`)
 
 ```yaml
@@ -34,6 +36,7 @@ part: foundations        # required: foundations|ssm-core|beyond-ssm|integration
 title: "..."             # string, required
 status: implemented      # required: implemented|chapter_only|prose_only|code_only|reading_only|scaffolded|planned
 # optional:
+slug: ch01-introduction  # clean URL override; else filename → /chapters/<slug>/
 roadmap_lines: [10, 42]  # [start, end] line refs into roadmap.md
 code_path: experiments/jax/week01/foo.py
 tests_path: experiments/jax/week01/test_foo.py
@@ -54,7 +57,7 @@ volatility: architectural-pattern  # required: stable-principle|architectural-pa
 tools_compared: [claude-code]      # required, ≥1 of: claude-code|gemini-cli|codex-cli|cross-tool
 last_verified: 2026-05-18          # date, required
 sources: []                        # array of source-manifest keys
-# optional: description, draft, updated
+# optional: slug (clean URL override), description, draft, updated
 ---
 ```
 

package/components/XRef.astro

@@ -1,28 +1,31 @@
 ---
-/**
- * XRef — resolves a `\cref{label}` LaTeX reference to a hyperlink.
- *
- * Reads src/data/labels.json built by scripts/build-labels.mjs
- * (Phase 2.6). For each known id, the map provides:
- *   { href: "/chapters/week04#thm-w4-stability", display: "Theorem 4.2" }
- *
- * Runtime: renders `<a href>` for known ids; renders an inline `[?id]`
- * placeholder for unknown ids so the Astro dev server stays running while
- * chapters are being authored or labels are being added.
- *
- * CI: `book-scaffold validate` (Phase 2.6, shipped) catches unknown ids
- * and **fails the build with a non-zero exit code** before unresolved
- * placeholders can reach production. The placeholder is a dev-ergonomic
- * affordance, not a soft-degradation path on the deploy critical line.
- *
- * Bootstrapping note: when porting a book chapter-by-chapter, early
- * chapters that reference yet-to-be-ported targets need either plain-prose
- * substitutes or a temporarily-commented `{/* <XRef …/> */}` until the
- * target chapter (and its `id="…"` attributes) exists.
- *
- * Usage:
- *   By <XRef id="thm:w4:stability" />, the discretized eigenvalues …
- */
+// XRef — resolves a `\cref{label}` LaTeX reference to a hyperlink.
+//
+// Reads src/data/labels.json built by scripts/build-labels.mjs
+// (Phase 2.6). For each known id, the map provides:
+//   { href: "/chapters/week04#thm-w4-stability", display: "Theorem 4.2" }
+//
+// Runtime: renders `<a href>` for known ids; renders an inline `[?id]`
+// placeholder for unknown ids so the Astro dev server stays running while
+// chapters are being authored or labels are being added.
+//
+// CI: `book-scaffold validate` (Phase 2.6, shipped) catches unknown ids
+// and **fails the build with a non-zero exit code** before unresolved
+// placeholders can reach production. The placeholder is a dev-ergonomic
+// affordance, not a soft-degradation path on the deploy critical line.
+//
+// Bootstrapping note: when porting a book chapter-by-chapter, early
+// chapters that reference yet-to-be-ported targets need either plain-prose
+// substitutes or a temporarily-commented `{/* <XRef …/> */}` until the
+// target chapter (and its `id="…"` attributes) exists. MDX uses JSX-style
+// expression comments — the HTML `<` + bang + `--` form is NOT valid MDX.
+//
+// NB: these are `//` line comments, not a `/** */` block, on purpose — the
+// literal `*/` in the example above would otherwise close a block comment
+// early and break esbuild on every MDX import (the v4.9.0 fix).
+//
+// Usage:
+//   By <XRef id="thm:w4:stability" />, the discretized eigenvalues …
 type LabelEntry = { href: string; display: string };
 
 // Resolve labels.json from the consumer's project root (Vite resolves `/`

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, o as Style } from './types-DTQ2l6B6.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, r as academicParts, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-DTQ2l6B6.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, o as Style } from './types-CULHImU4.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, r as academicParts, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CULHImU4.js';
 import 'astro/zod';
 
 /**

package/dist/index.mjs

@@ -184,6 +184,8 @@ var academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -203,6 +205,8 @@ var academicChapterSchema = z.object({
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -226,6 +230,8 @@ var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
 var courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-DTQ2l6B6.js';
+import { g as BookSchemasOptions } from './types-CULHImU4.js';
 import 'astro';
 import 'astro/zod';
 

package/dist/schemas.mjs

@@ -68,6 +68,8 @@ var academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -87,6 +89,8 @@ var academicChapterSchema = z.object({
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -110,6 +114,8 @@ var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
 var courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
+  slug: z.string().optional(),
+  // v4.9.0: explicit URL slug override (else filename → entry.id)
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/scripts/build-labels.mjs

@@ -15,10 +15,11 @@
  *   - tools profile: `chapter` field (number).
  *   - academic profile: `week` field (number).
  *
- * Slug used for the href = filename minus `.mdx`. The href shape mirrors
- * the consumer's pages router: `/chapters/<slug>#<id>`. Academic books
- * using `[...slug].astro` get the same shape since Astro slugifies
- * filenames identically.
+ * Slug used for the href: the chapter's frontmatter `slug:` if set,
+ * else filename minus `.mdx`. The href shape mirrors the consumer's pages
+ * router: `/chapters/<slug>#<id>`. Academic books using `[...slug].astro`
+ * get the same shape since Astro slugifies filenames identically when no
+ * frontmatter override is present.
  *
  * Optional override:
  *   <Theorem id="…" label="Custom display" />
@@ -178,7 +179,9 @@ async function main() {
     const source = await readFile(file, 'utf8');
     const fm = parseFrontmatter(source);
     const chapterNum = chapterNumberOf(fm);
-    const slug = basename(file).replace(/\.mdx?$/, '');
+    const slug = (typeof fm.slug === 'string' && fm.slug.length > 0)
+      ? fm.slug
+      : basename(file).replace(/\.mdx?$/, '');
 
     // Per-chapter counters reset for each file.
     const counters = {};

package/src/schemas.ts

@@ -116,6 +116,7 @@ export const academicChapterSchema = z.object({
   week: z.number().int().min(1).max(99),
   part: z.enum(academicParts),
   title: z.string().min(1),
+  slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -136,6 +137,7 @@ export const academicChapterSchema = z.object({
 
 export const toolsChapterSchema = z.object({
   title: z.string().min(1),
+  slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -178,6 +180,7 @@ export const sourceTiersResearch = ['T1', 'T2', 'T3', 'T4'] as const;
 export const courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
+  slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),