poops 1.5.3 → 1.7.0

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'
 
@@ -68,6 +69,26 @@ export function wordcount(text) {
   return words ? words.length : 0
 }
 
+// First prose paragraph of content as plain text, for a meta-description
+// fallback when front matter has none. Splits on blank lines, skips leading
+// headings and HTML comments, strips markdown/HTML like wordcount, then caps at
+// ~160 chars (search-snippet size) on a word boundary.
+// ponytail: content-level split; a leading code fence or raw template block
+// could still slip in — refine the skip list if a snippet looks wrong.
+export function excerpt(text, max = 160) {
+  if (!text) return ''
+  for (const block of text.split(/\n\s*\n/)) {
+    const trimmed = block.trim()
+    if (!trimmed || /^#{1,6}\s/.test(trimmed) || trimmed.startsWith('<!--')) continue
+    // eslint-disable-next-line no-useless-escape
+    const stripped = trimmed.replace(/<[^>]*>/g, ' ').replace(/[#*_`~\[\]()>|{}\\]/g, ' ').replace(/\s+/g, ' ').trim()
+    if (!stripped) continue
+    if (stripped.length <= max) return stripped
+    return stripped.slice(0, max).replace(/\s+\S*$/, '').trim() + '…'
+  }
+  return ''
+}
+
 // marked HTML-encodes quotes/brackets in template tags it treats as prose,
 // breaking string args like groupby("date"). Decode entities inside {{ }} / {% %}
 // after markdown, before the template engine parses. Decode &amp; last so
@@ -111,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)) {
@@ -123,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 }))
@@ -324,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')
 }
 
@@ -371,3 +406,275 @@ export function buildImageTag(imagePath, prefix, kwargs, getOutputDir) {
   }
   return `<img ${attrs.join(' ')}>`
 }
+
+// Serializes a JSON-LD data object into a <script> block. Drops empty top-level
+// keys (GEO parsers ignore them) and neutralizes `<`, `>`, `&` so front-matter
+// values can't break out of the <script> or inject entities.
+function jsonLdScript(data) {
+  for (const k of Object.keys(data)) {
+    if (data[k] === undefined || data[k] === null || data[k] === '') delete data[k]
+  }
+  const json = JSON.stringify(data).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026')
+  return `<script type="application/ld+json">${json}</script>`
+}
+
+// Turns a URL segment (or a filename) into a human title for a breadcrumb crumb
+// 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 humanize(String(seg).replace(/\.[a-z0-9]+$/i, ''))
+}
+
+// Builds a breadcrumb trail — a { name, path } array from the site root down to
+// the page — derived purely from URL depth (no nav tree needed). Intermediate
+// path segments are humanized (they have no page object); the last crumb is the
+// page's own title. The home crumb (site root) leads unless disabled.
+// `path` is the site-root-relative URL (page.url form: '' for home, no domain);
+// each consumer prefixes it — the JSON-LD with `site.url` (absolute, required by
+// Google), the visible filter with `relativePathPrefix` (so local-dev links stay
+// on localhost instead of jumping to the production domain).
+// Config: `site.breadcrumb` overlaid by front-matter `page.breadcrumb` (object
+// with `home` boolean / `homeLabel` string); `breadcrumb: false` on either
+// disables it. Returns [] for the homepage, a single-crumb trail, or when
+// disabled — every caller renders nothing on [].
+export function breadcrumbCrumbs(page, site = {}) {
+  page = page || {}
+  site = site || {}
+  if (page.breadcrumb === false || site.breadcrumb === false) return []
+
+  const cfg = { home: true, homeLabel: 'Home' }
+  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
+
+  const parts = rawUrl.split('/').filter(Boolean)
+  const crumbs = []
+  if (cfg.home) crumbs.push({ name: cfg.homeLabel, path: '' })
+
+  // Every part but the last is an ancestor directory; accumulate its path.
+  let acc = ''
+  for (let i = 0; i < parts.length - 1; i++) {
+    acc = acc ? `${acc}/${parts[i]}` : parts[i]
+    crumbs.push({ name: humanizeSegment(parts[i]), path: acc })
+  }
+  crumbs.push({ name: page.title || humanizeSegment(parts[parts.length - 1]), path: rawUrl })
+
+  // A lone crumb (e.g. home off, top-level page) is not a trail.
+  return crumbs.length >= 2 ? crumbs : []
+}
+
+// BreadcrumbList JSON-LD <script> for a page's position in the site hierarchy —
+// a Google rich result. Absolute item URLs are mandatory, so it's skipped
+// without `site.url` (like canonical). Names come from front matter / segments,
+// so jsonLdScript escapes them for the <script> context.
+function breadcrumbJsonLd(page, site) {
+  if (!(site && site.url)) return ''
+  const crumbs = breadcrumbCrumbs(page, site)
+  if (crumbs.length < 2) return ''
+  const baseUrl = String(site.url).replace(/\/+$/, '')
+  const abs = (p) => {
+    const rel = String(p).replace(/^\/+/, '')
+    return rel ? `${baseUrl}/${rel}` : baseUrl
+  }
+  return jsonLdScript({
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: crumbs.map((c, i) => ({
+      '@type': 'ListItem',
+      position: i + 1,
+      name: c.name,
+      item: abs(c.path)
+    }))
+  })
+}
+
+// Builds a visible <nav> breadcrumb trail for display in the page body (blog
+// posts, nested pages). Same crumbs as the JSON-LD, but hrefs are relative:
+// `prefix` is the page's `relativePathPrefix`, so links resolve against the
+// current output location (localhost in dev, the deployed path in prod) exactly
+// like the nav/header links — never the absolute production domain. The last
+// crumb renders as aria-current text (the current page is not a link). Returns
+// '' when there's no trail. Names/paths land in attributes, so they're escaped.
+export function buildBreadcrumb(page, site = {}, prefix = '') {
+  const crumbs = breadcrumbCrumbs(page, site)
+  if (crumbs.length < 2) return ''
+  const items = crumbs.map((c, i) => {
+    const name = escapeAttr(c.name)
+    if (i === crumbs.length - 1) return `<li><span aria-current="page">${name}</span></li>`
+    return `<li><a href="${escapeAttr(prefix + c.path)}">${name}</a></li>`
+  })
+  return `<nav class="breadcrumb" aria-label="Breadcrumb"><ol>${items.join('')}</ol></nav>`
+}
+
+// Builds a schema.org JSON-LD <script> block from a page's front matter + site
+// data, for GEO / structured data (generative engines lean on schema.org to
+// understand a page). @type auto-detects — BlogPosting when the page has a
+// `date`, else WebPage. Article-only fields (headline, dates, author,
+// wordCount) are added only for the article case. The publisher Organization
+// gains a `logo` ImageObject when `site.logo` is set — Google Article rich
+// results require it. On the homepage (page has no `url`) a second `WebSite`
+// block is emitted, declaring the site name for search results.
+// Anything in `page.jsonld` (an object) is merged over the generated defaults,
+// so a page can add or replace any field — including @type — as a full escape
+// hatch. Values come from front matter, so the JSON is escaped for a <script>
+// context to prevent a `</script>` break-out (XSS).
+export function buildJsonLd(page, site = {}) {
+  page = page || {}
+  site = site || {}
+
+  const baseUrl = site.url ? String(site.url).replace(/\/+$/, '') : ''
+  const absUrl = (u) => {
+    if (!u) return undefined
+    if (/^https?:\/\//i.test(u)) return u
+    return baseUrl ? `${baseUrl}/${String(u).replace(/^\/+/, '')}` : u
+  }
+
+  const author = (page.author && typeof page.author === 'object' ? page.author.name : page.author) || site.author
+  const publisherName = site.title || site.name
+
+  let publisher
+  if (publisherName) {
+    publisher = { '@type': 'Organization', name: publisherName }
+    const logo = absUrl(site.logo)
+    if (logo) publisher.logo = { '@type': 'ImageObject', url: logo }
+  }
+
+  const isArticle = !!page.date
+  const data = {
+    '@context': 'https://schema.org',
+    '@type': isArticle ? 'BlogPosting' : 'WebPage',
+    name: page.title,
+    description: page.description || page.excerpt || site.description,
+    url: absUrl(page.url),
+    inLanguage: page.lang || site.lang,
+    image: absUrl(page.image || site.image),
+    publisher
+  }
+
+  if (isArticle) {
+    data.headline = page.title
+    data.datePublished = page.date
+    data.dateModified = page.updated || page.date
+    if (author) data.author = { '@type': 'Person', name: author }
+    if (page.wordcount) data.wordCount = page.wordcount
+  }
+
+  // page.jsonld extends/overrides. Shallow merge — nested schema is rare and
+  // the escape hatch is meant for whole-key replacement.
+  if (page.jsonld && typeof page.jsonld === 'object') Object.assign(data, page.jsonld)
+
+  const blocks = [jsonLdScript(data)]
+
+  // Homepage (no page.url) gets a site-level WebSite block — defines the site
+  // name for search results.
+  if (!page.url && baseUrl) {
+    blocks.push(jsonLdScript({
+      '@context': 'https://schema.org',
+      '@type': 'WebSite',
+      name: publisherName,
+      url: baseUrl,
+      inLanguage: page.lang || site.lang
+    }))
+  }
+
+  // Nested pages get a BreadcrumbList block (zero-config rich result).
+  const breadcrumb = breadcrumbJsonLd(page, site)
+  if (breadcrumb) blocks.push(breadcrumb)
+
+  return blocks.join('\n')
+}
+
+// Builds Open Graph (+ a Twitter card) <meta> tags from a page's front matter
+// and site data, for link previews on social/chat platforms. og:type is
+// `article` when the page has a `date`, else `website`. Twitter tags fall back
+// to the og:* values on most crawlers, so only `twitter:card` is emitted. A
+// `page.og` object merges over (and overrides) the defaults — set any extra
+// property there, e.g. `og:image:alt` or a fixed `twitter:card`. Values come
+// from front matter and land in attributes, so they're escaped (escapeAttr).
+export function buildOpenGraph(page, site = {}) {
+  page = page || {}
+  site = site || {}
+
+  const baseUrl = site.url ? String(site.url).replace(/\/+$/, '') : ''
+  const absUrl = (u) => {
+    if (!u) return undefined
+    if (/^https?:\/\//i.test(u)) return u
+    return baseUrl ? `${baseUrl}/${String(u).replace(/^\/+/, '')}` : u
+  }
+
+  const author = (page.author && typeof page.author === 'object' ? page.author.name : page.author) || site.author
+  const isArticle = !!page.date
+  const image = absUrl(page.image || site.image)
+
+  const tags = {
+    'og:title': page.title || site.title,
+    'og:description': page.description || page.excerpt || site.description,
+    'og:type': isArticle ? 'article' : 'website',
+    'og:url': absUrl(page.url),
+    'og:site_name': site.title,
+    'og:locale': page.lang || site.lang,
+    'og:image': image,
+    'twitter:card': image ? 'summary_large_image' : 'summary'
+  }
+
+  if (isArticle) {
+    tags['article:published_time'] = page.date
+    tags['article:modified_time'] = page.updated || page.date
+    if (author) tags['article:author'] = author
+  }
+
+  // page.og extends/overrides. Shallow — one flat property:content map.
+  if (page.og && typeof page.og === 'object') Object.assign(tags, page.og)
+
+  const lines = []
+  for (const [prop, val] of Object.entries(tags)) {
+    if (val === undefined || val === null || val === '') continue
+    // Twitter's spec uses name=, Open Graph uses property=.
+    const attr = prop.startsWith('twitter:') ? 'name' : 'property'
+    lines.push(`<meta ${attr}="${escapeAttr(prop)}" content="${escapeAttr(val)}">`)
+  }
+  return lines.join('\n')
+}
+
+// Builds a `<link rel="canonical">` tag — the dedup signal that names a page's
+// authoritative URL. The href is absolute (needs `site.url`): front matter
+// `canonical` wins (an absolute URL as-is, or a path resolved against
+// `site.url`), else the page's own `url`. Homepage (`url` === '') canonicals to
+// the site root. Returns '' when no absolute URL can be formed (no site.url).
+export function buildCanonical(page, site = {}) {
+  page = page || {}
+  site = site || {}
+
+  const baseUrl = site.url ? String(site.url).replace(/\/+$/, '') : ''
+  const abs = (u) => {
+    if (u == null) return ''
+    if (/^https?:\/\//i.test(u)) return u
+    if (!baseUrl) return ''
+    const rel = String(u).replace(/^\/+/, '')
+    return rel ? `${baseUrl}/${rel}` : baseUrl
+  }
+
+  // The root index page has no `url` (poops leaves it unset), so a nullish url
+  // means the homepage → canonical to the site root.
+  const target = page.canonical != null ? page.canonical : (page.url != null ? page.url : '')
+  const href = abs(target)
+  return href ? `<link rel="canonical" href="${escapeAttr(href)}">` : ''
+}