poops 1.5.3 → 1.7.0

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 } from './helpers.js'
+import { replaceOutExtensions, getRelativePathPrefix, getPageUrlRelativeToOutput, parseFrontMatter, wordcount, excerpt, groupby } from './helpers.js'
 
 export function getSingleCollectionData(markupInDir, collectionName) {
   const collectionData = []
@@ -30,6 +31,7 @@ export function getSingleCollectionData(markupInDir, collectionName) {
       log({ tag: 'markup', warn: true, text: 'No date in front matter, falling back to file mtime:', link: file })
     }
     frontMatter.wordcount = wordcount(content)
+    frontMatter.excerpt = excerpt(content)
     frontMatter.fileName = path.basename(file)
     frontMatter.filePath = path.relative(process.cwd(), file)
     frontMatter.collection = collectionName
@@ -157,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
 
@@ -203,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)) {
@@ -222,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

@@ -3,9 +3,9 @@ import path from 'node:path'
 import { Liquid } from 'liquidjs'
 import { highlightCode } from '../highlight.js'
 import { marked, renderMarkdownCached } from '../renderer.js'
-import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc } from '../helpers.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 || '')))
@@ -115,6 +116,10 @@ export default class LiquidEngine {
       const outputDir = path.resolve(process.cwd(), markupOut)
       return listImages(dirPath, outputDir)
     })
+    engine.registerFilter('jsonld', (page, site) => buildJsonLd(page, site))
+    engine.registerFilter('og', (page, site) => buildOpenGraph(page, site))
+    engine.registerFilter('canonical', (page, site) => buildCanonical(page, site))
+    engine.registerFilter('breadcrumb', (page, site, prefix) => buildBreadcrumb(page, site, prefix))
     engine.registerFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
     engine.registerFilter('highlight', (code, lang) => {
       const highlighted = highlightCode(code, lang)
@@ -289,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

@@ -2,12 +2,12 @@ import fs from 'node:fs'
 import { globSync } from 'glob'
 import nunjucks from 'nunjucks'
 import path from 'node:path'
-import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc } from '../helpers.js'
+import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc, buildJsonLd, buildOpenGraph, buildCanonical, buildBreadcrumb } from '../helpers.js'
 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) => {
@@ -177,6 +178,10 @@ export default class NunjucksEngine {
       const outputDir = path.resolve(process.cwd(), markupOut)
       return listImages(dirPath, outputDir)
     })
+    env.addFilter('jsonld', (page, site) => new nunjucks.runtime.SafeString(buildJsonLd(page, site)))
+    env.addFilter('og', (page, site) => new nunjucks.runtime.SafeString(buildOpenGraph(page, site)))
+    env.addFilter('canonical', (page, site) => new nunjucks.runtime.SafeString(buildCanonical(page, site)))
+    env.addFilter('breadcrumb', (page, site, prefix) => new nunjucks.runtime.SafeString(buildBreadcrumb(page, site, prefix)))
     env.addFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
     env.addFilter('highlight', (code, lang) => {
       const highlighted = highlightCode(code, lang)
@@ -337,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))
   }
 }