@heroiclands/package-build 22.3.1 → 22.4.0

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

@@ -46,25 +46,24 @@ export function collectHomepages(contentBase: string, ctx: object): {
     addressFindings: object[];
 };
 /**
- * Writes each homepage at its address, below the package's own root.
+ * Writes each homepage as the package root's `_index.md`.
  *
  * Its own writer, deliberately small. A homepage is authored markdown published
- * verbatim — no table expansion, no section landing and no link resolution — so
- * routing it through {@link renderPages} would buy it a pipeline it has no input
- * for, and would make homepage-only mode depend on the index, the foreign
- * manifests and the table universe that mode exists to not build.
- *
- * **Verbatim is the answer, not a gap.** A landing's links
- * could not be *resolved* here without giving `homepage` mode the index its
- * licensing fence exists to not build, so they are **checked** instead:
- * {@link auditHomepageLinks} reads the `landing:` addresses and the body's
- * markdown links, and reports a wikilink on the page rather than resolving one.
- *
- * **Its destination is no longer fixed**. The file is written at the
- * note's address, flat at the package's site root, and the page states that
- * address as its `url` — the same separation of file from URL every other page
- * has. Nothing is written at `/<package>/` itself: that becomes a redirect the
- * package's own repository authors, which is a routing fact rather than a page.
+ * verbatim — no table expansion and no link resolution — so routing it through
+ * {@link renderPages} would buy it a pipeline it has no input for, and would
+ * make homepage-only mode depend on the index, the foreign manifests and the
+ * table universe that mode exists to not build.
+ *
+ * **Verbatim is the answer, not a gap.** A homepage's links could not be
+ * *resolved* here without giving `homepage` mode the index its licensing fence
+ * exists to not build, 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.
  *
  * @param {string} outRoot - The package's site root — the content mount's
  *   root, `build/hugo/content`, one level above the mount itself.
@@ -84,7 +83,7 @@ export function writeHomepages(outRoot: string, pages: readonly object[], config
  * - **Frontmatter wikilinks** first, because frontmatter is copied to the page
  *   verbatim and a link written in one reaches the reader as literal `[[…]]`.
  * - **Addresses** next: a note that has no address — no shortcode to be
- *   addressed by, or no section to be filed under — would silently drop a page.
+ *   addressed by — would silently drop a page.
  *   There is no collision gate beside it: an address is `(type, shortcode)`,
  *   which is unique within a package by rule, so two pages cannot claim one URL.
  * - **Foreign manifests** last, in two steps. *Unusable* is a file this build
@@ -125,31 +124,6 @@ export function gatesFailed(gates: any): boolean;
  * @returns {Map<string, object[]>} Package → the notes it may tabulate.
  */
 export function tableUniverse(pages: object[]): Map<string, object[]>;
-/**
- * The front matter a section's landing states about itself.
- *
- * The section metadata a configuration resolved, ready to be written or merged
- * onto a page. Two things happen here and nothing else does:
- *
- * - **`title` leads.** It is the one key every landing has carried since the
- *   first one, and a landing whose block opened with `banner:` would be a
- *   gratuitous diff on every consumer's tree.
- * - **An absent value is left off**, not written as `undefined` — which is not
- *   a value YAML can carry, and would abort the serializer.
- *
- * Everything else the section declared is passed through. That is the point of
- * the function: two writers transcribing `title` and `banner` by
- * name, so the vocabulary lived in three places — the schema that admits a key
- * and the two writers that copy it — and a key added to the schema alone
- * validated cleanly and then reached no page. The *schema* is the bound worth
- * keeping (see `normalizeSectionMeta`, which refuses a key it does not know and
- * names it); a second, silent bound in the writers is not.
- *
- * @param {object} meta - A resolved `site.sections` / `site.readmeSections`
- *   entry.
- * @returns {object} Its front matter, `title` first.
- */
-export function sectionFrontmatter(meta: object): object;
 /**
  * The frontmatter a page publishes with.
  *
@@ -180,10 +154,8 @@ export function sectionFrontmatter(meta: object): object;
  * A content page carries the package the build **derived**. No note
  * declares one — `package:` is retired — 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` builds its middle crumb from
- * `.Params.package`, so without it that crumb degrades from a linked, labelled
- * section to a bare type slug. Writing the derived value keeps a page
+ * emitted page is what a theme reads: `breadcrumbs.html` reads
+ * `.Params.package`. 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.
  *
@@ -209,16 +181,15 @@ export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
  * 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 now named
- * the same way, so the two agree. Filing it into `<section>/` so that
- * Hugo would read a section off its path; a section appears in no address, and
- * a directory chosen only to satisfy a rendering engine's idea of what a
- * section is has no business in the note format.
+ * 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 rather than a section-relative half of it, 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 whatever the sections.
+ * 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 {object} page - The page.
  * @returns {string} The file, relative to the mount.
@@ -251,74 +222,6 @@ export function renderPages(pages: object[], options: object): {
     wikiErrors: object[];
     imageErrors: object[];
 };
-/**
- * Writes the Hugo sections a published tree declares.
- *
- * **This is where a section lives now, and the only place**. A content
- * note carries none: it is addressed by `(type, shortcode)` and emitted flat
- * under the mount, so nothing a page does creates a directory. A site that wants
- * `/<package>/<prefix><section>/` to answer — with a title, a hero, and whatever
- * listing its layout builds — says so here, in configuration, and this writes
- * the `_index.md` that makes Hugo agree it is a section.
- *
- * Three jobs, all of them Hugo's directory semantics rather than the note
- * format's:
- *
- * - **The mount's own landing**, so `/<package>/<prefix>` is a page rather than
- *   a directory listing. It carries a `type` of its own: Hugo's template lookup
- *   walks up a page's path, so an untyped landing template at the mount would
- *   also serve every section below it that has none.
- * - **Declared sections** get a titled `_index.md` with their hero, so a landing
- *   matches the card that links to it instead of showing Hugo's auto-humanised
- *   directory name. The body is empty, which lets the theme decide what to list.
- * - **Every other directory directly under the mount** gets a bare `_index.md`,
- *   or its own address publishes nothing. Hugo generates a section page
- *   automatically only for a *top-level* content directory; below that, a
- *   directory without an `_index.md` is not a section, so its URL 404s while its
- *   children publish normally. With content pages flat, no note creates a
- *   directory below the mount, so this reaches only what something else
- *   placed there.
- *
- * **A section listing is not a page listing any more.** A layout that reads
- * `.Pages` off a section it declares here will find nothing, because no file is
- * filed into it; one that queries `site.RegularPages` by `Params.type` — which
- * is how `sohl`'s eleven catalog layouts already work — is unaffected. That is a
- * consumer's layout to choose, and it is stated here because the choice is no
- * longer free.
- *
- * Scoped to one level on purpose. A directory further down was not a section
- * before either, and giving it one here would silently re-scope the prev/next
- * navigation of every page inside it.
- *
- * @param {string} outRoot - The mount directory.
- * @param {object} options
- * @param {Record<string, object>} [options.sections] - The declared sections,
- *   each written as a titled `_index.md` carrying its own frontmatter.
- * @param {object} [options.landing] - The mount's own landing frontmatter.
- *   Omitted, the mount gets no `_index.md` of its own.
- * @param {((name: string) => string)|null} [options.sectionTitle] - Titles a
- *   directory below the mount that declared no section. `null` leaves such a
- *   directory without an `_index.md`.
- * @returns {number} How many landings were written.
- */
-export function writeSectionLandings(outRoot: string, { sections, landing, sectionTitle }: {
-    sections?: Record<string, object> | undefined;
-    landing?: object | undefined;
-    sectionTitle?: ((name: string) => string) | null | undefined;
-}): number;
-/**
- * A section landing's title, from its directory name — `macro` → `Macros`.
- *
- * Hugo derives exactly this for a section page it generates itself, but not for
- * one backed by an `_index.md`: an explicit file with no `title` renders a blank
- * heading. So a backfilled landing states its own, in plain English
- * pluralisation rather than Hugo's inflector, which spells that section
- * "Macroes".
- *
- * @param {string} name - The directory name.
- * @returns {string} The display title.
- */
-export function pluralTitle(name: string): string;
 /**
  * Resolves `site.pass` to its bundle.
  *
@@ -346,10 +249,7 @@ export function resolveSitePass(name: string | undefined, options: object): {
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], manifests: object|null,
- *   hasTags: boolean}} `hasTags` is whether any note the walk read carries
- *   `tags:` — what {@link module:engine/site-config.hugoConfig} reads to
- *   decide whether the site emits taxonomy pages.
+ *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
  */
 export function buildSite({ config, sqlTables }?: {
     config?: object | undefined;
@@ -361,7 +261,6 @@ export function buildSite({ config, sqlTables }?: {
     wikiErrors: object[];
     imageErrors: object[];
     manifests: object | null;
-    hasTags: boolean;
 };
 export { formatUnaddressableFinding };
 import { formatUnaddressableFinding } from "./metadata-index.mjs";

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

@@ -91,19 +91,15 @@ export function resolveThemesDir(rootDir: string): string;
  * @param {object} options.config - The resolved build configuration.
  * @param {readonly NavigationEntry[]} options.navigation - The navigation.
  * @param {string} options.themesDir - From {@link resolveThemesDir}.
- * @param {boolean} [options.hasTags] - Whether any note the site build walked
- *   carries `tags:`, from {@link module:engine/site-build.buildSite}'s
- *   `hasTags`. Defaults to `false` — no tagged note, no taxonomy pages.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
  *   configuration declares no `packageBuild.manifest.title`, no
  *   `site.description`, or no `site.assets`.
  */
-export function hugoConfig({ config, navigation, themesDir, hasTags }: {
+export function hugoConfig({ config, navigation, themesDir }: {
     config: object;
     navigation: readonly NavigationEntry[];
     themesDir: string;
-    hasTags?: boolean | undefined;
 }): Record<string, any>;
 /**
  * The configuration as the TOML Hugo reads.
@@ -120,17 +116,10 @@ export function hugoToml(generated: Record<string, unknown>): string;
  * run this before touching the output tree and fail with it intact.
  *
  * @param {object} config - The resolved build configuration.
- * @param {object} [options] - Options.
- * @param {boolean} [options.hasTags] - Whether any note the site build walked
- *   carries `tags:`. Defaults to `false`, so a caller generating the
- *   configuration before the walk (to fail fast on a missing source) gets the
- *   untagged shape; pass the site build's own `hasTags` once it is known.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {Error} When any source is missing or wrong.
  */
-export function generateHugoConfig(config: object, { hasTags }?: {
-    hasTags?: boolean | undefined;
-}): Record<string, any>;
+export function generateHugoConfig(config: object): Record<string, any>;
 /**
  * Write `build/hugo/hugo.toml`.
  *
@@ -171,13 +160,15 @@ export const BRAND: Readonly<{
     discordURL: "https://discord.gg/EwMfkNd3az";
 }>;
 /**
- * The kinds a site with no tagged notes renders.
+ * The kinds no site renders.
  *
- * A section exists only where `site.sections` declares one, so a tree holding
- * only the homepage emits nothing beyond it; a taxonomy nobody's notes fill
- * and a feed would be empty shells. A site whose notes carry `tags:` emits
- * `taxonomy` and `term` after all — see {@link hugoConfig} — but `RSS` is
- * disabled either way: nothing here publishes a feed.
+ * 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[];
 /**

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

@@ -1,13 +1,3 @@
-/**
- * Where a package's landing is served, now that it is an addressed page.
- *
- * The site build emits the homepage at its own address rather than as the
- * site root's `_index.md`, so the prefix root is a redirect to it.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The landing's path.
- */
-export function landingPath(pkg: string): string;
 /**
  * Suppress indexing of every address a deployment answers on but nobody
  * advertises.
@@ -28,37 +18,22 @@ export function landingPath(pkg: string): string;
  */
 export function noindexHeaders(): string[];
 /**
- * The lifetime pinned on the prefix-root redirect, and why it is pinned.
+ * The `_headers` file's contents: the `noindex` rules, and nothing else.
  *
- * Cloudflare Pages sets no `Cache-Control` on a redirect it generates — those
- * responses carry `location` and nothing else — and a 301 with no lifetime is
- * cached by a browser indefinitely, on the most-linked URL there is. An hour
- * keeps the 301's canonical signal without the permanence.
+ * No `Cache-Control` is pinned on the prefix root. It is the homepage, and a
+ * lifetime on it would hold a stale copy at the most-linked address after a
+ * deploy; Pages' own defaults for a page apply.
  *
- * @param {string} pkg - The content package name.
- * @returns {string[]} The header block's lines.
- */
-export function cacheHeaders(pkg: string): string[];
-/**
- * Both forms of the prefix root, because Pages matches the raw path.
- *
- * Redirect matching runs before any trailing-slash or `index.html` handling, so
- * `/<pkg>` and `/<pkg>/` are distinct keys and a rule on one does not catch the
- * other.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The `_redirects` file's contents.
- */
-export function redirects(pkg: string): string;
-/**
- * The `_headers` file's contents.
- *
- * @param {string} pkg - The content package name.
  * @returns {string} The file's contents.
  */
-export function headers(pkg: string): string;
+export function headers(): string;
 /**
- * Write `_headers` and `_redirects` beside the rendered site.
+ * Write `_headers` beside the rendered site, and remove any `_redirects`.
+ *
+ * The removal is part of owning the root: a `_redirects` this build did not
+ * write is one an earlier build left, and Cloudflare Pages applies whatever
+ * sits there. Left in place it would redirect the prefix root — the homepage —
+ * to an address nothing publishes.
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the