poops 1.6.0 → 1.7.1

package/README.md

@@ -1,4 +1,4 @@
-# 💩 Poops [![npm version](https://img.shields.io/npm/v/poops)](https://www.npmjs.com/package/poops)
+# 💩 Poops [![npm version](https://img.shields.io/npm/v/poops)](https://www.npmjs.com/package/poops) [![build status](https://github.com/stamat/poops/actions/workflows/ci.yml/badge.svg)](https://github.com/stamat/poops/actions/workflows/ci.yml) [![license](https://img.shields.io/github/license/stamat/poops.svg)](https://github.com/stamat/poops/blob/main/LICENSE)
 
 Straightforward, no-bullshit bundler for the web.
 
@@ -40,6 +40,7 @@ It uses a simple config file where you define your input and output paths and it
     - [Nunjucks vs Liquid](#nunjucks-vs-liquid)
     - [Custom Engines](#custom-engines)
     - [Collections & Pagination](#collections--pagination)
+    - [Taxonomies (Tags & Categories)](#taxonomies-tags--categories)
     - [Custom Tags](#custom-tags)
       - [image](#image)
       - [googleFonts](#googlefonts)
@@ -71,6 +72,7 @@ It uses a simple config file where you define your input and output paths and it
 - Resolves node modules
 - Can add a templatable banner to output files (optional)
 - Static site generation with swappable template engines: [Nunjucks](https://mozilla.github.io/nunjucks/) (default) or [Liquid](https://liquidjs.com/) — with blogging option (optional)
+- Collections with pagination, and taxonomies — tags/categories as paginated, crawlable landing pages (with localizable labels)
 - Has a configurable local server (optional)
 - Rebuilds on file changes (optional)
 - Live reloads on file changes (optional)
@@ -749,8 +751,73 @@ Or use the `{% pagination %}` shorthand tag (available in both engines), which r
 {% pagination changelog %}
 ```
 
+Pages 2..N automatically get a distinct `<title>` — `Changelog — Page 2` — so paginated pages don't all share the landing page's title (and its `og`/`jsonld` metadata). Page 1 keeps its own title.
+
+**Localizing the labels.** The `— Page N` title suffix and the `{% pagination %}` tag's `Previous`/`Next`/`of` wording default to English. Override them site-wide under `site.pagination`:
+
+```json
+{
+  "markup": {
+    "site": {
+      "pagination": {
+        "title": "{title} — Seite {n}",
+        "prev": "Zurück",
+        "next": "Weiter",
+        "of": "von"
+      }
+    }
+  }
+}
+```
+
+`title` accepts `{title}`, `{n}` and `{total}` tokens and applies to pages 2..N (and taxonomy term pages); `prev`/`next`/`of` localize the `{% pagination %}` tag (`{n} of {total}` → `{n} von {total}`).
+
 Item pages themselves are compiled like any other markup file, preserving the directory structure: `src/markup/changelog/my-post.md` → `dist/changelog/my-post.html`. A collection directory without an index file still builds its items and exposes the collection to templates — only the paginated listing pages are skipped.
 
+#### Taxonomies (Tags & Categories)
+
+A **taxonomy** turns a front-matter field (tags, categories, authors) into its own paginated, crawlable landing page per term — `changelog/tag/feature/`, `blog/category/release/`. Declare which fields become taxonomies on the collection, alongside `paginate`/`sort` — either in the index front matter or the config entry:
+
+```yaml
+---
+title: Changelog
+collection: true
+paginate: 10
+taxonomies:
+  - name: tags # front-matter field to group on
+    path: tag # URL segment (defaults to name); "tag" for a singular URL
+    paginate: 5 # per-term page size (defaults to the collection's paginate)
+---
+```
+
+Shorthand: a bare string list (`taxonomies: [tags, category]`) uses each field name as the URL segment and inherits the collection's `paginate`. Array-valued fields split per element — a post with `tags: [js, css]` lands under **both** `tag/js/` and `tag/css/`. Terms are slugified for the URL (`Static Site` → `static-site`).
+
+Term pages render with the **collection's own index template** — no extra file. On a term page the collection object carries the term context; branch on `activeTerm` to render a term view:
+
+```nunjucks
+{% if changelog.activeTerm %}
+  <h1>Tagged {{ changelog.activeTerm | humanize }}</h1>
+  {% for post in changelog.pageItems %}
+    <a href="{{ relativePathPrefix }}{{ post.url }}">{{ post.title }}</a>
+  {% endfor %}
+  {% pagination changelog %}
+{% endif %}
+```
+
+On a term page `items`/`pageItems` are scoped to that term (so `pagination` and `groupby` narrow to it too); `activeTaxonomy` holds the URL segment and `activeTermSlug` the slug. Build tag links anywhere from `collection.taxonomies`:
+
+```nunjucks
+{% for tax in changelog.taxonomies %}
+  {% for term in tax.terms %}
+    <a href="{{ relativePathPrefix }}{{ term.url }}">{{ term.term | humanize }} ({{ term.count }})</a>
+  {% endfor %}
+{% endfor %}
+```
+
+Each term exposes `term`, `slug`, `url`, `count` and `totalPages`.
+
+Term pages get a distinct `<title>` and `og`/`jsonld` metadata (`Tag: Feature`, paged `Tag: Feature — Page 2`), and the `breadcrumb`/`jsonld` filters resolve them to a **Home › Collection › Tag: Term** trail automatically (skipping the non-page `tag`/`category` URL segment). The `Tag:`/`Category:` label comes from `path`, so it localizes by naming the path in your language (`path: etiqueta` → `Etiqueta: …`). Term pages are listed in the sitemap but kept out of the search index and nav.
+
 #### Custom Tags
 
 ##### image
@@ -804,9 +871,15 @@ Output:
 ```
 
 ```html
-<img src="static/photo-thumb-480w.webp"
-     srcset="static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w"
-     width="480" height="480" sizes="240px" alt="" loading="lazy">
+<img
+  src="static/photo-thumb-480w.webp"
+  srcset="static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w"
+  width="480"
+  height="480"
+  sizes="240px"
+  alt=""
+  loading="lazy"
+/>
 ```
 
 This requires the [poops-images](https://github.com/stamat/poops-images) compile cache (named-size widths are read from it). The `size` name matches a named entry in your `images.sizes` config. The largest member of the group is written without a width suffix (`photo-thumb.webp`) — poops still srcsets it at its real width from the cache.
@@ -908,6 +981,8 @@ All filters are available in both engines. The only syntax difference is how arg
 
 - `slugify` — slugifies a string. Usage: `{{ "My Awesome Title" | slugify }}` will output `my-awesome-title`
 
+- `humanize` — the inverse of `slugify`: turns a slug or raw term into a display label. Usage: `{{ "static-site" | humanize }}` will output `Static Site`
+
 - `jsonify` — serializes a value to JSON. Usage: `{{ myObject | jsonify }}`
 
 - `markdown` — renders a markdown string to HTML with GitHub Flavored Markdown extras: emoji shortcodes (e.g. `:rocket:` → 🚀), alert callouts (`> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`, `[!INFO]`) and footnotes (`[^1]`). Code fences are syntax-highlighted and headings get slug `id`s plus permalink anchors. Usage: `{{ "**bold** :rocket:" | markdown }}`
@@ -972,13 +1047,13 @@ All filters are available in both engines. The only syntax difference is how arg
 
   poops auto-picks `BlogPosting` (page has a `date`) or `WebPage`. Override `@type` with the `jsonld` object for any schema.org type — common ones search/generative engines act on: `Article`, `NewsArticle`, `HowTo`, `FAQPage`, `QAPage`, `Product`, `Recipe`, `Event`, `Course`, `VideoObject`, `SoftwareApplication`, `Organization`, `Person`, `BreadcrumbList`, `WebSite`. Full list at [schema.org/docs/full](https://schema.org/docs/full.html); validate with the [Rich Results Test](https://search.google.com/test/rich-results). A per-`@type` table with the notable fields is in the [Templating docs](example/src/markup/docs/quick-start/templating-html.md).
 
-- `breadcrumb` — generates a visible breadcrumb `<nav class="breadcrumb"><ol>…</ol></nav>` trail for the page body (blog posts, nested pages), from the same URL-depth data the `jsonld` `BreadcrumbList` uses: the site root, each ancestor folder (humanized, e.g. `docs/static-site` → *Static Site*), then the current page as `aria-current` text. Pass `relativePathPrefix` so links resolve against the current output location (localhost in dev, your deployed subpath in prod) — not the absolute domain.
+- `breadcrumb` — generates a visible breadcrumb `<nav class="breadcrumb"><ol>…</ol></nav>` trail for the page body (blog posts, nested pages), from the same URL-depth data the `jsonld` `BreadcrumbList` uses: the site root, each ancestor folder (humanized, e.g. `docs/static-site` → _Static Site_), then the current page as `aria-current` text. Pass `relativePathPrefix` so links resolve against the current output location (localhost in dev, your deployed subpath in prod) — not the absolute domain.
   - Nunjucks: `{{ page | breadcrumb(site, relativePathPrefix) }}`
   - Liquid: `{{ page | breadcrumb: site, relativePathPrefix }}`
 
   The home crumb is optional: set `breadcrumb: { home: false }` (or `{ homeLabel: "Start" }` to rename it) under `site` or in a page's front matter — front matter wins. With the home crumb off, top-level pages fall to a single crumb and render nothing, while nested pages still show their folder trail. `breadcrumb: false` on a page or on `site` disables both the visible trail and the auto `BreadcrumbList` JSON-LD. Returns nothing on the homepage or any single-crumb page.
 
-- `groupby` — groups an array of objects by a field value. Returns an array of `{ key, items }` objects. Supports an optional second argument for date part extraction (`year`, `month`, `day`). Groups preserve insertion order, so if items are sorted by date descending, groups will be too.
+- `groupby` — groups an array of objects by a field value. Returns an array of `{ key, items }` objects. Supports an optional second argument for date part extraction (`year`, `month`, `day`). Groups preserve insertion order, so if items are sorted by date descending, groups will be too. Array-valued fields split per element — an item with `tags: [js, css]` appears in **both** the `js` and `css` groups (the mechanism behind [taxonomies](#taxonomies-tags--categories)).
   - Nunjucks: `{{ changelog.items | groupby("author") }}` or `{{ changelog.items | groupby("date", "year") }}`
   - Liquid: `{{ changelog.items | groupby: "author" }}` or `{{ changelog.items | groupby: "date", "year" }}`
 
@@ -1007,7 +1082,7 @@ All filters are available in both engines. The only syntax difference is how arg
 
 Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo-960w.webp 960w`
 
-  Pass a named crop/resize group as the second argument to get that group's srcset instead of the default widths: `{{ 'static/photo.jpg' | srcset: 'thumb' }}` → `static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w`.
+Pass a named crop/resize group as the second argument to get that group's srcset instead of the default widths: `{{ 'static/photo.jpg' | srcset: 'thumb' }}` → `static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w`.
 
 - `exif` — returns the EXIF metadata object for an image from the [poops-images](https://github.com/stamat/poops-images) compile cache (`.poops-images-cache.json` in the output directory), or `null` if there is no cache or no EXIF data. The object includes camera (`make`, `model`, `lensModel`), exposure (`fNumber`, `exposure.formatted`, `iso`, `focalLength35mm`), `dateTime`, and `gps` (`latitude.formatted`, `longitude.formatted`, `altitude`, and a ready-made `googleMapsUrl`).
 
@@ -1149,7 +1224,7 @@ All front matter fields are passed through to the index automatically. Internal
 ]
 ```
 
-**Sitemap** generates a standard `sitemap.xml` with `<loc>` and `<lastmod>` (from front matter `date`). If `site.url` is set in your markup config, it is prepended to all URLs. Collection index/pagination pages are included in the sitemap but excluded from the search index.
+**Sitemap** generates a standard `sitemap.xml` with `<loc>` and `<lastmod>` (from front matter `date`). If `site.url` is set in your markup config, it is prepended to all URLs. Collection index/pagination and taxonomy term pages are included in the sitemap but excluded from the search index.
 
 **llms.txt** generates an [`llms.txt`](https://llmstxt.org) — a Markdown index of your pages that LLMs and generative engines (GEO) read to understand your site. It has an `# H1` title, a `> ` blockquote summary, then `- [title](url): description` links grouped by URL path: the first folder is a `## section`, a second folder nests as a `### subsection` under it, and root-level pages fall under a lead "Pages" section. So `docs/config-reference.html` lands directly under `## Docs` while `docs/quick-start/x.html` lands under `### Quick Start` inside it. Collection items (which live under `collection/…`) group the same way and are ordered newest-first by their `date`; other sections keep file order. Set `intro` to a Markdown file path (relative to the project root) to insert free-form context between the blockquote and the link sections — a file authored for LLMs, e.g. `llms-intro.md`. Avoid `##` headings in it; they read as sections. (A raw README is a poor fit — badges, install noise and its own headings collide.) `title` and `description` default to your `site.title`/`site.description`; override them (and the lead section name via `sectionTitle`) with the object form. `site.url` makes the links absolute. Collection index/pagination pages are skipped, like the search index.
 
@@ -1172,7 +1247,8 @@ Pages with `published: false` in their front matter are excluded from all output
 A page's front matter `robots: noindex` (or `none`) drops it from the **sitemap and llms.txt** — for drafts, thin or utility pages (a 404, say) you don't want crawled or fed to LLMs. It stays in the search index (that's your own on-site search). Emit the matching crawler directive in your layout `<head>` so the page itself carries it:
 
 ```html
-{% if page.robots %}<meta name="robots" content="{{ page.robots }}">{% endif %}
+{% if page.robots %}<meta name="robots" content="{{ page.robots }}" />{% endif
+%}
 ```
 
 **Navigation tree** builds your page hierarchy as sidebar-ready data, exposed two ways: as the `nav` template global (loaded automatically, always reflecting the current build) and as a nested JSON file for client-side rendering. Subpages nest automatically from URL structure: `guide/index.md` becomes a parent node and `guide/getting-started.md`, `guide/advanced/config.md` become its (and its subsections') children. Add `nav` to your markup config:
@@ -1316,7 +1392,11 @@ Shorthand forms: `"feed": true` (or a filename string) emits an RSS feed for eve
 Point browsers and readers at it from your layout `<head>`:
 
 ```html
-<link rel="alternate" type="application/rss+xml" href="{{ site.url }}/blog/feed.rss">
+<link
+  rel="alternate"
+  type="application/rss+xml"
+  href="{{ site.url }}/blog/feed.rss"
+/>
 ```
 
 ### Images (optional)

package/lib/exec.js

@@ -1,6 +1,21 @@
 import { execSync } from 'node:child_process'
 import log, { styledLog } from './utils/log.js'
 
+// Every stage runExec fires a hook for. A key in config.exec outside this set
+// never runs (runExec only looks up known stages), so it's almost always a typo
+// (e.g. `style`, `script`). validateExec warns once at startup instead of
+// letting the hook silently no-op.
+export const EXEC_STAGES = ['reactor', 'scripts', 'images', 'markup', 'styles', 'copy', 'build']
+
+// Returns the unknown stage keys (for tests); warns for each as a side effect.
+export function validateExec(config) {
+  const unknown = Object.keys(config.exec || {}).filter((key) => !EXEC_STAGES.includes(key))
+  for (const key of unknown) {
+    log({ tag: 'exec', warn: true, text: `unknown stage "${key}" — never runs. Valid: ${EXEC_STAGES.join(', ')}` })
+  }
+  return unknown
+}
+
 // Post-stage shell hooks. `config.exec` maps a pipeline stage to a command (or
 // array of commands) run after that stage compiles — in both build and watch,
 // so a post-processor (e.g. stripping CSS comments, regenerating a reference)

package/lib/markup/collections.js

@@ -1,9 +1,10 @@
 import fs from 'node:fs'
 import { globSync } from 'glob'
 import path from 'node:path'
+import { slugify, humanize } from 'book-of-spells'
 import log from '../utils/log.js'
 import { mkDir, toPosix } from '../utils/helpers.js'
-import { replaceOutExtensions, getRelativePathPrefix, getPageUrlRelativeToOutput, parseFrontMatter, wordcount, excerpt } from './helpers.js'
+import { replaceOutExtensions, getRelativePathPrefix, getPageUrlRelativeToOutput, parseFrontMatter, wordcount, excerpt, groupby } from './helpers.js'
 
 export function getSingleCollectionData(markupInDir, collectionName) {
   const collectionData = []
@@ -158,9 +159,75 @@ export function buildCollectionObject(markupInDir, collectionProtoObject) {
     }
   })
 
+  if (collectionProtoObject.taxonomies) {
+    collection._taxonomies = normalizeTaxonomies(collectionProtoObject.taxonomies, collection.paginate)
+  }
+
   return collection
 }
 
+// Normalizes the `taxonomies` collection option into { name, path, paginate }.
+// Accepts "tags" | ["tags", "category"] | [{ name, path, paginate }]. `name` is
+// the front-matter field grouped on; `path` is the URL segment under the
+// collection (defaults to `name`, so use `{ name: "tags", path: "tag" }` for a
+// singular /tag/ URL); `paginate` falls back to the collection's page size.
+function normalizeTaxonomies(config, defaultPaginate) {
+  const items = Array.isArray(config) ? config : [config]
+  const out = []
+  for (let item of items) {
+    if (typeof item === 'string') item = { name: item }
+    if (!item || !item.name) continue
+    const paginate = parseInt(item.paginate)
+    out.push({
+      name: item.name,
+      path: item.path || item.name,
+      paginate: !isNaN(paginate) ? paginate : defaultPaginate
+    })
+  }
+  return out
+}
+
+// Chunks items into pages of `size`; no/invalid size → a single page holding all.
+export function paginateItems(items, size) {
+  if (!size || isNaN(size) || size < 1) return [items]
+  const pages = []
+  for (let i = 0; i < items.length; i += size) pages.push(items.slice(i, i + size))
+  return pages.length ? pages : [items]
+}
+
+// Groups each collection's items by every configured taxonomy field and attaches
+// collection.taxonomies = [{ name, path, terms: [{ term, slug, url, count,
+// totalPages, pages, items }] }] — consumed by both the listing template (to link
+// tag/category pages) and generateTaxonomyPages. Must run before any collection
+// template renders so page 1 of the index can already see the term links.
+// ponytail: two terms that slugify to the same slug collide on one URL (last
+// write wins). Add a per-slug de-dupe counter if real tag sets ever clash.
+export function buildTaxonomyData(collectionData) {
+  if (!collectionData) return
+  for (const name of Object.keys(collectionData)) {
+    const collection = collectionData[name]
+    if (!collection._taxonomies) continue
+    collection.taxonomies = collection._taxonomies.map((tax) => {
+      const terms = groupby(collection.items, tax.name)
+        .filter((g) => g.key !== '')
+        .map((g) => {
+          const slug = slugify(g.key)
+          const pages = paginateItems(g.items, tax.paginate)
+          return {
+            term: g.key,
+            slug,
+            url: toPosix(path.join(collection.name, tax.path, slug)),
+            count: g.items.length,
+            totalPages: pages.length,
+            pages,
+            items: g.items
+          }
+        })
+      return { name: tax.name, path: tax.path, terms }
+    })
+  }
+}
+
 export function buildCollectionPaginationData(collectionData) {
   if (!collectionData) return
 
@@ -204,9 +271,83 @@ export function pruneStalePaginationDirs(collectionName, markupInDir, markupOutD
   }
 }
 
-export function generateCollectionPaginationPages(collectionData, markupInDir, markupOutDir, compileEntryFn, baseURL) {
+// Renders a collection template once per page in `pages`, writing page 1 to
+// out/<urlBase>/index.html and page N (2..) to out/<urlBase>/N/index.html.
+// Shared by plain collection pagination and per-term taxonomy pages: the only
+// differences are urlBase and the `extra` context merged onto the collection
+// snapshot (taxonomy pages add activeTerm/activeTaxonomy and a term-filtered
+// items/pageItems). Returns a promise per page.
+function renderPages({ pages, urlBase, collection, extra, pageProps, titleBase, titleAlways, titleFormat, collectionName, collectionData, file, markupOutDir, compileEntryFn, baseURL }) {
+  const promises = []
+  const totalPages = pages.length
+
+  for (let i = 0; i < totalPages; i++) {
+    const pageNumber = i + 1
+    const pageUrl = pageNumber === 1 ? urlBase : `${urlBase}/${pageNumber}`
+    const nextPage = pageNumber === totalPages ? null : pageNumber + 1
+    const nextPageUrl = nextPage === null ? null : `${urlBase}/${nextPage}`
+    const prevPage = pageNumber === 1 ? null : pageNumber - 1
+    let prevPageUrl = prevPage === null ? null : `${urlBase}/${prevPage}`
+    if (prevPage === 1) prevPageUrl = urlBase
+
+    // Snapshot per-page properties to avoid async mutation
+    const pageSnapshot = {
+      ...collection,
+      ...extra,
+      pageItems: pages[i],
+      pageNumber,
+      totalPages,
+      pageUrl,
+      nextPage,
+      nextPageUrl,
+      prevPage,
+      prevPageUrl
+    }
+
+    const markupOut = path.resolve(process.cwd(), markupOutDir, pageUrl, 'index.html')
+    const fromPath = path.resolve(process.cwd(), markupOutDir)
+    const markupOutDirFull = path.dirname(markupOut)
+
+    const context = {
+      ...collectionData,
+      [collectionName]: pageSnapshot,
+      relativePathPrefix: getRelativePathPrefix(markupOutDirFull, fromPath, baseURL),
+      // output-relative so page.url matches nav.json/index urls, same as compileDirectory
+      _url: getPageUrlRelativeToOutput(markupOut, markupOutDir)
+    }
+    // extra props stamped onto page.* (compileEntry honors _page) — taxonomy
+    // pages use it to feed the breadcrumb a correct term trail, and both paths
+    // set a distinct title so <title>/og/jsonld don't duplicate across pages.
+    // titleAlways overrides page 1 too (term pages want "Tag: Feature"); plain
+    // pagination keeps page 1's front-matter title and only suffixes 2..N.
+    const props = { ...pageProps }
+    if (titleBase && (titleAlways || pageNumber > 1)) {
+      props.title = pageNumber === 1
+        ? titleBase
+        : (titleFormat || '{title} — Page {n}')
+            .replace('{title}', titleBase)
+            .replace('{n}', pageNumber)
+            .replace('{total}', totalPages)
+    }
+    if (Object.keys(props).length) context._page = props
+
+    // mkDir only when a page is actually written: no empty pagination dirs
+    // for index-less or unpublished (skipped) collection indexes
+    promises.push(compileEntryFn(file, context).then(({ result, skipped }) => {
+      if (skipped) return
+      mkDir(markupOutDirFull)
+      // async write so I/O overlaps rendering of the other pages
+      return fs.promises.writeFile(markupOut, result)
+    }))
+  }
+
+  return promises
+}
+
+export function generateCollectionPaginationPages(collectionData, markupInDir, markupOutDir, compileEntryFn, baseURL, site = {}) {
   if (!collectionData) return []
 
+  const titleFormat = site.pagination && site.pagination.title
   const compilePromises = []
 
   for (const collectionName of Object.keys(collectionData)) {
@@ -223,50 +364,106 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
 
     if (!file) continue
 
-    for (let i = 0; i < collection.totalPages; i++) {
-      const pageNumber = i + 1
-      const pageUrl = pageNumber === 1 ? collection.name : `${collection.name}/${pageNumber}`
-      const nextPage = pageNumber === collection.totalPages ? null : pageNumber + 1
-      const nextPageUrl = pageNumber === collection.totalPages ? null : `${collection.name}/${pageNumber + 1}`
-      const prevPage = pageNumber === 1 ? null : pageNumber - 1
-      let prevPageUrl = pageNumber === 1 ? null : `${collection.name}/${pageNumber - 1}`
-      if (prevPage === 1) {
-        prevPageUrl = collection.name
-      }
+    // base for "<title> — Page N" on pages 2..N (page 1 keeps its own title)
+    const indexTitle = parseFrontMatter(file).frontMatter.title || humanize(collection.name)
+
+    compilePromises.push(...renderPages({
+      pages: collection.pages,
+      urlBase: collection.name,
+      collection,
+      extra: {},
+      titleBase: indexTitle,
+      titleFormat,
+      collectionName,
+      collectionData,
+      file,
+      markupOutDir,
+      compileEntryFn,
+      baseURL
+    }))
+  }
 
-      // Snapshot per-page properties to avoid async mutation
-      const pageSnapshot = {
-        ...collection,
-        pageItems: collection.pages[i],
-        pageNumber,
-        pageUrl,
-        nextPage,
-        nextPageUrl,
-        prevPage,
-        prevPageUrl
-      }
+  return compilePromises
+}
 
-      const markupOut = path.resolve(process.cwd(), markupOutDir, pageUrl, 'index.html')
-      const fromPath = path.resolve(process.cwd(), markupOutDir)
-      const markupOutDirFull = path.dirname(markupOut)
+// Removes stale output under out/<collection>/<tax.path>/: whole term-slug dirs
+// for terms that no longer exist, plus leftover page dirs (2..) inside a
+// surviving term whose page count shrank. Guarded so a real source subdir
+// mirrored at the same path is never deleted.
+export function pruneStaleTaxonomyDirs(collectionName, tax, markupInDir, markupOutDir, terms) {
+  const taxDir = path.resolve(process.cwd(), markupOutDir, collectionName, tax.path)
+  if (!fs.existsSync(taxDir)) return
 
-      const context = {
-        ...collectionData,
-        [collectionName]: pageSnapshot,
-        relativePathPrefix: getRelativePathPrefix(markupOutDirFull, fromPath, baseURL),
-        // output-relative so page.url matches nav.json/index urls, same as compileDirectory
-        _url: getPageUrlRelativeToOutput(markupOut, markupOutDir)
-      }
+  // never touch a taxonomy path that shadows a real source directory
+  if (fs.existsSync(path.resolve(process.cwd(), markupInDir, collectionName, tax.path))) return
+
+  const bySlug = new Map(terms.map((t) => [t.slug, t]))
 
-      // mkDir only when a page is actually written: no empty pagination dirs
-      // for index-less or unpublished (skipped) collection indexes
-      const compilePromise = compileEntryFn(file, context).then(({ result, skipped }) => {
-        if (skipped) return
-        mkDir(markupOutDirFull)
-        // async write so I/O overlaps rendering of the other pages
-        return fs.promises.writeFile(markupOut, result)
-      })
-      compilePromises.push(compilePromise)
+  for (const entry of fs.readdirSync(taxDir)) {
+    const slugDir = path.join(taxDir, entry)
+    if (!fs.statSync(slugDir).isDirectory()) continue
+
+    const term = bySlug.get(entry)
+    if (!term) {
+      fs.rmSync(slugDir, { recursive: true, force: true })
+      continue
+    }
+
+    // surviving term: drop page-number dirs beyond its current totalPages
+    for (const sub of fs.readdirSync(slugDir)) {
+      const pageNumber = parseInt(sub, 10)
+      if (String(pageNumber) !== sub || pageNumber < 2 || pageNumber <= term.totalPages) continue
+      fs.rmSync(path.join(slugDir, sub), { recursive: true, force: true })
+    }
+  }
+}
+
+// Renders per-term taxonomy pages (e.g. changelog/tag/release/) using the
+// collection's own index template. Each term page carries the term-filtered
+// items/pageItems and activeTaxonomy/activeTerm so the shared template can show
+// a heading and paginate. buildTaxonomyData must have run first.
+export function generateTaxonomyPages(collectionData, markupInDir, markupOutDir, compileEntryFn, baseURL, site = {}) {
+  if (!collectionData) return []
+
+  const titleFormat = site.pagination && site.pagination.title
+  const compilePromises = []
+
+  for (const collectionName of Object.keys(collectionData)) {
+    const collection = collectionData[collectionName]
+    if (!collection.taxonomies) continue
+
+    const file = getCollectionIndexFile(markupInDir, collectionName)
+
+    for (const tax of collection.taxonomies) {
+      // prune before the index check so removed tags are cleaned even if the
+      // index template was deleted
+      pruneStaleTaxonomyDirs(collectionName, tax, markupInDir, markupOutDir, file ? tax.terms : [])
+      if (!file) continue
+
+      for (const term of tax.terms) {
+        compilePromises.push(...renderPages({
+          pages: term.pages,
+          urlBase: term.url,
+          collection,
+          // term-scope items so `.items` and `groupby(.items…)` also filter to
+          // the term on its page, not the whole collection
+          extra: { items: term.items, activeTaxonomy: tax.path, activeTerm: term.term, activeTermSlug: term.slug },
+          // breadcrumb hint: Home > collection > term (the tag/ path segment has
+          // no page, and page.title is the index's, not the term's)
+          pageProps: { _taxonomy: { collection: collectionName, path: tax.path, term: term.term, termUrl: term.url } },
+          // distinct <title>/og/jsonld per term ("Tag: Feature"), not the shared
+          // index title — matches the breadcrumb crumb label
+          titleBase: `${humanize(tax.path)}: ${humanize(term.term)}`,
+          titleAlways: true,
+          titleFormat,
+          collectionName,
+          collectionData,
+          file,
+          markupOutDir,
+          compileEntryFn,
+          baseURL
+        }))
+      }
     }
   }
 

package/lib/markup/engines/liquid.js

@@ -5,7 +5,7 @@ import { highlightCode } from '../highlight.js'
 import { marked, renderMarkdownCached } from '../renderer.js'
 import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc, buildJsonLd, buildOpenGraph, buildCanonical, buildBreadcrumb } from '../helpers.js'
 import { getImageExif, listImages } from '../image-cache.js'
-import { slugify } from 'book-of-spells'
+import { slugify, humanize } from 'book-of-spells'
 import dayjs from 'dayjs'
 
 // liquidjs parse-cache keys: "<lookupType>:<name>" (root/layouts/partials)
@@ -76,6 +76,7 @@ export default class LiquidEngine {
   registerFilters({ timeDateFormat, markupOut }) {
     const engine = this.engine
     engine.registerFilter('slugify', (str) => slugify(str))
+    engine.registerFilter('humanize', (str) => humanize(str))
     engine.registerFilter('jsonify', (obj) => JSON.stringify(obj))
     engine.registerFilter('markdown', (str) => marked.parse(String(str || '')))
     engine.registerFilter('toc', (html) => renderToc(String(html || '')))
@@ -293,7 +294,8 @@ function registerPaginationTag(engine) {
     * render(ctx) {
       const pagination = yield this.liquid._evalValue(this.value, ctx)
       const prefix = (yield ctx.get(['relativePathPrefix'])) || ''
-      return buildPaginationTag(pagination, prefix)
+      const site = (yield ctx.get(['site'])) || {}
+      return buildPaginationTag(pagination, prefix, site.pagination)
     }
   })
 }

package/lib/markup/engines/nunjucks.js

@@ -7,7 +7,7 @@ import { getImageExif, listImages } from '../image-cache.js'
 import { toPosix } from '../../utils/helpers.js'
 import { highlightCode } from '../highlight.js'
 import { marked, renderMarkdownCached } from '../renderer.js'
-import { slugify } from 'book-of-spells'
+import { slugify, humanize } from 'book-of-spells'
 import dayjs from 'dayjs'
 import log from '../../utils/log.js'
 
@@ -133,6 +133,7 @@ export default class NunjucksEngine {
   registerFilters({ timeDateFormat, markupOut }) {
     const env = this.env
     env.addFilter('slugify', slugify)
+    env.addFilter('humanize', humanize)
     env.addFilter('jsonify', (obj) => JSON.stringify(obj))
     env.addFilter('markdown', (str) => marked.parse(String(str || '')))
     env.addFilter('toc', (html) => {
@@ -341,6 +342,7 @@ export class PaginationExtension {
 
   run(context, pagination) {
     const prefix = context.lookup('relativePathPrefix') || ''
-    return new nunjucks.runtime.SafeString(buildPaginationTag(pagination, prefix))
+    const site = context.lookup('site') || {}
+    return new nunjucks.runtime.SafeString(buildPaginationTag(pagination, prefix, site.pagination))
   }
 }

package/lib/markup/helpers.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import yaml from 'yaml'
+import { humanize } from 'book-of-spells'
 import { toPosix } from '../utils/helpers.js'
 import { getImageEntry } from './image-cache.js'
 
@@ -131,8 +132,18 @@ export function groupby(arr, key, datePart) {
   if (!Array.isArray(arr)) return []
 
   const map = new Map()
+  const put = (groupKey, item) => {
+    if (!map.has(groupKey)) map.set(groupKey, [])
+    map.get(groupKey).push(item)
+  }
   for (const item of arr) {
     let value = item[key]
+    // Array value (e.g. `tags: [a, b]`) → item lands in each element's bucket,
+    // so one post appears under every tag it carries.
+    if (Array.isArray(value)) {
+      for (const v of value) put(v != null ? String(v) : '', item)
+      continue
+    }
     if (datePart && value) {
       const date = new Date(value)
       if (!isNaN(date)) {
@@ -143,9 +154,7 @@ export function groupby(arr, key, datePart) {
         }
       }
     }
-    const groupKey = value != null ? String(value) : ''
-    if (!map.has(groupKey)) map.set(groupKey, [])
-    map.get(groupKey).push(item)
+    put(value != null ? String(value) : '', item)
   }
 
   return Array.from(map, ([key, items]) => ({ key, items }))
@@ -344,15 +353,21 @@ export function escapeAttr(value) {
   return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
 }
 
-export function buildPaginationTag(pagination, prefix = '') {
+// `labels` (site.pagination) localizes the prev/next/of wording; English
+// defaults. Author-supplied, but escaped anyway since it lands in HTML.
+export function buildPaginationTag(pagination, prefix = '', labels = {}) {
   const totalPages = Number(pagination && pagination.totalPages) || 1
   if (totalPages <= 1) return ''
 
+  const prev = escapeAttr(labels.prev || 'Previous')
+  const next = escapeAttr(labels.next || 'Next')
+  const of = escapeAttr(labels.of || 'of')
+
   const pageNumber = Number(pagination && pagination.pageNumber) || 1
   const parts = []
-  if (pagination.prevPageUrl) parts.push(`<a href="${escapeAttr(prefix + pagination.prevPageUrl)}">Previous</a>`)
-  parts.push(`<span>${pageNumber} of ${totalPages}</span>`)
-  if (pagination.nextPageUrl) parts.push(`<a href="${escapeAttr(prefix + pagination.nextPageUrl)}">Next</a>`)
+  if (pagination.prevPageUrl) parts.push(`<a href="${escapeAttr(prefix + pagination.prevPageUrl)}">${prev}</a>`)
+  parts.push(`<span>${pageNumber} ${of} ${totalPages}</span>`)
+  if (pagination.nextPageUrl) parts.push(`<a href="${escapeAttr(prefix + pagination.nextPageUrl)}">${next}</a>`)
   return parts.join('\n')
 }
 
@@ -407,12 +422,7 @@ function jsonLdScript(data) {
 // that has no page object of its own — same rule the nav tree uses for virtual
 // parents. Strips a trailing extension, then dash/underscore → spaced Title Case.
 function humanizeSegment(seg) {
-  return String(seg)
-    .replace(/\.[a-z0-9]+$/i, '')
-    .replace(/[-_]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .replace(/\b\w/g, c => c.toUpperCase())
+  return humanize(String(seg).replace(/\.[a-z0-9]+$/i, ''))
 }
 
 // Builds a breadcrumb trail — a { name, path } array from the site root down to
@@ -436,6 +446,22 @@ export function breadcrumbCrumbs(page, site = {}) {
   if (site.breadcrumb && typeof site.breadcrumb === 'object') Object.assign(cfg, site.breadcrumb)
   if (page.breadcrumb && typeof page.breadcrumb === 'object') Object.assign(cfg, page.breadcrumb)
 
+  // Taxonomy term page: its URL segments (e.g. changelog/tag/feature) are not a
+  // real page hierarchy — the `tag` segment has no page, and the last segment is
+  // a slug, not the page title. Build the trail from the term hint instead:
+  // Home > collection landing > term.
+  if (page._taxonomy) {
+    const t = page._taxonomy
+    const crumbs = []
+    if (cfg.home) crumbs.push({ name: cfg.homeLabel, path: '' })
+    crumbs.push({ name: humanizeSegment(t.collection), path: t.collection })
+    // prefix with the taxonomy label ("Tag: Feature") — the dropped `tag/` path
+    // segment isn't a crumb, so this restores the "it's an archive" context
+    const label = t.path ? `${humanizeSegment(t.path)}: ` : ''
+    crumbs.push({ name: `${label}${humanizeSegment(t.term)}`, path: t.termUrl })
+    return crumbs.length >= 2 ? crumbs : []
+  }
+
   const rawUrl = page.url != null ? String(page.url) : ''
   if (rawUrl === '') return [] // homepage — you're already home
 
@@ -539,7 +565,7 @@ export function buildJsonLd(page, site = {}) {
     description: page.description || page.excerpt || site.description,
     url: absUrl(page.url),
     inLanguage: page.lang || site.lang,
-    image: absUrl(page.image),
+    image: absUrl(page.image || site.image),
     publisher
   }
 

package/lib/markup/indexer.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { readJsonFile, fileSize } from '../utils/helpers.js'
 import { parseFrontMatter } from './helpers.js'
 import { renderMarkdownCached } from './renderer.js'
+import { humanize } from 'book-of-spells'
 import log from '../utils/log.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -238,10 +239,10 @@ export function generateLlmsTxt(pageEntries, outputDir, siteUrl, config) {
     if (segs.length === 0) {
       sectionOf(lead).direct.push(e)
     } else if (segs.length === 1) {
-      sectionOf(humanizeSegment(segs[0])).direct.push(e)
+      sectionOf(humanize(segs[0])).direct.push(e)
     } else {
-      const subs = sectionOf(humanizeSegment(segs[0])).subs
-      const key = humanizeSegment(segs[1])
+      const subs = sectionOf(humanize(segs[0])).subs
+      const key = humanize(segs[1])
       if (!subs.has(key)) subs.set(key, [])
       subs.get(key).push(e)
     }
@@ -372,14 +373,6 @@ export function generateRobotsTxt(outputDir, siteUrl, config, sitemapOutput) {
   log({ tag: 'indexer', text: 'Generated robots.txt:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
 }
 
-function humanizeSegment(seg) {
-  return seg
-    .replace(/[-_]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .replace(/\b\w/g, c => c.toUpperCase())
-}
-
 function navNodeTitle(entry) {
   return entry.navTitle || entry.title
 }
@@ -401,7 +394,7 @@ function navFilterEntries(pageEntries, collectionsOpt) {
       // pagination pages (url has a slash) always dropped. Landing titles are
       // the raw collection name ("blog"), so humanize for display.
       if (mode === 'index' && !e.url.includes('/')) {
-        result.push({ ...e, title: humanizeSegment(e.title) })
+        result.push({ ...e, title: humanize(e.title) })
       }
       continue
     }
@@ -454,7 +447,7 @@ function serializeNavNode(node) {
   const children = [...node.children.values()].map(serializeNavNode)
   sortNavSiblings(children)
 
-  const out = { title: node.title != null ? node.title : humanizeSegment(node.segment) }
+  const out = { title: node.title != null ? node.title : humanize(node.segment) }
   if (node.url != null) out.url = node.url
 
   let order = node.order
@@ -564,7 +557,7 @@ function resolveFeedSpecs(config, collectionNames, site) {
         output: outName.includes('/') ? outName : `${name}/${outName}`,
         type: item.type === 'atom' ? 'atom' : 'rss',
         limit: Number(item.limit) > 0 ? Number(item.limit) : 20,
-        title: item.title || (site.title ? `${humanizeSegment(name)} | ${site.title}` : humanizeSegment(name)),
+        title: item.title || (site.title ? `${humanize(name)} | ${site.title}` : humanize(name)),
         description: item.description || site.description || '',
         author: feedAuthorName(item.author || site.author),
         lang: item.lang || site.lang || '',

package/lib/markups.js

@@ -1,6 +1,6 @@
 import { pathExists, pathIsDirectory, readDataFile, mkDir, buildTime, toPosix } from './utils/helpers.js'
 import { replaceOutExtensions, getRelativePathPrefix, getPageUrlRelativeToOutput, parseFrontMatter, wordcount, excerpt } from './markup/helpers.js'
-import { collectionAutoDiscovery, getCollectionDataBasedOnConfig, buildCollectionPaginationData, generateCollectionPaginationPages } from './markup/collections.js'
+import { collectionAutoDiscovery, getCollectionDataBasedOnConfig, buildCollectionPaginationData, generateCollectionPaginationPages, buildTaxonomyData, generateTaxonomyPages } from './markup/collections.js'
 import { generateIndexFiles, buildNavTree } from './markup/indexer.js'
 import NunjucksEngine from './markup/engines/nunjucks.js'
 import LiquidEngine from './markup/engines/liquid.js'
@@ -225,11 +225,18 @@ export default class Markups {
     const context = { page: {} }
     let pageUrl
 
+    let pageExtra
     if (additionalContext) {
       if (additionalContext._url) {
         pageUrl = additionalContext._url
         delete additionalContext._url
       }
+      // extra props to stamp on page.* after front-matter parse (e.g. taxonomy
+      // pages inject the breadcrumb hint the index template's front matter lacks)
+      if (additionalContext._page) {
+        pageExtra = additionalContext._page
+        delete additionalContext._page
+      }
       Object.assign(context, additionalContext)
     }
 
@@ -245,6 +252,7 @@ export default class Markups {
     }
 
     if (pageUrl) context.page.url = pageUrl
+    if (pageExtra) Object.assign(context.page, pageExtra)
 
     const frontMatter = context.page
 
@@ -339,7 +347,10 @@ export default class Markups {
       relativePathPrefix: getRelativePathPrefix(markupOutDir, fromPath, this.baseURL),
       // output-relative so page.url matches nav.json urls (getPageUrlRelativeToOutput),
       // otherwise `item.url == page.url` sidebar/active checks never fire
-      _url: getPageUrlRelativeToOutput(markupOut, this.markupOut)
+      _url: getPageUrlRelativeToOutput(markupOut, this.markupOut),
+      // source path relative to markup input (posix), so templates can build
+      // "edit on GitHub" links — .html output can't be reversed to .md reliably
+      _page: { inputPath: toPosix(relativePath) }
     }
 
     const shouldIndex = pageEntries && this.engine.indexableExtensions.has(path.extname(file))
@@ -520,12 +531,18 @@ export default class Markups {
     const pageEntries = shouldIndex ? [] : null
 
     buildCollectionPaginationData(collectionData)
+    // attach collection.taxonomies before any render so index/listing templates
+    // can link tag/category pages on page 1
+    buildTaxonomyData(collectionData)
 
     // must precede any rendering (incl. pagination pages) so every template
     // sees the current build's nav
     this.buildNavGlobal(markupIn, collectionData)
 
-    const collectionPromises = generateCollectionPaginationPages(collectionData, this.markupIn, this.markupOut, this.compileEntry.bind(this), this.baseURL)
+    const collectionPromises = [
+      ...generateCollectionPaginationPages(collectionData, this.markupIn, this.markupOut, this.compileEntry.bind(this), this.baseURL, this.siteData),
+      ...generateTaxonomyPages(collectionData, this.markupIn, this.markupOut, this.compileEntry.bind(this), this.baseURL, this.siteData)
+    ]
 
     await Promise.all(collectionPromises)
 
@@ -542,6 +559,20 @@ export default class Markups {
             isIndex: true
           })
         }
+
+        // taxonomy term pages: crawlable (sitemap) but isIndex, so out of the
+        // search index, llms.txt and nav — same as pagination pages
+        for (const tax of collection.taxonomies || []) {
+          for (const term of tax.terms) {
+            for (let p = 0; p < term.totalPages; p++) {
+              pageEntries.push({
+                url: p === 0 ? term.url : `${term.url}/${p + 1}`,
+                title: term.term,
+                isIndex: true
+              })
+            }
+          }
+        }
       }
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops",
   "description": "Straightforward, no-bullshit bundler for the web.",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "license": "MIT",
   "type": "module",
   "main": "poops.js",
@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "argoyle": "^1.0.0",
-    "book-of-spells": "^1.0.32",
+    "book-of-spells": "^1.3.0",
     "chokidar": "^3.5.3",
     "connect": "^3.7.0",
     "dayjs": "^1.11.19",

package/poops.js

@@ -3,7 +3,7 @@
 import chokidar from 'chokidar'
 import connect from 'connect'
 import Copy from './lib/copy.js'
-import runExec from './lib/exec.js'
+import runExec, { validateExec } from './lib/exec.js'
 import { pathExists, doesFileBelongToPath, pathContainsPathSegment, deriveWatchDirs } from './lib/utils/helpers.js'
 import http from 'node:http'
 import os from 'node:os'
@@ -246,6 +246,7 @@ function setupWatchers(config, modules) {
 
 // Main function 💩
 async function poops() {
+  validateExec(config)
   const styles = new Styles(config)
   const postcss = new PostCSS(config)
   const reactor = new Reactor(config)