@heroiclands/package-build 23.12.8 → 24.0.0

package/engine/heading-attributes.mjs

@@ -216,6 +216,95 @@ export function headingAttributesPlugin(md) {
     });
 }
 
+/**
+ * The id a heading's text gives it on the web: GitHub's form, lower case, each
+ * space or hyphen a hyphen, every character that is not a letter, a digit or
+ * an underscore dropped.
+ *
+ * @param {string} text - The heading's text, without its markup.
+ * @returns {string} The id, or `heading` when nothing is left of the text.
+ */
+export function headingId(text) {
+    let id = "";
+    for (const char of String(text ?? "").trim()) {
+        if (char === " " || char === "-") id += "-";
+        else if (char === "_" || /[\p{L}\p{Nd}]/u.test(char)) id += char.toLowerCase();
+    }
+    return id || "heading";
+}
+
+/** The tokens whose content is a heading's text. */
+const TEXT_TOKENS = new Set(["text", "code_inline", "typographic"]);
+
+/**
+ * The text a heading's id is made from.
+ *
+ * Its words, code and punctuation; a line break as a newline; no markup. An
+ * element inside the heading — emphasis, a link, an image — gives only its
+ * first piece of text, which ends at the first punctuation the page sets
+ * typographically, so `[Nkaru'thar](…)` gives `Nkaru`.
+ *
+ * @param {object[]} children - The heading's inline tokens.
+ * @returns {string} The text.
+ */
+function headingText(children) {
+    const list = children ?? [];
+    /** The first piece of text inside the element opening at `index`. */
+    const first = (index) => {
+        const token = list[index];
+        if (!token || token.nesting === -1) return "";
+        if (TEXT_TOKENS.has(token.type)) return token.content;
+        if (token.type === "image") return headingText(token.children?.slice(0, 1));
+        if (token.nesting === 1) return first(index + 1);
+        return "";
+    };
+    let text = "";
+    for (let i = 0; i < list.length; i++) {
+        const token = list[i];
+        if (TEXT_TOKENS.has(token.type)) text += token.content;
+        else if (token.type === "softbreak" || token.type === "hardbreak") text += "\n";
+        else if (token.type === "image") text += headingText(token.children?.slice(0, 1));
+        else if (token.nesting === 1) {
+            text += first(i + 1);
+            for (let depth = 1; depth > 0 && i + 1 < list.length;) {
+                i++;
+                depth += list[i].nesting;
+            }
+        }
+    }
+    return text;
+}
+
+/**
+ * Give every heading an id, so a page's contents list and a reader's link can
+ * name any section.
+ *
+ * An authored `{#id}` is kept, and every other heading takes {@link headingId}
+ * of its text. A repeated id takes `-1`, `-2` and so on, counted over every id
+ * on the page that came before it.
+ *
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function headingIdsPlugin(md) {
+    md.core.ruler.push("heading_ids", (state) => {
+        const taken = new Set();
+        const tokens = state.tokens;
+        for (let i = 0; i < tokens.length; i++) {
+            if (tokens[i].type !== "heading_open") continue;
+            const authored = tokens[i].attrGet("id");
+            if (authored) {
+                taken.add(authored);
+                continue;
+            }
+            const base = headingId(headingText(tokens[i + 1]?.children));
+            let id = base;
+            for (let n = 1; taken.has(id); n++) id = `${base}-${n}`;
+            taken.add(id);
+            tokens[i].attrSet("id", id);
+        }
+    });
+}
+
 /**
  * Parse one line as a heading, and say whether it starts a journal page.
  *

package/engine/helpers.mjs

@@ -25,8 +25,7 @@
  * journals.mjs, actors.mjs).
  */
 
-import { renderAlerts } from "./content-alerts.mjs";
-import { renderRuns } from "./content-scripts.mjs";
+import { createRenderer } from "./content-render.mjs";
 import { buildReferenceTargets } from "./reference-targets.mjs";
 import { standingsDigest } from "./standings.mjs";
 
@@ -39,12 +38,7 @@ import crypto from "crypto";
 import path from "path";
 import yaml from "yaml";
 import unidecode from "unidecode";
-import markdownit from "markdown-it";
-import footnotePlugin from "markdown-it-footnote";
-import deflistPlugin from "markdown-it-deflist";
-import { dictionaryListPlugin } from "./definition-list.mjs";
-import { iconPlugin } from "./content-icons.mjs";
-import { imagePlugin, imagesIn } from "./content-images.mjs";
+import { imagesIn } from "./content-images.mjs";
 import { embedRole, resolveEmbeds } from "./content-embeds.mjs";
 import { collectAssetRecords } from "./asset-index.mjs";
 import { assetImageInfoByPathname } from "./art-fields.mjs";
@@ -67,19 +61,15 @@ import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs
 // a record needs none of that.
 import { authoredFrontmatter, isAssetRecord, isNoteRecord, noteFile } from "./index-records.mjs";
 import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
-// One vocabulary of link findings, and one message per class, so the three
-// resolvers cannot word the same defect differently.
+// One vocabulary of link findings, and one message per class, so no two
+// builds word the same defect differently.
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
 // The declared tag vocabulary, which is where `draft` is stated. Read
 // from there rather than respelt, so the tag and its one reader cannot drift.
 import { isGmNote, isDraftNote } from "./note-vocabulary.mjs";
 import { DERIVED_PACKED_TYPES, NEVER_PACKED_TYPES } from "./note-claims.mjs";
 import { expandContentTables } from "./content-tables.mjs";
-import { spanMarkdownPlugin } from "./content-spans.mjs";
-import { dictionaryEntryPlugin } from "./dictionary-layout.mjs";
-import { renderBlocks } from "./content-blocks.mjs";
-import { headingAttributesPlugin } from "./heading-attributes.mjs";
-import { renderFigureBlocks, scanFigures } from "./content-figures.mjs";
+import { scanFigures } from "./content-figures.mjs";
 import { positionInBody, splitFrontmatter } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
 // registry can import them without reaching back through this one.
@@ -100,72 +90,68 @@ export {
 let localAssetImageInfoCache;
 
 /**
- * The markdown renderer every surface shares.
+ * The Foundry renderer: the shared configuration of
+ * {@link module:engine/content-render.createRenderer} for the `foundry`
+ * target.
  *
  * `html: true` is long-standing and load-bearing — notes carry raw blocks — and
  * it is also why {@link module:engine/content-icons} exists rather than an
  * instruction to write `<i class="fa-solid …">` by hand: that would render on
  * the two HTML surfaces and be silently dropped by the third.
+ *
+ * The icon registry and the image resolvers are read per render, not at import:
+ * this constant is built before any configuration is read, and a package's own
+ * icons live in the configuration. A tree with none — or a caller with no
+ * configuration to find — falls back to the shipped table and to the authored
+ * pathname.
  */
-export const md = markdownit({ html: true })
-    .use(footnotePlugin)
-    .use(deflistPlugin)
-    .use(dictionaryListPlugin)
-    .use(spanMarkdownPlugin, { spoilers: true })
-    .use(dictionaryEntryPlugin)
-    // A heading's attribute block, written onto the heading element rather than
-    // typeset into it — the reading the website's renderer does for itself.
-    .use(headingAttributesPlugin)
-    .use(
-        // Resolved per render, not at import: this constant is built before any
-        // configuration is read, and a package's own icons live in the
-        // configuration. A tree with none — or a caller with no configuration to
-        // find — falls back to the shipped table.
-        iconPlugin(() => {
-            try {
-                return loadPackConfig().icons;
-            } catch {
-                return undefined;
-            }
-        }),
-    )
+const renderer = createRenderer("foundry", {
+    icons: () => {
+        try {
+            return loadPackConfig().icons;
+        } catch {
+            return undefined;
+        }
+    },
     // The width and position an image states, honoured as a figure. The
     // vocabularies are closed and need no configuration; the address does, and
     // is resolved per render for the reason the icon registry is — Foundry
     // serves a file from inside the install, so a body image's address is
     // translated by the same rule `img:` follows.
-    .use(
-        imagePlugin(
-            (src) => {
-                // **Reported upstream, never here.** A renderer has no channel to
-                // report through, and this one runs inside the very passes whose
-                // job is to collect findings — a throw would take the whole lint
-                // down and lose every other finding in the tree. So nothing reaches
-                // this point unreported: {@link convertNoteWikilinks} refuses a body
-                // image with no address inside the install before a compiler renders
-                // one, and the address passes report the same pathname with a line
-                // and a column. What is left here is a fallback for a caller with no
-                // configuration to resolve against, where the authored pathname is
-                // the most honest thing to emit.
-                try {
-                    return resolveImg(src, loadPackConfig()) ?? src;
-                } catch {
-                    return src;
-                }
-            },
-            (src) => {
-                // A body image is free to write the bare, own-package form,
-                // so the address is normalized to the pathname the cache
-                // below keys by before it is looked up.
-                try {
-                    const key = assetPathnameKey(src, loadPackConfig());
-                    return key ? localAssetImageInfo().get(key) : undefined;
-                } catch {
-                    return undefined;
-                }
-            },
-        ),
-    );
+    images: {
+        resolveSrc: (src) => {
+            // **Reported upstream, never here.** A renderer has no channel to
+            // report through, and this one runs inside the very passes whose
+            // job is to collect findings — a throw would take the whole lint
+            // down and lose every other finding in the tree. So nothing reaches
+            // this point unreported: {@link convertNoteWikilinks} refuses a body
+            // image with no address inside the install before a compiler renders
+            // one, and the address passes report the same pathname with a line
+            // and a column. What is left here is a fallback for a caller with no
+            // configuration to resolve against, where the authored pathname is
+            // the most honest thing to emit.
+            try {
+                return resolveImg(src, loadPackConfig()) ?? src;
+            } catch {
+                return src;
+            }
+        },
+        lookupAsset: (src) => {
+            // A body image is free to write the bare, own-package form,
+            // so the address is normalized to the pathname the cache
+            // below keys by before it is looked up.
+            try {
+                const key = assetPathnameKey(src, loadPackConfig());
+                return key ? localAssetImageInfo().get(key) : undefined;
+            } catch {
+                return undefined;
+            }
+        },
+    },
+});
+
+/** The Foundry renderer's parser, for callers that parse or render a fragment. */
+export const md = renderer.md;
 
 /**
  * The pictures this package's own tree ships, by the pathname their address
@@ -194,25 +180,6 @@ function localAssetImageInfo() {
     return localAssetImageInfoCache;
 }
 
-md.renderer.rules.footnote_block_open = () =>
-    '<section class="footnotes"><h2>Footnotes</h2><ol class="footnotes-list">\n';
-md.renderer.rules.footnote_caption = (tokens, idx, _options, env) => {
-    const meta = tokens[idx].meta;
-    const number = env.footnoteNumbers?.get(meta.label) ?? meta.id + 1;
-    return `[${number}${meta.subId > 0 ? `:${meta.subId}` : ""}]`;
-};
-md.renderer.rules.footnote_anchor_name = (tokens, idx, _options, env) => {
-    const meta = tokens[idx].meta;
-    const number = env.footnoteNumbers?.get(meta.label) ?? meta.id + 1;
-    return `${env.docId ? `-${env.docId}-` : ""}${number}`;
-};
-md.renderer.rules.footnote_open = (tokens, idx, options, env, renderer) => {
-    const meta = tokens[idx].meta;
-    const number = env.footnoteNumbers?.get(meta.label) ?? meta.id + 1;
-    const id = renderer.rules.footnote_anchor_name(tokens, idx, options, env, renderer);
-    return `<li id="fn${id}" class="footnote-item" value="${number}">`;
-};
-
 /**
  * Render a note body with Foundry's named-block markup.
  *
@@ -232,12 +199,7 @@ md.renderer.rules.footnote_open = (tokens, idx, options, env, renderer) => {
  * @returns {string} The rendered HTML.
  */
 export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, resolveRole, runs) {
-    const marked = runs ? renderRuns(body, runs, undefined, { target: "foundry" }).markdown : body;
-    const figured = renderFigureBlocks(marked, (block) => md.render(block), figures, {
-        resolveRole,
-    });
-    const blocks = renderBlocks(figured.markdown, "foundry");
-    return md.render(renderAlerts(blocks.markdown, "foundry").markdown, { footnoteNumbers, docId });
+    return renderer.render(body, { runs, figures, resolveRole, footnoteNumbers, docId });
 }
 
 /**
@@ -983,7 +945,7 @@ export function buildContentLinkIndex(
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line.
  * @param {number} [ctx.bodyColumn] - 1-based file column of the same character.
  * @param {Array<{line: number, generated: boolean}>} [ctx.lineMap] - Which
- *   authored line each body line came from, from {@link expandNoteTables}.
+ *   authored line each body line came from, from {@link module:engine/content-tables.expandContentTables}.
  * @returns {{markdown: string, unresolved: Array<object>}}
  * @throws {Error} On any link that does not resolve — an unlabelled one, a
  *   target that is not an address, or an address nothing publishes — and on a
@@ -1086,11 +1048,9 @@ export function convertNoteWikilinks(
     }
 
     for (const u of result.unresolved) {
-        // Every class fails, and every class is worded by the shared table.
-        // The three resolvers read one authored link, so an author who
-        // ran the pack build first and the link checker second must not be told
-        // two different things about the same mistake — and a class the pack
-        // build alone knew how to describe is how they came apart before.
+        // Every class fails, and every class is worded by the shared table,
+        // so an author who ran the pack build first and the link checker second
+        // is told one thing about one mistake.
         //
         // The note's name is appended rather than woven in: the message is the
         // defect, the name is the context this build can add.

package/engine/homepage.mjs

@@ -43,8 +43,8 @@
  * module, which is most of the packages that need a homepage and nothing else.
  *
  * **Published at the package root, addressed like every other note.** A
- * homepage is written as the mount's `_index.md`, so Hugo's `home` kind renders
- * it at `/<package>/` — the address a reader expects a package's front page at,
+ * homepage is rendered at `/<package>/` — the address a reader expects a
+ * package's front page at,
  * and the one `package.json`'s `homepage` states. It still declares a
  * `shortcode` — conventionally {@link HOMEPAGE_SHORTCODE} — because that is what
  * a link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and
@@ -96,19 +96,6 @@ export const HOMEPAGE_FIELDS = Object.freeze([]);
  */
 export const HOMEPAGE_SHORTCODE = "root";
 
-/**
- * The file a homepage is written to, relative to the package's site root.
- *
- * The mount's own `_index.md`: Hugo renders it as the `home` kind, at
- * `baseURL` — which is `/<package>/`, the package's own address. One fixed
- * destination rather than one derived from the note's address, because the
- * homepage's address *is* the package root; the note's `shortcode` names the
- * page in links and decides no file.
- *
- * @type {string}
- */
-export const HOMEPAGE_DESTINATION = "_index.md";
-
 /**
  * Whether a note's frontmatter declares the homepage type.
  *
@@ -337,8 +324,10 @@ function positionOfType(file) {
  * authored `name.full` wins, because a front page may greet a reader
  * differently from a package browser.
  *
- * Falls back to `contentPackage` last, so a package that has no manifest of its
- * own still yields a titled page rather than a blank heading.
+ * A package with no manifest title — a `documentation` package has no manifest
+ * at all — takes `site.title`, the name its site is known by. It falls back to
+ * `contentPackage` last, so a package that states neither still yields a
+ * titled page rather than a blank heading.
  *
  * @param {object|null|undefined} fm - The note's frontmatter.
  * @param {object} config - The resolved configuration.
@@ -351,7 +340,9 @@ export function homepageTitle(fm, config) {
         config?.packageBuild?.manifest
     );
     const title = manifest?.title;
-    return typeof title === "string" && title.trim() ? title : config.contentPackage;
+    if (typeof title === "string" && title.trim()) return title;
+    const site = config?.site?.title;
+    return typeof site === "string" && site.trim() ? site : config.contentPackage;
 }
 
 /**
@@ -359,20 +350,17 @@ export function homepageTitle(fm, config) {
  *
  * The note's own, plus the two derived values every emitted page carries: the
  * resolved `title`, and the package the build derived — no note declares one
- * and the theme's breadcrumb partial reads `.Params.package`.
+ * and the theme's breadcrumbs read.
  *
- * **No `url` and no `slug`.** Hugo publishes the `home` kind at `baseURL`,
- * whose path is already where the package is served, so the page has no
- * address to state; a content page states one because its file sits under the
- * mount and its address does not.
+ * **No `url` and no `slug`.** The homepage publishes at the package root, so
+ * the page has no address to state.
  *
- * An authored `aliases` is dropped for the same reason it is on every other
- * page: Hugo reads it as URL redirects, so passing it through would publish a
- * redirect stub at each one.
+ * An authored `aliases` is dropped, as it is on every other page: this build
+ * emits no redirects.
  *
  * `related` is derived like every other page's — what links to the homepage
  * is a fact about the rest of the tree — so an authored value is dropped and
- * the caller's block, where it has one, is written in its place.
+ * the caller's block, where it has one, is set in its place.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
@@ -380,7 +368,7 @@ export function homepageTitle(fm, config) {
  * @param {string} options.title - The resolved title.
  * @param {object} [options.related] - The homepage's backlinks and mentions,
  *   where the site build found either.
- * @returns {object} The frontmatter to write.
+ * @returns {object} The frontmatter.
  */
 export function homepageFrontmatter(fm, { contentPackage, title, related }) {
     const data = { ...fm, package: contentPackage, title };
@@ -395,7 +383,7 @@ export function homepageFrontmatter(fm, { contentPackage, title, related }) {
  *
  * Reference-style links are deliberately not matched: a homepage is published
  * verbatim, so a `[x][y]` whose definition sits in the body reaches the reader
- * as Hugo renders it, and one whose definition is missing is a defect the
+ * as authored, and one whose definition is missing is a defect the
  * rendered page shows for itself.
  *
  * @type {RegExp}

package/engine/html-minify.mjs

@@ -0,0 +1,70 @@
+/*
+ * 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
+ */
+
+/**
+ * **Minified site pages.** {@link minifyHtml} drops what a browser does not
+ * read: comments, and every run of white space but one character.
+ *
+ * What a reader sees is unchanged. A run of white space between two words or
+ * two tags still separates them, as one space; it is only made shorter. The
+ * places where white space is the content are kept exactly as written: a
+ * `<pre>`, a `<textarea>`, a `<script>` or `<style>`, and a verse's lines,
+ * which set their spacing as authored. A tag is kept as written too, its
+ * attribute values included.
+ *
+ * @module
+ */
+
+/** The elements whose content is written out as it stands. */
+const VERBATIM = /^<(pre|textarea|script|style)\b/i;
+
+/** A verse's spans, whose white space is set as authored. */
+const VERSE_SPAN = /\bclass\s*=\s*"[^"]*\bverse-(?:line|column|part)\b/i;
+
+/**
+ * Minify a page.
+ *
+ * @param {string} html - A complete document.
+ * @returns {string} The same document without comments and with each run of
+ *   white space outside the verbatim elements cut to one character: a newline
+ *   where the run held one, a space otherwise.
+ */
+export function minifyHtml(html) {
+    const source = String(html ?? "");
+    const pieces =
+        /<!--[\s\S]*?-->|<(pre|textarea|script|style)\b[^>]*>[\s\S]*?<\/\1\s*>|<[^>]*>|[^<]+|</gi;
+    const verse = [];
+    let out = "";
+    for (const [piece] of source.matchAll(pieces)) {
+        if (piece.startsWith("<!--")) {
+            // A conditional comment is read by the browser it names.
+            if (piece.startsWith("<!--[if")) out += piece;
+            continue;
+        }
+        if (piece.startsWith("<")) {
+            if (VERBATIM.test(piece)) {
+                out += piece;
+                continue;
+            }
+            if (/^<span\b/i.test(piece)) verse.push(verse.at(-1) || VERSE_SPAN.test(piece));
+            else if (/^<\/span\s*>/i.test(piece)) verse.pop();
+            out += piece;
+            continue;
+        }
+        out +=
+            verse.at(-1) ? piece : (
+                piece.replace(/\s+/g, (run) => (run.includes("\n") ? "\n" : " "))
+            );
+    }
+    return out.replace(/^\s+/, "");
+}

package/engine/index.mjs

@@ -216,6 +216,12 @@ export * as siteBuild from "./site-build.mjs";
 /** In-memory page rendering for an editor preview. */
 export * as sitePreview from "./site-preview.mjs";
 
+/** What an editor with a content index gives the preview, so it renders as the site does. */
+export * as previewIndex from "./preview-index.mjs";
+
+/** The one markdown-it configuration every target renders through. */
+export * as contentRender from "./content-render.mjs";
+
 /** Address rules every content tree is linted against: shape, uniqueness, alias. */
 export * as contentLint from "./content-lint.mjs";
 
@@ -244,9 +250,6 @@ export * as pathnames from "./pathnames.mjs";
 /** Resolving every link in a tree, and the ones that land nowhere. */
 export * as contentLinks from "./content-links.mjs";
 
-/** Wikilinks resolved to a **web URL** — the site half of the pair below. */
-export * as webWikilinks from "./web-wikilinks.mjs";
-
 /** Prepared SQL content tables, expanded into Markdown at compile time. */
 export * as contentTables from "./content-tables.mjs";
 
@@ -262,10 +265,10 @@ export * as documentSubtypes from "./document-subtypes.mjs";
 /** Which types carry documentation of their own, and where it is addressed. */
 export * as itemDocs from "./item-docs.mjs";
 
-/** Wikilinks resolved to a **Foundry UUID**: qualifiers, the index, rewriting. */
+/** The link resolver: the pack index, the views, and each target's link form. */
 export * as wikilinks from "./wikilinks.mjs";
 
-/** What a `[[…]]` is, before either resolver decides where it points. */
+/** What a `[[…]]` is, before the resolver decides where it points. */
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
 
 /** The address index a site build resolves its wikilinks against. */