@heroiclands/package-build 23.13.0 → 24.0.0

package/types/engine/site-build.d.mts

@@ -3,9 +3,10 @@
  *
  * @param {string} contentBase - Absolute path to the content tree.
  * @param {object} ctx - `{ packages, contentPackage, skipDirectories, base,
- *   mount, scheme }`. `contentPackage` is the package a note that declares none
- *   belongs to; `base` is where the package is served and `mount` is where its
- *   content tree sits inside it.
+ *   mount, scheme, only }`. `contentPackage` is the package a note that
+ *   declares none belongs to; `base` is where the package is served and `mount`
+ *   is where its content tree sits inside it. `only`, an absolute path, reads
+ *   that one note and no other.
  * @returns {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}
  */
 export function collectContentPages(contentBase: string, ctx: object): {
@@ -42,34 +43,10 @@ export function collectHomepages(contentBase: string, ctx: object): {
     addressFindings: object[];
 };
 /**
- * Writes each homepage as the package root's `_index.md`.
+ * Each homepage's frontmatter as its page publishes it, and its body.
  *
- * Its own writer, deliberately small. A homepage is authored markdown published
- * verbatim — no table expansion and no link resolution — so routing it through
- * {@link renderPages} would give it a pipeline it does not use.
- *
- * **Verbatim is the answer, not a gap.** A homepage's links could not be
- * *resolved* here, so they are **checked** instead:
- * {@link auditHomepageLinks} reads the body's markdown links, and reports a
- * wikilink on the page rather than resolving one.
- *
- * **Its destination is fixed**: {@link HOMEPAGE_DESTINATION}, at the package's
- * site root, which Hugo renders as the `home` kind at `/<package>/`. The page
- * states no `url` — the home kind has none to state — and the mount below it
- * holds pages and nothing else, so this is the only `_index.md` in the tree.
- *
- * **Verbatim, but not unconnected.** The homepage is a page like any other on
- * both sides of the link graph: a content page reaches it through
- * `[[homepage-root|Text]]`, and its own markdown links name content pages. So
- * it carries the same `related` block every content page does — handed in by
- * the caller, since the graph is read off the content render and a tree with
- * only a homepage has no such graph.
- *
- * @param {string} outRoot - The package's site root — the content mount's
- *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
- * @param {object} config - The resolved configuration, for the package name and
- *   the default title.
+ * @param {object} config - The resolved configuration.
  * @param {object} [options] - Options.
  * @param {import("./related-pages.mjs").Related} [options.related] - The
  *   homepage's backlinks and mentions. Absent where nothing connects to it,
@@ -78,13 +55,18 @@ export function collectHomepages(contentBase: string, ctx: object): {
  *   address resolves against the images this package ships.
  * @param {object} [options.foreign] - The dependencies' vendored indexes, so a
  *   `data.banner` may name an image a dependency ships.
- * @returns {number} How many pages were written.
+ * @returns {Array<{file: string, body: string, data: object}>} One entry per
+ *   homepage, in walk order.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { related, records, foreign }?: {
+export function homepageData(pages: readonly object[], config: object, { related, records, foreign }?: {
     related?: import("./related-pages.mjs").Related | undefined;
     records?: readonly object[] | undefined;
     foreign?: object | undefined;
-}): number;
+}): Array<{
+    file: string;
+    body: string;
+    data: object;
+}>;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -132,7 +114,7 @@ export function emptyGates(): object;
 /**
  * Whether any gate produced a finding.
  * @param {{homepages: unknown[], frontmatterLinks: unknown[],
- *   addressErrors: unknown[], staleManifests: unknown[],
+ *   addressErrors: unknown[], sections?: unknown[], staleManifests: unknown[],
  *   unaddressable: unknown[]}} gates - Results of the site checks.
  * @returns {boolean} Whether at least one check found an error.
  */
@@ -140,9 +122,20 @@ export function gatesFailed(gates: {
     homepages: unknown[];
     frontmatterLinks: unknown[];
     addressErrors: unknown[];
+    sections?: unknown[];
     staleManifests: unknown[];
     unaddressable: unknown[];
 }): boolean;
+/**
+ * Whether a site build found anything that stops its pages being written: a
+ * gate that fired, or a note whose table, expression, block, caption, heading,
+ * footnote, link, image or embed is in error. What drawing the maps found does
+ * not stop it.
+ *
+ * @param {object} result - From {@link buildSite}.
+ * @returns {boolean} Whether the build failed.
+ */
+export function siteBuildFailed(result: object): boolean;
 /**
  * The universe a generated table searches, grouped by package.
  *
@@ -156,39 +149,19 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
 /**
  * The frontmatter a page publishes with.
  *
- * An authored `aliases` is a list of names a reader might call the note. Hugo reads
- * `aliases` as **URL redirects**, so passing them through would publish a
- * redirect stub at each name. They are dropped, and this build emits no
- * redirects of its own.
- *
- * A content page states its own **`url`**, which is its address rather than its
- * path. It is written flat under the content mount, so Hugo would
- * otherwise publish it at `<mount><type>-<shortcode>/` rather than at the
- * package-wide address the link manifest records — the same address, one
- * segment too deep. So the address is stated and the mount does not reach it.
- *
- * **It is stated relative to the site root, and so carries no package base**.
- * Hugo resolves a `url` against `baseURL`, whose path is already where
- * the package is served — a consumer's Hugo site *is* its package — so writing
- * `page.url`, which carries the base for every href this build renders, wrote
- * that base a second time and published every content page a segment too deep
- * (`/sohl/sohl/doc-rulesintro/`). The two are separate quantities: the page
- * states `/<slug>/`, and everything that points *at* the page — the address
- * index a wikilink resolves through, and the link manifest — composes
- * `<base><slug>/`.
+ * An authored `aliases` is a list of names a reader might call the note. It is
+ * dropped: this build emits no redirects.
  *
  * A content page carries the package the build **derived**. No note
- * declares one, so the note's frontmatter alone
- * would publish a page that does not say which package it belongs to. The
- * emitted page is what a theme reads: `breadcrumbs.html` reads
- * `.Params.package`. Writing the derived value keeps a page
+ * declares one, so the note's frontmatter alone would publish a page that does
+ * not say which package it belongs to. Writing the derived value keeps a page
  * self-describing and makes sweeping the field out of a content tree
  * output-preserving for a site as it already is for the packs.
  *
  * **`related` is derived, never authored.** What links to a page is a fact
  * about every other page, known only once the whole tree has resolved — see
  * {@link module:engine/related-pages} — so an authored value is dropped the
- * way `aliases` is, and {@link renderPages} writes the derived block once it
+ * way `aliases` is, and {@link renderPages} sets the derived block once it
  * holds the graph.
  *
  * @param {object} page - The page.
@@ -202,41 +175,19 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  *   pathname into the address the website serves. Every artwork field goes
  *   through it, so a page's `img:` and its body images name the same file the
  *   same way.
- * @returns {object} The frontmatter to write.
+ * @returns {object} The frontmatter.
  */
 export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
     decorate?: ((data: object, page: object) => void) | undefined;
     artSrc?: ((value: unknown, type: string, accepts?: Iterable<string>) => string | null) | undefined;
     webSrc?: ((src: string) => string) | undefined;
 }): object;
-/**
- * Where a page is written, relative to the output root.
- *
- * **Flat, under the mount, named by its address**. A content page's URL
- * is its address — `/<package>/<type>-<shortcode>/` — and the file is named
- * the same way, so the two agree. No page creates a directory: a section is
- * a Hugo listing over a content directory, the `section` kind is disabled on
- * every site, and a directory chosen only to satisfy a rendering engine's idea
- * of what a section is has no business in the note format.
- *
- * The name is the *whole* address, so two types cannot fight over one file: a
- * `doc` note's `subType` may be spelled the same as another note's `type`, and
- * `doc-gear.md` and `weapongear-gear.md` are distinct.
- *
- * @param {{slug: string}} page - The page.
- * @returns {string} The file, relative to the mount.
- */
-export function pageDestination(page: {
-    slug: string;
-}): string;
-/** Transform one content page without writing the site mount. */
-export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, events, drawings, runs, }: {
+/** Transform one content page. */
+export function renderSitePage(page: any, { index, foreign, pass, decorate, sqlTables, config, artIndex, figuresByAddress, events, drawings, runs, }: {
     index: any;
     foreign: any;
-    universe: any;
     pass?: {} | undefined;
     decorate: any;
-    linkable?: ((d: any) => boolean) | undefined;
     sqlTables: any;
     config: any;
     artIndex: any;
@@ -246,11 +197,12 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     runs?: import("./content-scripts.mjs").RunContext | undefined;
 }): {
     page: any;
-    body: string;
+    markdown: string;
+    figures: object[];
     data: object;
-    resolved: any[];
+    resolved: object[];
     tableErrors: object[];
-    expressionErrors: any[];
+    expressionErrors: object[];
     secretErrors: {
         file: any;
         line: number;
@@ -260,8 +212,8 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     captionErrors: {
         file: any;
         line: any;
-        column: number;
-        message: string;
+        column: any;
+        message: any;
     }[];
     headingErrors: {
         line: number;
@@ -275,7 +227,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
         column: number;
         message: string;
     }[];
-    wikiErrors: any[];
+    wikiErrors: object[];
     imageErrors: any[];
     embedErrors: {
         file: string;
@@ -286,24 +238,20 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     }[];
 };
 /**
- * Renders and writes every page.
- *
- * The order inside a page is load-bearing and is the same order the pack
- * compilers use:
- *
- * 1. **Tables expand first**, and outside code-fence protection. A table is
- *    authored as a fenced `sql` block, which `protectCode` would otherwise
- *    stash away before the expander saw it. Expanding first leaves an ordinary
- *    markdown table to walk, with every other fence still protected.
- * 2. **Then, inside protection**: the consumer's `beforeLinks` pass, then
- *    wikilink resolution. A `{@link}` tag may sit in prose a wikilink also
- *    touches, so the repository's own rewrite runs before the shared one
- *    rather than replacing it.
- *
- * **Every page is rendered before any is written.** What links *to* a page is
- * known only once every other page has resolved, and it is written into the
- * page's own front matter, so the render is one pass over the tree and the
- * write is a second — with the link graph read off the first, at the one
+ * Renders every page.
+ *
+ * Each page's body is expanded by
+ * {@link module:engine/content-expand.expandContent}, the step the pack
+ * compilers take too: tables first and outside code-fence protection, then
+ * figure numbers and expressions, then, inside protection, the consumer's
+ * `beforeLinks` pass and wikilink resolution. A `{@link}` tag may sit in prose
+ * a wikilink also touches, so the repository's own rewrite runs before the
+ * shared one rather than replacing it.
+ *
+ * **Every page is rendered before any is finished.** What links *to* a page is
+ * known only once every other page has resolved, and it is set in the page's
+ * own front matter, so the render is one pass over the tree and the
+ * finishing is a second — with the link graph read off the first, at the one
  * point the resolver answers, and inverted once between them. Nothing is
  * resolved twice.
  *
@@ -320,10 +268,12 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
  *   related: Map<string, import("./related-pages.mjs").Related>,
- *   maps: number}} `related`
+ *   maps: number, pages: object[], runs: object}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
- *   page's, so the caller can write it on the page this render does not.
- *   `maps` counts the pages carrying a map.
+ *   page's, so the caller can set it on the page this render does not.
+ *   `maps` counts the pages carrying a map. `pages` holds
+ *   `{page, markdown, figures, data}` for each page and `runs` the package's
+ *   marked-text context.
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
@@ -334,6 +284,8 @@ export function renderPages(pages: object[], options: object): {
     embedErrors: object[];
     related: Map<string, import("./related-pages.mjs").Related>;
     maps: number;
+    pages: object[];
+    runs: object;
 };
 /**
  * Resolves `site.pass` to its bundle.
@@ -348,7 +300,7 @@ export function resolveSitePass(name: string | undefined, options: object): {
 /** The site frontmatter decoration shared by the site writer and page preview. */
 export function sitePageDecorator(config: any, index: any): (data: any, page: any) => void;
 /**
- * Builds a Hugo content tree from a content tree, and reports what it found.
+ * Collects, checks and renders a content tree's pages, and reports what it found.
  *
  * Returns rather than exits, in every case. A caller — the command, or a test —
  * decides what a finding means; the gates below are grouped so it can report
@@ -366,8 +318,13 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
  *   mapFindings: object[],
- *   manifests: object|null}} `mapFindings` is what drawing the maps found —
- *   warnings, never a reason to fail the build.
+ *   manifests: object|null, site?: object}} `mapFindings` is what drawing the
+ *   maps found — warnings, never a reason to fail the build. `site` holds what a page renderer needs: `base`, `pages` (each content
+ *   page's `{page, markdown, figures, data}`), `homepages` (each
+ *   `{file, body, data}`), `runs`, `index`, `foreign` and `records`; and
+ *   `renderNote(file)`, which reads one content note again and renders it
+ *   against the rest of the build, or returns `null` when its address, name
+ *   or type changed and the whole site must be built again.
  */
 export function buildSite({ config, sqlTables }?: {
     config?: object | undefined;
@@ -381,6 +338,7 @@ export function buildSite({ config, sqlTables }?: {
     embedErrors: object[];
     mapFindings: object[];
     manifests: object | null;
+    site?: object;
 };
 export { formatUnaddressableFinding };
 import { formatUnaddressableFinding } from "./metadata-index.mjs";

package/types/engine/site-config.d.mts

@@ -3,7 +3,7 @@
  *
  * `[{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.
@@ -11,18 +11,6 @@
  * @throws {TypeError} When the shape is not a navigation.
  */
 export function checkNavigation(value: unknown, where?: string): NavigationEntry[];
-/**
- * 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: readonly NavigationEntry[]): MenuEntry[];
 /**
  * Where the fetched navigation sits.
  *
@@ -64,137 +52,45 @@ export function fetchNavigation(config: object, { url, fetch }?: {
     fetch?: typeof globalThis.fetch | undefined;
 }): Promise<string>;
 /**
- * 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: string): string;
-/**
- * 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 }: {
+export function siteSettings({ config }: {
     config: object;
-    navigation: readonly NavigationEntry[];
-    themesDir: string;
-}): Record<string, any>;
-/**
- * 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: Record<string, unknown>): string;
-/**
- * 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: object): Record<string, any>;
-/**
- * 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: object, generated?: Record<string, unknown>): {
-    file: string;
+}): {
+    baseURL: string;
+    title: string;
+    params: Record<string, unknown>;
 };
-/** 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: "build/hugo/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";
-/** 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: Readonly<{
     logo: "images/brand/sohl-icon-white.webp";
     licenseURL: "https://www.heroiclands.org/license/";
     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: readonly string[];
-/**
- * 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: Readonly<{
-    goldmark: Readonly<{
-        renderer: Readonly<{
-            unsafe: true;
-        }>;
-        extensions: Readonly<{
-            taskList: false;
-        }>;
-    }>;
-}>;
 /** Where the navigation is published. */
 export const NAVIGATION_URL: "https://www.heroiclands.org/nav.json";
 /** The cached navigation's file name. */
@@ -216,19 +112,3 @@ export type NavigationEntry = {
      */
     children?: NavigationEntry[] | undefined;
 };
-/**
- * A Hugo menu entry, as `[[menu.main]]` states one.
- */
-export type MenuEntry = {
-    name: string;
-    url: string;
-    weight: number;
-    /**
-     * - Set on an entry that has children.
-     */
-    identifier?: string | undefined;
-    /**
-     * - Set on a child, naming its parent's identifier.
-     */
-    parent?: string | undefined;
-};

package/types/engine/site-files.d.mts

@@ -0,0 +1,73 @@
+/**
+ * Text escaped for XML content and attribute values.
+ *
+ * @param {unknown} value - The text.
+ * @returns {string} The escaped text.
+ */
+export function escapeXml(value: unknown): string;
+/**
+ * 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: unknown): string;
+/**
+ * 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: Array<{
+    loc: string;
+    lastmod?: unknown;
+}>): string;
+/**
+ * A sitemap index naming other sitemaps.
+ *
+ * @param {readonly string[]} sitemaps - Each sitemap's full address.
+ * @returns {string} The document.
+ */
+export function sitemapIndexXml(sitemaps: readonly string[]): string;
+/**
+ * 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: readonly string[]): string;
+/**
+ * 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 }: {
+    title: string;
+    id: string;
+    self: string;
+    author?: string | undefined;
+    entries: Array<{
+        title: string;
+        url: string;
+        date: unknown;
+        author?: string;
+        summary?: string;
+        content?: string;
+    }>;
+}): string;

package/types/engine/site-index.d.mts

@@ -2,7 +2,9 @@
  * 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.
@@ -156,11 +158,11 @@ export type SiteEntry = {
     /**
      * URL segment.
      */
-    slug: string;
+    slug?: string | undefined;
     /**
      * Source file's basename, e.g. `Climbing.md`.
      */
-    base: string;
+    base?: string | undefined;
     /**
      * The page's published address.
      */
@@ -171,6 +173,12 @@ export type SiteEntry = {
      *  page is indexed as declaring none.
      */
     body?: string | undefined;
+    /**
+     * The anchors the body declares, when the
+     * caller holds them already — a content-index
+     * record's — in place of reading `body`.
+     */
+    anchors?: object[] | undefined;
 };
 /**
  * The resolved index and everything a wikilink resolver reads beside it.