poops 1.5.3 → 1.7.0

package/README.md

@@ -40,12 +40,13 @@ 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)
       - [highlight](#highlight)
     - [Custom Filters](#custom-filters)
-    - [Search Index, Sitemap & Navigation](#search-index-sitemap--navigation)
+    - [Search Index, Sitemap, llms.txt, robots.txt & Navigation](#search-index-sitemap-llmstxt-robotstxt--navigation)
   - [Images (optional)](#images-optional)
   - [Copy](#copy)
   - [Banner (optional)](#banner-optional)
@@ -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)
@@ -703,7 +705,7 @@ sort: date
 - `url` - the item's output path relative to the site root (e.g. `changelog/my-post.html`)
 - `title` - falls back to the file name if not set in front matter
 - `date` - falls back to the file's modification time if not set, with a build warning. Set a real `date` in front matter — mtime is meaningless on CI checkouts (git clone resets it), so undated posts will reshuffle between deploys.
-- `wordcount`, `fileName`, `filePath`, `collection`
+- `wordcount`, `excerpt` (first paragraph, plain text — a meta-description fallback), `fileName`, `filePath`, `collection`
 
 An item with `published: false` in its front matter is excluded from the collection and its page is not built.
 
@@ -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
@@ -908,6 +975,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 }}`
@@ -930,7 +999,55 @@ All filters are available in both engines. The only syntax difference is how arg
   - Nunjucks: `{{ someCodeVariable | highlight('javascript') }}`
   - Liquid: `{{ someCodeVariable | highlight: 'javascript' }}`
 
-- `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.
+- `og` — generates Open Graph (and a Twitter card) `<meta>` tags from a page's front matter and your `site` data, for link previews on social/chat platforms. Put it in your layout `<head>`. `og:type` auto-detects: `article` when the page has a `date`, otherwise `website`.
+  - Nunjucks: `{{ page | og(site) }}`
+  - Liquid: `{{ page | og: site }}`
+
+  Emits `og:title`, `og:description` (a missing `description` falls back to the page's auto-`excerpt`, then `site.description`), `og:type`, `og:url` (made absolute with `site.url`), `og:site_name` (from `site.title`), `og:locale` (`page.lang`/`site.lang`), `og:image` (`page.image`/`site.image`, made absolute), and `twitter:card` (`summary_large_image` when there's an image, else `summary`). For articles it adds `article:published_time`, `article:modified_time` and `article:author`. Attribute values are escaped. Set an `og` object in front matter to add or override any tag (e.g. `og:image:alt`, a fixed `twitter:card`):
+
+  ```yaml
+  ---
+  title: My post
+  date: 2026-01-01
+  image: static/cover.jpg
+  og:
+    "og:image:alt": Cover illustration
+  ---
+  ```
+
+- `canonical` — generates a `<link rel="canonical">` tag pointing at a page's authoritative absolute URL (`site.url` + the page's `url`), the dedup signal that stops query-string and duplicate URLs splitting your ranking. Put it in your layout `<head>`. Front matter `canonical` overrides the target — an absolute URL as-is, or a path resolved against `site.url` (for cross-domain or hand-picked canonicals). The homepage canonicals to the site root. Returns nothing without `site.url`.
+  - Nunjucks: `{{ page | canonical(site) }}`
+  - Liquid: `{{ page | canonical: site }}`
+
+- `jsonld` — generates a schema.org JSON-LD `<script type="application/ld+json">` block from a page's front matter and your `site` data, for GEO (Generative Engine Optimization) and structured data. Put it in your layout `<head>`. The `@type` auto-detects: `BlogPosting` when the page has a `date`, otherwise `WebPage`.
+  - Nunjucks: `{{ page | jsonld(site) }}`
+  - Liquid: `{{ page | jsonld: site }}`
+
+  It reads these front-matter fields when present: `title`, `description` (falls back to the page's auto-`excerpt`, then `site.description`), `url` (made absolute with `site.url`), `date` → `datePublished`, `updated` → `dateModified`, `author` (string or `{ name }`, falls back to `site.author`), `image`, `lang` → `inLanguage`, and `wordcount`. `publisher` comes from `site.title`; set `site.logo` to add a `publisher.logo` ImageObject (made absolute) — Google Article rich results require it. Front-matter values are escaped so they can't break out of the `<script>` tag.
+
+  On the homepage (a page with no `url`) it also emits a site-level `WebSite` block with `name` + `url`, which declares the site name for search results. On nested pages (a `url` with at least one folder) it auto-appends a `BreadcrumbList` block derived from URL depth — a Google breadcrumb rich result, no extra markup (needs `site.url` for the absolute item URLs). See the `breadcrumb` filter below for a visible trail from the same data.
+
+  For full control, set a `jsonld` object in front matter — its keys are merged over (and override) the generated defaults, including `@type`:
+
+  ```yaml
+  ---
+  title: How to brew coffee
+  date: 2026-01-01
+  jsonld:
+    "@type": HowTo
+    totalTime: PT5M
+  ---
+  ```
+
+  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.
+  - 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. 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" }}`
 
@@ -1026,11 +1143,11 @@ Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo
   {% endfor %}
   ```
 
-#### Search Index, Sitemap & Navigation
+#### Search Index, Sitemap, llms.txt, robots.txt & Navigation
 
-Poops can automatically generate a JSON search index, an XML sitemap and a navigation tree from your compiled pages. All are generated in a single pass during the markup compilation phase.
+Poops can automatically generate a JSON search index, an XML sitemap, an `llms.txt`, a `robots.txt` and a navigation tree from your compiled pages. All are generated in a single pass during the markup compilation phase.
 
-To enable, add `searchIndex`, `sitemap` and/or `nav` to your markup config:
+To enable, add `searchIndex`, `sitemap`, `llms`, `robots` and/or `nav` to your markup config:
 
 ```json
 {
@@ -1039,7 +1156,9 @@ To enable, add `searchIndex`, `sitemap` and/or `nav` to your markup config:
     "out": "dist",
     "options": {
       "searchIndex": "search-index.json",
-      "sitemap": "sitemap.xml"
+      "sitemap": "sitemap.xml",
+      "llms": "llms.txt",
+      "robots": "robots.txt"
     }
   }
 }
@@ -1058,6 +1177,13 @@ The string shorthand sets the output filename with default options. For more con
   },
   "sitemap": {
     "output": "sitemap.xml"
+  },
+  "llms": {
+    "output": "llms.txt",
+    "title": "My Site",
+    "description": "One-line summary of the site.",
+    "intro": "src/llms-intro.md",
+    "full": true
   }
 }
 ```
@@ -1092,9 +1218,31 @@ 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.
+
+Set `full` to also write a companion full-content file — every page's Markdown body concatenated into one file an LLM can ingest whole (the index is the link map; this is the corpus). `true` names it after `output` with a `-full` suffix (`llms.txt` → `llms-full.txt`, `ai.txt` → `ai-full.txt`); pass a string to set the path yourself. The file opens with a `# Full Documentation Archive for {title}` header, a one-line intro naming the site and a `> ` blockquote of the `description` so a whole-file ingest starts with context, then each page becomes an `# title` (its own leading H1 if it has one) + `URL:` line + body, joined by `---`. Set `fullIntro` to a Markdown file path (from the project root) to insert your own preamble after that header — the `full` counterpart to `intro` (inserted verbatim; a missing file warns and is skipped). Only `.md`/`.markdown` sources qualify (a `.njk`/`.liquid` source is template code, not prose); `noindex` and collection-index pages are dropped. Content is the Markdown **source**, so unrendered `{% raw %}{% … %}{% endraw %}` tags or shortcodes in a body pass through verbatim.
+
+**robots.txt** generates a `robots.txt`. The string shorthand writes an allow-all file (`User-agent: *`, empty `Disallow:`) with a `Sitemap:` line pointing at your generated sitemap — absolute when `site.url` is set. The object form takes `output`, `userAgent`, `allow`/`disallow` (a path or array of paths), and `sitemap` (an explicit URL, or `false` to omit the line):
+
+```json
+{
+  "robots": {
+    "output": "robots.txt",
+    "disallow": ["/admin", "/drafts"],
+    "sitemap": false
+  }
+}
+```
+
+Pages with `published: false` in their front matter are excluded from all outputs.
 
-Pages with `published: false` in their front matter are excluded from both outputs.
+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 %}
+```
 
 **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:
 
@@ -1206,6 +1354,40 @@ Liquid — a partial that recurses via `render` (save as `_partials/navtree.liqu
 {% render 'navtree', items: nav, relativePathPrefix: relativePathPrefix %}
 ```
 
+#### RSS / Atom feeds
+
+Generate a subscription feed for a [collection](#collections) — no hand-authored feed template. Each feed lists the collection's posts newest-first (by `date`), with the channel metadata taken from your `site` data.
+
+```json
+{
+  "markup": {
+    "in": "src/markup",
+    "out": "dist",
+    "options": {
+      "feed": { "collection": "blog", "output": "blog/feed.rss" }
+    }
+  }
+}
+```
+
+**Feed options:**
+
+- `collection` — the collection to build the feed from. Omit it to emit a feed for **every** collection.
+- `output` — the file to write. A bare filename (`feed.xml`, the default) is placed inside the collection's own folder (`blog/feed.xml`); a value with a slash is used as-is under the output directory.
+- `type` — `"rss"` (default) or `"atom"`.
+- `limit` — max items, newest first (default `20`).
+- `title` — channel title (default `"<Collection> | <site.title>"`).
+- `description` — channel description (default `site.description`).
+- `author`, `lang` — default to `site.author` / `site.lang`.
+
+Shorthand forms: `"feed": true` (or a filename string) emits an RSS feed for every collection; an array of the objects above generates several feeds at once (e.g. an RSS and an Atom for the same collection). Item `<description>` uses each post's `description`, falling back to its auto-`excerpt`; links, `guid`s and `<atom:link rel="self">` are made absolute with `site.url`. `robots: noindex` posts are excluded, matching the sitemap.
+
+Point browsers and readers at it from your layout `<head>`:
+
+```html
+<link rel="alternate" type="application/rss+xml" href="{{ site.url }}/blog/feed.rss">
+```
+
 ### Images (optional)
 
 Process and optimize images — compression, responsive size variants, format conversion (WebP/AVIF), crops and EXIF extraction — by running [poops-images](https://github.com/stamat/poops-images) as part of the build. This is what feeds the `{% image %}` tag, the `exif`/`images` filters and the `.poops-images-cache.json` compile cache described in [Custom Tags](#custom-tags) and [Custom Filters](#custom-filters).

package/lib/exec.js

@@ -0,0 +1,44 @@
+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)
+// stays in sync during dev instead of only running behind `poops -b && cmd`.
+// Sync + stdio:inherit so ordering is deterministic and output streams live;
+// cwd is the project root, matching how the compilers resolve their paths.
+// Returns true if any command failed, so build can fail the exit code; in watch
+// the failure is logged and swallowed so the watcher survives.
+// Stages: reactor, scripts, images, markup, styles (fires after PostCSS, so the
+// CSS is final), copy, and build (once, after the full initial pipeline).
+// `run` is injectable so tests exercise the branching without forking a shell.
+export default function runExec(config, cwd, stage, run = execSync) {
+  const hooks = config.exec && config.exec[stage]
+  if (!hooks) return false
+  let failed = false
+  for (const cmd of [hooks].flat()) {
+    try {
+      styledLog(`⚡ {dim}exec ${stage}:{/} ${cmd}`)
+      run(cmd, { cwd, stdio: 'inherit' })
+    } catch (err) {
+      failed = true
+      log({ tag: 'error', text: `exec ${stage} failed: ${cmd}` })
+    }
+  }
+  return failed
+}