@heroiclands/package-build 23.13.0 → 24.0.1

package/engine/site-config.mjs

@@ -12,76 +12,44 @@
  */
 
 /**
- * The Hugo configuration a site build generates.
- *
- * `package-build site` writes the whole Hugo source tree under `build/hugo/`
- * — `hugo.toml`, the content mount, Hugo's own cache — as a sibling of the
- * deployment root `build/site/`, so nothing Hugo reads lands in what is
- * published. The consumer's script runs Hugo over it; the toolchain never
- * does.
- *
- * Every value in the generated file has one source. The package's identity
- * (`baseURL`, `title`, `params.description`, `params.author`) is read from
- * `package.json` and `package-build.config.yaml`, where it is already stated.
- * The organisation's constants — the brand links, the locale — are stated once
- * here, because they are the same on every site and a copy per repository is
- * a copy that drifts. The navigation is neither: it is the list of packages
- * the organisation publishes, which lives in one place, heroiclands-site's
- * roster, and reaches every site as the `nav.json` that site publishes.
- * package-build carries no package list; `deps fetch` caches the navigation
- * and the site build writes `[menu.main]` from the cache.
+ * What a site build reads from the configuration: the site's address, title
+ * and parameters, and the organisation's navigation.
+ *
+ * Every value has one source. The package's identity (`baseURL`, `title`,
+ * `params.description`, `params.author`) is read from `package.json` and
+ * `package-build.config.yaml`, where it is already stated. The organisation's
+ * constants — the brand links — are stated once here, because they are the
+ * same on every site and a copy per repository is a copy that drifts. The
+ * navigation is neither: it is the list of packages the organisation
+ * publishes, which lives in one place, heroiclands-site's roster, and reaches
+ * every site as the `nav.json` that site publishes. package-build carries no
+ * package list; `deps fetch` caches the navigation and the site build reads
+ * the cache.
  *
  * What a repository still says for itself is the residue that is genuinely
- * its own — the wording of its "page not found" page — and, through
- * `site.hugo`, the one key nobody anticipated.
- * {@link module:content-config.DERIVED_HUGO_KEYS} refuses everything the
- * generator writes from being authored there too.
+ * its own, such as the wording of its "page not found" page.
  *
  * @module
  */
 
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { stringify as stringifyToml } from "smol-toml";
 
 import { checkHomepage, fail } from "../config.mjs";
-import { slugify } from "./content-slug.mjs";
 import { siteFontsParam } from "./script-font-delivery.mjs";
 
-/** The Hugo source directory, relative to the repository root. */
-export const HUGO_SOURCE = "build/hugo";
-
-/** The content mount `package-build site` writes, relative to the repository root. */
-export const HUGO_CONTENT = `${HUGO_SOURCE}/content`;
-
 /**
  * The directory that is deployed, relative to the repository root.
  *
- * Hugo renders into `<DEPLOY_ROOT>/<contentPackage>/`; `package-build
- * site-root` writes `_headers` beside it and the search index inside it.
+ * `package-build site build` renders into `<DEPLOY_ROOT>/<contentPackage>/`
+ * and writes `_headers` beside it and the search index inside it.
  */
 export const DEPLOY_ROOT = "build/site";
 
-/**
- * This package's own root, which is the directory Hugo reads themes from.
- *
- * The theme ships inside this package, so the directory holding it is found
- * from this module's own location rather than searched for.
- */
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-
-/** The theme's directory name under `themesDir`. */
-export const THEME = "hugo-theme";
-
-/** The locale every site renders in. */
-export const LOCALE = "en-us";
-
 /**
  * The brand chrome's own links, the same on every site.
  *
- * `logo` is resolved through the theme's `cdn-url.html`, so it is a path on
- * the asset host rather than an address.
+ * `logo` is a path on the asset host rather than an address.
  */
 export const BRAND = Object.freeze({
     logo: "images/brand/sohl-icon-white.webp",
@@ -89,40 +57,6 @@ export const BRAND = Object.freeze({
     discordURL: "https://discord.gg/EwMfkNd3az",
 });
 
-/**
- * The kinds no site renders.
- *
- * A site is its homepage and its pages: `home` and `page` are the only kinds,
- * for every package and whatever its notes carry. A `section` is a listing
- * Hugo would generate from a content directory; `taxonomy` and `term` are
- * listings it would generate from `tags:`; `RSS` is a feed. Every structure
- * between the homepage and the pages is authored instead, as a `doc` note
- * carrying a content table — a tag is a field such a table filters on, not a
- * page of its own.
- */
-export const DISABLE_KINDS = Object.freeze(["section", "taxonomy", "term", "RSS"]);
-
-/**
- * The markup settings the toolchain's own output requires.
- *
- * Pages are written with raw HTML in them — a `<figure>` for every image, a
- * `<span>` marking an unresolved link — and Goldmark drops raw HTML unless
- * told otherwise. A theme cannot supply this: Hugo does not merge a theme's
- * `markup` block.
- *
- * `extensions.taskList` is off because the format has no checkbox: Goldmark
- * enables it by default, which is the only reason a list item opened with
- * `[ ]` renders a `<input type="checkbox">` here and the same two characters as
- * plain text in the pack and the book. Off, a list item's text begins right
- * after its marker on every surface.
- */
-export const MARKUP = Object.freeze({
-    goldmark: Object.freeze({
-        renderer: Object.freeze({ unsafe: true }),
-        extensions: Object.freeze({ taskList: false }),
-    }),
-});
-
 /** Where the navigation is published. */
 export const NAVIGATION_URL = "https://www.heroiclands.org/nav.json";
 
@@ -144,17 +78,6 @@ const STAMP = ".complete";
  * @property {NavigationEntry[]} [children] - A dropdown's entries.
  */
 
-/**
- * A Hugo menu entry, as `[[menu.main]]` states one.
- *
- * @typedef {object} MenuEntry
- * @property {string} name
- * @property {string} url
- * @property {number} weight
- * @property {string} [identifier] - Set on an entry that has children.
- * @property {string} [parent] - Set on a child, naming its parent's identifier.
- */
-
 /**
  * @param {unknown} value - Anything.
  * @returns {value is Record<string, unknown>} Whether it is a plain mapping.
@@ -180,7 +103,7 @@ function requireNonEmptyString(value, where) {
  *
  * `[{name, url, children?: [{name, url}]}]`, every `url` absolute. Checked
  * on fetch and again on read: a file that is not a navigation would otherwise
- * reach the generated menu as `undefined` labels and links.
+ * reach the menu as `undefined` labels and links.
  *
  * @param {unknown} value - The parsed document.
  * @param {string} where - What is being checked, for the error.
@@ -214,35 +137,6 @@ export function checkNavigation(value, where = "the navigation") {
     return value.map((entry, i) => check(entry, `${where}[${i}]`, false));
 }
 
-/**
- * The `[[menu.main]]` entries a navigation renders as.
- *
- * Entry for entry, in order; a dropdown is an entry with an `identifier` and
- * its children are entries naming it as `parent`, which is how the theme's
- * header partial draws one. Weights count from one within each level, so the
- * order is the navigation's and not Hugo's alphabetical fallback.
- *
- * @param {readonly NavigationEntry[]} navigation - The navigation.
- * @returns {MenuEntry[]} The menu entries.
- */
-export function menuEntries(navigation) {
-    /** @type {MenuEntry[]} */
-    const out = [];
-    navigation.forEach((entry, index) => {
-        const children = entry.children ?? [];
-        if (!children.length) {
-            out.push({ name: entry.name, url: entry.url, weight: index + 1 });
-            return;
-        }
-        const identifier = slugify(entry.name);
-        out.push({ name: entry.name, url: entry.url, weight: index + 1, identifier });
-        children.forEach((child, i) => {
-            out.push({ name: child.name, url: child.url, weight: i + 1, parent: identifier });
-        });
-    });
-    return out;
-}
-
 /**
  * Where the fetched navigation sits.
  *
@@ -314,66 +208,23 @@ export async function fetchNavigation(
 }
 
 /**
- * The `themesDir` for a repository, as the path from `build/hugo/` to the
- * directory holding the theme.
- *
- * The theme ships inside this package at `hugo-theme/`, so the directory Hugo
- * reads themes from is {@link PACKAGE_ROOT}. `theme` stays {@link THEME}, so
- * Hugo opens `<themesDir>/hugo-theme/layouts`.
- *
- * Written as a path rather than assumed: `build/hugo/` and the installed
- * package sit at whatever distance the install put them, and a worktree
- * resolving its parent's install says so in the generated file.
- *
- * @param {string} rootDir - The repository root.
- * @returns {string} The relative path, POSIX-separated.
- */
-export function resolveThemesDir(rootDir) {
-    const from = path.resolve(rootDir, HUGO_SOURCE);
-    return path.relative(from, PACKAGE_ROOT).split(path.sep).join("/");
-}
-
-/**
- * Deep-merge `overrides` over `base`, arrays replaced whole.
- *
- * @param {Record<string, unknown>} base - The generated configuration.
- * @param {Record<string, unknown>} overrides - What `site.hugo` declares.
- * @returns {Record<string, unknown>} A new object.
- */
-function deepMerge(base, overrides) {
-    /** @type {Record<string, unknown>} */
-    const out = { ...base };
-    for (const [key, value] of Object.entries(overrides)) {
-        const current = out[key];
-        out[key] =
-            isPlainObject(current) && isPlainObject(value) ?
-                deepMerge(current, value)
-            :   structuredClone(value);
-    }
-    return out;
-}
-
-/**
- * The Hugo configuration, as an object.
- *
- * Pure: every input is handed in, so a test can describe the generated shape
- * without a repository on disk. {@link generateHugoConfig} is the same function
- * with the reading put back.
+ * What a site is, read from the configuration: its address, its title and the
+ * parameters its layouts read.
  *
  * `checkHomepage` runs first, before any value is composed — a missing or
  * mismatched `package.json` `homepage` is a finding on every site build.
  *
  * @param {object} options - The sources.
  * @param {object} options.config - The resolved build configuration.
- * @param {readonly NavigationEntry[]} options.navigation - The navigation.
- * @param {string} options.themesDir - From {@link resolveThemesDir}.
- * @returns {Record<string, any>} The configuration Hugo reads.
+ * @returns {{baseURL: string, title: string, params: Record<string, unknown>}}
+ *   The site. `params` holds `description`, `author`, `cdnBaseURL`, `brand`,
+ *   `notfound` and `scriptFonts`, each where the configuration states it.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
  *   configuration declares no `site.title` or `packageBuild.manifest.title`, no
  *   `site.description`, or no `site.assets`.
  */
-export function hugoConfig({ config, navigation, themesDir }) {
-    checkHomepage(config.homepage, config.contentPackage);
+export function siteSettings({ config }) {
+    checkHomepage(config.homepage, config.contentPackage, config.site.base);
 
     const title = config.site.title || config.packageBuild?.manifest?.title;
     if (typeof title !== "string" || !title.trim()) {
@@ -407,68 +258,5 @@ export function hugoConfig({ config, navigation, themesDir }) {
     // it does not ship.
     const scriptFonts = siteFontsParam(config);
     if (scriptFonts) params.scriptFonts = scriptFonts;
-
-    const generated = {
-        baseURL: config.homepage,
-        title,
-        locale: LOCALE,
-        publishDir: path.posix.relative(HUGO_SOURCE, `${DEPLOY_ROOT}/${config.contentPackage}`),
-        themesDir,
-        theme: THEME,
-        contentDir: path.posix.relative(HUGO_SOURCE, HUGO_CONTENT),
-        disableKinds: [...DISABLE_KINDS],
-        params,
-        markup: structuredClone(MARKUP),
-        menu: { main: menuEntries(navigation) },
-    };
-    return deepMerge(generated, config.site.hugo);
-}
-
-/**
- * The configuration as the TOML Hugo reads.
- *
- * @param {Record<string, unknown>} generated - From {@link hugoConfig}.
- * @returns {string} The file's contents.
- */
-export function hugoToml(generated) {
-    return (
-        "# Generated by `package-build site` from package.json and " +
-        "package-build.config.yaml.\n# Every value here has a source there; edit " +
-        "the source, not this file.\n\n" +
-        `${stringifyToml(generated)}\n`
-    );
-}
-
-/**
- * The Hugo configuration, every source read from the repository.
- *
- * Reads the cached navigation and the installed theme's location, and
- * composes them with {@link hugoConfig}. Nothing is written, so a caller can
- * run this before touching the output tree and fail with it intact.
- *
- * @param {object} config - The resolved build configuration.
- * @returns {Record<string, any>} The configuration Hugo reads.
- * @throws {Error} When any source is missing or wrong.
- */
-export function generateHugoConfig(config) {
-    return hugoConfig({
-        config,
-        navigation: readCachedNavigation(config),
-        themesDir: resolveThemesDir(config.rootDir),
-    });
-}
-
-/**
- * Write `build/hugo/hugo.toml`.
- *
- * @param {object} config - The resolved build configuration.
- * @param {Record<string, unknown>} [generated] - The configuration to write,
- *   when the caller already generated it. Generated here otherwise.
- * @returns {{file: string}} The file written.
- */
-export function writeHugoConfig(config, generated = generateHugoConfig(config)) {
-    const file = path.join(config.rootDir, HUGO_SOURCE, "hugo.toml");
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, hugoToml(generated));
-    return { file };
+    return { baseURL: config.homepage, title, params };
 }

package/engine/site-files.mjs

@@ -0,0 +1,175 @@
+/*
+ * 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 files a site writes beside its pages**, for search engines and feed
+ * readers:
+ *
+ * | File | Holds |
+ * | ---- | ----- |
+ * | `sitemap.xml` | every page of the site, by its full address ({@link sitemapXml}) |
+ * | a sitemap index | every site's sitemap ({@link sitemapIndexXml}) |
+ * | `robots.txt` | where every sitemap is ({@link robotsTxt}) |
+ * | an Atom feed | a section's posts, newest first ({@link atomFeed}) |
+ *
+ * Each is a pure function of what it is given, and states no time of its own:
+ * a date is a page's date, so a build of the same content writes the same
+ * files.
+ *
+ * @module
+ */
+
+/** @param {unknown} value */
+const text = (value) => (value === undefined || value === null ? "" : String(value));
+
+/**
+ * Text escaped for XML content and attribute values.
+ *
+ * @param {unknown} value - The text.
+ * @returns {string} The escaped text.
+ */
+export function escapeXml(value) {
+    return text(value)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+
+/**
+ * A date as an RFC 3339 timestamp, or `""` for a value that is no date.
+ *
+ * @param {unknown} value - A date, or a string a `Date` reads.
+ * @returns {string} The timestamp, in UTC.
+ */
+export function timestamp(value) {
+    if (value === undefined || value === null || value === "") return "";
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? "" : date.toISOString().replace(/\.000Z$/, "Z");
+}
+
+/**
+ * A site's sitemap.
+ *
+ * @param {Array<{loc: string, lastmod?: unknown}>} entries - Each page's full
+ *   address, and the date it states where it states one.
+ * @returns {string} The document.
+ */
+export function sitemapXml(entries) {
+    const urls = entries.map((entry) => {
+        const lastmod = timestamp(entry.lastmod);
+        return [
+            "  <url>",
+            `    <loc>${escapeXml(entry.loc)}</loc>`,
+            ...(lastmod ? [`    <lastmod>${lastmod}</lastmod>`] : []),
+            "  </url>",
+        ].join("\n");
+    });
+    return [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+        ...urls,
+        "</urlset>",
+        "",
+    ].join("\n");
+}
+
+/**
+ * A sitemap index naming other sitemaps.
+ *
+ * @param {readonly string[]} sitemaps - Each sitemap's full address.
+ * @returns {string} The document.
+ */
+export function sitemapIndexXml(sitemaps) {
+    return [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+        ...sitemaps.map((loc) => `  <sitemap>\n    <loc>${escapeXml(loc)}</loc>\n  </sitemap>`),
+        "</sitemapindex>",
+        "",
+    ].join("\n");
+}
+
+/**
+ * The `robots.txt` of a site's root: every agent may read every page, and
+ * every sitemap is named.
+ *
+ * @param {readonly string[]} sitemaps - Each sitemap's full address, the
+ *   sitemap index first.
+ * @returns {string} The file.
+ */
+export function robotsTxt(sitemaps) {
+    return ["User-agent: *", "Allow: /", "", ...sitemaps.map((loc) => `Sitemap: ${loc}`), ""].join(
+        "\n",
+    );
+}
+
+/**
+ * An Atom feed.
+ *
+ * The feed is dated by its newest entry, and an entry by its own date, so the
+ * feed changes only when a post does.
+ *
+ * @param {object} feed - The feed.
+ * @param {string} feed.title - The feed's title.
+ * @param {string} feed.id - The full address of the page the feed follows,
+ *   which is also its id.
+ * @param {string} feed.self - The feed's own full address.
+ * @param {string} [feed.author] - Who writes the posts, where an entry names
+ *   no author of its own.
+ * @param {Array<{title: string, url: string, date: unknown, author?: string,
+ *   summary?: string, content?: string}>} feed.entries - The posts, each with
+ *   its full address and its HTML `content`.
+ * @returns {string} The document.
+ */
+export function atomFeed({ title, id, self, author, entries }) {
+    const dated = entries
+        .map((entry) => ({ ...entry, updated: timestamp(entry.date) }))
+        .filter((entry) => entry.updated)
+        .sort((a, b) =>
+            a.updated < b.updated ? 1
+            : a.updated > b.updated ? -1
+            : a.url < b.url ? -1
+            : 1,
+        );
+    const name = (who) => `<author><name>${escapeXml(who)}</name></author>`;
+    const lines = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<feed xmlns="http://www.w3.org/2005/Atom">',
+        `  <title>${escapeXml(title)}</title>`,
+        `  <id>${escapeXml(id)}</id>`,
+        `  <link rel="self" type="application/atom+xml" href="${escapeXml(self)}"/>`,
+        `  <link rel="alternate" type="text/html" href="${escapeXml(id)}"/>`,
+        ...(dated.length ? [`  <updated>${dated[0].updated}</updated>`] : []),
+        ...(author ? [`  ${name(author)}`] : []),
+    ];
+    for (const entry of dated) {
+        lines.push(
+            "  <entry>",
+            `    <title>${escapeXml(entry.title)}</title>`,
+            `    <id>${escapeXml(entry.url)}</id>`,
+            `    <link rel="alternate" type="text/html" href="${escapeXml(entry.url)}"/>`,
+            `    <published>${entry.updated}</published>`,
+            `    <updated>${entry.updated}</updated>`,
+            ...(entry.author ? [`    ${name(entry.author)}`] : []),
+            ...(entry.summary ? [`    <summary>${escapeXml(entry.summary)}</summary>`] : []),
+            ...(entry.content ?
+                [`    <content type="html">${escapeXml(entry.content)}</content>`]
+            :   []),
+            "  </entry>",
+        );
+    }
+    lines.push("</feed>", "");
+    return lines.join("\n");
+}

package/engine/site-index.mjs

@@ -82,12 +82,15 @@ import { isGmNote, isDraftNote } from "./note-vocabulary.mjs";
  *                           through unindexed.
  * @property {object} fm     The note's frontmatter.
  * @property {string} name   Display name.
- * @property {string} slug   URL segment.
- * @property {string} base   Source file's basename, e.g. `Climbing.md`.
+ * @property {string} [slug]  URL segment.
+ * @property {string} [base] Source file's basename, e.g. `Climbing.md`.
  * @property {string} url    The page's published address.
  * @property {string} [body] The note's markdown body, for its anchors. A
  *                           content entry always carries one; absent, the
  *                           page is indexed as declaring none.
+ * @property {object[]} [anchors] The anchors the body declares, when the
+ *                           caller holds them already — a content-index
+ *                           record's — in place of reading `body`.
  */
 
 /**
@@ -163,7 +166,9 @@ function mergeForeign(index, foreignIndex) {
  * Build the address index a site's wikilink resolver reads.
  *
  * @param {readonly SiteEntry[]} entries - Every page the site will publish,
- *   each already knowing its own `url`.
+ *   each already knowing its own `url`. An entry may carry the `anchors` its
+ *   body declares, from a content-index record, in place of the body they are
+ *   read from.
  * @param {object} [options] - Cross-package inputs.
  * @param {string} [options.package] - The builder's own content package.
  * @param {string} [options.currentDate="720.1"] - Setting-wide neutral date for recurring events.
@@ -254,7 +259,7 @@ export function buildSiteIndex(
         // `subType` is: a being states a rank as a number, and what that
         // number is called is declared on the body.
         const standings = standingsDigest(e.fm);
-        const noteAnchors = collectAnchors(e.body ?? "", 1, undefined, syntax);
+        const noteAnchors = e.anchors ?? collectAnchors(e.body ?? "", 1, undefined, syntax);
         const value = {
             url: e.url,
             name: e.name,