@brandon_m_behring/book-scaffold-astro 4.1.0 → 4.2.0

package/components/PocLayout.astro

@@ -11,12 +11,7 @@
  * Closed `kind` union: discriminated literal type. To add a 6th kind in
  * a future release, expand the union + add a CSS block in poc-layouts.css.
  */
-export type PocLayoutKind =
-  | 'tutorial'
-  | 'how-to'
-  | 'tldr'
-  | 'part-summary'
-  | 'cheat-sheet';
+export type PocLayoutKind = 'tutorial' | 'how-to' | 'tldr' | 'part-summary' | 'cheat-sheet';
 
 interface Props {
   kind: PocLayoutKind;

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.1.0",
+  "version": "4.2.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/recipes/16-tikz-figures.md

@@ -0,0 +1,102 @@
+# Recipe 16 — TikZ figures (v4.2.0+)
+
+`book-scaffold build-figures` (v4.2.0+) auto-compiles TikZ standalone `.tex` sources to PDF via `pdflatex`, then converts the PDF to SVG via the existing pdf2svg pipeline. Closes [#17](https://github.com/brandon-behring/book-scaffold-astro/issues/17).
+
+## TL;DR
+
+Drop `figures/<topic>/diagram.tex` (standalone TikZ source). Run `npm run build:figures` (or it's wired into `prebuild`). Get `public/figures/<topic>/diagram.svg` ready to reference in MDX as `<Figure src="/figures/<topic>/diagram.svg" />`.
+
+## The TikZ source
+
+Use the `standalone` document class; configure for SVG via `tikz` option. Recommended:
+
+```latex
+\documentclass[tikz,border=2mm]{standalone}
+\usepackage{tikz}
+\usetikzlibrary{positioning, shapes, arrows}  % whichever libraries you need
+\begin{document}
+\begin{tikzpicture}
+  \node (a) at (0,0) {Hello};
+  \node (b) at (3,0) {World};
+  \draw[->] (a) -- (b);
+\end{tikzpicture}
+\end{document}
+```
+
+The `border=2mm` adds a small margin around the figure so it doesn't crop right at the edge.
+
+## Discovery rule
+
+`build-figures` walks `figures/` (or `BOOK_FIGURES_PATH`) for both `.pdf` and `.tex` files. For each `.tex` source:
+
+- If no sibling `.pdf` exists → compile.
+- If `.pdf` exists but `.tex` is newer → recompile.
+- If `.pdf` is newer than (or equal in mtime to) `.tex` → skip (use the existing PDF).
+
+This means consumers who ship pre-compiled `.pdf` figures alongside their `.tex` sources don't pay the compilation cost on every build.
+
+## Working directory
+
+`pdflatex` runs in `figures/<topic>/` (the directory containing the source). This makes TikZ `\input{}` relative paths work correctly and keeps intermediate files (`.aux`, `.log`) alongside the source for easy debugging.
+
+## Gitignore intermediate files
+
+Add to your project's `.gitignore`:
+
+```gitignore
+figures/**/*.aux
+figures/**/*.log
+figures/**/*.fdb_latexmk
+figures/**/*.fls
+figures/**/*.synctex.gz
+```
+
+The intermediate `.pdf` files generated from `.tex` SHOULD be committed — they let consumers without TeX Live still see your figures (the SVGs still get generated from the committed PDFs).
+
+## Required: TeX Live install
+
+`pdflatex` is a system dependency (not an npm package). Install:
+
+- **macOS**: `brew install --cask mactex` (full) or `brew install --cask basictex` (minimal — add packages via `tlmgr`)
+- **Ubuntu/Debian**: `sudo apt-get install texlive-base texlive-pictures` (minimal for TikZ)
+- **Other**: https://www.tug.org/texlive/
+
+If `pdflatex` is missing but `.tex` files are present, `build-figures` prints a clear ERROR with the install link and continues processing any `.pdf`-only topics. Doesn't crash the build.
+
+## CI workflow note
+
+If your CI builds rely on regenerating SVGs from `.tex` sources (rather than just serving committed SVGs), add TeX Live to your CI workflow:
+
+```yaml
+- name: Install TeX Live for TikZ figures
+  run: sudo apt-get install -y texlive-base texlive-pictures
+```
+
+This adds ~200 MB to the runner — only do it if your figures actually change between commits. The recommended pattern is to commit both `.tex` AND the generated `.pdf`/`.svg`, treating regeneration as a local-dev concern.
+
+## Debugging compilation failures
+
+When pdflatex fails on a `.tex` source, `build-figures` prints the stderr (and falls back to stdout) and continues with the remaining figures. Don't fail the whole build for one broken figure.
+
+To debug interactively:
+
+```bash
+cd figures/<topic>/
+pdflatex diagram.tex
+# read diagram.log for the full error trace
+```
+
+Common failures:
+- **Missing package**: `! LaTeX Error: File 'tikz-cd.sty' not found.` → install with `tlmgr install tikz-cd` (macOS/Linux Tex Live) or `sudo apt-get install texlive-tikz-cd` (Debian).
+- **Syntax error**: `! Undefined control sequence.` → check the `.log` file for the line number.
+- **Compilation hang**: should auto-resolve via `-halt-on-error -interaction=nonstopmode` flags the scaffold uses.
+
+## Feedback loop
+
+If you hit friction with the TikZ pipeline (a TikZ feature that doesn't compile, an obscure error message, a workflow pattern that doesn't fit), file an issue at https://github.com/brandon-behring/book-scaffold-astro/issues with the `consumer:<your-workspace>` label. v4.x is the iteration window.
+
+## See also
+
+- `recipes/06-figures.md` — overall figure pipeline + matplotlib/svg sources
+- `PACKAGE_DESIGN.md §7` — peer dependencies (lists `pdflatex` as optional system dep)
+- `PACKAGE_DESIGN.md §8` — `book-scaffold` CLI reference (build-figures subcommand)

package/scripts/build-figures.mjs

@@ -6,6 +6,13 @@
  * pdftocairo, emitting under public/figures/. SVG preserves zoom/quality
  * and stays small for matplotlib-style plots.
  *
+ * v4.2.0 (closes #17): TikZ standalone `.tex` sources are auto-compiled
+ * to `.pdf` via pdflatex before the existing PDF→SVG pass runs. Discovery
+ * rule: if `figures/<topic>/<name>.tex` exists AND no sibling `.pdf`
+ * (or `.tex` is newer than `.pdf`), pdflatex runs. Graceful skip when
+ * pdflatex is not on PATH (only emits ERROR if .tex sources exist).
+ * See recipes/16-tikz-figures.md for the workflow + install pointers.
+ *
  * Default source: figures/ at scaffold root. Override via BOOK_FIGURES_PATH
  * env var (absolute path or path relative to scaffold root) — useful for
  * books that share figures with a LaTeX sibling at e.g. ../shared/figures/.
@@ -98,6 +105,55 @@ async function listPdfsRecursive(root, prefix = '') {
   return out;
 }
 
+/**
+ * v4.2.0 (#17): recursively collect .tex sources under FIGURES_SRC.
+ * Same shape as listPdfsRecursive but for `.tex` extension. TikZ
+ * standalone files at any subdirectory depth are picked up.
+ */
+async function listTexRecursive(root, prefix = '') {
+  if (!existsSync(root)) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  const out = [];
+  for (const entry of entries) {
+    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...(await listTexRecursive(resolve(root, entry.name), relPath)));
+    } else if (entry.isFile() && entry.name.endsWith('.tex')) {
+      out.push({ relPath });
+    }
+  }
+  return out;
+}
+
+/**
+ * v4.2.0 (#17): compile a TikZ standalone .tex to .pdf via pdflatex.
+ * Run in the source directory so TikZ \input{} relative paths resolve
+ * + intermediate .aux/.log files land alongside the source.
+ * Returns true on success; throws Error with stderr on failure.
+ */
+function compileTikz(srcPath) {
+  const srcDir = dirname(srcPath);
+  const srcName = basename(srcPath);
+  const r = spawnSync(
+    'pdflatex',
+    [
+      '-halt-on-error',
+      '-interaction=nonstopmode',
+      '-output-directory=.',
+      srcName,
+    ],
+    { cwd: srcDir, stdio: 'pipe' },
+  );
+  if (r.status !== 0) {
+    const stderr = (r.stderr ?? Buffer.from('')).toString().trim();
+    const stdout = (r.stdout ?? Buffer.from('')).toString().trim();
+    throw new Error(
+      `pdflatex failed for ${srcPath}: ${stderr || stdout || `exit code ${r.status}`}`,
+    );
+  }
+  return true;
+}
+
 function isUpToDate(srcPath, dstPath) {
   if (!existsSync(dstPath)) return false;
   const srcMtime = statSync(srcPath).mtimeMs;
@@ -153,6 +209,38 @@ async function main() {
     return;
   }
 
+  // v4.2.0 (#17): stage 1 — compile any TikZ standalone .tex sources to .pdf
+  // BEFORE the PDF→SVG loop. Topic-walk discovers .tex files; compiles those
+  // where no sibling .pdf exists OR .tex is newer than .pdf.
+  const texSources = await listTexRecursive(FIGURES_SRC);
+  let tikzCompiled = 0;
+  if (texSources.length > 0) {
+    if (!check('pdflatex')) {
+      console.error(
+        `build-figures: pdflatex not on $PATH but ${texSources.length} ` +
+          `.tex source(s) detected. Install TeX Live to enable TikZ ` +
+          `compilation (see https://www.tug.org/texlive/). Skipping ` +
+          `.tex sources; pre-compiled .pdf siblings (if any) will still ` +
+          `be converted to SVG.`,
+      );
+    } else {
+      for (const { relPath } of texSources) {
+        const srcPath = resolve(FIGURES_SRC, relPath);
+        const pdfPath = srcPath.replace(/\.tex$/, '.pdf');
+        if (existsSync(pdfPath) && statSync(pdfPath).mtimeMs >= statSync(srcPath).mtimeMs) {
+          continue; // pdf is up-to-date
+        }
+        try {
+          compileTikz(srcPath);
+          tikzCompiled++;
+        } catch (err) {
+          console.error(`build-figures: ${err.message ?? err}`);
+          // Continue — don't fail the whole build on one broken .tex file.
+        }
+      }
+    }
+  }
+
   const pdfs = await listPdfsRecursive(FIGURES_SRC);
   if (pdfs.length === 0) {
     console.log('build-figures: no PDFs found; nothing to do.');
@@ -185,9 +273,10 @@ async function main() {
     converted++;
   }
 
+  const tikzNote = tikzCompiled > 0 ? `, ${tikzCompiled} tikz→pdf` : '';
   console.log(
     `build-figures: ${total} total, ${converted} converted ` +
-      `(${pngFallback} png fallback), ${skipped} cached`,
+      `(${pngFallback} png fallback), ${skipped} cached${tikzNote}`,
   );
 }
 

package/scripts/build-labels.mjs

@@ -34,7 +34,8 @@
  * Designed to run in <2 s on a medium book.
  */
 import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
-import { resolve, join, basename, dirname } from 'node:path';
+import { resolve, relative, join, basename, dirname } from 'node:path';
+import { readChaptersBase } from './walk-mdx.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-labels
@@ -56,7 +57,15 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   process.exit(0);
 }
 
-const CHAPTERS_DIR = process.env.BOOK_CHAPTERS_DIR ?? 'src/content/chapters';
+// v4.1.1 (closes #63): readChaptersBase honors BOOK_CHAPTERS_DIR env (when set)
+// then parses the consumer's content.config.{ts,mjs,js} for a `chapters`
+// collection `loader.base` override. Multi-guide consumers use
+// `src/content/<guide-slug>/` rather than the Astro 5 default.
+const CHAPTERS_DIR_ABS = await readChaptersBase(process.cwd());
+// build-labels uses CHAPTERS_DIR as a path relative to cwd elsewhere in the
+// script (joined with `walkMdx`). Convert the absolute path back to relative
+// for compatibility with the existing call sites.
+const CHAPTERS_DIR = relative(process.cwd(), CHAPTERS_DIR_ABS) || 'src/content/chapters';
 const OUTPUT_PATH = process.env.BOOK_LABELS_OUT ?? 'src/data/labels.json';
 
 /** Component names that participate in cross-referencing. */

package/scripts/validate.mjs

@@ -28,7 +28,7 @@
 import { readFile, access } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
-import { walkMdx } from './walk-mdx.mjs';
+import { walkMdx, readChaptersBase } from './walk-mdx.mjs';
 
 /**
  * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
@@ -95,7 +95,11 @@ const presetFromFlag = presetFlagIdx >= 0 ? argv[presetFlagIdx + 1] : undefined;
 // Resolves issue #8 — three reference consumers reported "0 chapter(s) checked"
 // because ROOT was the package directory inside node_modules.
 const ROOT = process.cwd();
-const CHAPTERS_DIR = resolve(ROOT, 'src/content/chapters');
+// v4.1.1 (closes #63): read the consumer's content.config.{ts,mjs,js} to
+// honor `loader.base` overrides (multi-guide pattern uses
+// `src/content/<guide-slug>/` instead of the Astro 5 default).
+// Falls back to `src/content/chapters` when no override / no config file.
+const CHAPTERS_DIR = await readChaptersBase(ROOT);
 const PUBLIC_DIR = resolve(ROOT, 'public');
 const DATA_DIR = resolve(ROOT, 'src/data');
 

package/scripts/walk-mdx.mjs

@@ -12,8 +12,9 @@
  * Output: relative paths in POSIX form ("subdir/file.mdx"), matching what
  * the previous `glob('**\/*.{md,mdx}', { cwd })` produced.
  */
-import { readdir } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
 
 export async function* walkMdx(dir, baseDir = dir) {
   let entries;
@@ -32,3 +33,68 @@ export async function* walkMdx(dir, baseDir = dir) {
     }
   }
 }
+
+/**
+ * Read the consumer's `content.config.ts` (or `.mjs` / `.js`) and extract
+ * the `loader.base` path for the `chapters` content collection.
+ *
+ * v4.1.1 (closes #63): consumers in the multi-guide / multi-book pattern
+ * override the chapters dir to `src/content/<guide-slug>` rather than the
+ * Astro 5 default `src/content/chapters/`. Without this helper,
+ * `book-scaffold validate` + `book-scaffold build-labels` silently report
+ * 0 chapters because they walk the default path. This helper parses the
+ * consumer's config file and returns the actual base path so both scripts
+ * discover the consumer's chapter files.
+ *
+ * Strategy: regex-parse the source file (avoid runtime import; the file
+ * imports from `astro:content` / `astro/loaders` which don't resolve in
+ * plain Node). Matches both single- and double-quoted string literals;
+ * matches paths with or without the `./` prefix.
+ *
+ * Returns the resolved absolute path. Falls back to
+ * `${projectRoot}/src/content/chapters` when:
+ *   - content.config.{ts,mjs,js} doesn't exist
+ *   - the file exists but no `chapters` collection or `loader.base` found
+ *   - the matched base path uses dynamic forms (variables, template literals)
+ *     instead of a string literal
+ *
+ * Honors env override: BOOK_CHAPTERS_DIR (when set) wins over config parse.
+ */
+export async function readChaptersBase(projectRoot) {
+  const envOverride = process.env.BOOK_CHAPTERS_DIR;
+  if (envOverride) {
+    return resolve(projectRoot, envOverride);
+  }
+  const DEFAULT_BASE = resolve(projectRoot, 'src/content/chapters');
+  for (const ext of ['ts', 'mjs', 'js']) {
+    const configPath = join(projectRoot, `src/content.config.${ext}`);
+    if (!existsSync(configPath)) continue;
+    let source;
+    try {
+      source = await readFile(configPath, 'utf8');
+    } catch {
+      return DEFAULT_BASE;
+    }
+    // Look for a `chapters` collection's `loader.base` string. Permissive
+    // form: match the `chapters` identifier, then within the next 500
+    // chars find `base: 'string'` or `base: "string"`. NOT template
+    // literals (which use backticks and may contain ${} interpolation —
+    // those fall back to the default since the value is dynamic).
+    //
+    // Forms matched:
+    //   - `const chapters = defineCollection({ loader: glob({ base: './foo' }) })`
+    //   - `export const collections = { chapters: defineCollection({ loader: glob({ base: './foo' }) }) }`
+    //   - any indentation / line break style
+    const re = /\bchapters\b[\s\S]{0,500}?\bbase\s*:\s*'([^']+)'|\bchapters\b[\s\S]{0,500}?\bbase\s*:\s*"([^"]+)"/;
+    const m = source.match(re);
+    const captured = m && (m[1] || m[2]);
+    if (captured) {
+      return resolve(projectRoot, captured);
+    }
+    // File exists but no override found — assume the consumer uses the
+    // scaffold's defineBookSchemas() default.
+    return DEFAULT_BASE;
+  }
+  // No content.config.{ts,mjs,js} at all — return the Astro 5 default.
+  return DEFAULT_BASE;
+}