explico 0.13.1 → 0.14.0

package/src/compiler/exports/latex-export.ts

@@ -4,11 +4,12 @@ import { dirname, extname, join } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 
-import type { Manifest } from '../manifest';
-import type { StaticPage } from './static-tree';
+import type { Manifest, ManifestLesson } from '../manifest';
+import type { Block } from './static-tree';
 import { zip } from './zip';
 import {
   consoleLogger,
+  deckBlocks,
   epochOf,
   figuresOf,
   imageFile,
@@ -19,9 +20,21 @@ import {
   type ExportLogger,
   type PreparedChapters,
 } from './export-chapters';
+import type { CaptureResults } from './latex/capture';
+import { latexCacheFromEnvironment } from './latex/cache';
 import { compileLatex, missingCharacters, findLatexEngine } from './latex/compile';
-import { bookSource, chapterFolderName, chapterSource, type BookPart, type SourceFile } from './latex/document';
-import { courseFileStem } from './export-pages';
+import { deckNumberingProblems, deckOverflows, deckSource } from './latex/deck';
+import {
+  bookSince,
+  bookSource,
+  chapterFolderName,
+  chapterSource,
+  deckCheckItems,
+  type BookPart,
+  type BookSlidesLesson,
+  type SourceFile,
+} from './latex/document';
+import { courseFileStem, deckFileStem, deckOwnerSlug, deckSaveName } from './export-pages';
 import { auxLabels, numberingMismatches, websiteNumbers } from './latex/numbering';
 
 export type { ExportLogger } from './export-chapters';
@@ -32,61 +45,107 @@ export type { ExportLogger } from './export-chapters';
  * figures — is zipped to `downloads/<slug>-latex.zip`, and the same folder is
  * compiled to `downloads/<slug>.pdf`. Each part and the course are books
  * (`bookSource`): `downloads/part/<dir>-latex.zip` and `.pdf`,
- * `downloads/course-latex.zip` and `.pdf`. Every document compiles at once,
- * up to one per core.
+ * `downloads/course-latex.zip` and `.pdf`. Each deck is beamer slides
+ * (`latex/deck.ts`): `downloads/<lesson>-slides.pdf`, its handout
+ * `-slides-notes.pdf` and its source `-slides-latex.zip`; a book keeps a
+ * slides-first lesson's place with a short chapter. Every document compiles at once,
+ * up to one per core, the longest first. With `EXPLICO_LATEX_CACHE` set, a
+ * document whose folder a build already compiled is reused (`latex/cache.ts`).
  *
- * The build fails when a compiled number differs from the website's, when
- * LaTeX reports an error, and — in CI (`CI` set) or with
+ * The build fails when a compiled number differs from the website's (a
+ * deck's frame numbers included), when LaTeX reports an error, and — in CI (`CI` set) or with
  * `EXPLICO_LATEX_STRICT=1` — when the TeX engine or the browser for figures
  * is missing. On a developer's machine without them it warns and still
  * writes the source zips.
  */
 
+/**
+ * The pictures of a page's figures, by anchor: what the capture pass drew,
+ * or the image the page shows. `drawnOn` says which page drew a figure (a
+ * deck's recalled figure is its chapter's); `folder` is where the pictures
+ * go in the document's folder.
+ */
 async function pagePictures(
   outputRoot: string,
   base: string,
-  page: StaticPage,
-  captured: ReadonlyMap<string, { pdf: Uint8Array }> | undefined,
+  page: { readonly route: string; readonly blocks: readonly Block[] },
+  captures: CaptureResults,
+  drawnOn: (anchor: string) => string = () => page.route,
+  folder = `figures/${page.route}`,
 ): Promise<Map<string, { path: string; content: Uint8Array }>> {
   const pictures = new Map<string, { path: string; content: Uint8Array }>();
   for (const figure of figuresOf(page.blocks)) {
-    const capturedFigure = captured?.get(figure.anchor);
+    const capturedFigure = captures.get(drawnOn(figure.anchor))?.get(figure.anchor);
     if (capturedFigure) {
-      pictures.set(figure.anchor, {
-        path: `figures/${page.route}/${figure.anchor}.pdf`,
-        content: capturedFigure.pdf,
-      });
+      pictures.set(figure.anchor, { path: `${folder}/${figure.anchor}.pdf`, content: capturedFigure.pdf });
       continue;
     }
     if (figure.picture.kind !== 'image' || needsCapture(figure)) continue;
     const file = imageFile(outputRoot, base, page.route, figure.picture.src);
     pictures.set(figure.anchor, {
-      path: `figures/${page.route}/${figure.anchor}${extname(file).toLowerCase()}`,
+      path: `${folder}/${figure.anchor}${extname(file).toLowerCase()}`,
       content: await readFile(file),
     });
   }
   return pictures;
 }
 
+/** What a slides-first lesson's place in a book says: its outcomes and where its slides are. */
+function slidesLesson(manifest: Manifest, lesson: ManifestLesson): BookSlidesLesson {
+  const byId = new Map(manifest.competencies.map((competency) => [competency.id, competency]));
+  const outcomes = lesson.teaches.flatMap((id) => {
+    const outcome = byId.get(id)?.outcome;
+    return typeof outcome === 'string' && outcome.trim() !== '' ? [outcome.trim()] : [];
+  });
+  const base = manifest.lessonExports.canonicalBaseUrl;
+  return { lesson, outcomes, ...(base ? { slidesUrl: `${base}${lesson.slug}/` } : {}) };
+}
+
 interface PendingFile {
   readonly target: string;
   readonly content: Uint8Array;
 }
 
-/** `work` over every item, at most `limit` at a time; results in the items' order. */
-async function mapWithLimit<T, R>(items: readonly T[], limit: number, work: (item: T) => Promise<R>): Promise<R[]> {
+/**
+ * `work` over every item, at most `limit` at a time, started in `order` (the
+ * items' indices, by default their own order); results in the items' order.
+ */
+export async function mapWithLimit<T, R>(
+  items: readonly T[],
+  limit: number,
+  work: (item: T) => Promise<R>,
+  order: readonly number[] = items.map((_item, index) => index),
+): Promise<R[]> {
   const results: R[] = new Array(items.length);
   let next = 0;
   const worker = async () => {
-    while (next < items.length) {
-      const index = next++;
+    while (next < order.length) {
+      const index = order[next++]!;
       results[index] = await work(items[index]!);
     }
   };
-  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, order.length)) }, worker));
   return results;
 }
 
+/**
+ * The order to start documents in: the course, then the parts, then the
+ * chapters, the largest folder first within each. The course takes longest
+ * and is the one document a cache never reuses after a change; started last,
+ * it ran alone at the end while the other cores had nothing left to do.
+ */
+export function startOrder(
+  jobs: readonly { readonly kind: 'chapter' | 'deck' | 'part' | 'course'; readonly files: readonly SourceFile[] }[],
+): number[] {
+  const rank = { course: 0, part: 1, chapter: 2, deck: 2 } as const;
+  const size = jobs.map(({ files }) =>
+    files.reduce((sum, file) => sum + (typeof file.content === 'string' ? Buffer.byteLength(file.content) : file.content.byteLength), 0),
+  );
+  return jobs
+    .map((_job, index) => index)
+    .sort((a, b) => rank[jobs[a]!.kind] - rank[jobs[b]!.kind] || size[b]! - size[a]! || a - b);
+}
+
 /**
  * Write each chapter's, each part's and the course's LaTeX source zip and PDF
  * under `downloads/`, from the chapters `prepareChapters` read and drew (read
@@ -105,7 +164,7 @@ export async function writeLatexExports(
   const logger = options.logger ?? consoleLogger;
   const strict = strictMode();
   const outputRoot = fileURLToPath(directory);
-  const { base, chapters, captures } =
+  const { base, chapters, decks, captures } =
     options.prepared ?? (await prepareChapters(outputRoot, manifest, { logger, projectRoot: options.projectRoot }));
 
   const engine = await findLatexEngine();
@@ -116,17 +175,25 @@ export async function writeLatexExports(
 
   /** One LaTeX document: its folder, where its zip and PDF go, and the numbers it must print. */
   interface Job {
-    readonly kind: 'chapter' | 'part' | 'course';
+    readonly kind: 'chapter' | 'deck' | 'part' | 'course';
     readonly name: string;
     readonly files: SourceFile[];
     readonly target: string;
     readonly folder: string;
-    readonly website: Map<string, string>;
+    /** No source zip of its own: a deck's handout is built from its slides' folder. */
+    readonly noZip?: boolean;
+    /** Where LaTeX's numbers differ from the website's, from the compiled `.aux`. */
+    readonly numbering: (aux: string) => string[];
+    /** What else its log says that a reader would see: a deck's frames that run over on paper. */
+    readonly review?: (log: string) => void;
+    /** The version the document's content is at (rule C5): its date, and its cache key through its files. */
+    readonly since: string | null;
   }
   const jobs: Job[] = [];
+  const againstWebsite = (website: Map<string, string>) => (aux: string) => numberingMismatches(website, auxLabels(aux));
   const pictures = new Map<string, Awaited<ReturnType<typeof pagePictures>>>();
   for (const { lesson, page } of chapters) {
-    const chapterPictures = await pagePictures(outputRoot, base, page, captures.get(page.route));
+    const chapterPictures = await pagePictures(outputRoot, base, page, captures);
     pictures.set(lesson.id, chapterPictures);
     jobs.push({
       kind: 'chapter',
@@ -134,8 +201,57 @@ export async function writeLatexExports(
       files: chapterSource({ manifest, lesson, page, documentRoutes: new Set([page.route]), pictures: chapterPictures }),
       target: lesson.slug,
       folder: chapterFolderName(lesson),
-      website: websiteNumbers(page, `${lesson.part}.${lesson.chapter}`),
+      numbering: againstWebsite(websiteNumbers(page, `${lesson.part}.${lesson.chapter}`)),
+      since: lesson.since,
+    });
+  }
+
+  // Each deck as beamer slides, and as a handout of each slide with its notes:
+  // a lesson's, named after the lesson, and a part's, after the part.
+  const lessonsById = new Map(manifest.lessons.map((lesson) => [lesson.id, lesson]));
+  for (const { deck, page, figureRoutes } of decks) {
+    if (deck.part === undefined && !lessonsById.has(deck.lessonId ?? '')) continue;
+    const owner = deckOwnerSlug(deck, manifest);
+    const deckPictures = await pagePictures(
+      outputRoot,
+      base,
+      { route: page.route, blocks: deckBlocks(page) },
+      captures,
+      (anchor) => figureRoutes.get(anchor) ?? page.route,
+      'figures',
+    );
+    const { files, frameEnds } = deckSource({ manifest, deck, page, checkItems: deckCheckItems(manifest, deck), pictures: deckPictures });
+    const stem = deckFileStem(owner);
+    const numbering = (aux: string) => deckNumberingProblems(aux, page.frames.length);
+    const common = { kind: 'deck', folder: `${deckSaveName(owner)}-latex`, numbering, since: deck.since } as const;
+    jobs.push({
+      ...common,
+      name: stem,
+      files,
+      target: stem,
+      review: (log) => {
+        const over = deckOverflows(log, frameEnds);
+        if (over.length === 0) return;
+        logger.warn(
+          `LaTeX export: on paper, ${over.length === 1 ? 'a slide' : `${over.length} slides`} of ${stem} ` +
+            `run${over.length === 1 ? 's' : ''} over the bottom: ` +
+            `${over.map(({ frame, points }) => `slide ${frame} by ${points} pt`).join(', ')}. ` +
+            'The web page fits them (rule D2), but the PDF cuts them off. Shorten the slide, or split it.',
+        );
+      },
     });
+    if (manifest.deck.handoutPdf && manifest.deck.notes !== 'off') {
+      const handout = files.find((file) => file.path === 'handout.tex')!;
+      jobs.push({
+        ...common,
+        name: `${stem}-notes`,
+        files: files.flatMap((file) =>
+          file.path === 'handout.tex' ? [] : file.path === 'main.tex' ? [{ path: 'main.tex', content: handout.content }] : [file],
+        ),
+        target: `${stem}-notes`,
+        noZip: true,
+      });
+    }
   }
 
   // Each part, and the course, as a book (plan step 6).
@@ -147,11 +263,16 @@ export async function writeLatexExports(
       const chapter = byId.get(id);
       return chapter ? [{ ...chapter, pictures: pictures.get(id)! }] : [];
     });
+    // A slides-first lesson keeps its place: the chapters after it keep their numbers.
+    const slides = part.lessons.flatMap((id) => {
+      const lesson = lessonsById.get(id);
+      return lesson && !lesson.editions.includes('chapter') ? [slidesLesson(manifest, lesson)] : [];
+    });
     if (partChapters.length === 0) continue;
     const overview = pageSlugs.has(`${part.dir}/index`)
       ? (await readBuiltPage(outputRoot, `${part.dir}/index`)).page
       : undefined;
-    parts.push({ part, ...(overview ? { overview } : {}), chapters: partChapters });
+    parts.push({ part, ...(overview ? { overview } : {}), chapters: partChapters, ...(slides.length > 0 ? { slides } : {}) });
   }
   const bookNumbers = (bookParts: readonly BookPart[]) =>
     new Map(
@@ -173,7 +294,8 @@ export async function writeLatexExports(
       }),
       target: `part/${entry.part.dir}`,
       folder: `${entry.part.dir}-latex`,
-      website: bookNumbers([entry]),
+      numbering: againstWebsite(bookNumbers([entry])),
+      since: bookSince([entry]),
     });
   }
   if (parts.length > 0) {
@@ -183,31 +305,44 @@ export async function writeLatexExports(
       files: bookSource({ manifest, parts, document: 'course', title: course }),
       target: 'course',
       folder: `${courseFileStem(manifest)}-latex`,
-      website: bookNumbers(parts),
+      numbering: againstWebsite(bookNumbers(parts)),
+      since: bookSince(parts),
     });
   }
 
-  const pending: PendingFile[] = jobs.map((job) => ({
-    target: join(outputRoot, 'downloads', `${job.target}-latex.zip`),
-    content: zip(job.files.map((file) => ({ path: `${job.folder}/${file.path}`, content: file.content }))),
-  }));
+  const pending: PendingFile[] = jobs
+    .filter((job) => !job.noZip)
+    .map((job) => ({
+      target: join(outputRoot, 'downloads', `${job.target}-latex.zip`),
+      content: zip(job.files.map((file) => ({ path: `${job.folder}/${file.path}`, content: file.content }))),
+    }));
 
-  // Compile every document at once, up to one per core; a book numbers
-  // every chapter, so each is checked against the website whole.
+  // Compile every document at once, up to one per core, the longest first;
+  // a book numbers every chapter, so each is checked against the website
+  // whole. A document reused from the cache is checked the same way.
   const durations: { kind: Job['kind']; seconds: number }[] = [];
+  const cache = 'missing' in engine ? undefined : await latexCacheFromEnvironment(engine, logger);
+  let reused = 0;
   const started = performance.now();
   if (!('missing' in engine)) {
     const compiled = await mapWithLimit(jobs, availableParallelism(), async (job) => {
       const jobStarted = performance.now();
-      const result = await compileLatex(job.files, engine, { epoch: epochOf(manifest), name: job.name });
-      durations.push({ kind: job.kind, seconds: (performance.now() - jobStarted) / 1000 });
-      const problems = numberingMismatches(job.website, auxLabels(result.aux));
+      const options = { epoch: epochOf(manifest, job.since), name: job.name };
+      const compile = cache
+        ? await cache.compile(job.files, options)
+        : { result: await compileLatex(job.files, engine, options), reused: false };
+      const { result } = compile;
+      if (compile.reused) reused += 1;
+      else durations.push({ kind: job.kind, seconds: (performance.now() - jobStarted) / 1000 });
+      const problems = job.numbering(result.aux);
       if (problems.length > 0) {
         throw new Error(`LaTeX numbers ${job.name} differently from the website:\n  ${problems.join('\n  ')}`);
       }
-      // A part's and the course's PDFs repeat their chapters' text, so each
-      // character is reported once, by the chapter that has it.
-      const missing = job.kind === 'chapter' ? missingCharacters(result.log) : [];
+      job.review?.(result.log);
+      // A part's and the course's PDFs repeat their chapters' text, and a
+      // handout its slides', so each character is reported once, by the
+      // document that has it first.
+      const missing = (job.kind === 'chapter' || job.kind === 'deck') && !job.noZip ? missingCharacters(result.log) : [];
       if (missing.length > 0) {
         logger.warn(
           `LaTeX export: the PDF of ${job.name} leaves ${missing.length} character(s) blank, ` +
@@ -220,7 +355,7 @@ export async function writeLatexExports(
         );
       }
       return result.pdf;
-    });
+    }, startOrder(jobs));
     jobs.forEach((job, index) => {
       pending.push({ target: join(outputRoot, 'downloads', `${job.target}.pdf`), content: compiled[index]! });
     });
@@ -238,15 +373,22 @@ export async function writeLatexExports(
   } finally {
     await Promise.all(temporary.map((file) => rm(file.temporary, { force: true })));
   }
+  const pruned = cache ? await cache.prune() : 0;
   const pdfs = pending.filter((file) => file.target.endsWith('.pdf')).length;
   const seconds = (kind: Job['kind']) =>
     durations.filter((entry) => entry.kind === kind).reduce((sum, entry) => sum + entry.seconds, 0);
   logger.info(
-    `LaTeX export: ${chapters.length} chapter(s), ${parts.length} part(s)${parts.length > 0 ? ' and the course' : ''}: ` +
-      `${jobs.length} source zip(s)` +
+    `LaTeX export: ${chapters.length} chapter(s), ${decks.length} deck(s), ` +
+      `${parts.length} part(s)${parts.length > 0 ? ' and the course' : ''}: ` +
+      `${jobs.filter((job) => !job.noZip).length} source zip(s)` +
       (pdfs > 0
         ? `, ${pdfs} PDF(s) with ${'name' in engine ? engine.name : ''} in ${wall.toFixed(1)} s on up to ` +
-          `${availableParallelism()} core(s) (compile time: chapters ${seconds('chapter').toFixed(1)} s, ` +
+          `${availableParallelism()} core(s) (` +
+          (cache
+            ? `${pdfs - reused} compiled, ${reused} reused from ${cache.directory}` +
+              `${pruned > 0 ? `, ${pruned} unused entr${pruned === 1 ? 'y' : 'ies'} deleted` : ''}; `
+            : '') +
+          `compile time: chapters ${seconds('chapter').toFixed(1)} s, decks ${seconds('deck').toFixed(1)} s, ` +
           `parts ${seconds('part').toFixed(1)} s, course ${seconds('course').toFixed(1)} s)`
         : '') +
       (captures.size > 0 ? `, figures from ${captures.size} page(s) drawn as vector PDF` : '') +

package/src/compiler/exports/markdown/serialize.ts

@@ -15,7 +15,7 @@ import { gfmTableToMarkdown } from 'mdast-util-gfm-table';
 import { mathToMarkdown } from 'mdast-util-math';
 import { toMarkdown } from 'mdast-util-to-markdown';
 
-import { captionTitle } from '../../../components/float-name';
+import { captionTitle } from '../../../reference/float-name';
 import { stripNotationMarkers } from '../../../reference/math-glyphs.mjs';
 import type { ContentSegment } from '../../../reference/mixed-content';
 import type { CheckItem } from '../latex/serialize';
@@ -25,6 +25,7 @@ import type {
   DiagramGeometry,
   Inline,
   NotationEntry,
+  StaticDeck,
   StaticPage,
   TableCell,
 } from '../static-tree';
@@ -55,8 +56,11 @@ export interface MarkdownChapterContext {
   readonly pictures: ReadonlyMap<string, string>;
   /** Answers of this page's checks, by assessment id, in authored order. */
   readonly checkItems: ReadonlyMap<string, readonly CheckItem[]>;
-  /** Course title, version and the page's live URL, for the line under its title. */
-  readonly source?: { readonly course: string; readonly version?: string; readonly url?: string };
+  /**
+   * The line under the title: the course, the version the page's content is
+   * at (`versionPhrase`, rule C5) and its live URL.
+   */
+  readonly source?: { readonly course: string; readonly since?: string; readonly url?: string };
 }
 
 type Phrasing = PhrasingContent;
@@ -526,16 +530,19 @@ class MarkdownWriter {
     ];
   }
 
-  answers(checks: readonly Extract<Block, { kind: 'check' }>[]): RootContent[] {
+  /**
+   * The answers to `checks`: under their own heading at a page's end, or
+   * bare (`inline`), as a deck's speaker notes give them.
+   */
+  answers(checks: readonly Extract<Block, { kind: 'check' }>[], inline = false): RootContent[] {
     if (checks.length === 0) return [];
     return [
-      { type: 'heading', depth: 2, children: [anchor('answers'), text('Answers to the knowledge checks')] },
+      ...(inline ? [] : [{ type: 'heading', depth: 2, children: [anchor('answers'), text('Answers to the knowledge checks')] } as RootContent]),
       ...checks.flatMap((check): RootContent[] => {
         const items = this.context.checkItems.get(check.assessmentId) ?? [];
+        const name = text(`Knowledge check ${check.number}`);
         return [
-          paragraph([
-            strong([link(`#${check.anchor}`, [text(`Knowledge check ${check.number}`)]), text(': '), ...this.inlines(check.title)]),
-          ]),
+          paragraph([strong([inline ? name : link(`#${check.anchor}`, [name]), text(': '), ...this.inlines(check.title)])]),
           {
             type: 'list',
             ordered: true,
@@ -608,7 +615,7 @@ export function serializeMarkdownPage(
     ? [
         text('From '),
         emphasis([text(source.course)]),
-        ...(source.version ? [text(`, version ${source.version}`)] : []),
+        ...(source.since ? [text(`, ${source.since}`)] : []),
         text('.'),
         ...(source.url ? [text(' Interactive version: '), link(source.url, [text(source.url)]), text('.')] : []),
       ]
@@ -626,6 +633,108 @@ export function serializeMarkdownPage(
   ]);
 }
 
+/** The slide sizes Marp's built-in themes have. */
+export type MarpSize = '16:9' | '4:3';
+
+export interface MarpDeckContext extends Omit<MarkdownChapterContext, 'page'> {
+  readonly deck: StaticDeck;
+  /** The symbols its frames use, by first use: its closing notation slide. */
+  readonly symbols: readonly NotationEntry[];
+  readonly size: MarpSize;
+}
+
+/**
+ * A deck in Marp's Markdown (decision D10): front matter that turns Marp on,
+ * one slide per frame between `---` lines, numbered as the deck is, each
+ * frame's notes and its check's answers as an HTML comment (Marp's speaker
+ * notes), and a closing slide of the symbols the frames use. A step shows
+ * its frame's final state, as the handout does. The file reads as plain
+ * Markdown too; Marp, its VS Code extension and Deckset present it.
+ */
+export function serializeMarpDeck(context: MarpDeckContext): string {
+  const { deck, source } = context;
+  const page: StaticPage = {
+    slug: deck.slug,
+    route: deck.route,
+    title: deck.title,
+    blocks: [],
+    notation: deck.notation,
+    notationRemarks: [],
+  };
+  const writer = new MarkdownWriter({ ...context, page });
+  const heading = (depth: 1 | 2, children: Phrasing[]): RootContent => ({ type: 'heading', depth, children });
+  // Marp's own class for a slide whose content is centred: the title and a divider.
+  const lead: RootContent = { type: 'html', value: '<!-- _class: lead -->' };
+  const notes = (blocks: RootContent[]): RootContent[] =>
+    blocks.length === 0
+      ? []
+      : [{ type: 'html', value: `<!--\n${serializeNodes(blocks).trim().replace(/--/gu, '- -')}\n-->` }];
+  const slides: RootContent[][] = deck.frames.map((frame) => {
+    const title = writer.inlines(frame.title);
+    if (frame.kind === 'title') {
+      return [
+        lead,
+        heading(1, title),
+        ...(source
+          ? [
+              paragraph([
+                emphasis([text(source.course)]),
+                ...(source.since ? [text(`, ${source.since}`)] : []),
+                text('.'),
+                ...(source.url ? [text(' Interactive version: '), link(source.url, [text(source.url)]), text('.')] : []),
+              ]),
+            ]
+          : []),
+      ];
+    }
+    if (frame.kind === 'section') return [lead, heading(1, title)];
+    const blocks = frame.segments.flatMap((segment) => segment.blocks);
+    const legend = frame.legend.filter((item) => item.tex);
+    return [
+      heading(2, title),
+      ...writer.blocks(blocks),
+      ...(legend.length > 0
+        ? [
+            paragraph([
+              emphasis(
+                legend.flatMap((item, index): Phrasing[] => [
+                  ...(index > 0 ? [text(' · ')] : []),
+                  { type: 'inlineMath', value: plainTex(item.tex) } as Phrasing,
+                  text(' '),
+                  ...writer.inlines(item.label),
+                ]),
+              ),
+            ]),
+          ]
+        : []),
+      ...notes([...writer.blocks(frame.notes), ...writer.answers(checksOf(blocks), true)]),
+    ];
+  });
+  if (context.symbols.length > 0) {
+    slides.push([heading(2, [text('Notation')]), ...writer.notation(context.symbols, []).slice(1)]);
+  }
+  const body = serializeNodes(
+    slides.flatMap((slide, index): RootContent[] => [...(index > 0 ? [{ type: 'thematicBreak' } as RootContent] : []), ...slide]),
+  );
+  const frontMatter = [
+    '---',
+    'marp: true',
+    `title: ${JSON.stringify(deck.title)}`,
+    `size: ${context.size}`,
+    'paginate: true',
+    'math: katex',
+    '---',
+    '',
+  ].join('\n');
+  // Marp shows raw HTML as text: the `<a id>` anchors a page's links land on
+  // go, and a link to one of them keeps its words.
+  const markdown = body
+    .replace(/<a id="[^"]*"><\/a> ?/gu, '')
+    .replace(/(?<!!)\[([^\]]*)\]\(#[^)]*\)/gu, '$1')
+    .replace(/\n{3,}/gu, '\n\n');
+  return `${frontMatter}\n${markdown}`;
+}
+
 /** Markdown of a few blocks of mdast, written the same way (for a download's `index.md`). */
 export function serializeMarkdownNodes(children: RootContent[]): string {
   return serializeNodes(children);