@heroiclands/package-build 20.5.0 → 20.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heroiclands/package-build
 
+## 20.6.0
+
+### Minor Changes
+
+- a2742cc: **PDF book outline** — a book's printed table of contents now lists only the
+  sections its document tree declares; every note stays reachable from the PDF
+  bookmarks panel, titled from its own name, without also cluttering the printed
+  contents. A note's own body headings never surface on either surface, so a note
+  opening with a heading that repeats its own title no longer shows a duplicate
+  entry in the sidebar. Every heading — printed, bookmarked or neither — is still
+  a working link target, including one an author never gave an explicit anchor.
+
 ## 20.5.0
 
 ### Minor Changes

package/docs/api.md

@@ -714,16 +714,16 @@ The document tree a PDF is built from, and the plan it resolves to (#316). The p
 
 A note's markdown, and a document plan, rendered as Typst source. **This module emits text and reads nothing.** It takes markdown and a plan and returns a `.typ` document; the filesystem, the note bodies and the compiler that turns the result into a PDF all live in {@link module:engine/pdf-build}. That split is what lets the outline, the table of contents, every anchor and every link destination be asserted in a unit test with no renderer installed — which is most of what a book has to get right, and all of what a test can check without eyes.
 
-| Export                  | Signature                                                                        | Returns                                                      | Use it when                                                              |
-| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
-| `escapeTypst`           | `function escapeTypst(text)`                                                     | {string} The same text, inert.                               | Escape literal text for Typst markup.                                    |
-| `escapeTypstString`     | `function escapeTypstString(text)`                                               | {string} The same value, quotable.                           | Escape a string going inside Typst string quotes, as a `#link` URL does. |
-| `labelFor`              | `function labelFor(anchor)`                                                      | {string} A Typst label name.                                 | A Typst label, from a plan anchor.                                       |
-| `createParser`          | `function createParser(registry)`                                                | {object} A markdown-it instance.                             | A markdown-it configured to parse, not to render.                        |
-| `markdownToTypst`       | `function markdownToTypst(markdown, opts`                                        | {string} Typst markup.                                       | Render markdown as Typst content.                                        |
-| `renderBook`            | `renderBook({ plan, bodies, title, subtitle, front, fonts, tocDepth, version })` | {string} A complete `.typ` document.                         | The whole book, as one Typst document.                                   |
-| `resolveDanglingLabels` | `function resolveDanglingLabels(source, findings`                                | {string} The same document, with no reference left dangling. | Point every internal link at a label the document actually declares.     |
-| `iconNamesIn`           | `function iconNamesIn(markdown)`                                                 | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.           |
+| Export                  | Signature                                                              | Returns                                                      | Use it when                                                              |
+| ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `escapeTypst`           | `function escapeTypst(text)`                                           | {string} The same text, inert.                               | Escape literal text for Typst markup.                                    |
+| `escapeTypstString`     | `function escapeTypstString(text)`                                     | {string} The same value, quotable.                           | Escape a string going inside Typst string quotes, as a `#link` URL does. |
+| `labelFor`              | `function labelFor(anchor)`                                            | {string} A Typst label name.                                 | A Typst label, from a plan anchor.                                       |
+| `createParser`          | `function createParser(registry)`                                      | {object} A markdown-it instance.                             | A markdown-it configured to parse, not to render.                        |
+| `markdownToTypst`       | `function markdownToTypst(markdown, opts`                              | {string} Typst markup.                                       | Render markdown as Typst content.                                        |
+| `renderBook`            | `renderBook({ plan, bodies, title, subtitle, front, fonts, version })` | {string} A complete `.typ` document.                         | The whole book, as one Typst document.                                   |
+| `resolveDanglingLabels` | `function resolveDanglingLabels(source, findings`                      | {string} The same document, with no reference left dangling. | Point every internal link at a label the document actually declares.     |
+| `iconNamesIn`           | `function iconNamesIn(markdown)`                                       | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.           |
 
 ### `engine.pdfFonts`
 

package/engine/pdf-render.mjs

@@ -64,6 +64,7 @@
 import MarkdownIt from "markdown-it";
 
 import { iconPlugin, ICON_PATTERN } from "./content-icons.mjs";
+import { slugify } from "./content-slug.mjs";
 
 /**
  * Characters that mean something to Typst's markup parser.
@@ -170,7 +171,11 @@ export function markdownToTypst(markdown, opts = {}) {
         anchorPrefix = "",
     } = opts;
     const tokens = md.parse(String(markdown ?? ""), {});
-    return renderTokens(tokens, { links, glyphs, headingOffset, anchorPrefix });
+    // One map for the whole body, not one per block: a heading inside a
+    // blockquote or a list item shares the entry's anchor namespace with every
+    // other heading in the same body, because `sectionLabel` scopes by entry
+    // rather than by container.
+    return renderTokens(tokens, { links, glyphs, headingOffset, anchorPrefix, seen: new Map() });
 }
 
 /**
@@ -209,15 +214,26 @@ function renderBlock(tokens, i, out, ctx) {
             // Typst caps headings at a depth no book reaches by accident; going
             // past it would be a compile error in the middle of a 2,500-entry
             // run, so it clamps and keeps setting.
-            const level = Math.min(6, Number(token.tag.slice(1)) + ctx.headingOffset);
+            const level = Math.max(1, Math.min(6, Number(token.tag.slice(1)) + ctx.headingOffset));
             const inline = tokens[i + 1];
             // `## Appearance {#appearance}` declares an addressable section. The
             // journals compiler strips the suffix and surfaces it as an anchor;
             // so does this, because a book that printed the braces would show
             // every reader the markup that makes a link work.
             const { text, anchor } = splitHeadingAnchor(inline, ctx);
-            const label = anchor ? ` <${sectionLabel(ctx.anchorPrefix, anchor)}>` : "";
-            out.push(`\n${"=".repeat(Math.max(1, level))} ${text}${label}\n\n`);
+            // A heading with no authored anchor still needs a link target, so one
+            // is derived from its own text. `anchorFor` keeps it from colliding
+            // with an authored anchor, or with another derived one, that lands on
+            // the same words later in the same entry.
+            const base = anchor || slugify(plainHeadingText(inline)) || "heading";
+            const unique = anchorFor(base, ctx.seen);
+            const label = ` <${sectionLabel(ctx.anchorPrefix, unique)}>`;
+            // A body heading is never printed and never bookmarked — it is
+            // structure a reader reaches only by following a link, not a
+            // destination either outline offers on its own.
+            out.push(
+                `\n#heading(level: ${level}, outlined: false, bookmarked: false)[${text}]${label}\n\n`,
+            );
             return 3;
         }
         case "paragraph_open": {
@@ -285,6 +301,44 @@ function splitHeadingAnchor(inline, ctx) {
     return { text: renderInline({ ...inline, children }, ctx), anchor: match[2] };
 }
 
+/**
+ * A heading's text, unescaped and with any `{#anchor}` suffix still attached.
+ *
+ * Used only to derive an anchor when the author wrote none, so it wants the
+ * words as typed rather than the Typst-escaped, suffix-stripped text
+ * {@link splitHeadingAnchor} renders — {@link module:engine/content-slug.slugify}
+ * normalises punctuation and case itself and has no use for an escape
+ * backslash.
+ *
+ * @param {object} inline - The heading's `inline` token.
+ * @returns {string} The heading's raw text.
+ */
+function plainHeadingText(inline) {
+    const children = inline?.children ?? [];
+    return children.map((child) => child.content ?? "").join("");
+}
+
+/**
+ * A unique anchor within one render pass, suffixed when the base repeats.
+ *
+ * A derived anchor is only as good as its uniqueness: two headings reading
+ * "Notes" in one entry, or a derived "description" landing on an author's own
+ * `{#description}`, would otherwise give one label two meanings. First use of
+ * a base anchor keeps it exactly as written or slugified; every later use in
+ * the same body is suffixed, in the order headings are walked — which is
+ * stable across rebuilds because the body's markdown is.
+ *
+ * @param {string} base - The preferred anchor.
+ * @param {Map<string, number>} seen - How many times each base has been used,
+ *   scoped to one call to {@link markdownToTypst}.
+ * @returns {string} The anchor.
+ */
+function anchorFor(base, seen) {
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return n === 1 ? base : `${base}-${n}`;
+}
+
 /**
  * A label for an anchor declared inside a note.
  *
@@ -612,25 +666,39 @@ function renderIcon(token, ctx) {
  * with no filesystem and no compiler. {@link module:engine/pdf-build} supplies
  * both and runs Typst over the result.
  *
- * ## Two outlines, and why they are not the same outline
+ * ## Three surfaces, one heading tree
  *
  * A roster of 2,500 entries wants every entry reachable from a viewer's
  * sidebar, and emphatically does not want all 2,500 printed in the front
- * matter: that is forty pages of contents before the book starts.
- *
- * Typst separates the two for us. **The PDF bookmark outline is built from
- * every heading**, so each entry gets its own node at its own depth for free
- * and the sidebar is the navigational interface the issue asks for.
- * **`#outline()` prints only to `tocDepth`**, so the paper table of contents
- * stays the sections. Both are page-numbered and both are links.
+ * matter: that is forty pages of contents before the book starts. It also
+ * wants every heading in a note's own body to keep working as a link target,
+ * without appearing on either surface — the anchor an author writes for
+ * `[[note#appearance]]` is structure, not a destination either outline offers
+ * on its own.
+ *
+ * `heading` carries `outlined` and `bookmarked` independently, so the three
+ * wants are three settings rather than three passes:
+ *
+ * - A **section** — `outlined: true, bookmarked: true` — prints in the paper
+ *   contents and the PDF sidebar alike.
+ * - A **note leaf**, titled from `name.full`, is `outlined: false,
+ *   bookmarked: true`: reachable from the sidebar, absent from the printed
+ *   contents.
+ * - A **body heading**, inside a note's own markdown, is `outlined: false,
+ *   bookmarked: false`: a real heading with a label, so it still supplies a
+ *   link target, a running head and a page break, but neither outline lists
+ *   it. {@link markdownToTypst} emits these.
+ *
+ * `#outline()` needs no depth limit under this model: what prints is decided
+ * per heading, not by how deep the tree happens to go.
  *
  * ## Headings carry the structure, so nothing else has to
  *
  * Every section, every prose file and every entry is a real Typst heading at
- * its plan depth. That single decision supplies the bookmarks, the printed
- * contents, the running heads and the page breaks at once — where drawing
- * titles as styled text would have meant building all four by hand and keeping
- * them agreeing with each other.
+ * its plan depth. That single decision supplies both outlines, the running
+ * heads and the page breaks at once — where drawing titles as styled text
+ * would have meant building all four by hand and keeping them agreeing with
+ * each other.
  *
  * @param {object} opts - Options.
  * @param {object} opts.plan - From {@link module:engine/pdf-toc.planDocument}.
@@ -640,7 +708,6 @@ function renderIcon(token, ctx) {
  * @param {string} [opts.subtitle] - Shown under it on the title page.
  * @param {string[]} [opts.front] - Rendered Typst for each front-matter file.
  * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names.
- * @param {number} [opts.tocDepth] - How deep the *printed* contents go.
  * @param {string} [opts.version] - Stamped on the title page when given.
  * @returns {string} A complete `.typ` document.
  */
@@ -651,7 +718,6 @@ export function renderBook({
     subtitle = "",
     front = [],
     fonts = {},
-    tocDepth = 2,
     version = "",
 } = {}) {
     const serif = fonts.serif || "Libertinus Serif";
@@ -700,7 +766,9 @@ export function renderBook({
         out.push("");
     }
 
-    out.push(`#outline(title: [Contents], depth: ${Math.max(1, Number(tocDepth) || 2)})`);
+    // No `depth:` limit: what prints is decided per heading by `outlined`,
+    // below, not by how deep the plan's tree happens to go.
+    out.push("#outline(title: [Contents])");
     out.push("#pagebreak()");
     out.push("");
 
@@ -708,7 +776,12 @@ export function renderBook({
         const label = labelFor(entry.anchor);
         const depth = Math.min(6, Math.max(1, Number(entry.depth) || 1));
         if (entry.kind === "section") {
-            out.push(`${"=".repeat(depth)} ${escapeTypst(entry.title)} <${label}>`);
+            // A declared `sectionName:` — the structure the printed contents
+            // shows and the bookmarks panel shows alongside it.
+            out.push(
+                `#heading(level: ${depth}, outlined: true, bookmarked: true)` +
+                    `[${escapeTypst(entry.title)}] <${label}>`,
+            );
             out.push("");
             continue;
         }
@@ -721,8 +794,13 @@ export function renderBook({
             out.push("");
             continue;
         }
+        // A note leaf: reachable from the bookmarks panel, titled from
+        // `name.full`, and never printed in the paper contents.
         const name = entry.record?.name?.full ?? entry.record?.address?.slug ?? "(untitled)";
-        out.push(`${"=".repeat(Math.min(6, depth + 1))} ${escapeTypst(name)} <${label}>`);
+        out.push(
+            `#heading(level: ${Math.min(6, depth + 1)}, outlined: false, bookmarked: true)` +
+                `[${escapeTypst(name)}] <${label}>`,
+        );
         out.push("");
         const body = bodies.get(entry.anchor);
         if (body) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "20.5.0",
+    "version": "20.6.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/pdf-render.d.mts

@@ -70,25 +70,39 @@ export function markdownToTypst(markdown: string, opts?: {
  * with no filesystem and no compiler. {@link module:engine/pdf-build} supplies
  * both and runs Typst over the result.
  *
- * ## Two outlines, and why they are not the same outline
+ * ## Three surfaces, one heading tree
  *
  * A roster of 2,500 entries wants every entry reachable from a viewer's
  * sidebar, and emphatically does not want all 2,500 printed in the front
- * matter: that is forty pages of contents before the book starts.
- *
- * Typst separates the two for us. **The PDF bookmark outline is built from
- * every heading**, so each entry gets its own node at its own depth for free
- * and the sidebar is the navigational interface the issue asks for.
- * **`#outline()` prints only to `tocDepth`**, so the paper table of contents
- * stays the sections. Both are page-numbered and both are links.
+ * matter: that is forty pages of contents before the book starts. It also
+ * wants every heading in a note's own body to keep working as a link target,
+ * without appearing on either surface — the anchor an author writes for
+ * `[[note#appearance]]` is structure, not a destination either outline offers
+ * on its own.
+ *
+ * `heading` carries `outlined` and `bookmarked` independently, so the three
+ * wants are three settings rather than three passes:
+ *
+ * - A **section** — `outlined: true, bookmarked: true` — prints in the paper
+ *   contents and the PDF sidebar alike.
+ * - A **note leaf**, titled from `name.full`, is `outlined: false,
+ *   bookmarked: true`: reachable from the sidebar, absent from the printed
+ *   contents.
+ * - A **body heading**, inside a note's own markdown, is `outlined: false,
+ *   bookmarked: false`: a real heading with a label, so it still supplies a
+ *   link target, a running head and a page break, but neither outline lists
+ *   it. {@link markdownToTypst} emits these.
+ *
+ * `#outline()` needs no depth limit under this model: what prints is decided
+ * per heading, not by how deep the tree happens to go.
  *
  * ## Headings carry the structure, so nothing else has to
  *
  * Every section, every prose file and every entry is a real Typst heading at
- * its plan depth. That single decision supplies the bookmarks, the printed
- * contents, the running heads and the page breaks at once — where drawing
- * titles as styled text would have meant building all four by hand and keeping
- * them agreeing with each other.
+ * its plan depth. That single decision supplies both outlines, the running
+ * heads and the page breaks at once — where drawing titles as styled text
+ * would have meant building all four by hand and keeping them agreeing with
+ * each other.
  *
  * @param {object} opts - Options.
  * @param {object} opts.plan - From {@link module:engine/pdf-toc.planDocument}.
@@ -98,18 +112,16 @@ export function markdownToTypst(markdown: string, opts?: {
  * @param {string} [opts.subtitle] - Shown under it on the title page.
  * @param {string[]} [opts.front] - Rendered Typst for each front-matter file.
  * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names.
- * @param {number} [opts.tocDepth] - How deep the *printed* contents go.
  * @param {string} [opts.version] - Stamped on the title page when given.
  * @returns {string} A complete `.typ` document.
  */
-export function renderBook({ plan, bodies, title, subtitle, front, fonts, tocDepth, version, }?: {
+export function renderBook({ plan, bodies, title, subtitle, front, fonts, version, }?: {
     plan: object;
     bodies: Map<string, string>;
     title: string;
     subtitle?: string | undefined;
     front?: string[] | undefined;
     fonts?: object | undefined;
-    tocDepth?: number | undefined;
     version?: string | undefined;
 }): string;
 /**