@heroiclands/package-build 23.0.0 → 23.1.1

package/engine/pdf-build.mjs

@@ -107,6 +107,7 @@ import { artPathname, assetAddressIndex, pathnameRoles } from "./art-fields.mjs"
 import { embedRole } from "./content-embeds.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
+import { eventNoteIndex } from "./event-fields.mjs";
 import { numberFigures, scanFigures } from "./content-figures.mjs";
 import { collectAnchors } from "./anchors.mjs";
 import { protectCode } from "./code-fences.mjs";
@@ -141,8 +142,8 @@ import { isDraftNote, isGmNote } from "./note-vocabulary.mjs";
 import { infoboxTypstPreamble, infoboxesToTypst, linkToTypst } from "./infobox-render.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
 import { resolveIconGlyphs } from "./pdf-fonts.mjs";
-import { buildMaps, relatedPlaces } from "./map-build.mjs";
-import { mapWorld } from "./map-places.mjs";
+import { drawMapsFrom } from "./derived-sections.mjs";
+import { generatedDrawing, markGenerated, splitGenerated } from "./generated-sections.mjs";
 import { resolveAssetReplacement } from "./asset-replacement.mjs";
 
 /**
@@ -340,6 +341,9 @@ function stagedReplacementPath(forms, config, { foreignIndex = new Map(), resolv
  */
 const STAGED_PLATES = "plates";
 
+/** Where the book draws the map from a place, beside its Typst source. */
+const BOOK_MAP_DIR = "maps";
+
 /**
  * Copy every banner the document tree names into the output directory.
  *
@@ -657,6 +661,14 @@ export async function buildPdf({
     const stageImages = (body, file, columns = 2) => {
         for (const image of imagesIn(body)) {
             const src = image.src;
+            // A generated section's drawing is the one this build drew beside
+            // its source — see `drawn` below — and is vector, so nothing
+            // resamples it.
+            const drawing = generatedDrawing(src);
+            if (drawing) {
+                if (drawn.maps.has(drawing)) images.set(src, `${BOOK_MAP_DIR}/${drawing}`);
+                continue;
+            }
             const directive = parseImageDirective(image.directive);
             const wide =
                 directive.size === "full-width" || directive.classes.includes("full-width");
@@ -786,6 +798,25 @@ export async function buildPdf({
      *   lineMap?: object[], numberedFigures: object[]}>}
      */
     const prepared = new Map();
+    // The map from each selected place given a From here section, drawn before
+    // any body is rendered so the section's image names a file the book holds.
+    // A place's map is printed there, inside its entry, and nowhere else.
+    const drawn = drawMapsFrom(records, {
+        outDir: path.join(outDir, BOOK_MAP_DIR),
+        foreignIndex: gates.foreign.index,
+        config: resolved,
+        only: plan.entries
+            .filter((entry) => entry.kind === "note" && entry.record?.type === "place")
+            .map((entry) => String(entry.record.shortcode ?? "")),
+    });
+    findings.push(...drawn.findings);
+    // Every note's events by Address, for an inline reference to an event's
+    // field — the same lookup the website and the Foundry compile build.
+    const events = eventNoteIndex(records, {
+        contentPackage: gates.index.contentPackage,
+        foreignIndex: gates.foreign?.index,
+        dates: gates.index.dateContext,
+    });
     // Every note's figures, by the address a `ref` crossing into it would
     // write — see `engine/site-index.mjs`'s `figureIndexKeys`.
     const figuresByAddress = new Map();
@@ -795,7 +826,7 @@ export async function buildPdf({
             const page = byFile.get(file);
             if (!page) continue; // reported as `missing` by the render loop below
             const src = page.relPath ?? page.base;
-            const { markdown, errors, lineMap } = expandContentTables(page.body, {
+            const { markdown, errors, lineMap, generatedFrom } = expandContentTables(page.body, {
                 docs: universe.get(page.pkg) ?? [],
                 linkable: (d) => Boolean(d.fm.shortcode),
                 source: src,
@@ -807,7 +838,13 @@ export async function buildPdf({
                 scanFigures(markdown, { resolveRole }).figures,
                 figureCounts,
             );
-            prepared.set(entry.anchor, { markdown, errors, lineMap, numberedFigures });
+            prepared.set(entry.anchor, {
+                markdown,
+                errors,
+                lineMap,
+                numberedFigures,
+                generatedFrom,
+            });
             const shortcode = page.fm.shortcode;
             if (typeof shortcode === "string" && shortcode) {
                 const byId = new Map(
@@ -848,7 +885,8 @@ export async function buildPdf({
     const renderPage = (page, headingOffset, anchorPrefix, columns) => {
         const src = page.relPath ?? page.base;
         const wikiErrors = [];
-        const { markdown, errors, lineMap, numberedFigures } = prepared.get(anchorPrefix);
+        const { markdown, errors, lineMap, numberedFigures, generatedFrom } =
+            prepared.get(anchorPrefix);
         // A content-table finding states its `reason`, its 0-based line within
         // the body and its column, exactly as the site build reports them.
         // Reading it as `message` yields `[object Object]` and discards the
@@ -899,12 +937,17 @@ export async function buildPdf({
         // Code fences are protected for the same reason every other pass
         // protects them: a wikilink shown as an example is prose about a
         // wikilink, and resolving it would make the example impossible to write.
-        const expressions = renderMarkdownExpressions(markdown, {
+        // Where the generated sections begin is marked before any pass can move
+        // a line, and the body is split there once its links resolve: the
+        // sections are set by the rules for generated links — see
+        // `renderLink` in `engine/pdf-render.mjs`.
+        const expressions = renderMarkdownExpressions(markGenerated(markdown, generatedFrom), {
             fm: page.fm,
             dates: gates.index.dateContext,
             sqlResults: sqlTables?.inline?.get(page.file),
             file: page.file,
             bodyLine: page.bodyLine,
+            events,
             figures: {
                 get: (id) => figuresById.get(id),
                 // A cross-note `ref` resolves the written address exactly as
@@ -964,23 +1007,36 @@ export async function buildPdf({
             });
         }
         stageImages(resolvedBody, page.file, columns);
-        const prose = markdownToTypst(resolvedBody, {
-            md,
-            links: plan.links,
-            glyphs,
-            images,
-            assets: imageAssets,
-            headingOffset,
-            anchorPrefix,
-            captions: numberedFigures,
-            url: site,
-            findings,
-            file: page.file,
-            bodyLine: page.bodyLine,
-            lineMap,
-            prepared: true,
-            resolveRole: (pathname) => pathRoles.get(pathname),
-        });
+        const { authored, generated } = splitGenerated(resolvedBody);
+        const typst = (text, options) =>
+            markdownToTypst(text, {
+                md,
+                links: plan.links,
+                glyphs,
+                images,
+                assets: imageAssets,
+                headingOffset,
+                anchorPrefix,
+                url: site,
+                findings,
+                file: page.file,
+                bodyLine: page.bodyLine,
+                prepared: true,
+                resolveRole: (pathname) => pathRoles.get(pathname),
+                ...options,
+            });
+        const prose = [
+            typst(authored, { captions: numberedFigures, lineMap, indexMentions: true }),
+            ...(generated ?
+                [
+                    typst(generated, {
+                        captions: [],
+                        lineMap: lineMap.slice(generatedFrom),
+                        generated: true,
+                    }),
+                ]
+            :   []),
+        ].join("\n");
         // Infoboxes follow the authored body within this note's entry.
         const boxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
@@ -1044,6 +1100,7 @@ export async function buildPdf({
                     anchorPrefix: entry.anchor,
                     captions: prepared.get(entry.anchor).numberedFigures,
                     url: site,
+                    indexMentions: true,
                     findings,
                     file,
                 }),
@@ -1073,6 +1130,7 @@ export async function buildPdf({
                 footnotePrefix: `footnote-front-${index + 1}`,
                 captions: frontFigures.get(file),
                 url: site,
+                indexMentions: true,
                 findings,
                 file,
             });
@@ -1140,49 +1198,28 @@ export async function buildPdf({
                 uses: [use],
             });
     };
-    const world = mapWorld({
-        records,
-        foreignIndex: gates.foreign.index,
-        contentBase,
-        config: resolved,
-    });
-    const related = new Set(relatedPlaces(world.places));
-    const mapDir = path.join(outDir, "maps");
-    fs.rmSync(mapDir, { recursive: true, force: true });
-    const mappedEntries = plan.entries.filter(
-        (entry) =>
-            entry.kind === "note" &&
-            entry.record?.type === "place" &&
-            related.has(String(entry.record.shortcode ?? "").toLowerCase()),
-    );
-    if (mappedEntries.length) {
-        const centres = [...new Set(mappedEntries.map((entry) => entry.record.shortcode))];
-        const drawn = buildMaps({ world, outDir: mapDir, from: centres });
-        findings.push(...drawn.findings);
-        for (const entry of mappedEntries) {
-            addMapPage(entry.anchor, {
-                path: `maps/from-${entry.record.shortcode}.svg`,
-                title: `From here: ${entry.record.name?.full ?? entry.record.shortcode}`,
-            });
-        }
-    }
     for (const entry of plan.entries) {
         if (entry.kind !== "note" || entry.record?.type !== "map") continue;
         const title = entry.record.name?.full ?? entry.record.shortcode;
-        if (["regionalmap", "totm"].includes(entry.record.subType)) {
-            if (entry.record.data?.bgImage) {
-                stageMapBackground(entry, entry.record.data.bgImage, title);
-            }
-            continue;
-        }
-        if (!["battlemap", "localmap"].includes(entry.record.subType)) continue;
-        for (const [index, level] of (entry.record.data?.scene?.levels ?? []).entries()) {
+        // Every subtype's picture is its exported Scene's level backgrounds,
+        // each with `data.fixup` applied. Nothing else in the Scene is read.
+        const levels = entry.record.data?.scene?.levels;
+        for (const [index, level] of (Array.isArray(levels) ? levels : []).entries()) {
+            if (!level || typeof level !== "object") continue;
             const paths = [
                 `.levels[${index}].background.src`,
-                ...(level._id ? [`.levels[${level._id}].background.src`] : []),
+                ...(level._id ?
+                    [
+                        `.levels[${level._id}].background.src`,
+                        `.levels[_id=${level._id}].background.src`,
+                        `.levels[_id="${level._id}"].background.src`,
+                        `.levels[_id='${level._id}'].background.src`,
+                    ]
+                :   []),
             ];
-            const fixup = (entry.record.data?.fixup ?? []).find((item) =>
-                paths.includes(item.path),
+            const fixups = entry.record.data?.fixup;
+            const fixup = (Array.isArray(fixups) ? fixups : []).find((item) =>
+                paths.includes(item?.path),
             );
             const value = fixup?.value ?? level.background?.src;
             if (value)

package/engine/pdf-index.mjs

@@ -0,0 +1,263 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The book's index: which terms it lists, in what order, and the Typst that
+ * finds their pages.
+ *
+ * **Terms are decided here, pages are decided by layout.** The set of terms and
+ * their order are known from the plan alone, so they are computed in this
+ * module and written into the source as data. Which page a term lands on is
+ * known only once the compiler has laid the book out, so every entry heading
+ * and every authored mention carries an invisible `metadata` marker and the
+ * chapter queries them from inside a `context`. The page numbers are therefore
+ * right however the book reflows.
+ *
+ * - A note's own entry lists its name, with the entry's page in bold.
+ * - An authored mention of a note in the book adds the page it appears on.
+ * - An alias (`name.aliases`) and an event's in-world name
+ *   (`data.events[].names`) list a cross-reference to the note's name.
+ *
+ * Terms sort on the ASCII fold the content index derives for names
+ * ({@link module:engine/content-index.asciiName}), ignoring case, so an
+ * accented name files under its base letter.
+ *
+ * @module
+ */
+
+import { asciiName } from "./content-index.mjs";
+
+/**
+ * The marker an entry heading or an authored mention carries.
+ *
+ * @param {string} slug - The address slug of the note the marker is about.
+ * @param {boolean} [main] - Whether this is the note's own entry.
+ * @returns {string} Typst markup occupying no space.
+ */
+export function indexMarker(slug, main = false) {
+    return `#book-ix("${escapeString(slug)}"${main ? ", main: true" : ""})`;
+}
+
+/** @param {string} text @returns {string} The text inside a Typst string literal. */
+function escapeString(text) {
+    return String(text).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * The slug a note is indexed under.
+ *
+ * @param {object} record - A plan entry's record.
+ * @returns {string} The slug, or "".
+ */
+function slugOf(record) {
+    return String(record?.address?.slug ?? record?.shortcode ?? "");
+}
+
+/**
+ * The folded sort key of a term.
+ *
+ * @param {string} name - The term as printed.
+ * @returns {string} Lower-case printable ASCII.
+ */
+function sortKey(name) {
+    return (asciiName(name) ?? name).toLowerCase();
+}
+
+/**
+ * The letter heading a term files under: `#` for anything that does not begin
+ * with a letter.
+ *
+ * @param {string} key - The term's sort key.
+ * @returns {string} A capital letter or `#`.
+ */
+function letterOf(key) {
+    const first = key.charAt(0).toUpperCase();
+    return first >= "A" && first <= "Z" ? first : "#";
+}
+
+/**
+ * Every term the book's index lists, in index order.
+ *
+ * @param {object[]} entries - The plan's entries.
+ * @returns {Array<{letter: string, name: string, slug: string, see?: string}>}
+ *   Terms with `see` set for a cross-reference to the main name it points at.
+ */
+export function indexTerms(entries) {
+    const terms = [];
+    const info = new Map();
+    const nameByCanonical = new Map();
+    for (const entry of entries ?? []) {
+        if (entry?.kind !== "note") continue;
+        const canonical = entry.record?.address?.canonical;
+        const name = String(entry.record?.name?.full ?? "").trim();
+        if (canonical && name) nameByCanonical.set(String(canonical), name);
+    }
+    for (const entry of entries ?? []) {
+        if (entry?.kind !== "note") continue;
+        const slug = slugOf(entry.record);
+        const name = String(entry.record?.name?.full ?? "").trim();
+        if (!slug || !name || info.has(slug)) continue;
+        const parents = Array.isArray(entry.record?.data?.parents) ? entry.record.data.parents : [];
+        const parent = parents
+            .map((one) =>
+                nameByCanonical.get(String(typeof one === "string" ? one : one?.canonical)),
+            )
+            .find(Boolean);
+        info.set(slug, {
+            kind: String(entry.record?.subType || entry.record?.type || ""),
+            parent: parent ?? "",
+        });
+        terms.push({ name, slug, main: true });
+        const taken = new Set([sortKey(name)]);
+        const names = [
+            ...(Array.isArray(entry.record?.name?.aliases) ? entry.record.name.aliases : []),
+            ...(Array.isArray(entry.record?.data?.events) ? entry.record.data.events : []).flatMap(
+                (event) => (Array.isArray(event?.names) ? event.names.map((n) => n?.name) : []),
+            ),
+        ];
+        for (const other of names) {
+            if (typeof other !== "string" || !other.trim()) continue;
+            const key = sortKey(other.trim());
+            if (taken.has(key)) continue;
+            taken.add(key);
+            terms.push({ name: other.trim(), slug, main: false });
+        }
+    }
+    // Terms printing one name for different notes are told apart: first by the
+    // note's subtype (or its type), then, where that still collides, by the
+    // place the note is within.
+    const clashing = (shown) => {
+        const owners = new Map();
+        terms.forEach((term, i) => {
+            const key = sortKey(shown[i]);
+            if (!owners.has(key)) owners.set(key, new Set());
+            owners.get(key).add(term.slug);
+        });
+        return terms.map((_, i) => owners.get(sortKey(shown[i])).size > 1);
+    };
+    const qualified = (term, withParent) => {
+        const { kind, parent } = info.get(term.slug);
+        const qualifier = withParent && parent ? `${kind}, ${parent}` : kind;
+        return qualifier ? `${term.name} (${qualifier})` : term.name;
+    };
+    let shown = terms.map((term) => term.name);
+    for (const withParent of [false, true]) {
+        const clash = clashing(shown);
+        if (!clash.some(Boolean)) break;
+        shown = terms.map((term, i) => (clash[i] ? qualified(term, withParent) : shown[i]));
+    }
+    const mainShown = new Map();
+    terms.forEach((term, i) => {
+        if (term.main) mainShown.set(term.slug, shown[i]);
+    });
+    const keyed = terms.map((term, i) => ({
+        name: shown[i],
+        slug: term.slug,
+        ...(term.main ? {} : { see: mainShown.get(term.slug) }),
+        key: sortKey(shown[i]),
+    }));
+    keyed.sort((a, b) => {
+        const la = letterOf(a.key);
+        const lb = letterOf(b.key);
+        if (la !== lb)
+            return (
+                la === "#" ? -1
+                : lb === "#" ? 1
+                : la < lb ? -1
+                : 1
+            );
+        if (a.key !== b.key) return a.key < b.key ? -1 : 1;
+        if (a.name !== b.name) return a.name < b.name ? -1 : 1;
+        return (
+            a.slug < b.slug ? -1
+            : a.slug > b.slug ? 1
+            : 0
+        );
+    });
+    return keyed.map(({ key, ...term }) => ({ letter: letterOf(key), ...term }));
+}
+
+/**
+ * The Typst function definitions the markers and the chapter rely on.
+ *
+ * @returns {string} Typst source.
+ */
+export function indexPreamble() {
+    return [
+        // Zero-size and invisible; the label is what the chapter queries.
+        "#let book-ix(key, main: false) = [#metadata((key: key, main: main)) <book-index>]",
+        "#let book-index(terms) = context {",
+        "  set par(justify: false, first-line-indent: 0em, hanging-indent: 1em, spacing: 0.45em)",
+        "  set text(size: 8.8pt)",
+        "  let by = (:)",
+        "  for m in query(<book-index>) {",
+        "    let loc = m.location()",
+        "    let n = counter(page).at(loc).first()",
+        "    let pages = by.at(m.value.key, default: ())",
+        "    pages.push((n: n, main: m.value.main, loc: loc))",
+        "    by.insert(m.value.key, pages)",
+        "  }",
+        "  let merged(key) = {",
+        "    let out = (:)",
+        "    for p in by.at(key, default: ()) {",
+        "      let at = str(p.n)",
+        "      let seen = out.at(at, default: none)",
+        "      if seen == none or (p.main and not seen.main) { out.insert(at, p) }",
+        "    }",
+        "    out.values().sorted(key: p => p.n)",
+        "  }",
+        "  let letter = none",
+        "  for term in terms {",
+        "    if term.letter != letter {",
+        "      letter = term.letter",
+        "      heading(level: 5, outlined: false, bookmarked: false)[#letter]",
+        "    }",
+        "    if term.see != none {",
+        "      let main = merged(term.slug).filter(p => p.main)",
+        "      let shown = if main.len() > 0 { link(main.first().loc)[#term.see] } else { term.see }",
+        "      par[#term.name, #emph[see] #shown]",
+        "    } else {",
+        "      let numbers = merged(term.slug).map(p => link(p.loc)[#text(",
+        '        weight: if p.main { "bold" } else { "regular" })[#numbering("1", p.n)]])',
+        "      par[#term.name #h(0.35em) #numbers.join[, ]]",
+        "    }",
+        "  }",
+        "}",
+    ].join("\n");
+}
+
+/**
+ * The index chapter, ready to follow the last entry.
+ *
+ * @param {object[]} entries - The plan's entries.
+ * @param {string} title - The book's title, which kicks the chapter.
+ * @returns {string} Typst source, or "" when the book has nothing to index.
+ */
+export function indexChapter(entries, title) {
+    const terms = indexTerms(entries);
+    if (!terms.length) return "";
+    const rows = terms.map(
+        (term) =>
+            `(letter: "${escapeString(term.letter)}", name: "${escapeString(term.name)}", ` +
+            `slug: "${escapeString(term.slug)}", see: ${
+                term.see === undefined ? "none" : `"${escapeString(term.see)}"`
+            })`,
+    );
+    return [
+        "#set page(columns: 2, footer: book-footer[Index])",
+        `#book-section("${escapeString(title)}", "Index", none)[` +
+            "#heading(level: 1, outlined: true, bookmarked: true)[Index] <book-index-chapter>]",
+        `#book-index((${rows.join(",\n  ")},))`,
+        "",
+    ].join("\n");
+}

package/engine/pdf-render.mjs

@@ -86,6 +86,7 @@ export const BOOK_IMAGE_WIDTHS = Object.freeze({
     "full-width": '"full-width"',
 });
 import { markupAnchorFindings } from "./anchors.mjs";
+import { indexChapter, indexMarker, indexPreamble } from "./pdf-index.mjs";
 import { slugify } from "./content-slug.mjs";
 import { alertMarkdownPlugin, scanAlerts, ALERT_TYPES } from "./content-alerts.mjs";
 import { spanMarkdownPlugin, scanSpans } from "./content-spans.mjs";
@@ -474,6 +475,10 @@ function reportUnrenderable(source, definitions, opts, original) {
  *   at. Every link the book sets as a URL is resolved against it, because a
  *   reader holding a PDF has no page to resolve a path against — see
  *   {@link renderLink}.
+ * @param {boolean} [opts.generated] - Whether the Markdown is a note's
+ *   generated sections rather than its author's text — see
+ *   {@link module:engine/generated-sections}. Their links follow the rules
+ *   {@link renderLink} states for generated links.
  * @returns {string} Typst markup.
  */
 export function markdownToTypst(markdown, opts = {}) {
@@ -513,6 +518,8 @@ export function markdownToTypst(markdown, opts = {}) {
         headingOffset,
         anchorPrefix,
         url: opts.url,
+        indexMentions: opts.indexMentions === true,
+        generated: Boolean(opts.generated),
         seen: new Map(),
         footnoteState,
         footnotePrefix: opts.footnotePrefix ?? `footnote-${slugify(anchorPrefix || "body")}`,
@@ -1330,9 +1337,30 @@ export function absolutePageUrl(url, site) {
     }
 }
 
+/**
+ * The page a label's element starts on, printed in that page's own numbering
+ * once the book is laid out — the number the contents prints for it.
+ *
+ * @param {string} label - A label the book declares.
+ * @returns {string} Typst markup.
+ */
+function pageOfLabel(label) {
+    return (
+        `#context { let here = locate(<${label}>); numbering(if here.page-numbering() == none ` +
+        `{ "1" } else { here.page-numbering() }, ..counter(page).at(here)) }`
+    );
+}
+
 /**
  * A link, internal when the book prints its destination and external otherwise.
  *
+ * **A link in a generated section** — `ctx.generated` — names a note the build
+ * derived rather than one an author chose, and a book is often a selection of
+ * notes. So one whose target the book prints is an internal link followed by
+ * the page the target starts on, `Ford (p. 12)`, which keeps a printed copy
+ * usable; one whose target the book leaves out is its words alone, with no
+ * link and no finding.
+ *
  * The address slug is read from the tail of the URL, which is where every
  * address this toolchain publishes puts it — `…/<type>-<shortcode>/`. A
  * cross-package URL resolved through the link manifest is on another package's
@@ -1360,9 +1388,14 @@ function renderLink(href, inner, ctx) {
         // `[[note#appearance]]` reaches the section, not just the entry — the
         // same namespaced label the heading declared.
         const target = fragment ? sectionLabel(anchor, fragment) : labelFor(anchor);
-        return `#link(<${target}>)[${inner}]`;
+        const link = `#link(<${target}>)[${inner}]`;
+        // Generated text prints its page and adds nothing to the index; only
+        // authored prose that sets `indexMentions` marks a mention.
+        if (ctx.generated) return fragment ? link : `${link}~(p.~${pageOfLabel(target)})`;
+        const marker = ctx.indexMentions && slug ? indexMarker(slug) : "";
+        return `${link}${marker}`;
     }
-    if (!url) return inner;
+    if (!url || ctx.generated) return inner;
     return `#link("${escapeTypstString(absolutePageUrl(url, ctx.url))}")[${inner}]`;
 }
 
@@ -1850,6 +1883,7 @@ export function renderBook({
     const out = [];
 
     out.push(bookTypstPreamble());
+    out.push(indexPreamble());
     out.push("");
     out.push(`#set document(title: "${escapeTypstString(title)}")`);
     // Cream stock and dark ink rather than a dark screen theme: 2,000 pages of
@@ -1980,6 +2014,9 @@ export function renderBook({
                 `#heading(level: ${Math.min(6, depth + 1)}, outlined: false, bookmarked: true)` +
                 `[${escapeTypst(name)}] <${label}>]`,
         );
+        out.push(
+            indexMarker(String(entry.record?.address?.slug ?? entry.record?.shortcode ?? ""), true),
+        );
         out.push("");
         const body = bodies.get(entry.anchor);
         if (body) {
@@ -1994,6 +2031,9 @@ export function renderBook({
         }
     }
 
+    const index = indexChapter(plan?.entries, title);
+    if (index) out.push(index);
+
     return `${out.join("\n")}\n`;
 }
 
@@ -2092,8 +2132,9 @@ function footerName(entry) {
  * that would have contained it, which is where a reader wants to end up anyway;
  * a link with no entry to fall back to becomes plain text. Both are reported.
  *
- * A declaration is a label not preceded by `#link(` — the only two places a
- * label appears are the heading that declares one and the link that uses one.
+ * A declaration is a label preceded by neither `#link(` nor `locate(` — a
+ * label appears in the heading that declares it, the link that uses it, and
+ * the page lookup a generated link prints after itself.
  *
  * @param {string} source - The assembled Typst document.
  * @param {object[]} [findings] - Collected here rather than thrown.
@@ -2102,7 +2143,8 @@ function footerName(entry) {
 export function resolveDanglingLabels(source, findings = []) {
     const text = String(source ?? "");
     const declared = new Set();
-    for (const match of text.matchAll(/(?<!#link\()<([A-Za-z0-9_-]+)>/g)) declared.add(match[1]);
+    for (const match of text.matchAll(/(?<!#link\(|locate\()<([A-Za-z0-9_-]+)>/g))
+        declared.add(match[1]);
 
     return text.replace(/#link\(<([A-Za-z0-9_-]+)>\)/g, (whole, label) => {
         if (declared.has(label)) return whole;