@heroiclands/package-build 22.4.2 → 22.4.4

package/types/engine/homepage.d.mts

@@ -148,15 +148,22 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * redirect stub at each one. The field is retired and refused before a
  * build reaches here, which makes this a guard rather than a working path.
  *
+ * `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.
+ *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @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.
  */
-export function homepageFrontmatter(fm: object, { contentPackage, title }: {
+export function homepageFrontmatter(fm: object, { contentPackage, title, related }: {
     contentPackage: string;
     title: string;
+    related?: object | undefined;
 }): object;
 /**
  * Every address a homepage carries: the markdown links in its body.

package/types/engine/related-pages.d.mts

@@ -0,0 +1,70 @@
+/**
+ * Inverts a link graph into each page's backlinks and mentions.
+ *
+ * An edge is `(source URL, target URL)`, and a URL that is not in `entries` is
+ * not a page of this site, so an edge touching one is dropped. A self-link says
+ * nothing a reader is not already looking at, and a page that links another
+ * three times is connected to it once, so both collapse.
+ *
+ * The result holds only pages with at least one connection, so the caller can
+ * write nothing on a page with none — the theme's silent-disappear convention,
+ * kept at the source rather than papered over with an empty block.
+ *
+ * @param {Iterable<readonly [string, string]>} edges - Every resolved link, as
+ *   the source page's URL and the target page's.
+ * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
+ *   site, keyed by URL.
+ * @returns {Map<string, Related>} URL → the page's `related` block, both lists
+ *   sorted, for every page with at least one entry in either.
+ */
+export function relatedPages(edges: Iterable<readonly [string, string]>, entries: ReadonlyMap<string, RelatedEntry>): Map<string, Related>;
+/**
+ * The pages a homepage's body links to, as URLs.
+ *
+ * A homepage is published verbatim — no wikilink on it resolves, and its links
+ * are ordinary markdown the browser resolves against the page's own address,
+ * which is the package root. So its edges are read the same way: each target
+ * resolved against `base`, the way a browser would. A package-relative
+ * `being-x/`, a root-relative `/pkg/being-x/` and a `./being-x/#anchor` all
+ * name the same page; a bare `#anchor` names the homepage itself.
+ *
+ * A link that names a host or a scheme leaves the site, whatever path it
+ * carries, and yields nothing: the site's own pages are addressed without one.
+ *
+ * @param {string} body - The homepage's markdown body.
+ * @param {string} base - Where the package is served — the homepage's own URL.
+ * @returns {string[]} The targets' URLs, in body order, repeats included.
+ */
+export function homepageLinkTargets(body: string, base: string): string[];
+/**
+ * One entry in a `related` list — the page a reader is pointed at.
+ */
+export type RelatedEntry = {
+    /**
+     * The page's published title.
+     */
+    title: string;
+    /**
+     * `<base><slug>/` — the page's address as every href
+     * this build renders composes it, never the
+     * site-root-relative form the page states for itself.
+     */
+    url: string;
+    /**
+     * The note's `type`, which the theme groups by.
+     */
+    type: string;
+};
+/**
+ * The `related` block one page publishes.
+ */
+export type Related = {
+    /**
+     * Pages that link to this one.
+     */
+    backlinks: RelatedEntry[];
+    /**
+     * Pages this one links to.
+     */
+    mentions: RelatedEntry[];
+};

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

@@ -65,14 +65,27 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * 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 homepage-only
+ * mode has none.
+ *
  * @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} [options] - Options.
+ * @param {import("./related-pages.mjs").Related} [options.related] - The
+ *   homepage's backlinks and mentions. Absent where nothing connects to it,
+ *   and in homepage-only mode, where no link resolves.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { related }?: {
+    related?: import("./related-pages.mjs").Related | undefined;
+}): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -159,6 +172,12 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * 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
+ * holds the graph.
+ *
  * @param {object} page - The page.
  * @param {object} options
  * @param {(data: object, page: object) => void} [options.decorate] - Called
@@ -210,10 +229,23 @@ export function pageDestination(page: object): string;
  *    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
+ * point the resolver answers, and inverted once between them. Nothing is
+ * resolved twice.
+ *
  * @param {object[]} pages - Every page.
- * @param {object} options - Everything the render needs.
+ * @param {object} options - Everything the render needs. `homepages` is the
+ *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
+ *   no part in the render and every part in the graph: a content page links
+ *   it by wikilink, and its own markdown links name content pages.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[]}}
+ *   wikiErrors: object[], imageErrors: object[],
+ *   related: Map<string, import("./related-pages.mjs").Related>}} `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.
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
@@ -221,6 +253,7 @@ export function renderPages(pages: object[], options: object): {
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    related: Map<string, import("./related-pages.mjs").Related>;
 };
 /**
  * Resolves `site.pass` to its bundle.

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

@@ -41,6 +41,9 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
  *   resolvers that distinguish a foreign hit from a local one.
  * @param {object} [options.assets] - The address space an `![[…]]` embed
  *   resolves against, shaped as every asset resolver reads one.
+ * @param {object[]} [options.resolved] - Collector the resolver appends every
+ *   resolved target's index entry to — the page's outbound edges, read off
+ *   the one pass that resolves them.
  * @returns {object} The resolver context.
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
@@ -49,13 +52,14 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
  * checker never had it and one authored link must not get two verdicts. A
  * caller still passing it is ignored rather than obeyed.
  */
-export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets }: {
+export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets, resolved }: {
     src: string;
     type?: string | null | undefined;
     errors: object[];
     file?: string | undefined;
     foreignIndex?: Map<string, object> | undefined;
     assets?: object | undefined;
+    resolved?: object[] | undefined;
 }): object;
 /**
  * Resolve one infobox reference against a site index.

package/types/engine/web-wikilinks.d.mts

@@ -76,9 +76,17 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  * {@link module:engine/content-images.renderImageFigures} turns into a figure
  * for the website, and what the book reads its staging list out of.
  *
+ * ## Every hit is recorded, so the page's edges come out of one pass
+ *
+ * A caller that hands in `ctx.resolved` is given every index entry a link on
+ * the page resolved to, in body order, repeats included. That is the link
+ * graph, read at the one point where it exists: the build never has to walk a
+ * page a second time to learn what it links to. Nothing is recorded for a
+ * same-page anchor or for a target that resolved nowhere.
+ *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, assets, collide, contentTypes,
- *   packages, noIndexPackages, foreign, type, errors, src, file }`.
+ *   packages, noIndexPackages, foreign, type, errors, src, file, resolved }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;
  *   `noIndexPackages` is every package declared `contentIndex: false`, so a
@@ -87,7 +95,8 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *   is the cross-package manifest index; `assets` is the address space an embed
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
- *   stands in.
+ *   stands in. `resolved`, when supplied, is the array every resolved
+ *   target's index entry is appended to.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body: string, ctx: object): string;