explico 0.13.1 → 0.14.0

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

@@ -3,9 +3,11 @@ import { basename, dirname, extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import type { Manifest, ManifestLesson, ManifestPart } from '../manifest';
-import { courseFileStem } from './export-pages';
+import { newestSince, versionPhrase } from '../page-versions';
+import { courseFileStem, deckFileStem, deckOwnerSlug, deckSaveName } from './export-pages';
 import {
   consoleLogger,
+  deckBlocks,
   diagramsOf,
   figuresOf,
   imageExtension,
@@ -18,8 +20,9 @@ import {
   type PreparedChapters,
 } from './export-chapters';
 import type { CapturedFigure } from './latex/capture';
-import { checkItems } from './latex/document';
-import { serializeMarkdownNodes, serializeMarkdownPage } from './markdown/serialize';
+import { deckSymbols } from './latex/deck';
+import { checkItems, deckCheckItems } from './latex/document';
+import { serializeMarkdownNodes, serializeMarkdownPage, serializeMarpDeck } from './markdown/serialize';
 import type { StaticPage } from './static-tree';
 import { zip, type ZipEntry } from './zip';
 
@@ -33,6 +36,8 @@ import { zip, type ZipEntry } from './zip';
  *   contents), one file per chapter, and shared `assets/`.
  * - `downloads/course-markdown.zip`: `index.md` (the course and its
  *   contents), each part's page, one file per chapter, and `assets/`.
+ * - `downloads/<lesson>-slides-markdown.zip`: a deck as Marp's Markdown,
+ *   `<name>-slides-markdown/slides.md` and its `assets/`.
  *
  * A figure a browser draws is a PNG at two device pixels per CSS pixel; an
  * image is the site's own file; a `<Diagram>` is a PNG with its boxes and
@@ -112,16 +117,22 @@ export async function writeMarkdownExports(
   if (!manifest.lessonExports.markdown) return;
   const logger = options.logger ?? consoleLogger;
   const outputRoot = fileURLToPath(directory);
-  const { base, chapters, captures } =
+  const { base, chapters, decks, captures } =
     options.prepared ?? (await prepareChapters(outputRoot, manifest, { logger, projectRoot: options.projectRoot }));
   const canonicalBaseUrl = manifest.lessonExports.canonicalBaseUrl;
   const course = manifest.about.material.name;
-  const version = manifest.about.knowledge.version;
-  const source = (route: string) => ({
+  const current = manifest.about.knowledge.version;
+  // The line under a title: the version the document's content is at (rule C5).
+  const source = (route: string, since: string | null) => ({
     course,
-    version,
+    since: versionPhrase(since, current),
     ...(canonicalBaseUrl ? { url: `${canonicalBaseUrl}${route ? `${route}/` : ''}` } : {}),
   });
+  const partSince = (entry: { part: ManifestPart; chapters: readonly { lesson: ManifestLesson }[] }) =>
+    newestSince([
+      ...(entry.part.overview ? [entry.part.overview.since] : []),
+      ...entry.chapters.map(({ lesson }) => lesson.since),
+    ]);
 
   /** One chapter's Markdown and pictures, seen from `documentFiles`. */
   const chapterFiles = async (
@@ -139,7 +150,7 @@ export async function writeMarkdownExports(
         ...(canonicalBaseUrl ? { canonicalBaseUrl } : {}),
         pictures: new Map([...pictures].map(([key, picture]) => [key, picture.path])),
         checkItems: checkItems(manifest, lesson),
-        source: source(page.route),
+        source: source(page.route, lesson.since),
       },
       { number: `${lesson.part}.${lesson.chapter}` },
     );
@@ -168,6 +179,40 @@ export async function writeMarkdownExports(
     );
   }
 
+  // Each deck as Marp's Markdown: a figure or diagram it recalls is its chapter's picture.
+  for (const { deck, page, figureRoutes } of decks) {
+    if (deck.part === undefined && !manifest.lessons.some((entry) => entry.id === deck.lessonId)) continue;
+    const owner = deckOwnerSlug(deck, manifest);
+    const captured = new Map<string, CapturedFigure>();
+    for (const [anchor, route] of figureRoutes) {
+      const figure = captures.get(route)?.get(anchor);
+      if (figure) captured.set(anchor, figure);
+    }
+    const blocks = [...deckBlocks(page), ...page.frames.flatMap((frame) => frame.notes)];
+    const pictures = await pagePictures(
+      outputRoot,
+      base,
+      { slug: page.slug, route: page.route, title: page.title, blocks, notation: [], notationRemarks: [] },
+      captured,
+      'assets',
+    );
+    const items = deckCheckItems(manifest, deck);
+    const markdown = serializeMarpDeck({
+      deck: page,
+      documentFiles: new Map([[page.route, '']]),
+      ...(canonicalBaseUrl ? { canonicalBaseUrl } : {}),
+      pictures: new Map([...pictures].map(([key, picture]) => [key, picture.path])),
+      checkItems: items,
+      source: source(page.route, deck.since),
+      symbols: deckSymbols({ deck: page, documentRoutes: new Set([page.route]), pictures: new Map(), checkItems: items }),
+      size: manifest.deck.aspectRatio === '4:3' ? '4:3' : '16:9',
+    });
+    pack(`${deckFileStem(owner)}-markdown.zip`, `${deckSaveName(owner)}-markdown`, [
+      { path: 'slides.md', content: markdown },
+      ...[...pictures.values()].map((picture) => ({ path: picture.path, content: picture.content })),
+    ]);
+  }
+
   const byId = new Map(chapters.map((chapter) => [chapter.lesson.id, chapter]));
   const pageSlugs = new Set(manifest.pages.map((page) => page.slug));
   const parts = manifest.parts
@@ -196,7 +241,7 @@ export async function writeMarkdownExports(
         ...(canonicalBaseUrl ? { canonicalBaseUrl } : {}),
         pictures: new Map([...pictures].map(([key, picture]) => [key, picture.path])),
         checkItems: new Map(),
-        source: source(page.route),
+        source: source(page.route, partSince(entry)),
       },
       { number: `Part ${entry.part.ordinal}:` },
     );
@@ -268,7 +313,7 @@ export async function writeMarkdownExports(
       {
         type: 'paragraph',
         children: [
-          { type: 'text', value: `Content version ${version}.` },
+          { type: 'text', value: `Content ${versionPhrase(newestSince(parts.map(partSince)), current)}.` },
           ...(canonicalBaseUrl
             ? [
                 { type: 'text' as const, value: ' Interactive version: ' },
@@ -322,7 +367,7 @@ export async function writeMarkdownExports(
     await Promise.all(pending.map((file) => rm(`${file.target}.tmp-${process.pid}`, { force: true })));
   }
   logger.info(
-    `Markdown export: ${chapters.length} chapter(s), ${parts.length} part(s)` +
+    `Markdown export: ${chapters.length} chapter(s), ${decks.length} deck(s), ${parts.length} part(s)` +
       (parts.length > 0 ? ' and the course' : '') +
       '.',
   );

package/src/compiler/exports/standalone-html.ts

@@ -12,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { parse, serialize } from 'parse5';
 
 import type { Manifest } from '../manifest';
-import { exportPageRoute, standalonePageSlugs } from './export-pages';
+import { exportPageRoute, standaloneDownloads } from './export-pages';
 import {
   attribute,
   elements,
@@ -910,10 +910,11 @@ export async function pageSourceFile(outputRoot: string, slug: string): Promise<
 }
 
 /**
- * Emit the opt-in standalone HTML artifact of every chapter
- * (`standalonePageSlugs`) from Astro's completed static output, at
- * `downloads/<docs slug>.html`. A page that is not a chapter is in its
- * part's and the course's files (`combined-html.ts`).
+ * Emit the opt-in standalone HTML artifact of every chapter and deck
+ * (`standaloneDownloads`) from Astro's completed static output, at
+ * `downloads/<docs slug>.html` and `downloads/<lesson>-slides.html`. A page
+ * that is not a chapter is in its part's and the course's files
+ * (`combined-html.ts`).
  */
 export async function writeStandaloneLessonExports(
   directory: URL,
@@ -922,9 +923,9 @@ export async function writeStandaloneLessonExports(
   if (!manifest.lessonExports.standaloneHtml) return;
   const outputRoot = fileURLToPath(directory);
   const pending: { target: string; temporary: string; html: string }[] = [];
-  for (const slug of standalonePageSlugs(manifest)) {
+  for (const { slug, download } of standaloneDownloads(manifest)) {
     const sourceFile = await pageSourceFile(outputRoot, slug);
-    const target = join(outputRoot, 'downloads', `${slug}.html`);
+    const target = join(outputRoot, 'downloads', `${download}.html`);
     pending.push({
       target,
       temporary: `${target}.tmp-${process.pid}`,

package/src/compiler/exports/static-tree.ts

@@ -130,6 +130,8 @@ export type Block =
       readonly ordered: boolean;
       readonly start?: number;
       readonly items: readonly (readonly Block[])[];
+      /** On a deck, the step each item appears at (1 for the first), when an item is a step of its own. */
+      readonly itemSteps?: readonly number[];
     }
   | {
       readonly kind: 'equation';
@@ -137,6 +139,8 @@ export type Block =
       readonly number: string;
       readonly key?: string;
       readonly tex: string;
+      /** On a deck, a recalled equation's place in its chapter. */
+      readonly recall?: string;
     }
   | { readonly kind: 'displayMath'; readonly tex: string }
   | (FloatBase & {
@@ -694,6 +698,7 @@ function readBlock(node: HtmlElement, context: ReadContext): Block[] | undefined
         number: attribute(node, 'data-eq-number') ?? '',
         ...(key ? { key } : {}),
         tex: (katex && texOf(katex)) ?? '',
+        ...(attribute(node, 'data-eq-recall') ? { recall: attribute(node, 'data-eq-recall')! } : {}),
       },
     ];
   }
@@ -788,6 +793,19 @@ function readBlock(node: HtmlElement, context: ReadContext): Block[] | undefined
   if (node.tagName === 'compact-examples' || hasClass(node, 'compact-examples')) {
     return [readExamples(node, context)];
   }
+  // A deck's question frame labels its check instead of heading it.
+  if (hasClass(node, 'deck-check__label') && attribute(node, 'data-block-kind') === 'check') {
+    const anchor = attribute(node, 'id') ?? '';
+    return [
+      {
+        kind: 'check',
+        anchor,
+        number: attribute(node, 'data-check-number') ?? '',
+        assessmentId: anchor.replace(/^check-/u, ''),
+        title: [{ kind: 'text', value: attribute(node, 'data-check-title') ?? '' }],
+      },
+    ];
+  }
   if (hasClass(node, 'sl-heading-wrapper')) {
     const heading = headingOf(node);
     if (!heading) return readBlocks(node, context);
@@ -918,6 +936,22 @@ export function readStaticPage(html: string, slug: string, route: string): Stati
   const title = elements(main, (node) => node.tagName === 'h1')[0];
   const content = elements(main, (node) => hasClass(node, 'sl-markdown-content'))[0];
   if (!content) throw new Error(`Built page ${slug} has no .sl-markdown-content element.`);
+  const { notation, notationRemarks } = readPageNotation(main, context);
+  return {
+    slug,
+    route,
+    title: title ? collapse(readableText(title)).trim() : slug,
+    blocks: readBlocks(content, context),
+    notation,
+    notationRemarks,
+  };
+}
+
+/** The page's notation list (its notation layer's entries) and its page-specific remarks. */
+function readPageNotation(
+  main: HtmlElement,
+  context: ReadContext,
+): Pick<StaticPage, 'notation' | 'notationRemarks'> {
   const layer = elements(
     main,
     (node) => hasClass(node, 'notation-layer') && attribute(node, 'data-notation-layer-id') === 'page-notation',
@@ -933,12 +967,150 @@ export function readStaticPage(html: string, slug: string, route: string): Stati
             .map((item) => inlineContent(item, context)),
       )
     : [];
+  return { notation: entries.map((entry) => readNotationEntry(entry, context)), notationRemarks: remarks };
+}
+
+// --- decks ------------------------------------------------------------------
+
+/** One frame of a deck page (docs/authoring/deck.md), as print exports read it. */
+export interface DeckFrame {
+  readonly number: number;
+  readonly kind: 'title' | 'section' | 'frame' | 'outcomes' | 'references';
+  /** The frame heading's anchor. */
+  readonly anchor?: string;
+  readonly title: readonly Inline[];
+  /** The frame's content, a run of blocks per step, in reading order: step 1 is what shows first. */
+  readonly segments: readonly { readonly step: number; readonly blocks: readonly Block[] }[];
+  readonly steps: number;
+  readonly notes: readonly Block[];
+  /** The legend line: each symbol's TeX and its name. */
+  readonly legend: readonly { readonly tex: string; readonly label: readonly Inline[] }[];
+}
+
+export interface StaticDeck {
+  readonly slug: string;
+  readonly route: string;
+  readonly title: string;
+  readonly frames: readonly DeckFrame[];
+  /**
+   * The page's notation list: its lesson's symbols, its chapter's included.
+   * The PDF's appendix keeps the ones its frames use.
+   */
+  readonly notation: readonly NotationEntry[];
+}
+
+/** Each item's step, for a list a step mark split, or `undefined` when no item is a step. */
+function listItemSteps(list: HtmlElement): number[] | undefined {
+  const items = childrenOf(list).filter((child): child is HtmlElement => isElement(child) && child.tagName === 'li');
+  let step = 1;
+  let any = false;
+  const steps = items.map((item) => {
+    const at = attribute(item, 'data-step');
+    if (at !== undefined) {
+      step = Number(at) || step;
+      any = true;
+    }
+    return step;
+  });
+  return any ? steps : undefined;
+}
+
+/** A frame body's content, step by step. */
+function readSegments(body: HtmlElement, context: ReadContext): { step: number; blocks: Block[] }[] {
+  const segments: { step: number; blocks: Block[] }[] = [];
+  const add = (step: number, blocks: readonly Block[]) => {
+    if (blocks.length === 0) return;
+    const last = segments.at(-1);
+    if (last && last.step === step) last.blocks.push(...blocks);
+    else segments.push({ step, blocks: [...blocks] });
+  };
+  let pending: HtmlNode[] = [];
+  const flush = () => {
+    if (pending.length === 0) return;
+    const holder = { nodeName: 'div', tagName: 'div', attrs: [], childNodes: pending } as unknown as HtmlElement;
+    add(1, withItemSteps(holder, readBlocks(holder, context)));
+    pending = [];
+  };
+  for (const child of childrenOf(body)) {
+    if (isElement(child) && hasClass(child, 'deck-step') && attribute(child, 'data-step') !== undefined) {
+      flush();
+      add(Number(attribute(child, 'data-step')) || 1, withItemSteps(child, readBlocks(child, context)));
+      continue;
+    }
+    pending.push(child);
+  }
+  flush();
+  return segments;
+}
+
+/** The list blocks of `node`'s own lists, given the step of each item. */
+function withItemSteps(node: HtmlElement, blocks: Block[]): Block[] {
+  const lists = childrenOf(node).filter(
+    (child): child is HtmlElement => isElement(child) && (child.tagName === 'ul' || child.tagName === 'ol'),
+  );
+  let index = 0;
+  return blocks.map((block) => {
+    if (block.kind !== 'list') return block;
+    const list = lists[index++];
+    const itemSteps = list ? listItemSteps(list) : undefined;
+    return itemSteps ? { ...block, itemSteps } : block;
+  });
+}
+
+/** Read the frames of one built deck page. */
+export function readStaticDeck(html: string, slug: string, route: string): StaticDeck {
+  const document = parse(html);
+  const base = inferBasePrefix(document);
+  const context: ReadContext = { route, base };
+  const main = elements(document, (node) => node.tagName === 'main')[0];
+  if (!main) throw new Error(`Built page ${slug} has no <main> element.`);
+  const deck = elements(main, (node) => hasClass(node, 'deck') && attribute(node, 'data-deck') !== undefined)[0];
+  if (!deck) throw new Error(`Built page ${slug} has no deck (.deck[data-deck]).`);
+  const title = elements(main, (node) => node.tagName === 'h1')[0];
+  const frames = childrenOf(deck)
+    .filter((child): child is HtmlElement => isElement(child) && hasClass(child, 'deck-frame'))
+    .map((frame): DeckFrame => {
+      const canvas = firstByClass(frame, 'deck-canvas');
+      const heading = canvas ? firstByClass(canvas, 'deck-frame__title') ?? firstByClass(canvas, 'deck-title__title') : undefined;
+      const body = canvas ? firstByClass(canvas, 'deck-frame__body') : undefined;
+      const notes = childrenOf(frame).find(
+        (child): child is HtmlElement => isElement(child) && hasClass(child, 'deck-notes'),
+      );
+      const legend = canvas ? firstByClass(canvas, 'deck-legend') : undefined;
+      const kind = (attribute(frame, 'data-kind') ?? 'frame') as DeckFrame['kind'];
+      // A generated frame has no body of its own: its content is the canvas,
+      // less its title and its foot.
+      const generatedContent =
+        !body && canvas
+          ? readBlocks(
+              canvas,
+              context,
+              (child) =>
+                !(isElement(child) && (hasClass(child, 'deck-frame__title') || hasClass(child, 'deck-frame__foot') || hasClass(child, 'deck-title__title'))),
+            )
+          : [];
+      return {
+        number: Number(attribute(frame, 'data-frame')) || 0,
+        kind,
+        ...(heading && attribute(heading, 'id') ? { anchor: attribute(heading, 'id')! } : {}),
+        title: heading ? inlineContent(heading, context) : [],
+        segments: body ? readSegments(body, context) : generatedContent.length > 0 ? [{ step: 1, blocks: generatedContent }] : [],
+        steps: Number(attribute(frame, 'data-steps')) || 1,
+        notes: notes ? readBlocks(notes, context) : [],
+        legend: legend
+          ? elements(legend, (node) => hasClass(node, 'deck-legend__item')).map((item) => {
+              const katex = elements(item, (node) => hasClass(node, 'katex'))[0];
+              const label = firstByClass(item, 'deck-legend__label');
+              return { tex: (katex && texOf(katex)) ?? '', label: label ? inlineContent(label, context) : [] };
+            })
+          : [],
+      };
+    });
   return {
     slug,
     route,
     title: title ? collapse(readableText(title)).trim() : slug,
-    blocks: readBlocks(content, context),
-    notation: entries.map((entry) => readNotationEntry(entry, context)),
-    notationRemarks: remarks,
+    frames,
+    notation: readPageNotation(main, context).notation,
   };
 }

package/src/compiler/knowledge-version.ts

@@ -23,10 +23,18 @@ export interface KnowledgeChangelogEntry {
   readonly notes: readonly string[];
 }
 
+/** The released entries and, apart from them, the bullets `## [Unreleased]` holds. */
+export interface KnowledgeChangelog {
+  readonly entries: readonly KnowledgeChangelogEntry[];
+  /** Bullet lines under `## [Unreleased]`, any `###` group included, marker stripped. */
+  readonly unreleased: readonly string[];
+}
+
 export type KnowledgeVersionCode =
   | 'knowledge-changelog-missing'
   | 'knowledge-version-invalid'
-  | 'knowledge-version-mismatch';
+  | 'knowledge-version-mismatch'
+  | 'page-versions-invalid';
 
 export interface KnowledgeVersionDiagnostic {
   readonly code: KnowledgeVersionCode;
@@ -41,6 +49,15 @@ export interface KnowledgeVersion {
   readonly version: string;
   /** The newest released `## [x.y.z]` entry, when the changelog has one. */
   readonly latest?: KnowledgeChangelogEntry;
+  /** Every released entry, newest first; empty without a changelog. */
+  readonly entries: readonly KnowledgeChangelogEntry[];
+  /**
+   * The bullets `## [Unreleased]` holds: a content change not yet released
+   * (rule C1). A page changed while there are any is "not yet released"
+   * (rule C5); with none, a change is the release's own, or one rule C1 lets
+   * go unlisted.
+   */
+  readonly unreleased: readonly string[];
   readonly diagnostics: readonly KnowledgeVersionDiagnostic[];
 }
 
@@ -56,29 +73,32 @@ export function isKnowledgeSemver(value: string): boolean {
 }
 
 /**
- * Every released entry in a `content/CHANGELOG.md` body, in file order (newest
- * first, by Keep a Changelog convention). `## [Unreleased]` is skipped.
+ * A `content/CHANGELOG.md` body: every released entry in file order (newest
+ * first, by Keep a Changelog convention), and the bullets of
+ * `## [Unreleased]`. A released entry's notes end at a `###` group heading,
+ * as the About panel has always shown them; the unreleased bullets are
+ * counted through every group, since what they answer is whether anything
+ * is waiting for a release.
  */
-export function parseKnowledgeChangelog(
-  text: string,
-): KnowledgeChangelogEntry[] {
+export function scanKnowledgeChangelog(text: string): KnowledgeChangelog {
   const lines = text.split(/\r?\n/);
   const entries: {
     version: string;
     date?: string;
     notes: string[];
   }[] = [];
+  const unreleased: string[] = [];
   let current: { version: string; date?: string; notes: string[] } | null =
     null;
+  let inUnreleased = false;
 
   for (const line of lines) {
     const heading = HEADING_RE.exec(line);
     if (heading) {
       const token = (heading[1] ?? '').trim();
-      if (/^unreleased$/i.test(token)) {
-        current = null;
-        continue;
-      }
+      current = null;
+      inUnreleased = /^unreleased$/i.test(token);
+      if (inUnreleased) continue;
       current = { version: token, notes: [] };
       const date = (heading[2] ?? '').trim();
       if (date) current.date = date;
@@ -88,18 +108,33 @@ export function parseKnowledgeChangelog(
     // A top-level `#` or a deeper `###` heading ends the current entry's notes.
     if (/^#{1,3}\s/.test(line) && !line.startsWith('## [')) {
       current = null;
+      if (/^#{1,2}\s/.test(line)) inUnreleased = false;
       continue;
     }
-    if (!current) continue;
     const bullet = BULLET_RE.exec(line);
-    if (bullet) current.notes.push(bullet[1] ?? '');
+    if (!bullet) continue;
+    if (current) current.notes.push(bullet[1] ?? '');
+    else if (inUnreleased) unreleased.push(bullet[1] ?? '');
   }
 
-  return entries.map((entry) => ({
-    version: entry.version,
-    ...(entry.date === undefined ? {} : { date: entry.date }),
-    notes: [...entry.notes],
-  }));
+  return {
+    entries: entries.map((entry) => ({
+      version: entry.version,
+      ...(entry.date === undefined ? {} : { date: entry.date }),
+      notes: [...entry.notes],
+    })),
+    unreleased,
+  };
+}
+
+/**
+ * Every released entry in a `content/CHANGELOG.md` body, in file order (newest
+ * first, by Keep a Changelog convention). `## [Unreleased]` is skipped.
+ */
+export function parseKnowledgeChangelog(
+  text: string,
+): KnowledgeChangelogEntry[] {
+  return [...scanKnowledgeChangelog(text).entries];
 }
 
 /**
@@ -133,17 +168,17 @@ export function resolveKnowledgeVersion(options: {
       'knowledge-changelog-missing',
       `No ${file}. Add a Keep a Changelog file whose newest \`## [x.y.z]\` heading is ${JSON.stringify(declaredVersion)} (rule C1).`,
     );
-    return { version: declaredVersion, diagnostics };
+    return { version: declaredVersion, entries: [], unreleased: [], diagnostics };
   }
 
-  const entries = parseKnowledgeChangelog(changelogText);
+  const { entries, unreleased } = scanKnowledgeChangelog(changelogText);
   const latest = entries[0];
   if (!latest) {
     warn(
       'knowledge-changelog-missing',
       `${file} has no released \`## [x.y.z]\` entry — only \`## [Unreleased]\`. Cut a release: move it to \`## [${declaredVersion}] - <date>\` (rule C3).`,
     );
-    return { version: declaredVersion, diagnostics };
+    return { version: declaredVersion, entries, unreleased, diagnostics };
   }
 
   if (isKnowledgeSemver(declaredVersion) && latest.version !== declaredVersion) {
@@ -153,5 +188,5 @@ export function resolveKnowledgeVersion(options: {
     );
   }
 
-  return { version: declaredVersion, latest, diagnostics };
+  return { version: declaredVersion, latest, entries, unreleased, diagnostics };
 }