@brandon_m_behring/book-scaffold-astro 4.5.0 → 4.6.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-DLIpEgTm.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, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-DLIpEgTm.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-B2bO9Nga.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, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-B2bO9Nga.js';
 import 'astro/zod';
 
 /**

package/dist/index.mjs

@@ -117,6 +117,7 @@ var init_katex_macros = __esm({
 // src/config.ts
 import mdx from "@astrojs/mdx";
 import preact from "@astrojs/preact";
+import sitemap from "@astrojs/sitemap";
 
 // src/profile-kit.ts
 function defineProfile(p) {
@@ -177,7 +178,14 @@ var academicChapterSchema = z.object({
   tests_path: z.string().optional(),
   notebook_path: z.string().optional(),
   description: z.string().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // All optional; existing chapters without these continue to work.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
@@ -189,7 +197,13 @@ var toolsChapterSchema = z.object({
   sources: z.array(z.string()).default([]),
   description: z.string().optional(),
   draft: z.boolean().default(false),
-  updated: z.date().optional()
+  updated: z.date().optional(),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `updated` already existed; the rest are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var minimalChapterSchema = toolsChapterSchema;
 var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
@@ -216,7 +230,14 @@ var courseNotesChapterSchema = z.object({
   last_verified: z.date(),
   volatility: z.enum(volatilityLevels).default("architectural-pattern"),
   sources: z.array(z.string()).default([]),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` already existed; the rest are new. `instructor` (line 130) is
+  // attribution metadata — distinct from `author` (the note-writer/curator).
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  image: z.string().optional()
 });
 var researchPortfolioChapterSchema = z.object({
   // Identity
@@ -269,7 +290,12 @@ var researchPortfolioChapterSchema = z.object({
   // Status + dates.
   last_verified: z.date(),
   updated: z.date().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` + `updated` already existed; `author` + `published` + `image` are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  image: z.string().optional()
 });
 var sourcesSchema = z.object({
   url: z.string().url(),
@@ -387,8 +413,11 @@ var academicProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
-  chaptersRenderer: academicChaptersRenderer
+  chaptersRenderer: academicChaptersRenderer,
   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Academic-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/lib/freshness.ts
@@ -616,7 +645,10 @@ var courseNotesProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
-  chaptersRenderer: fallbackChaptersRenderer
+  chaptersRenderer: fallbackChaptersRenderer,
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Course-notes-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/profiles/research-portfolio.ts
@@ -824,6 +856,23 @@ function defineMdxComponents(components) {
 }
 
 // src/integration.ts
+var BOOK_CONFIG_VIRTUAL_ID = "virtual:book-scaffold/book-config";
+var BOOK_CONFIG_RESOLVED_ID = "\0" + BOOK_CONFIG_VIRTUAL_ID;
+function makeBookConfigVitePlugin(config) {
+  const serialized = `export default ${JSON.stringify(config)};`;
+  return {
+    name: "book-scaffold:book-config",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === BOOK_CONFIG_VIRTUAL_ID) return BOOK_CONFIG_RESOLVED_ID;
+      return null;
+    },
+    load(id) {
+      if (id !== BOOK_CONFIG_RESOLVED_ID) return null;
+      return serialized;
+    }
+  };
+}
 var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
 var ROUTE_REGISTRY = {
   references: { pattern: "/references", file: "references.astro" },
@@ -870,10 +919,14 @@ function bookScaffoldIntegration(opts) {
     routes: userOverrides = {},
     extraStyles = [],
     mdxComponentsModule,
-    // v4.5.0: landing-page data, propagated via vite.define to /index.astro.
+    // v4.5.0: landing-page data, propagated via virtual module to /index.astro.
     title,
     description,
-    portfolio
+    portfolio,
+    // v4.6.0: book-level author + SEO config, propagated through the
+    // (renamed) book-config virtual module to Base.astro + Chapter.astro.
+    author,
+    seo
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -918,17 +971,27 @@ function bookScaffoldIntegration(opts) {
         const enabledRouteNames = Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name);
         updateConfig({
           vite: {
-            plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)],
+            plugins: [
+              makeMdxComponentsVitePlugin(resolvedMdxPath),
+              makeBookConfigVitePlugin({
+                title: title ?? null,
+                description: description ?? null,
+                portfolio: portfolio ?? false,
+                enabledRoutes: enabledRouteNames,
+                author: author ?? null,
+                seo: {
+                  ogImage: seo?.ogImage ?? null,
+                  twitterHandle: seo?.twitterHandle ?? null
+                }
+              })
+            ],
             define: {
+              // Preset/profile stay as env vars — preference-flag pattern where
+              // env-based override IS the convention (resolvePreset reads from
+              // process.env / .env explicitly). Config values (title, etc.) now
+              // route through the virtual module above to avoid that override.
               "import.meta.env.BOOK_PRESET": presetLiteral,
-              "import.meta.env.BOOK_PROFILE": presetLiteral,
-              // v4.5.0: landing-page data. JSON.stringify on undefined → 'undefined'
-              // (which evaluates to JavaScript undefined at use site); on object →
-              // the JSON literal; on false → 'false'.
-              "import.meta.env.BOOK_TITLE": JSON.stringify(title ?? null),
-              "import.meta.env.BOOK_DESCRIPTION": JSON.stringify(description ?? null),
-              "import.meta.env.BOOK_PORTFOLIO": JSON.stringify(portfolio ?? null),
-              "import.meta.env.BOOK_ROUTES_ENABLED": JSON.stringify(enabledRouteNames)
+              "import.meta.env.BOOK_PROFILE": presetLiteral
             }
           }
         });
@@ -1023,19 +1086,36 @@ async function defineBookConfig(opts) {
     ]);
   }
   const resolvedPortfolio = opts.portfolio === false ? false : opts.portfolio ?? BRANDON_PORTFOLIO_DEFAULT;
+  const profileSitemapFilter = PROFILES[profile]?.sitemapFilter;
+  const sitemapFilter = opts.seo?.sitemap?.filter ?? profileSitemapFilter;
+  const sitemapCustomPages = opts.seo?.sitemap?.customPages;
+  const sitemapOptions = {};
+  if (sitemapFilter) sitemapOptions.filter = sitemapFilter;
+  if (sitemapCustomPages) sitemapOptions.customPages = sitemapCustomPages;
   const integrations = [
     mdx(),
     preact(),
+    // v4.6.0: @astrojs/sitemap default integration. Emits
+    // /sitemap-index.xml + per-route sitemaps from the resolved `site:`
+    // (defineBookConfig throws above if site is missing, so the URL is
+    // always available to the sitemap integration here).
+    sitemap(sitemapOptions),
     bookScaffoldIntegration({
       profile,
       routes: mergedRoutes,
       mdxComponentsModule,
       extraStyles: mergedExtraStyles,
       // v4.5.0: pass landing-page data through to the integration so it can
-      // be exposed to the auto-injected /index.astro via vite.define.
+      // be exposed to the auto-injected /index.astro via the virtual module.
       title: opts.title,
       description: opts.description,
-      portfolio: resolvedPortfolio
+      portfolio: resolvedPortfolio,
+      // v4.6.0: book-level author + SEO config (ogImage, twitterHandle),
+      // propagated through the renamed `book-config` virtual module to
+      // Base.astro + Chapter.astro. `seo.sitemap` is NOT passed through —
+      // it's consumed below at config-time by the @astrojs/sitemap call.
+      author: opts.author,
+      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0
     }),
     ...mergedExtraIntegrations
   ];
@@ -1074,6 +1154,9 @@ async function defineBookConfig(opts) {
     title: _title,
     description: _description,
     portfolio: _portfolio,
+    // v4.6.0: strip new book-level SEO opts (author + seo block).
+    author: _author,
+    seo: _seo,
     ...rest
   } = opts;
   void _styles;
@@ -1088,6 +1171,8 @@ async function defineBookConfig(opts) {
   void _title;
   void _description;
   void _portfolio;
+  void _author;
+  void _seo;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const config = {
     site,

package/dist/schemas.d.ts

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

package/dist/schemas.mjs

@@ -62,7 +62,14 @@ var academicChapterSchema = z.object({
   tests_path: z.string().optional(),
   notebook_path: z.string().optional(),
   description: z.string().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // All optional; existing chapters without these continue to work.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
@@ -74,7 +81,13 @@ var toolsChapterSchema = z.object({
   sources: z.array(z.string()).default([]),
   description: z.string().optional(),
   draft: z.boolean().default(false),
-  updated: z.date().optional()
+  updated: z.date().optional(),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `updated` already existed; the rest are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var minimalChapterSchema = toolsChapterSchema;
 var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
@@ -101,7 +114,14 @@ var courseNotesChapterSchema = z.object({
   last_verified: z.date(),
   volatility: z.enum(volatilityLevels).default("architectural-pattern"),
   sources: z.array(z.string()).default([]),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` already existed; the rest are new. `instructor` (line 130) is
+  // attribution metadata — distinct from `author` (the note-writer/curator).
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  image: z.string().optional()
 });
 var researchPortfolioChapterSchema = z.object({
   // Identity
@@ -154,7 +174,12 @@ var researchPortfolioChapterSchema = z.object({
   // Status + dates.
   last_verified: z.date(),
   updated: z.date().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` + `updated` already existed; `author` + `published` + `image` are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  image: z.string().optional()
 });
 var sourcesSchema = z.object({
   url: z.string().url(),
@@ -272,8 +297,11 @@ var academicProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
-  chaptersRenderer: academicChaptersRenderer
+  chaptersRenderer: academicChaptersRenderer,
   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Academic-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/lib/freshness.ts
@@ -501,7 +529,10 @@ var courseNotesProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
-  chaptersRenderer: fallbackChaptersRenderer
+  chaptersRenderer: fallbackChaptersRenderer,
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Course-notes-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/profiles/research-portfolio.ts

package/layouts/Base.astro

@@ -50,6 +50,10 @@ import '../styles/print.css';
 import VersionSelector from '@brandon_m_behring/book-scaffold-astro/components/VersionSelector';
 import ToolFilter from '@brandon_m_behring/book-scaffold-astro/components/ToolFilter';
 import Sidebar from '../components/Sidebar.astro';
+// v4.6.0: SEO meta tags read book-level identity (title fallback,
+// description fallback, ogImage default, twitterHandle) from the
+// book-config virtual module (was landing-config in v4.5.1).
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
 const showToolsChrome = profile !== 'academic';
@@ -59,9 +63,37 @@ interface Props {
   description?: string;
   lang?: string;
   showSidebar?: boolean;
+  /** v4.6.0: Open Graph image URL (relative to site root, or absolute). */
+  ogImage?: string;
+  /** v4.6.0: Open Graph type. Defaults to 'website'; Chapter.astro passes 'article'. */
+  ogType?: string;
 }
 
-const { title, description, lang = 'en', showSidebar = true } = Astro.props;
+const {
+  title,
+  description,
+  lang = 'en',
+  showSidebar = true,
+  ogImage,
+  ogType = 'website',
+} = Astro.props;
+
+// v4.6.0: canonical + og:url need Astro.site. defineBookConfig throws at
+// config-load if `site` is missing, so Astro.site is guaranteed populated
+// here. `new URL` resolves the relative pathname against it.
+const canonicalURL = new URL(Astro.url.pathname, Astro.site).toString();
+
+// Per D3: og:image emits only when an image is explicitly set — either via
+// per-page Astro.props.ogImage or book-level bookConfig.seo.ogImage. No
+// '/og-default.png' fallback to avoid broken-link meta tags on consumers
+// without an OG image authored.
+const resolvedOgImage = ogImage ?? bookConfig.seo?.ogImage ?? null;
+const absoluteOgImage = resolvedOgImage
+  ? new URL(resolvedOgImage, Astro.site).toString()
+  : null;
+const twitterHandle = bookConfig.seo?.twitterHandle ?? null;
+const ogSiteName = bookConfig.title ?? title;
+const ogDescription = description ?? bookConfig.description ?? '';
 ---
 
 <!doctype html>
@@ -74,6 +106,27 @@ const { title, description, lang = 'en', showSidebar = true } = Astro.props;
     <meta name="generator" content={Astro.generator} />
     <title>{title}</title>
     {description && <meta name="description" content={description} />}
+
+    {/* v4.6.0: SEO meta-tag block (issue #76 Primary). canonical + og:* +
+        twitter:* on every page; article:* lives in Chapter.astro via the
+        Base `<slot name="head" />` (below). og:image + twitter:image emit
+        only when an image is explicitly set (per D3, avoids broken-link
+        OG tags). sitemap link points at @astrojs/sitemap's auto-emitted
+        index. */}
+    <link rel="canonical" href={canonicalURL} />
+    <link rel="sitemap" type="application/xml" href="/sitemap-index.xml" />
+    <meta property="og:title" content={title} />
+    {ogDescription && <meta property="og:description" content={ogDescription} />}
+    <meta property="og:url" content={canonicalURL} />
+    <meta property="og:type" content={ogType} />
+    <meta property="og:site_name" content={ogSiteName} />
+    {absoluteOgImage && <meta property="og:image" content={absoluteOgImage} />}
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content={title} />
+    {ogDescription && <meta name="twitter:description" content={ogDescription} />}
+    {absoluteOgImage && <meta name="twitter:image" content={absoluteOgImage} />}
+    {twitterHandle && <meta name="twitter:site" content={twitterHandle} />}
+
     {/* FOUC prevention — apply saved theme before any paint. */}
     <script is:inline>
       (function () {

package/layouts/Chapter.astro

@@ -12,10 +12,17 @@
  *
  * Driven by a CollectionEntry<'chapters'> passed in Astro.props.entry
  * plus the `headings` array Astro's MDX renderer provides.
+ *
+ * v4.6.0: passes ogType="article" to Base + emits article:* meta tags via
+ * Base's `<slot name="head" />`. Article tags read from chapter frontmatter
+ * (`author`, `published`, `updated`, `tags`) with `author` falling back to
+ * book-level `bookConfig.author`. `entry.data.image` (chapter-specific OG
+ * image) is passed as `ogImage` for richer per-chapter social cards.
  */
 import type { CollectionEntry } from 'astro:content';
 import type { MarkdownHeading } from 'astro';
 import Base from './Base.astro';
+import bookConfig from 'virtual:book-scaffold/book-config';
 import ChapterHeader from '../components/ChapterHeader.astro';
 import ChapterTOC from '../components/ChapterTOC.astro';
 import ChapterNav from '../components/ChapterNav.astro';
@@ -25,9 +32,36 @@ interface Props {
   headings: MarkdownHeading[];
 }
 const { entry, headings } = Astro.props;
+
+// v4.6.0: article:* meta-tag data. All fields are Zod-optional in the
+// chapter schemas (academic / tools / course-notes / research-portfolio),
+// so any of these may be undefined. `author` falls back to bookConfig.author
+// (the top-level defineBookConfig field) so single-author books don't
+// repeat themselves per chapter.
+const articleAuthor =
+  (entry.data as { author?: string }).author ?? bookConfig.author ?? null;
+const articlePublished = (entry.data as { published?: Date }).published;
+const articleUpdated = (entry.data as { updated?: Date }).updated;
+const articleTags = ((entry.data as { tags?: string[] }).tags ?? []) as string[];
+const chapterImage = (entry.data as { image?: string }).image;
 ---
 
-<Base title={entry.data.title} description={entry.data.description}>
+<Base
+  title={entry.data.title}
+  description={entry.data.description}
+  ogType="article"
+  ogImage={chapterImage}
+>
+  <Fragment slot="head">
+    {articleAuthor && <meta property="article:author" content={articleAuthor} />}
+    {articlePublished && (
+      <meta property="article:published_time" content={articlePublished.toISOString()} />
+    )}
+    {articleUpdated && (
+      <meta property="article:modified_time" content={articleUpdated.toISOString()} />
+    )}
+    {articleTags.map((t) => <meta property="article:tag" content={t} />)}
+  </Fragment>
   <article class="prose">
     <ChapterHeader data={entry.data} />
     <ChapterTOC headings={headings} />

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.5.0",
+  "version": "4.6.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -152,6 +152,7 @@
     "remark-math": { "optional": true }
   },
   "dependencies": {
+    "@astrojs/sitemap": "^3.6.1",
     "@citation-js/core": "^0.7.21",
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",

package/pages/index.astro

@@ -1,14 +1,24 @@
 ---
 /**
- * /index — minimal default landing page (v4.5.0).
+ * /index — minimal default landing page (v4.5.0; landing-config source
+ * refactored in v4.5.1 from env vars to virtual module).
  *
  * Auto-injected by bookScaffoldIntegration when routes.landing === true
  * (default for every profile). Consumers with their own src/pages/index.astro
  * override automatically — file-system routes win over injectRoute, no extra
  * config needed.
  *
- * Reads book identity + portfolio + enabled-routes from vite.define-injected
- * env vars (see integration.ts §4.5.0). Renders:
+ * Reads book identity + portfolio + enabled-routes from the
+ * `virtual:book-scaffold/book-config` virtual module exposed by
+ * makeBookConfigVitePlugin (renamed from makeLandingConfigVitePlugin in
+ * v4.6.0 since Base.astro now also imports the module on every page).
+ * v4.5.0 used
+ * import.meta.env.BOOK_* env vars; that pattern was vulnerable to silent
+ * override by consumer .env files (caught during DML deploy when a stale
+ * `BOOK_TITLE=web` in web/.env overrode defineBookConfig({title})). The
+ * virtual module isolates landing config from any env-based override.
+ *
+ * Renders:
  *   - h1 with book title (fallback: 'book-scaffold-astro')
  *   - lead paragraph with description (omitted if not set)
  *   - "Read" list of links to enabled scaffold routes (filtered to only
@@ -23,13 +33,12 @@
  *     or defineBookConfig({ portfolio: false })
  */
 import Base from '../layouts/Base.astro';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
-// Vite-injected at build time. JSON.stringify(value ?? null) is the
-// integration's convention; null means "not set", an object/string means real value.
-const title = (import.meta.env.BOOK_TITLE as string | null) ?? 'book-scaffold-astro';
-const description = import.meta.env.BOOK_DESCRIPTION as string | null;
-const portfolio = import.meta.env.BOOK_PORTFOLIO as { url: string; label: string } | false | null;
-const enabledRoutes = (import.meta.env.BOOK_ROUTES_ENABLED as string[] | undefined) ?? [];
+const title = bookConfig.title ?? 'book-scaffold-astro';
+const description = bookConfig.description;
+const portfolio = bookConfig.portfolio;
+const enabledRoutes = bookConfig.enabledRoutes;
 
 // Map from internal route name → display label + URL. Only routes that
 // produce a single landing-list entry are listed here (frontmatter is a

package/recipes/18-chapter-route-ownership.md

@@ -0,0 +1,87 @@
+# Recipe 18 — Chapter-route ownership (v4.3.0+)
+
+Since v4.3.0, `book-scaffold-astro` **auto-injects** the per-chapter route `/chapters/[...slug]/` when `routes.chapters: true` is in `defineBookConfig`. Consumers that pre-date v4.3.0 (or were scaffolded from older templates) may carry their own `src/pages/chapters/[...slug].astro` that **shadows** the auto-injected one — Astro's filesystem routing picks the consumer file over `injectRoute`, with no error or warning until v4.6.0.
+
+This recipe explains the three valid states and how to pick one.
+
+---
+
+## TL;DR
+
+If your `src/pages/chapters/[...slug].astro` is a stock copy from a pre-v4.3.0 template (mechanical boilerplate, no custom layout work), **delete it**. The scaffold's auto-injected route handles every academic / tools / research-portfolio consumer's per-chapter rendering identically.
+
+If you customized the file (e.g., book-specific chapter chrome, citation styling, sidebar variations), **keep it** AND set `routes: { chapters: false }` in your `defineBookConfig` to signal the override is intentional.
+
+The `book-scaffold validate` CLI emits a warning (v4.6.0+) when it detects a consumer-owned file without the `chapters: false` override, prompting you to pick one of the two states.
+
+---
+
+## Three states
+
+### State 1 — Default (90% case, recommended)
+
+No `src/pages/chapters/[...slug].astro` in your consumer repo. Scaffold's auto-injected route handles per-chapter rendering. `routes.chapters` defaults to whatever your profile sets (`true` for academic by default).
+
+```
+your-book/
+└── src/
+    └── pages/
+        └── chapters.astro    ← optional: the /chapters/ index page (also auto-injected if missing)
+        # no chapters/ directory; scaffold provides /chapters/[...slug]/
+```
+
+Pros: zero per-consumer code. Future scaffold improvements (e.g., richer chapter sidebars, better TOC rendering) propagate automatically on the next scaffold bump.
+
+### State 2 — Intentional override (custom chapter layout)
+
+`src/pages/chapters/[...slug].astro` exists in your consumer repo AND `defineBookConfig({ routes: { chapters: false } })` is set. The consumer file owns the route; scaffold's auto-injected route is suppressed.
+
+```ts
+// astro.config.mjs
+export default await defineBookConfig({
+  styles: [academicStyle],
+  site: 'https://your-book.example/',
+  routes: { chapters: false },   // ← signal: I own the chapter route
+});
+```
+
+```
+your-book/
+└── src/
+    └── pages/
+        └── chapters/
+            └── [...slug].astro    ← consumer-owned; scaffold defers
+```
+
+Pros: full control over per-chapter chrome, sidebar, TOC layout, etc. Cons: must hand-maintain when scaffold ships chapter-level improvements (the consumer file is now your source of truth for chapter rendering).
+
+### State 3 — Anti-pattern (shadow, fixed by v4.6 validator warning)
+
+`src/pages/chapters/[...slug].astro` exists in your consumer repo BUT `routes.chapters` is undefined or `true`. Astro's filesystem routing wins, so the consumer file renders — but the scaffold is also trying to inject a route at the same pattern. Functionally works today (Astro picks the consumer file), but:
+
+- Future scaffold improvements to chapter rendering silently no-op for this consumer.
+- Dual-source ownership is confusing for future maintainers.
+- `book-scaffold validate` emits a warning in v4.6.0+.
+
+**Fix**: pick State 1 (delete the file) or State 2 (set `chapters: false`).
+
+---
+
+## Migration from pre-v4.3.0 templates
+
+Reference consumers `double_ml_time_series` (Phase 1f, 2026-05-26) and `ssm-foundations` (Phase 1c, 2026-05-26) both migrated from State 3 → State 1 — the consumer-owned `src/pages/chapters/[...slug].astro` was a mechanical copy of the same boilerplate that scaffold v4.3.0+ auto-injects, so deletion was lossless.
+
+Migration steps:
+
+1. `diff` your consumer's `src/pages/chapters/[...slug].astro` against the scaffold's `package/pages/chapters/[...slug].astro` to confirm no customization. If they're equivalent (ignoring trivial formatting), proceed.
+2. `rm src/pages/chapters/'[...slug].astro'` (note the shell-escaped brackets).
+3. `git commit -m "chore: delete chapter-route override (scaffold v4.3.0+ auto-injects)"`.
+4. Push + redeploy. The scaffold's auto-injected route takes over without behavior change.
+
+If your file has real customization, prefer State 2: keep the file and add `routes: { chapters: false }` to `defineBookConfig`.
+
+---
+
+## Why this matters
+
+Layer-3 cleanup is part of [issue #76](https://github.com/brandon-behring/book-scaffold-astro/issues/76)'s v4.6 bundle. Related companion: [recipe 19 — prevalidate-hook](./19-prevalidate-hook.md), which fixes another silent-CI gap surfaced during the same first-deploy sessions.

package/recipes/19-prevalidate-hook.md

@@ -0,0 +1,113 @@
+# Recipe 19 — `prevalidate` npm hook (v4.6.0+)
+
+`book-scaffold validate` checks `<Cite key="...">` against `src/data/references.json` (academic profile) and `<XRef id="...">` against `src/data/labels.json`. Both JSON files are **derived artifacts** regenerated from `bibliography.bib` + chapter MDX by `book-scaffold build-bib` + `book-scaffold build-labels`. Both are gitignored.
+
+When `npm run validate` runs **standalone** (e.g., a reusable deploy workflow runs only the validate command, without the full `npm run build` chain), the prereq scripts don't fire and the validator chokes on apparently-missing keys.
+
+The `prevalidate` npm lifecycle hook is the canonical fix: it auto-runs the prereqs whenever `npm run validate` is invoked, regardless of how validate is called.
+
+---
+
+## TL;DR
+
+```json
+{
+  "scripts": {
+    "prevalidate": "npm run build:bib && npm run build:labels --if-present",
+    "validate": "book-scaffold validate"
+  }
+}
+```
+
+`npm run validate` → automatically runs `prevalidate` first (build:bib + build:labels) → then runs `validate`. CI and local behave identically; no separate `ci:validate` wrapper script needed.
+
+---
+
+## Why the workaround was needed
+
+`brandon-behring/deploy-workflows@v1` (the reusable Cloudflare Workers deploy) runs `npm run <validate-command>` between `npm ci` and `npm run build`. Without the `prevalidate` hook OR an explicit wrapper script, the validate step ran against missing artifacts.
+
+The Phase 1c first-deploy of `ssm-foundations` (2026-05-26) hit this — validate emitted 25+ "Unknown bibkey" errors that pointed at chapter content instead of the missing `references.json` artifact. The deploy-time fix shipped as a `ci:validate` wrapper:
+
+```json
+{
+  "scripts": {
+    "ci:validate": "npm run build:bib && npm run build:labels --if-present && npm run validate"
+  }
+}
+```
+
+…with `validate-command: ci:validate` in `.github/workflows/deploy.yml`. This worked but introduced consumer-side ceremony for what is structurally a scaffold-level convention.
+
+The cleaner long-term fix is the `prevalidate` npm-lifecycle hook (this recipe). v4.6.0's `create-book` automatically scaffolds it for academic + research-portfolio profiles.
+
+---
+
+## Migration: from `ci:validate` to `prevalidate`
+
+Existing consumers (DML, ssm, dlai when it ships) that adopted the `ci:validate` wrapper during 2026-05-26 deploys can migrate when they bump to scaffold `^4.6.0`. Three-file mechanical change per consumer:
+
+### 1. `package.json` — rename `ci:validate` → `prevalidate`
+
+```diff
+ {
+   "scripts": {
+-    "ci:validate": "npm run build:bib && npm run build:labels --if-present && npm run validate",
++    "prevalidate": "npm run build:bib && npm run build:labels --if-present",
+     "validate": "book-scaffold validate"
+   }
+ }
+```
+
+Note the renamed script no longer needs to call `validate` itself — npm's lifecycle invokes it automatically after `prevalidate` completes.
+
+### 2. `.github/workflows/deploy.yml` — revert `validate-command`
+
+```diff
+ jobs:
+   deploy:
+     uses: brandon-behring/deploy-workflows/.github/workflows/deploy-astro-worker.yml@v2
+     secrets: inherit
+     with:
+       working-directory: web
+-      validate-command: ci:validate
++      validate-command: validate
+       enable-pr-previews: true
+```
+
+The reusable workflow's `validate-command` now points at the native `validate` script; the `prevalidate` hook handles its own prereqs transparently.
+
+### 3. Simplify `prebuild` (optional)
+
+If the consumer's `prebuild` still has the long chain:
+
+```diff
+ {
+   "scripts": {
+-    "prebuild": "npm run build:bib --if-present && npm run build:labels --if-present && npm run validate --if-present",
++    "prebuild": "npm run validate --if-present",
+     "build": "astro build && pagefind --site dist"
+   }
+ }
+```
+
+Now `npm run build` → triggers `prebuild` (which runs `validate`) → triggers `prevalidate` (which runs the prereqs) → validate runs cleanly. Single source of truth for the prereq chain.
+
+---
+
+## When `prevalidate` is NOT needed
+
+Profiles that don't run cite-key or XRef validation don't need `prevalidate`. Specifically:
+
+- `tools`, `minimal`: no `<Cite>` resolution against `references.json`.
+- `course-notes`: depends on whether the consumer uses `<Cite>` (some do for source-tier attribution).
+
+For these profiles, `book-scaffold validate` operates on chapter structure + XRef IDs only; `prevalidate` would be a no-op. The v4.6.0 create-book template adds `prevalidate` ONLY for academic + research-portfolio.
+
+---
+
+## Why this matters
+
+Recipe 19 is part of [issue #76](https://github.com/brandon-behring/book-scaffold-astro/issues/76)'s v4.6 bundle. Companion: [recipe 18 — chapter-route ownership](./18-chapter-route-ownership.md), which fixes another silent-CI surface from the same Phase 1c first-deploys.
+
+The `prevalidate` convention also closes [issue #77](https://github.com/brandon-behring/book-scaffold-astro/issues/77) — the v4.6 validator now emits a single re-framed error pointing at this recipe when `references.json` is missing, replacing the noisy 25-symptom output.

package/scripts/validate.mjs

@@ -121,6 +121,46 @@ const PRESET =
 const PROFILE = PRESET;
 const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;
 
+// v4.6.0 (issue #76 Layer 3b): chapter-route shadow warning. Detect a
+// consumer-owned `src/pages/chapters/[...slug].astro` that shadows the
+// scaffold v4.3.0+ auto-injected route. Non-blocking — emits to stderr,
+// validate continues normally. Suppressed when the consumer explicitly
+// disabled the scaffold's chapter route (intentional override).
+//
+// Edge cases per issue #76:
+//   file + routes.chapters undefined/true → WARN
+//   file + routes.chapters: false         → silent (intentional override)
+//   no file (any routes config)           → silent
+//
+// Heuristic for "routes.chapters: false": regex-grep astro.config.mjs for
+// the literal `chapters: false`. Light-touch detection that matches the
+// issue's warning-not-error intent; consumers wanting a stricter detector
+// can run `astro check` separately.
+{
+  const consumerChapterRoute = resolve(ROOT, 'src/pages/chapters/[...slug].astro');
+  if (existsSync(consumerChapterRoute)) {
+    const astroConfigPath = resolve(ROOT, 'astro.config.mjs');
+    let chaptersDisabled = false;
+    if (existsSync(astroConfigPath)) {
+      const astroConfig = readFileSync(astroConfigPath, 'utf8');
+      // Match `chapters: false` (with optional whitespace) inside a routes
+      // object. Slight false-positive risk on commented-out code; acceptable
+      // for a non-blocking warning.
+      chaptersDisabled = /\bchapters\s*:\s*false\b/.test(astroConfig);
+    }
+    if (!chaptersDisabled) {
+      console.warn(
+        `\n⚠ Consumer-owned chapter route at src/pages/chapters/[...slug].astro\n` +
+        `  shadows the scaffold v4.3.0+ auto-injected route. Either:\n` +
+        `  • Delete the consumer file to defer to the scaffold (recommended), OR\n` +
+        `  • Set 'routes: { chapters: false }' in defineBookConfig to keep\n` +
+        `    your override (intentional).\n` +
+        `  See: package/recipes/18-chapter-route-ownership.md\n`,
+      );
+    }
+  }
+}
+
 const errors = [];
 const warnings = [];
 const fail = (file, line, msg) => errors.push({ file, line, msg });
@@ -231,6 +271,44 @@ for (const rel of chapterFiles) {
   }
 }
 
+// ===== v4.6.0 (issue #77): missing-prereq re-framing =====
+//
+// When errors are downstream symptoms of a missing artifact (references.json
+// or labels.json), abort with ONE leading error pointing at the prereq
+// instead of printing 25 "Unknown bibkey" / "Unknown XRef" symptoms. Single
+// clean signal: fix the prereq. Per D12 of the v4.6.0 plan.
+{
+  if (PROFILE === 'academic') {
+    const refsPath = join(DATA_DIR, 'references.json');
+    const hasBibkeyErrors = errors.some((e) => /Unknown bibkey/.test(e.msg));
+    if (hasBibkeyErrors && !existsSync(refsPath)) {
+      console.error(
+        `\n✗ Validate cannot run: src/data/references.json is missing.\n\n` +
+          `This file is generated from bibliography.bib by 'npm run build:bib'.\n` +
+          `Run that first, OR adopt the prevalidate npm hook convention so\n` +
+          `'npm run validate' regenerates it automatically:\n\n` +
+          `  "prevalidate": "npm run build:bib && npm run build:labels --if-present"\n` +
+          `  "validate": "book-scaffold validate"\n\n` +
+          `See package/recipes/19-prevalidate-hook.md.\n`,
+      );
+      process.exit(1);
+    }
+  }
+  const labelsPath = join(DATA_DIR, 'labels.json');
+  const hasXrefErrors = errors.some((e) => /Unknown XRef/.test(e.msg));
+  if (hasXrefErrors && !existsSync(labelsPath)) {
+    console.error(
+      `\n✗ Validate cannot run: src/data/labels.json is missing.\n\n` +
+        `This file is generated from <Theorem id="..."> and <Figure id="..."> markers\n` +
+        `in chapter MDX by 'npm run build:labels'. Run that first, OR adopt the\n` +
+        `prevalidate npm hook convention so 'npm run validate' regenerates it:\n\n` +
+        `  "prevalidate": "npm run build:bib && npm run build:labels --if-present"\n\n` +
+        `See package/recipes/19-prevalidate-hook.md.\n`,
+    );
+    process.exit(1);
+  }
+}
+
 // ===== Report =====
 const format = ({ file, line, msg }) => `  ${file}:${line}  ${msg}`;
 if (warnings.length > 0) {

package/src/profile-kit.ts

@@ -105,6 +105,23 @@ export interface ProfileDefinition {
    * fallbackChaptersRenderer (field-presence dispatch) at route render time.
    */
   chaptersRenderer?: ChaptersRenderer;
+  /**
+   * v4.6.0 (issue #76 Secondary): per-profile default sitemap filter.
+   * Predicate run against every page URL by `@astrojs/sitemap` — return
+   * true to include in sitemap, false to exclude.
+   *
+   * Defaults:
+   *   academic + course-notes  → excludes `/print/` (print-friendly view,
+   *                              crawl-redundant)
+   *   tools + minimal + research-portfolio → omitted (include everything)
+   *
+   * Per D7 of the v4.6.0 plan: when a consumer sets
+   * `defineBookConfig({ seo: { sitemap: { filter } } })`, the consumer's
+   * filter REPLACES this profile default (not composed). Consumers wanting
+   * to also exclude /print/ on top of additional exclusions copy the
+   * profile-default predicate's behavior into their own filter.
+   */
+  sitemapFilter?: (page: string) => boolean;
 }
 
 /**

package/src/profiles/academic.ts

@@ -30,4 +30,7 @@ export const academicProfile = defineProfile({
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   katex: true,
   chaptersRenderer: academicChaptersRenderer,   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Academic-profile default.
+  sitemapFilter: (page: string) => !page.includes('/print/'),
 });

package/src/profiles/course-notes.ts

@@ -32,4 +32,7 @@ export const courseNotesProfile = defineProfile({
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
   chaptersRenderer: fallbackChaptersRenderer,
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Course-notes-profile default.
+  sitemapFilter: (page: string) => !page.includes('/print/'),
 });

package/src/schemas.ts

@@ -83,6 +83,13 @@ export const academicChapterSchema = z.object({
   notebook_path: z.string().optional(),
   description: z.string().optional(),
   draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // All optional; existing chapters without these continue to work.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional(),
 });
 
 export const toolsChapterSchema = z.object({
@@ -96,6 +103,12 @@ export const toolsChapterSchema = z.object({
   description: z.string().optional(),
   draft: z.boolean().default(false),
   updated: z.date().optional(),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `updated` already existed; the rest are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional(),
 });
 
 /** Minimal profile currently aliases the tools schema. */
@@ -147,6 +160,14 @@ export const courseNotesChapterSchema = z.object({
   volatility: z.enum(volatilityLevels).default('architectural-pattern'),
   sources: z.array(z.string()).default([]),
   draft: z.boolean().default(false),
+
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` already existed; the rest are new. `instructor` (line 130) is
+  // attribution metadata — distinct from `author` (the note-writer/curator).
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  image: z.string().optional(),
 });
 
 /**
@@ -228,6 +249,12 @@ export const researchPortfolioChapterSchema = z.object({
   last_verified: z.date(),
   updated: z.date().optional(),
   draft: z.boolean().default(false),
+
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` + `updated` already existed; `author` + `published` + `image` are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  image: z.string().optional(),
 });
 
 // ===== Inferred chapter types — one per schema =====