@heroiclands/package-build 11.1.0 → 14.0.0

package/CONTENT.md

@@ -138,7 +138,6 @@ publish:
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/
-    landing: readme
 
 # How this repository frames the website `content-build site` publishes.
 # Framing only: addresses come from `publish.address` above.
@@ -796,6 +795,26 @@ values. A `weapon` declares none — SoHL distinguishes a weapon's uses by strik
 mode rather than by kind — so `subType` on one is a finding; a `skill` declares
 ten, so `subType: crafte` is a finding naming `craft`.
 
+**A `type` and a `subType` are both held to `^[A-Za-z0-9]+$`** (#206) — the same
+constant a `shortcode` is held to, read rather than restated. A type is the
+first segment of every address, so a hyphen in one is read back as a segment
+boundary nobody wrote. A `subType` reaches no address since #204 retired
+sections, and keeps the rule anyway: it is a vocabulary term the toolchain keys
+on, and one charset that holds for every term is a rule an author can state. The
+rule is checked ahead of the closed-set check, which is what makes it reach a
+type whose values are declared but not yet enumerated:
+
+```text
+assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not a well-formed subType — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. …
+```
+
+One declared value broke that rule: a `doc`'s `user-guide`, now **`userguide`**.
+The old spelling was accepted for one transitional release, as a warning naming
+the replacement, because an error would have redded every tree that took the
+release before it had a chance to sweep. Every tree has swept, so the acceptance
+is gone (#210): `user-guide` is refused by the charset check like any other
+hyphenated value, and nothing retirement-specific was left to remove.
+
 The vocabulary lives in `engine/note-vocabulary.mjs`, one entry per note type,
 taken from the content-format specification. It is note-format knowledge rather
 than any system's: `data:` holds what is true of the thing, and what a system
@@ -1206,21 +1225,29 @@ package's fixed mounts (`/<package>/` for the landing page, `/<package>/api/` fo
 generated API docs), neither of which contains a hyphen or names a type. So the
 namespace is provably disjoint rather than conventionally so.
 
-**Sections stay, as directories.** Hugo derives a page's section from where the
-file is written, not from its URL, and that section is what gives a landing page,
-`.CurrentSection` and the per-section layout lookup. So a page is still written
-into `<section>/`, and carries a front-matter `url:` publishing it at its
-address. The two are free to differ, and do.
-
-**A landing page is the one exception**, because it is not addressed by
-`(type, shortcode)` at all: it _is_ its section, so it addresses the section —
-under the content mount, where the section directories live (`kb/rules/`).
+**A page is written flat, named by its address** (#204). It used to be filed
+into `<section>/`, because Hugo derives a page's section from where the file is
+written and a section gave it a landing page, `.CurrentSection` and a per-section
+layout lookup. But a section appears in no address, so the note format was
+carrying a key, a filename convention, a landing rule and a synthesis pass in
+order to satisfy a rendering engine's directory semantics. The file is now
+`<mount>/<type>-<shortcode>.md` and the front-matter `url:` still publishes it at
+the package root, one level above.
+
+**There is no landing page.** A `README.md` was its section's landing and
+addressed the section itself; that is retired with the section. A page that
+introduces the notes of a type is an ordinary note addressed `doc-<type>`, with
+no build path of its own — exactly as the package's own front page is
+`homepage-root` (#182).
+
+**Sections stay, as configuration.** `site.sections` still writes an `_index.md`
+per section, and that is now the _only_ thing that makes one exist — see
+[What a section may declare](#what-a-section-may-declare).
 
 ### The address scheme
 
-Where the content tree mounts _inside the package_, and which note addresses a
-whole section rather than a page within one, differ between repositories and are
-both load-bearing. They are one setting, read by this command **and** by the page
+Where the content tree mounts _inside the package_ differs between repositories
+and is load-bearing. It is one setting, read by this command **and** by the page
 emitter, so the address a manifest publishes is the address a page is emitted at
 — stating it twice is how a manifest comes to assert a URL that resolves at build
 time and 404s for the reader.
@@ -1231,49 +1258,29 @@ publish:
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/ # default: "" — the package root
-    landing: readme # default: readme
 ```
 
-- **`prefix`** — the content tree's mount within the package: where its section
-  directories and their landing pages live. `sohl` publishes a knowledgebase
-  alongside generated API docs, so its sections sit under `kb/` (`kb/affliction/`)
-  while its pages address the package root (`affliction-aconite/`); `thalorna`'s
-  site is nothing but its content, so it has no prefix. It must end in a slash and
-  must not begin with one — where the _package_ is mounted is the consuming
-  build's knowledge and is never recorded here.
-- **`landing`** — which note is a section's landing page, and so is addressed by
-  the section rather than by `(type, shortcode)`:
-  - `readme` — a `README.md` addresses its section. A `doc` note then routes by
-    its `category` like any other, so a `category: collection` note publishes
-    under a literal `collection/` section.
-  - `collection` — a `doc` note whose `category` is `collection` addresses the
-    section it introduces, named by its authored `section`.
-
-  The two are alternatives rather than a pair that could both apply: each live
-  content tree holds notes the other rule would move.
-
-**Under `readme`, a landing's `subType` is an address rather than a genre.** The
-segment the `README` lands at is what `sectionOf` reads — for a `doc`, its
-`subType` — so `Weapons/README.md` writes `subType: weapongear` and publishes at
-`weapongear/`. `content-build lint` checks that value against the sections that
-can exist, which is three sets: every **content type** the format declares
-(`sectionOf` returns a non-`doc` note's own type, so `being` and `weapongear` are
-sections by construction), the **subtypes the type declares** (`rules`,
-`user-guide`, `reference`), and any section named in
-[`site.sections` / `site.readmeSections`](#what-a-section-may-declare). A
-misspelt one is still refused, by name and against all three, with the near miss
-suggested. This applies to a `README` only: every other note's `subType` stays
-closed to the values its type declares.
-
-Configuring the section is **not** a prerequisite — `site.sections` is framing,
-and a package that renders its own site need declare no `site:` block at all.
-
-A note the scheme yields no address for — one carrying no `shortcode`, a `doc`
-with no subtype (so no section to be filed under), a collection note naming no
-section — is **reported and omitted**, never guessed. The command
-prints one located diagnostic per note and still writes the file, because a note
-with no address is ordinary while a manifest entry pointing at a page that does
-not exist is not.
+- **`prefix`** — the content tree's mount within the package: the Hugo directory
+  its pages are written under. `sohl` publishes a knowledgebase alongside
+  generated API docs, so its tree sits under `kb/` while its pages address the
+  package root (`affliction-aconite/`); `thalorna`'s site is nothing but its
+  content, so it has no prefix. It must end in a slash and must not begin with
+  one — where the _package_ is mounted is the consuming build's knowledge and is
+  never recorded here.
+
+`prefix` is the whole scheme. The `collection` subtype and the top-level
+`section:` key are refused by name (#202).
+
+A note's `subType` is checked against the values its type declares, and only
+those. It briefly had a second reading — a `README` landing's `subType` was the
+_address_ it landed at, so the closed genre list could not answer for it (#197,
+#198, #200, #201) — and #204 removed the cause rather than widening the
+vocabulary again.
+
+The only note the scheme yields no address for is one carrying no `shortcode`.
+It is **reported and omitted**, never guessed: the command prints one located
+diagnostic per note and still writes the file, because a note with no address is
+ordinary while a manifest entry pointing at a page that does not exist is not.
 
 ## Publishing a website
 
@@ -1286,7 +1293,7 @@ The sibling of `package compile`: the same content tree, rendered as pages
 instead of compiled into packs. It does the walk, the frontmatter read, the
 address derivation, the address index, table expansion, wikilink resolution,
 code-fence protection, the foreign-manifest merge, the page emission and the
-section-landing backfill.
+section-landing synthesis.
 
 ### The homepage, and how much else is published
 
@@ -1316,8 +1323,9 @@ still refuses `id`. Everything else about its address is ordinary: it declares a
 [The homepage is addressed like every other note](#the-homepage-is-addressed-like-every-other-note)).
 `/<contentPackage>/` itself is a redirect the package authors, not a page this
 build writes. It is dispatched on `type` like every other note, not on a
-filename: `README.md` is already a section landing under `landing: readme`, and
-in `sohl-thalorna` it is a developer explainer about the source tree.
+filename — nothing in this format is decided by a file's name, which is why
+`sohl-thalorna` can keep a `README.md` in its content tree as a developer
+explainer about the source tree.
 
 `type: homepage` is declared by the **engine**, not by the `sohl` item registry,
 so a package that configures no `itemBuilders` at all — `HarnMaster-3-FoundryVTT`
@@ -1354,8 +1362,8 @@ module being withdrawable, and a homepage is one row in a routing table.
 The homepage's file is written at the root of `site.out` — the package's own
 site root, one level above the content mount, which is where
 `publish.address.prefix` puts everything else — under the name its address gives
-it, `homepage-root.md`. As with every other page, the file's location decides
-the Hugo section and the front matter's `url` decides where it publishes.
+it, `homepage-root.md`. As with every other page, the front matter's `url`
+decides where it publishes.
 
 **What it does not do is decide addresses.** Those come from `publish.address`,
 the same setting the link manifest reads, so a page and its manifest entry cannot
@@ -1391,36 +1399,97 @@ site:
 | `out`              | The Hugo content root. **Required** in both modes, and wiped on every run — see below.           |
 | `base`             | Where the package is served. Defaults to `/<contentPackage>/`.                                   |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                   |
-| `sections`         | What each section says about itself on its landing — see below.                                  |
-| `readmeSections`   | The same, for a section whose landing comes from a `README`.                                     |
+| `sections`         | The Hugo sections this site declares, and what each says about itself — see below.               |
+| `readmeSections`   | The same, for a `trees` entry, whose landing comes from its own `README`.                        |
 | `landing`          | Frontmatter for the mount's own `_index.md`. Passed through — the vocabulary is the theme's.     |
-| `backfillSections` | Write a bare `_index.md` for any other section directly under the mount.                         |
+| `backfillSections` | Write a bare `_index.md` for any other directory directly under the mount.                       |
 | `trees`            | Extra source trees published beside the content, preserving their source layout below a section. |
 | `pass`             | A named bundle of this repository's own body rewrites.                                           |
 | `passOptions`      | That bundle's options.                                                                           |
 
 ### What a section may declare
 
-A generated section landing is the **only** place a section can describe itself.
-A content package authors no `_index.md` for `weapongear` or `affliction`, so
-the file the theme reads is the one this build writes from `sections` — and
-whatever that entry may carry is the whole of what the section can say.
+**`sections` is what a section _is_ now** (#204). A content page is addressed
+`(type, shortcode)` and written flat under the mount, so no page creates a
+directory and nothing else makes `/<package>/<prefix><section>/` answer at all.
+A site that wants that address says so here, and this build writes the
+`_index.md` that makes Hugo agree it is a section.
+
+Two consequences follow, and neither is optional:
+
+- **Declare every section the site links to.** A card, a menu entry or a
+  breadcrumb pointing at a section nobody declared is a 404.
+- **A section landing lists no child pages.** Its directory holds only its own
+  `_index.md`, so a layout reading `.Pages` finds nothing. A layout that queries
+  `site.RegularPages` by `Params.type` is unaffected, and that is the shape a
+  content catalog wants anyway — it groups by what a page _is_, not by where its
+  file happened to be written. A section that wants that query run for it says
+  so with `listType` — see below.
+
+Whatever the entry may carry is the whole of what the section can say.
 
 | Key           | Required | What it does                                                              |
 | ------------- | -------- | ------------------------------------------------------------------------- |
 | `title`       | yes      | The landing's heading, so it matches the card that links to it.           |
 | `banner`      | no       | The hero image, resolved as a CDN asset like any other `banner:`.         |
 | `description` | no       | The hero standfirst under the heading, and the blurb a landing card uses. |
+| `listType`    | no       | The content **type** whose pages this section lists.                      |
+| `listSubType` | no       | Narrows that to one **subType**. Only with a `listType`.                  |
+
+`readmeSections` takes the same keys, for a **`trees`** entry: those pages keep
+their source layout below a named section, so the tree's own `README.md` is that
+section's landing. What the section declares wins over what the `README` happens
+to carry — the landing has to match the card that links to it. No content note
+reaches this map any more.
+
+#### Saying what a section lists
+
+A generic list layout has nothing to render, because the membership a section
+landing used to get free from Hugo's page tree no longer exists anywhere the
+theme can read: not on the page, not on the landing, not in any URL — only here.
+So a section states its own query, and a layout substitutes it when `.Pages` is
+empty:
+
+```yaml
+sections:
+  being: { title: Beings, listType: being }
+  rules: { title: Rules, listType: doc, listSubType: rules }
+  user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+```
+
+emits, for the last of those, `user-guide/_index.md`:
+
+```yaml
+---
+title: User Guide
+listType: doc
+listSubType: userguide
+---
+```
 
-`readmeSections` takes the same three, for a section whose landing comes from a
-`README` rather than from nothing. What the section declares wins over what the
-`README` happens to carry — the landing has to match the card that links to it.
+Three things about the spelling, each of them load-bearing:
+
+- **Not `type`.** On an `_index.md` that is Hugo's own layout selector — a
+  landing carrying `type: doc` is rendered by `layouts/doc/list.html` rather
+  than the default list template — so writing the content type there would
+  silently change which template serves the landing. This build already relies
+  on that behaviour for the mount's own `landing`.
+- **Not inferred from the section's name.** A section is named for a URL the
+  site chose; a type and a subType are addresses. They need not agree, and on
+  `sohl` they do not: the section is `user-guide`, because that is a published
+  URL, while the subType is `userguide` because an address segment is
+  alphanumeric (#207). Both values are checked against that charset here, so
+  copying the section's name in is refused rather than quietly matching nothing.
+- **`listSubType` needs a `listType`.** A subType only tells pages apart within
+  a type — `rules`, `userguide` and `reference` are all `doc` — so alone it
+  names no query.
 
 **The vocabulary is closed, and a key outside it is refused by name:**
 
 ```text
 package-build config: `site.sections.affliction.descrption` is not a
-recognized option (expected one of: title, banner, description).
+recognized option (expected one of: title, banner, description, listType,
+listSubType).
 ```
 
 That refusal is the point. `landing` is passed through unvalidated because it is
@@ -1429,7 +1498,10 @@ entry is written fourteen to twenty times per build against a contract every
 package and every section shares, so an unbounded one would let a mistyped
 `descrption:` publish into front matter, be read by nobody, and say nothing to
 anyone. Refusing it costs one line here when the vocabulary genuinely grows, and
-buys a build that cannot quietly emit a key no theme reads.
+buys a build that cannot quietly emit a key no theme reads. `listType` and
+`listSubType` are that growth: two named keys, checked, rather than an open
+passthrough in which `listTpye:` would publish and no landing would list
+anything.
 
 The **writers** name no keys: a section's `_index.md` is whatever the entry
 resolved to, `title` first. So extending the vocabulary is a change to the
@@ -1593,7 +1665,7 @@ path now rides on the error, and the loader that read the file resolves it
 against the YAML, so all of them come out located:
 
 ```text
-package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner).
+package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner, description, listType, listSubType).
 ```
 
 The same two rules apply. A key the file never declares — a required one that is

package/MIGRATING.md

@@ -1,3 +1,74 @@
+# Migrating to `@heroiclands/package-build` 12.0.0
+
+**No note edit, no URL change, and one thing to check in the Hugo layer.** A
+section is a Hugo directory concept that the note format no longer carries
+(#204): content pages are written **flat** under the content mount, named by
+their address, instead of into a `<section>/` directory.
+
+## 1. Nothing in the content tree changes
+
+A page's address never contained a section, so **no published URL moves**. A
+`README.md` in the content tree stops being its section's landing and becomes an
+ordinary page addressed `<type>-<shortcode>/` like every other note; if a tree
+still has one that was serving as a landing, it now publishes at its own address.
+No tree in this project had one.
+
+A `doc` with no `subType` used to be refused ("no section, so there is nowhere to
+file the page") and now publishes. Its `subType` is a **genre** again — closed to
+`rules`, `userguide`, `reference` — because it no longer doubles as a section
+address on a `README`. That closed check runs after the two #206 added ahead of
+it: a retired spelling is a warning naming its replacement, a hyphenated value
+is an error, and only then is the type's own list the reason.
+
+## 2. Declare every section your site links to
+
+`site.sections` is now the whole of what a section is. No page is filed into a
+section directory any more, so nothing else makes `/<package>/<prefix><section>/`
+exist:
+
+```yaml
+site:
+  sections:
+    being: { title: Beings, banner: banners/creature.webp }
+    weapongear: { title: Weapons, banner: banners/weapons.webp }
+```
+
+A card, menu entry or breadcrumb pointing at a section nobody declares is a 404.
+
+## 3. Check how a section landing lists its members
+
+A declared section's directory holds only its own `_index.md`, so a layout
+reading `.Pages` renders an empty listing. Query the site instead, on the page's
+own `type`:
+
+```go-html-template
+{{- $pages := where site.RegularPages "Type" "weapongear" -}}
+```
+
+That is the shape a content catalog wants regardless — it groups by what a page
+_is_ rather than by where its file happened to be written — and it is what
+`sohl`'s catalog layouts already do.
+
+A site rendering through a **shared theme** has no layout of its own to edit. As
+of 13.1.0 the section declares its query instead, and the theme runs it:
+
+```yaml
+sections:
+  weapongear: { title: Weapons, listType: weapongear }
+  user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+```
+
+`listType` is the content type, not the section's name — the two need not agree,
+and `listSubType` narrows a type whose genres share it. See
+[What a section may declare](CONTENT.md#what-a-section-may-declare).
+
+## What did not change
+
+- Every content page's `url:`, and so every published address.
+- Every link-manifest entry, including each entry's `path`.
+- Every compiled compendium document.
+- `site.sections` / `site.readmeSections` and what an entry may declare.
+
 # Migrating to `@heroiclands/package-build` 11.0.0
 
 **Two edits, and the second is one line per repository.** Every published page

package/bin/content-build.mjs

@@ -72,10 +72,6 @@ import {
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
-// The sections this repository declares — the open set a `README` landing's
-// `subType` names (#197). Read from the resolved configuration the site build
-// renders those landings from, so neither can name a section the other does not.
-import { declaredSections } from "../content-config.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     checkDeclaredFields,
@@ -740,22 +736,6 @@ function lintCommand() {
                     // decides which vocabulary a tree is held to.
                     vocabulary: NOTE_VOCABULARY,
                     references: argv.references,
-                    // How this repository addresses a section landing, and the
-                    // sections that can exist — the open vocabulary a
-                    // `README`'s `subType` is read against (#197, #200).
-                    // Passed in for the same reason the schemas are: the
-                    // linter checks a note against what it is handed.
-                    //
-                    // The types come from the **specification**, not from
-                    // `schemas`: a landing's `subType` is an address, and a
-                    // type the format declares is a section whether or not
-                    // this build carries a schema to check its notes' fields
-                    // with. Reading `schemas` here would refuse `Lore/README.md`
-                    // for a reason that is not about addresses, and report one
-                    // gap twice in two vocabularies.
-                    landing: config.publish.address.landing,
-                    types: [...loadContentFormat().types.keys()],
-                    sections: declaredSections(config),
                 });
 
                 // What the builders emit, against what the receiving system