@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/pdf-render.mjs

@@ -51,7 +51,7 @@
  *
  * ## Icons
  *
- * `:icon-star-outline:` is parsed by the *same* {@link module:engine/content-icons.iconPlugin}
+ * `:icon star-outline:` is parsed by the *same* {@link module:engine/content-icons.iconPlugin}
  * the journals and the website use — one rule, three surfaces — and only the
  * output differs. The glyph is resolved from the font file the consumer named,
  * because the registry deliberately holds no codepoints; when no font is
@@ -62,9 +62,11 @@
  */
 
 import MarkdownIt from "markdown-it";
+import footnotePlugin from "markdown-it-footnote";
+import deflistPlugin from "markdown-it-deflist";
 
 import { bookDraftNoticePreamble } from "./draft-notice.mjs";
-import { iconPlugin, ICON_PATTERN } from "./content-icons.mjs";
+import { iconPlugin, ICON_PATTERN, ICON_SIZES } from "./content-icons.mjs";
 import { IMAGE_CLASSES, IMAGE_FLOATS, imagePlugin } from "./content-images.mjs";
 
 /** Requested print width for every named image size. */
@@ -77,6 +79,9 @@ export const BOOK_IMAGE_WIDTHS = Object.freeze({
     "full-width": '"full-width"',
 });
 import { slugify } from "./content-slug.mjs";
+import { scanCaptions } from "./content-captions.mjs";
+import { scanAdmonitions } from "./content-admonitions.mjs";
+import { separateFootnotes } from "./content-footnotes.mjs";
 
 /**
  * Characters that mean something to Typst's markup parser.
@@ -154,6 +159,8 @@ export function labelFor(anchor) {
  */
 export function createParser(registry) {
     const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
+    md.use(footnotePlugin);
+    md.use(deflistPlugin);
     md.use(iconPlugin(registry));
     // The same plugin the HTML surfaces use, so one directive is read once and
     // three renderers read the same `meta` off the same token.
@@ -192,19 +199,110 @@ export function markdownToTypst(markdown, opts = {}) {
         headingOffset = 0,
         anchorPrefix = "",
     } = opts;
-    const tokens = md.parse(String(markdown ?? ""), {});
+    const separated =
+        opts.footnoteDefinitions === undefined ? separateFootnotes(String(markdown ?? "")) : null;
+    const source = separated?.markdown ?? String(markdown ?? "");
+    const definitions = opts.footnoteDefinitions ?? separated?.definitions ?? "";
+    const footnoteState = opts.footnoteState ?? { seen: new Set() };
+    const sharedOptions = { ...opts, footnoteDefinitions: definitions, footnoteState };
+    if (!opts.insideAdmonition) {
+        const { blocks } = scanAdmonitions(source);
+        if (blocks.length) {
+            const lines = source.split("\n");
+            const output = [];
+            let cursor = 0;
+            for (const block of blocks) {
+                output.push(
+                    markdownToTypst(lines.slice(cursor, block.start).join("\n"), {
+                        ...sharedOptions,
+                        insideAdmonition: true,
+                    }),
+                );
+                const color = block.kind === "warn" ? "#9a6700" : "#2f6f9f";
+                const background = block.kind === "warn" ? "#fff5db" : "#eef6fb";
+                const label = block.kind === "warn" ? "Warning" : "Info";
+                const symbol = block.kind === "warn" ? "!" : "i";
+                const content = markdownToTypst(block.body, {
+                    ...sharedOptions,
+                    insideAdmonition: true,
+                });
+                output.push(
+                    `\n#block(width: 100%, fill: rgb("${background}"), stroke: (left: 2pt + rgb("${color}")), inset: 8pt, above: 0.7em, below: 0.7em)[#text(fill: rgb("${color}"), weight: "bold")[${symbol} ${label}]\n\n${content}]\n`,
+                );
+                cursor = block.end + 1;
+            }
+            output.push(
+                markdownToTypst(lines.slice(cursor).join("\n"), {
+                    ...sharedOptions,
+                    insideAdmonition: true,
+                }),
+            );
+            return output.join("\n");
+        }
+    }
     // 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, {
+    const ctx = {
+        md,
         links,
         glyphs,
         images,
         headingOffset,
         anchorPrefix,
         seen: new Map(),
-    });
+        footnoteState,
+        footnotePrefix: opts.footnotePrefix ?? `footnote-${slugify(anchorPrefix || "body")}`,
+    };
+    const lines = source.split("\n");
+    const localCaptions = scanCaptions(source).captions;
+    const numbered = new Map(
+        (opts.captions ?? localCaptions).map((caption) => [caption.id, caption]),
+    );
+    const captions = localCaptions.map((caption) => numbered.get(caption.id) ?? caption);
+    if (!captions.length) return renderMarkdownSegment(source, md, ctx, definitions);
+    const out = [];
+    let cursor = 0;
+    for (const caption of captions) {
+        out.push(
+            renderMarkdownSegment(
+                lines.slice(cursor, caption.line - 1).join("\n"),
+                md,
+                ctx,
+                definitions,
+            ),
+        );
+        const block = lines.slice(caption.blockStart, caption.blockEnd).join("\n");
+        out.push(renderMarkdownSegment(block, md, { ...ctx, caption }, definitions));
+        if (caption.kind !== "table" && caption.kind !== "figure") {
+            out.push(
+                `\n#block(below: 0.6em)[#text(size: 7.6pt, style: "italic")[${captionMarkup(caption, ctx)}]] <${sectionLabel(anchorPrefix, slugify(caption.id))}>\n\n`,
+            );
+        }
+        cursor = caption.blockEnd;
+    }
+    out.push(renderMarkdownSegment(lines.slice(cursor).join("\n"), md, ctx, definitions));
+    return out.filter(Boolean).join("\n\n");
+}
+
+/** Render one fragment with the note's footnote definitions available. */
+function renderMarkdownSegment(source, md, ctx, definitions) {
+    const input = definitions ? `${source}\n\n${definitions}` : source;
+    const tokens = md.parse(input, {});
+    const footnoteStart = tokens.findIndex((token) => token.type === "footnote_block_open");
+    const visible = footnoteStart < 0 ? tokens : tokens.slice(0, footnoteStart);
+    const footnotes = new Map();
+    if (footnoteStart >= 0) {
+        for (let at = footnoteStart + 1; at < tokens.length; at++) {
+            if (tokens[at].type !== "footnote_open") continue;
+            const id = tokens[at].meta.id;
+            const start = at + 1;
+            while (at < tokens.length && tokens[at].type !== "footnote_close") at++;
+            footnotes.set(id, tokens.slice(start, at));
+        }
+    }
+    return renderTokens(visible, { ...ctx, footnotes });
 }
 
 /**
@@ -293,6 +391,29 @@ function renderBlock(tokens, i, out, ctx) {
             out.push(`\n#${fn}(${items.map((it) => `[${it}]`).join(", ")})\n\n`);
             return end - i + 1;
         }
+        case "dl_open": {
+            const end = matching(tokens, i, "dl_open", "dl_close");
+            const entries = [];
+            let at = i + 1;
+            while (at < end) {
+                if (tokens[at].type !== "dt_open") {
+                    at++;
+                    continue;
+                }
+                const termEnd = matching(tokens, at, "dt_open", "dt_close");
+                const term = renderTokens(tokens.slice(at + 1, termEnd), ctx);
+                at = termEnd + 1;
+                const definitions = [];
+                while (at < end && tokens[at].type === "dd_open") {
+                    const definitionEnd = matching(tokens, at, "dd_open", "dd_close");
+                    definitions.push(renderTokens(tokens.slice(at + 1, definitionEnd), ctx));
+                    at = definitionEnd + 1;
+                }
+                entries.push(`terms.item([${term}],[${definitions.join("\n\n")}])`);
+            }
+            out.push(`\n#terms(${entries.join(", ")})\n\n`);
+            return end - i + 1;
+        }
         case "table_open": {
             const end = matching(tokens, i, "table_open", "table_close");
             out.push(renderTable(tokens.slice(i, end + 1), ctx));
@@ -429,6 +550,12 @@ function listItems(tokens, start, end, ctx) {
     return items;
 }
 
+/** Caption text with the same inline Markdown handling as the surrounding prose. */
+function captionMarkup(caption, ctx) {
+    const inline = ctx.md.parseInline(caption.text, {})[0];
+    return `${escapeTypst(caption.label)}: ${renderInline(inline, ctx)}`;
+}
+
 /**
  * A markdown table as a Typst `#table`.
  *
@@ -502,11 +629,17 @@ function renderTable(tokens, ctx) {
             )}),`
         :   "";
     const drawn = `#table(\n  columns: ${columns},${alignment}${header}\n${body}\n)`;
+    const caption = ctx.caption;
+    const labelled =
+        caption ?
+            `#text(size: 7.6pt, style: "italic")[${captionMarkup(caption, ctx)}] <${sectionLabel(ctx.anchorPrefix, slugify(caption.id))}>\n${drawn}`
+        :   drawn;
     // Wide content is given an explicit span rather than left to overflow the
     // measure: past three columns a table is set across the page, and
     // `book-wide` decides between a float and pages of its own by measuring it.
-    if (columns > WIDE_TABLE_COLUMNS) return `\n#book-wide[\n${drawn}\n]\n\n`;
-    return `\n${drawn}\n\n`;
+    if (columns > WIDE_TABLE_COLUMNS)
+        return `${caption ? "" : "\n#pagebreak(weak: true)\n"}\n#book-wide[\n${labelled}\n]\n\n`;
+    return `\n${labelled}\n\n`;
 }
 
 /**
@@ -586,6 +719,21 @@ function renderInline(token, ctx) {
             case "heroiclands_icon":
                 out.push(renderIcon(child, ctx));
                 break;
+            case "footnote_ref": {
+                const label = child.meta?.label ?? String(child.meta?.id ?? "");
+                const key = `${ctx.footnotePrefix}-${slugify(label)}`;
+                const body = ctx.footnotes?.get(child.meta?.id);
+                if (!body) {
+                    out.push(escapeTypst(`[^${label}]`));
+                    break;
+                }
+                if (ctx.footnoteState.seen.has(key)) out.push(`#footnote(<${key}>)`);
+                else {
+                    ctx.footnoteState.seen.add(key);
+                    out.push(`#footnote[${renderTokens(body, ctx)}] <${key}>`);
+                }
+                break;
+            }
             case "link_open": {
                 const close = childMatching(children, i, "link_open", "link_close");
                 const inner = renderInline({ children: children.slice(i + 1, close) }, ctx);
@@ -632,10 +780,7 @@ function childMatching(children, i, open, close) {
  * @returns {string} Typst markup.
  */
 function inlineRaw(content) {
-    const text = String(content ?? "");
-    const longest = (text.match(/`+/g) ?? []).reduce((n, run) => Math.max(n, run.length), 0);
-    const ticks = "`".repeat(Math.max(1, longest + 1));
-    return `${ticks}${text}${ticks}`;
+    return `#raw("${escapeTypstString(content)}", block: false)`;
 }
 
 /**
@@ -655,6 +800,8 @@ function inlineRaw(content) {
 function renderLink(href, inner, ctx) {
     const url = String(href ?? "");
     const fragment = /#([^?]*)/.exec(url)?.[1] ?? "";
+    if (url.startsWith("#") && fragment)
+        return `#link(<${sectionLabel(ctx.anchorPrefix, fragment)}>)[${inner}]`;
     const slug =
         url
             .replace(/[#?].*$/, "")
@@ -692,7 +839,7 @@ function renderLink(href, inner, ctx) {
  * the figure at the top of the fresh one, where nothing is above it to displace
  * it and nothing that follows it can print first.
  *
- * A `.full-width` image that **also states a `float:`** is asking for a float,
+ * A `.full-width` image that **also states a `float`** is asking for a float,
  * and keeps one — deferral is the honest consequence of the request.
  *
  * ## A float occupies the measure
@@ -716,15 +863,18 @@ function renderLink(href, inner, ctx) {
  */
 function renderImage(token, ctx) {
     const alt = token.content || token.attrGet?.("alt") || "";
-    const caption = alt ? `[${escapeTypst(alt)}]` : "none";
+    const captionText = ctx.caption ? captionMarkup(ctx.caption, ctx) : escapeTypst(alt);
+    const caption = captionText ? `[${captionText}]` : "none";
+    const anchor =
+        ctx.caption ? ` <${sectionLabel(ctx.anchorPrefix, slugify(ctx.caption.id))}>` : "";
     const staged = ctx.images.get(token.attrGet?.("src") ?? "");
     if (!staged)
-        return alt ?
-                `\n#block(below: 0.6em)[#text(size: 7.6pt, style: "italic", fill: luma(45%))${caption}]\n\n`
+        return captionText ?
+                `\n#block(below: 0.6em)[#text(size: 7.6pt, style: "italic", fill: luma(45%))${caption}]${anchor}\n\n`
             :   "";
 
     const size = BOOK_IMAGE_WIDTHS[token.meta?.size] ?? BOOK_IMAGE_WIDTHS.auto;
-    const figure = `#book-image("${escapeTypstString(staged)}", requested: ${size}, caption: ${caption})`;
+    const figure = `#book-image("${escapeTypstString(staged)}", requested: ${size}, caption: ${caption})${anchor}`;
 
     const width = token.meta?.classes?.[0];
     const scope =
@@ -749,8 +899,10 @@ function renderImage(token, ctx) {
 function renderIcon(token, ctx) {
     const name = token?.meta?.name ?? "";
     const glyph = ctx.glyphs.get(name);
-    if (!glyph) return escapeTypst(`:icon-${name}:`);
-    return `#text(font: "${escapeTypstString(glyph.font)}")[\\u{${glyph.codepoint.toString(16)}}]`;
+    if (!glyph) return escapeTypst(`:icon ${name}:`);
+    const scale = ICON_SIZES[token?.meta?.attrs?.size]?.scale;
+    const size = scale ? `, size: ${scale}em` : "";
+    return `#text(font: "${escapeTypstString(glyph.font)}"${size})[\\u{${glyph.codepoint.toString(16)}}]`;
 }
 
 /**
@@ -964,11 +1116,11 @@ export function bookTypstPreamble() {
             "  }\n" +
             "}",
         "#let book-place-map(title, path) = {\n" +
-            "  page(columns: 1)[\n" +
+            "  page(columns: 1, flipped: true)[\n" +
             "    #set par(justify: false, first-line-indent: 0em)\n" +
             '    #text(size: 18pt, weight: "bold", fill: book-head)[#title]\n' +
             "    #v(0.4cm)\n" +
-            '    #image(path, width: 100%, height: book-text-height - 2cm, fit: "contain")\n' +
+            '    #image(path, width: 100%, height: book-text-width - 2cm, fit: "contain")\n' +
             "  ]\n" +
             "}",
         // Wide content spans the page, and how it spans depends on how tall it
@@ -1122,6 +1274,7 @@ export function renderBook({
     out.push(
         `#set text(font: "${escapeTypstString(serif)}", size: 9.6pt, fill: book-ink, lang: "en")`,
     );
+    out.push("#show footnote.entry: set text(size: 7.8pt)");
     out.push("#set par(justify: true, leading: 0.55em, first-line-indent: 1.2em)");
     // The first-line indent is what separates one paragraph of running prose
     // from the next, and inside a list item the marker already does that. An
@@ -1247,8 +1400,7 @@ export function renderBook({
             out.push(body);
             out.push("");
         }
-        const map = maps.get(entry.anchor);
-        if (map) {
+        for (const map of maps.get(entry.anchor) ?? []) {
             out.push(
                 `#book-place-map([${escapeTypst(map.title)}], "${escapeTypstString(map.path)}")`,
             );

package/engine/populations.mjs

@@ -217,8 +217,8 @@ function localNode(note) {
 /**
  * Read a fetched index entry into a node, or `null` where it takes no part.
  *
- * A fetched entry carries the structure its record stated and no figure, so
- * a dependency's place sits in the geography and counts nobody.
+ * A fetched entry carries its author's figure when the published index has
+ * one. An older index without a figure contributes no population.
  *
  * @param {string} canonical - The entry's address.
  * @param {object} entry - The entry.
@@ -234,6 +234,7 @@ export function foreignNode(canonical, entry) {
         type,
         subType: String(entry.subType ?? ""),
         title: String(entry.name ?? shortcode),
+        population: figureOf(entry.population),
         parents: shortcodesOf(entry.parents),
         domains: type === "affiliation" ? shortcodesOf(entry.domains) : [],
     };