@hutusi/amytis 1.15.0 → 1.16.0

package/src/lib/markdown.test.ts

@@ -5,7 +5,8 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { RstParseError } from "./rst";
 import {
   generateExcerpt,
-  calculateReadingTime,
+  calculateReadingMinutes,
+  calculateWordCount,
   getHeadings,
   getAuthorSlug,
   getPythonRstRendererAvailabilityForTests,
@@ -66,38 +67,80 @@ describe("markdown utils", () => {
     });
   });
 
-  describe("calculateReadingTime", () => {
-    test("short content returns 1 min read", () => {
+  describe("calculateReadingMinutes", () => {
+    test("short content returns 1 minute (floor)", () => {
       const text = "Hello world, this is a short post.";
-      expect(calculateReadingTime(text)).toBe("1 min read");
+      expect(calculateReadingMinutes(text)).toBe(1);
     });
 
-    test("600 words returns 3 min read", () => {
+    test("600 words returns 3 minutes", () => {
       const words = Array(600).fill("word").join(" ");
-      expect(calculateReadingTime(words)).toBe("3 min read");
+      expect(calculateReadingMinutes(words)).toBe(3);
     });
 
-    test("empty content returns 1 min read", () => {
-      expect(calculateReadingTime("")).toBe("1 min read");
+    test("empty content returns 1 (floor)", () => {
+      expect(calculateReadingMinutes("")).toBe(1);
     });
 
     test("strips markdown formatting before counting", () => {
       // 400 actual words surrounded by markdown syntax
       const words = Array(400).fill("**word**").join(" ");
-      const result = calculateReadingTime(words);
-      expect(result).toBe("2 min read");
+      expect(calculateReadingMinutes(words)).toBe(2);
     });
 
-    test("counts Chinese characters for reading time", () => {
+    test("counts Chinese characters at 300 cpm", () => {
       const han = "中".repeat(600);
-      expect(calculateReadingTime(han)).toBe("2 min read");
+      expect(calculateReadingMinutes(han)).toBe(2);
     });
 
     test("combines Latin words and Chinese characters", () => {
       const latinWords = Array(200).fill("word").join(" ");
       const han = "中".repeat(300);
       const mixed = `${latinWords} ${han}`;
-      expect(calculateReadingTime(mixed)).toBe("2 min read");
+      expect(calculateReadingMinutes(mixed)).toBe(2);
+    });
+  });
+
+  describe("calculateWordCount", () => {
+    test("empty content returns 0", () => {
+      expect(calculateWordCount("")).toBe(0);
+    });
+
+    test("Latin words: each whitespace-bounded token counts once", () => {
+      expect(calculateWordCount("Hello world, this is a short post.")).toBe(7);
+      expect(calculateWordCount(Array(600).fill("word").join(" "))).toBe(600);
+    });
+
+    test("Chinese characters count per-character", () => {
+      expect(calculateWordCount("中".repeat(600))).toBe(600);
+    });
+
+    test("mixed Latin + Chinese sums both counts", () => {
+      const latin = Array(200).fill("word").join(" ");
+      const han = "中".repeat(300);
+      expect(calculateWordCount(`${latin} ${han}`)).toBe(500);
+    });
+
+    test("strips fenced code blocks before counting", () => {
+      const src = ["pre", "```", "code line one two three", "```", "post"].join("\n");
+      // Only "pre" and "post" count.
+      expect(calculateWordCount(src)).toBe(2);
+    });
+
+    test("strips inline HTML tags before counting", () => {
+      expect(calculateWordCount("hello <span>world</span> again")).toBe(3);
+    });
+
+    test("strips markdown link syntax, keeps link text", () => {
+      expect(calculateWordCount("See [the docs](https://example.com) here")).toBe(4);
+    });
+
+    test("matches calculateReadingMinutes on the same input", () => {
+      // The two metrics share a tokenizer; both should agree on the underlying
+      // token counts. 600 Latin words → 600 wordCount, 3-minute reading time.
+      const text = Array(600).fill("word").join(" ");
+      expect(calculateWordCount(text)).toBe(600);
+      expect(calculateReadingMinutes(text)).toBe(3);
     });
   });
 

package/src/lib/markdown.ts

@@ -123,7 +123,8 @@ export interface PostData {
   commentable?: boolean;
   externalLinks?: ExternalLink[];
   redirectFrom?: string[];
-  readingTime: string;
+  readingMinutes: number;
+  wordCount: number;
   content: string;
   renderedHtml?: string;
   plainText?: string;
@@ -263,11 +264,10 @@ function shouldUsePythonRstRenderer(): boolean {
   return process.env.NODE_ENV !== 'test';
 }
 
-export function calculateReadingTime(content: string): string {
-  const wordsPerMinute = 200;
-  const hanCharsPerMinute = 300;
-
-  // Strip tags and common markdown syntax before counting.
+// Shared text-stripping + tokenization used by both `calculateReadingMinutes`
+// and `calculateWordCount`. Both metrics need the same view of "what counts
+// as a word," so funnel them through a single source of truth.
+function countContentTokens(content: string): { latinWords: number; hanChars: number } {
   const text = content
     .replace(/<\/?[^>]+(>|$)/g, "")
     .replace(/```[\s\S]*?```/g, "")
@@ -275,15 +275,47 @@ export function calculateReadingTime(content: string): string {
     .replace(/!\[[^\]]*\]\([^)]+\)/g, "")
     .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
     .replace(/[#*_~>\-[\]()]/g, " ");
+  return countTokenizedText(text);
+}
+
+function countTokenizedText(text: string): { latinWords: number; hanChars: number } {
+  const hanChars = (text.match(HAN_CHAR_RE) || []).length;
+  const latinWords = (text.match(LATIN_WORD_RE) || []).length;
+  return { latinWords, hanChars };
+}
+
+// Han character ranges: CJK Unified Ideographs Extension A, CJK Unified
+// Ideographs, CJK Compatibility Ideographs.
+const HAN_CHAR_RE = /[㐀-䶿一-鿿豈-﫿]/g;
+// Latin word: alphanumeric runs allowing apostrophes/hyphens between runs.
+const LATIN_WORD_RE = /[A-Za-z0-9]+(?:['’-][A-Za-z0-9]+)*/g;
 
-  const hanCharCount = (text.match(/[\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF]/g) || []).length;
-  const latinWordCount = (text.match(/[A-Za-z0-9]+(?:['’-][A-Za-z0-9]+)*/g) || []).length;
+/**
+ * Estimated minutes-to-read, ceiled to a whole minute and floored at 1.
+ * Returns a raw number so layouts can localize via `t('reading_time')`
+ * — store-as-number rather than pre-baked "N min read" string lets
+ * the locale switch take effect at render time.
+ */
+export function calculateReadingMinutes(content: string): number {
+  const wordsPerMinute = 200;
+  const hanCharsPerMinute = 300;
+  const { latinWords, hanChars } = countContentTokens(content);
+  const estimatedMinutes = (latinWords / wordsPerMinute) + (hanChars / hanCharsPerMinute);
+  return Math.max(1, Math.ceil(estimatedMinutes));
+}
 
-  const estimatedMinutes = (latinWordCount / wordsPerMinute) + (hanCharCount / hanCharsPerMinute);
-  const minutes = Math.max(1, Math.ceil(estimatedMinutes));
-  return `${minutes} min read`;
+/**
+ * Aggregate word count: Latin word matches plus Han characters.
+ * Han is counted per-character (the convention in Chinese typography
+ * — "字数" literally means "character count") while Latin counts per
+ * whitespace-bounded token. Returns 0 for empty input.
+ */
+export function calculateWordCount(content: string): number {
+  const { latinWords, hanChars } = countContentTokens(content);
+  return latinWords + hanChars;
 }
 
+
 export function generateExcerpt(content: string): string {
   let plain = content.replace(/^#+\s+/gm, '');
   plain = plain.replace(/```[\s\S]*?```/g, '');
@@ -608,8 +640,9 @@ function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: st
   }
 
   const excerpt = data.excerpt || generateExcerpt(contentWithoutH1);
-  const readingTime = calculateReadingTime(contentWithoutH1);
-  
+  const readingMinutes = calculateReadingMinutes(contentWithoutH1);
+  const wordCount = calculateWordCount(contentWithoutH1);
+
   let date = data.date;
   if (!date && dateFromFileName) date = dateFromFileName;
   if (!date) date = fs.statSync(fullPath).mtime.toISOString().split('T')[0];
@@ -647,7 +680,8 @@ function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: st
     items: data.items as CollectionItem[] | undefined,
     externalLinks: data.externalLinks,
     redirectFrom: data.redirectFrom,
-    readingTime,
+    readingMinutes,
+    wordCount,
     content: contentWithoutH1,
     headings,
     imageBaseSlug,
@@ -680,7 +714,8 @@ function parseRstFile(
     let parsedText: string | undefined;
     let parsedHeadings: Heading[];
     let parsedExcerpt: string;
-    let parsedReadingTime: string;
+    let parsedReadingMinutes: number;
+    let parsedWordCount: number;
     let parsedHtml: string | undefined;
     let data: ReturnType<typeof parseRstDocument>['metadata'];
     try {
@@ -691,7 +726,8 @@ function parseRstFile(
         parsedText = rendered.text;
         parsedHeadings = rendered.headings;
         parsedExcerpt = rendered.excerpt;
-        parsedReadingTime = rendered.readingTime;
+        parsedReadingMinutes = rendered.readingMinutes;
+        parsedWordCount = rendered.wordCount;
         parsedHtml = rendered.html;
         data = rendered.metadata;
       } else if (shouldUsePythonRstRenderer() && pythonRstRendererAvailable !== false) {
@@ -702,7 +738,8 @@ function parseRstFile(
         parsedText = rendered.text;
         parsedHeadings = rendered.headings;
         parsedExcerpt = rendered.excerpt;
-        parsedReadingTime = rendered.readingTime;
+        parsedReadingMinutes = rendered.readingMinutes;
+        parsedWordCount = rendered.wordCount;
         parsedHtml = rendered.html;
         data = rendered.metadata;
       } else {
@@ -720,7 +757,8 @@ function parseRstFile(
       parsedBody = parsed.body;
       parsedHeadings = parsed.headings;
       parsedExcerpt = parsed.excerpt;
-      parsedReadingTime = parsed.readingTime;
+      parsedReadingMinutes = parsed.readingMinutes;
+      parsedWordCount = parsed.wordCount;
       data = parsed.metadata;
     }
 
@@ -783,7 +821,8 @@ function parseRstFile(
       toc: data.toc ?? true,
       commentable: data.commentable,
       redirectFrom: data.redirectFrom ?? [],
-      readingTime: parsedReadingTime,
+      readingMinutes: parsedReadingMinutes,
+      wordCount: parsedWordCount,
       content: parsedBody,
       renderedHtml: parsedHtml,
       plainText: parsedText,
@@ -1456,14 +1495,32 @@ export function getCollectionsForPost(postSlug: string): CollectionContext[] {
 export interface BookChapterEntry {
   title: string;
   id: string;
+  /** Legacy single-level grouping; set when the chapter sits under a `{ part, chapters }` item. */
   part?: string;
+  /** Deepest section title above this chapter (last element of sectionPath). */
+  section?: string;
+  /** Full ancestry of section titles from outermost to innermost. */
+  sectionPath?: string[];
+}
+
+export interface BookChapterRef {
+  title: string;
+  id: string;
 }
 
 export interface BookTocPart {
   part: string;
-  chapters: { title: string; id: string }[];
+  chapters: BookChapterRef[];
 }
-export type BookTocItem = BookTocPart | { title: string; id: string };
+
+/** Nested grouping. `items` may recurse into further sections or hold leaf chapter refs. */
+export interface BookTocSection {
+  section: string;
+  collapsible?: boolean;
+  items: Array<BookTocSection | BookChapterRef>;
+}
+
+export type BookTocItem = BookTocPart | BookTocSection | BookChapterRef;
 
 export interface BookData {
   title: string;
@@ -1474,6 +1531,16 @@ export interface BookData {
   featured: boolean;
   draft: boolean;
   authors: string[];
+  /** Book-level LaTeX flag — when true, all chapters render math even if their
+   *  own frontmatter omits `latex: true`. Cheaper for math-heavy books than
+   *  annotating every chapter file. */
+  latex: boolean;
+  /** Whether the chapter-page header renders the chapter's `excerpt`. Defaults
+   *  to false: the typical case is that a chapter opens with its own lede
+   *  paragraph, and an excerpt line above it just duplicates that text in the
+   *  header. Set to true on books where the excerpt is a distinct subtitle
+   *  the author actually wants the reader to see at the top of every chapter. */
+  showChapterExcerpt: boolean;
   content: string;
   toc: BookTocItem[];
   chapters: BookChapterEntry[];
@@ -1488,8 +1555,11 @@ export interface BookChapterData {
   excerpt?: string;
   latex: boolean;
   commentable?: boolean;
-  readingTime: string;
+  readingMinutes: number;
+  wordCount: number;
   isFolder: boolean;
+  /** Absolute path of the markdown source file. Used to resolve relative `.md` links. */
+  sourcePath: string;
   prevChapter: { title: string; id: string } | null;
   nextChapter: { title: string; id: string } | null;
 }
@@ -1499,15 +1569,25 @@ const BookChapterRefSchema = z.object({
   id: z.string(),
 });
 
+// Recursive: a section can nest further sections or leaf chapter refs.
+const BookTocSectionSchema: z.ZodType<BookTocSection> = z.lazy(() =>
+  z.object({
+    section: z.string(),
+    collapsible: z.boolean().optional(),
+    items: z.array(z.union([BookTocSectionSchema, BookChapterRefSchema])),
+  })
+);
+
 const BookTocItemSchema: z.ZodType<BookTocItem> = z.union([
   z.object({
     part: z.string(),
     chapters: z.array(BookChapterRefSchema),
   }),
+  BookTocSectionSchema,
   BookChapterRefSchema,
 ]);
 
-const BookSchema = z.object({
+export const BookSchema = z.object({
   title: z.string(),
   excerpt: z.string().optional(),
   date: z.union([z.string(), z.date()]).transform(val => new Date(val).toISOString().split('T')[0]),
@@ -1515,24 +1595,47 @@ const BookSchema = z.object({
   featured: z.boolean().optional().default(false),
   draft: z.boolean().optional().default(false),
   authors: z.array(z.string()).optional().default([]),
+  latex: z.boolean().optional().default(false),
+  showChapterExcerpt: z.boolean().optional().default(false),
   chapters: z.array(BookTocItemSchema),
 });
 
 const BookChapterSchema = z.object({
-  title: z.string(),
+  title: z.string().optional(),
   excerpt: z.string().optional(),
   draft: z.boolean().optional().default(false),
   latex: z.boolean().optional().default(false),
   commentable: z.boolean().optional(),
 });
 
-function flattenBookChapters(toc: BookTocItem[]): BookChapterEntry[] {
+export function flattenBookChapters(toc: BookTocItem[]): BookChapterEntry[] {
   const result: BookChapterEntry[] = [];
+
+  const walkSection = (
+    items: Array<BookTocSection | BookChapterRef>,
+    sectionPath: string[],
+  ): void => {
+    for (const item of items) {
+      if ('section' in item) {
+        walkSection(item.items, [...sectionPath, item.section]);
+      } else {
+        result.push({
+          title: item.title,
+          id: item.id,
+          section: sectionPath[sectionPath.length - 1],
+          sectionPath: sectionPath.length > 0 ? [...sectionPath] : undefined,
+        });
+      }
+    }
+  };
+
   for (const item of toc) {
     if ('part' in item) {
       for (const ch of item.chapters) {
         result.push({ title: ch.title, id: ch.id, part: item.part });
       }
+    } else if ('section' in item) {
+      walkSection([item], []);
     } else {
       result.push({ title: item.title, id: item.id });
     }
@@ -1540,6 +1643,35 @@ function flattenBookChapters(toc: BookTocItem[]): BookChapterEntry[] {
   return result;
 }
 
+/**
+ * Resolves a chapter id (possibly nested with `/`) to a markdown file on disk.
+ * Returns `{ path, isFolder }` if a file exists in one of the four supported forms,
+ * or `null` if the id has no match. Guards against `..`-style path escapes — any
+ * id that resolves outside `bookDir` returns null.
+ */
+function resolveChapterFilePath(
+  bookDir: string,
+  chapterId: string,
+): { path: string; isFolder: boolean } | null {
+  const bookDirResolved = path.resolve(bookDir);
+  const candidate = path.resolve(bookDir, chapterId);
+  if (
+    candidate !== bookDirResolved &&
+    !candidate.startsWith(bookDirResolved + path.sep)
+  ) {
+    return null;
+  }
+  const chMdx = `${candidate}.mdx`;
+  const chMd = `${candidate}.md`;
+  const chFolderMdx = path.join(candidate, 'index.mdx');
+  const chFolderMd = path.join(candidate, 'index.md');
+  if (fs.existsSync(chMdx)) return { path: chMdx, isFolder: false };
+  if (fs.existsSync(chMd)) return { path: chMd, isFolder: false };
+  if (fs.existsSync(chFolderMdx)) return { path: chFolderMdx, isFolder: true };
+  if (fs.existsSync(chFolderMd)) return { path: chFolderMd, isFolder: true };
+  return null;
+}
+
 export function getBookData(slug: string): BookData | null {
   if (!fs.existsSync(booksDirectory)) return null;
   const bookDir = path.join(booksDirectory, slug);
@@ -1562,17 +1694,22 @@ export function getBookData(slug: string): BookData | null {
   }
   const data = parsed.data;
 
-  // Warn about missing chapter files
+  // Resolve chapter file paths and surface missing files as build-time errors
+  // (strict-build invariant: misconfiguration must fail loudly, not silently).
   const chapters = flattenBookChapters(data.chapters);
+  const missing: string[] = [];
   for (const ch of chapters) {
-    const chMdx = path.join(bookDir, `${ch.id}.mdx`);
-    const chMd = path.join(bookDir, `${ch.id}.md`);
-    const chFolderMdx = path.join(bookDir, ch.id, 'index.mdx');
-    const chFolderMd = path.join(bookDir, ch.id, 'index.md');
-    if (!fs.existsSync(chMdx) && !fs.existsSync(chMd) && !fs.existsSync(chFolderMdx) && !fs.existsSync(chFolderMd)) {
-      console.warn(`Book "${slug}": chapter "${ch.id}" not found`);
+    if (!resolveChapterFilePath(bookDir, ch.id)) {
+      missing.push(ch.id);
     }
   }
+  if (missing.length > 0) {
+    throw new Error(
+      `[amytis] Book "${slug}" references chapter${missing.length === 1 ? '' : 's'} ` +
+      `with no matching file on disk: ${missing.map(id => `"${id}"`).join(', ')}. ` +
+      `Expected one of <bookDir>/<id>.{md,mdx} or <bookDir>/<id>/index.{md,mdx}.`
+    );
+  }
 
   let coverImage = data.coverImage;
   if (coverImage && !coverImage.startsWith('http') && !coverImage.startsWith('/') && !coverImage.startsWith('text:')) {
@@ -1594,6 +1731,8 @@ export function getBookData(slug: string): BookData | null {
     featured: data.featured,
     draft: data.draft,
     authors,
+    latex: data.latex,
+    showChapterExcerpt: data.showChapterExcerpt,
     content: content.trim(),
     toc: data.chapters,
     chapters,
@@ -1605,17 +1744,9 @@ export function getBookChapter(bookSlug: string, chapterSlug: string): BookChapt
   if (!book) return null;
 
   const bookDir = path.join(booksDirectory, bookSlug);
-  const chMdx = path.join(bookDir, `${chapterSlug}.mdx`);
-  const chMd = path.join(bookDir, `${chapterSlug}.md`);
-  const chFolderMdx = path.join(bookDir, chapterSlug, 'index.mdx');
-  const chFolderMd = path.join(bookDir, chapterSlug, 'index.md');
-  let fullPath = '';
-  let isFolder = false;
-  if (fs.existsSync(chMdx)) fullPath = chMdx;
-  else if (fs.existsSync(chMd)) fullPath = chMd;
-  else if (fs.existsSync(chFolderMdx)) { fullPath = chFolderMdx; isFolder = true; }
-  else if (fs.existsSync(chFolderMd)) { fullPath = chFolderMd; isFolder = true; }
-  else return null;
+  const resolved = resolveChapterFilePath(bookDir, chapterSlug);
+  if (!resolved) return null;
+  const { path: fullPath, isFolder } = resolved;
 
   const fileContents = fs.readFileSync(fullPath, 'utf8');
   const { data: rawData, content } = matter(fileContents);
@@ -1633,7 +1764,8 @@ export function getBookChapter(bookSlug: string, chapterSlug: string): BookChapt
 
   const contentWithoutH1 = content.replace(/^\s*#\s+[^\n]+/, '').trim();
   const headings = getHeadings(content);
-  const readingTime = calculateReadingTime(contentWithoutH1);
+  const readingMinutes = calculateReadingMinutes(contentWithoutH1);
+  const wordCount = calculateWordCount(contentWithoutH1);
   const excerpt = data.excerpt || generateExcerpt(contentWithoutH1);
 
   // Find prev/next
@@ -1641,22 +1773,40 @@ export function getBookChapter(bookSlug: string, chapterSlug: string): BookChapt
   const prevChapter = chapterIndex > 0 ? book.chapters[chapterIndex - 1] : null;
   const nextChapter = chapterIndex < book.chapters.length - 1 ? book.chapters[chapterIndex + 1] : null;
 
+  // Title resolution: frontmatter wins, then book TOC entry, then first H1
+  // in the body. VuePress chapters often omit frontmatter entirely and rely
+  // on the H1 as the title, so this fallback chain keeps the import flow lossless.
+  const fallbackFromToc = chapterIndex >= 0 ? book.chapters[chapterIndex].title : undefined;
+  const h1Match = content.match(/^\s*#\s+([^\n]+)/);
+  const fallbackFromH1 = h1Match?.[1].trim();
+  const title = data.title || fallbackFromToc || fallbackFromH1 || chapterSlug;
+
   return {
-    title: data.title,
+    title,
     slug: chapterSlug,
     bookSlug,
     content: contentWithoutH1,
     headings,
     excerpt,
-    latex: data.latex,
+    // Chapter-level `latex: true` takes precedence; otherwise inherit the
+    // book-level flag so math-heavy books don't need per-chapter annotation.
+    latex: data.latex || book.latex,
     commentable: data.commentable,
-    readingTime,
+    readingMinutes,
+    wordCount,
     isFolder,
+    sourcePath: fullPath,
     prevChapter: prevChapter ? { title: prevChapter.title, id: prevChapter.id } : null,
     nextChapter: nextChapter ? { title: nextChapter.title, id: nextChapter.id } : null,
   };
 }
 
+/** Absolute path of a book's content directory. Useful for plugins that
+ *  need to resolve relative paths from chapter source files. */
+export function getBookDirPath(bookSlug: string): string {
+  return path.join(booksDirectory, bookSlug);
+}
+
 export function getAllBooks(): BookData[] {
   if (!fs.existsSync(booksDirectory)) return [];
 
@@ -1874,7 +2024,8 @@ export interface NoteData {
   content: string;
   excerpt: string;
   headings: Heading[];
-  readingTime: string;
+  readingMinutes: number;
+  wordCount: number;
 }
 
 function parseNoteFile(fullPath: string, slug: string): NoteData {
@@ -1892,7 +2043,8 @@ function parseNoteFile(fullPath: string, slug: string): NoteData {
   const date = data.date || fs.statSync(fullPath).mtime.toISOString().split('T')[0];
   const excerpt = generateExcerpt(contentWithoutH1);
   const headings = getHeadings(content);
-  const readingTime = calculateReadingTime(contentWithoutH1);
+  const readingMinutes = calculateReadingMinutes(contentWithoutH1);
+  const wordCount = calculateWordCount(contentWithoutH1);
 
   return {
     slug,
@@ -1907,7 +2059,8 @@ function parseNoteFile(fullPath: string, slug: string): NoteData {
     content: contentWithoutH1,
     excerpt,
     headings,
-    readingTime,
+    readingMinutes,
+    wordCount,
   };
 }
 

package/src/lib/normalize-vuepress-math.ts

@@ -0,0 +1,118 @@
+const FENCE_OPEN_RE = /^[ \t]*(`{3,}|~{3,})/;
+
+/**
+ * VuePress's math plugin accepts block math with the `$$` markers on the
+ * same line as the math body — `$$ \mathbf{A} = \begin{bmatrix}` opening
+ * and `\end{bmatrix} $$` closing. `remark-math` (the upstream micromark
+ * extension) is stricter: a block-math opener must be on its own line and
+ * the closer must be on its own line. When that's violated, the parser
+ * falls back to *inline* math — which either explodes in KaTeX (when the
+ * body contains `\\` line breaks or `&` column separators) or silently
+ * mis-renders as inline (no `katex-display` wrapper, so it loses block
+ * margin and centering even though it visually looks fine).
+ *
+ * This pre-processor splits VuePress-style fences onto their own lines
+ * before parsing, so imported chapters render correctly without touching
+ * their source files. Two cases:
+ *
+ *   $$ \mathbf{A} = \begin{bmatrix}        $$
+ *   a & b \\               becomes →       \mathbf{A} = \begin{bmatrix}
+ *   c & d                                  a & b \\
+ *   \end{bmatrix} $$                       c & d
+ *                                          \end{bmatrix}
+ *                                          $$
+ *
+ *                                          $$
+ *   $$ x = y $$           becomes →        x = y
+ *                                          $$
+ *
+ * - Inline math (`$x$`, with a single `$`) is never matched — only `$$`.
+ * - Empty single-line blocks (`$$$$`, `$$  $$`) are left alone.
+ * - Fenced code blocks (``` and ~~~) are skipped so code samples that
+ *   *show* the VuePress syntax verbatim aren't mutated. Fence semantics
+ *   match CommonMark: closer must be the same character type and at
+ *   least as long as the opener.
+ *
+ * Idempotent: re-running on already-normalized content is a no-op, so
+ * it's safe to apply unconditionally whenever LaTeX rendering is on.
+ */
+export function normalizeVuepressBlockMath(source: string): string {
+  const lines = source.split('\n');
+  const out: string[] = [];
+  let inMath = false;
+  let openFence: string | null = null;
+  // Indent of the current block-math opener — preserved on every emitted
+  // synthetic line so list-item-nested math (4-space indent inside a `-`
+  // bullet) doesn't lose its list context when we split the opener / closer.
+  let blockIndent = '';
+
+  for (const line of lines) {
+    if (openFence !== null) {
+      // Inside a code fence — pass through verbatim, just track close.
+      out.push(line);
+      const closeRe = new RegExp(`^[ \\t]*${openFence[0]}{${openFence.length},}\\s*$`);
+      if (closeRe.test(line)) openFence = null;
+      continue;
+    }
+
+    const fenceOpen = line.match(FENCE_OPEN_RE);
+    if (fenceOpen) {
+      openFence = fenceOpen[1];
+      out.push(line);
+      continue;
+    }
+
+    if (!inMath) {
+      // Match an opener with content tacked on after `$$`. The trimmed body
+      // must NOT itself end in `$$` — that would make it a single-line block.
+      const m = line.match(/^([ \t]*)\$\$(.+)$/);
+      if (m) {
+        const rest = m[2].trimEnd();
+        if (rest.endsWith('$$')) {
+          // Single-line block math like `$$ x $$`. micromark-extension-math
+          // parses this as *inline* math (no `katex-display` wrapper), so
+          // expand it to opener / body / closer on three lines.
+          const body = rest.slice(0, -2).trim();
+          if (body.length === 0) {
+            // `$$$$` or `$$  $$` — degenerate, leave alone.
+            out.push(line);
+            continue;
+          }
+          out.push(`${m[1]}$$`);
+          out.push(`${m[1]}${body}`);
+          out.push(`${m[1]}$$`);
+          continue;
+        }
+        blockIndent = m[1];
+        out.push(`${blockIndent}$$`);
+        // Re-apply the opener's indent on the math body so list-nested
+        // blocks stay inside their list item. Trim only the gap between
+        // `$$` and the actual math content (e.g. `$$ \mathbf{A}` → `\mathbf{A}`).
+        out.push(`${blockIndent}${m[2].trimStart()}`);
+        inMath = true;
+        continue;
+      }
+      out.push(line);
+      continue;
+    }
+
+    // Inside a block-math run started above. Look for an inline closer.
+    const close = line.match(/^(.*?)[ \t]*\$\$[ \t]*$/);
+    if (close && !line.trim().startsWith('$$')) {
+      // Closer with content before `$$` on the same line — split.
+      // `close[1]` already includes its own leading whitespace, so we don't
+      // need to re-apply blockIndent to it; we only need to indent the `$$`.
+      if (close[1].length > 0) out.push(close[1]);
+      out.push(`${blockIndent}$$`);
+      inMath = false;
+      blockIndent = '';
+      continue;
+    }
+    out.push(line);
+    if (line.trim() === '$$') {
+      inMath = false;
+      blockIndent = '';
+    }
+  }
+  return out.join('\n');
+}