poops 1.2.3 → 1.3.0

package/lib/markup/helpers.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import yaml from 'yaml'
+import { toPosix } from '../utils/helpers.js'
+import { getImageEntry } from './image-cache.js'
 
 const frontMatterCache = new Map()
 
@@ -81,6 +83,25 @@ export function decodeTemplateEntities(html) {
   )
 }
 
+// Builds a flat H2/H3 table of contents from rendered HTML, reading the ids
+// the markdown heading renderer emits so TOC links always match the anchors.
+// H3s carry a `toc-h3` class for indentation — no nested <ul>, so leading H3s
+// (no parent H2) stay valid. Heading text is already entity-encoded by marked,
+// so it's spliced in as-is (re-escaping would double-encode &amp;).
+export function renderToc(html) {
+  if (!html) return ''
+  const re = /<h([23])\b[^>]*\sid="([^"]*)"[^>]*>([\s\S]*?)<\/h\1>/gi
+  let items = ''
+  let match
+  while ((match = re.exec(html)) !== null) {
+    const text = match[3].replace(/<[^>]*>/g, '').trim()
+    if (!match[2] || !text) continue
+    items += `<li class="toc-h${match[1]}"><a href="#${match[2]}">${text}</a></li>`
+  }
+  if (!items) return ''
+  return `<nav class="toc" aria-label="On this page"><ul>${items}</ul></nav>`
+}
+
 export function groupby(arr, key, datePart) {
   if (!Array.isArray(arr)) return []
 
@@ -107,7 +128,90 @@ export function groupby(arr, key, datePart) {
 
 const FORMAT_PRIORITY = ['avif', 'webp']
 
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// jpeg sources compile to .jpg variants — same format for grouping purposes
+function normalizeFormat(fmt) {
+  return fmt === 'jpeg' ? 'jpg' : fmt
+}
+
+// Pick best format for srcset (highest priority format that has variants)
+// and the middle-sized original-format variant as the src fallback.
+function pickSrcsetAndSrc(variants, originalExt) {
+  originalExt = normalizeFormat(originalExt)
+  variants.sort((a, b) => a.width - b.width)
+
+  const availableFormats = new Set(variants.map(v => normalizeFormat(v.format)))
+  let srcsetFormat = null
+  for (const fmt of FORMAT_PRIORITY) {
+    if (availableFormats.has(fmt)) {
+      srcsetFormat = fmt
+      break
+    }
+  }
+  if (!srcsetFormat && availableFormats.has(originalExt)) {
+    srcsetFormat = originalExt
+  }
+  if (!srcsetFormat && availableFormats.size > 0) {
+    srcsetFormat = [...availableFormats][0]
+  }
+
+  const srcsetVariants = srcsetFormat ? variants.filter(v => normalizeFormat(v.format) === srcsetFormat) : []
+
+  const originalVariants = variants.filter(v => normalizeFormat(v.format) === originalExt)
+  let srcVariant = null
+  if (originalVariants.length > 0) {
+    srcVariant = originalVariants[Math.floor((originalVariants.length - 1) / 2)]
+  } else if (srcsetVariants.length > 0) {
+    srcVariant = srcsetVariants[Math.floor((srcsetVariants.length - 1) / 2)]
+  }
+
+  return { srcVariant, srcsetVariants }
+}
+
+// Variant discovery from the poops-images compile cache: exact output paths
+// and dimensions, no directory scan. Only `{name}-{width}w.{ext}` outputs are
+// srcset material — named sizes (`-thumb-200w`) and preprocessed outputs
+// (`-blurred-...`) are crops or effects with their own aspect ratios.
+function discoverImageVariantsFromCache(imagePath, outputDir) {
+  const found = getImageEntry(imagePath, outputDir)
+  if (!found) return null
+
+  const { entry, prefixDir } = found
+  const parsed = path.parse(imagePath)
+  const originalExt = parsed.ext.replace('.', '')
+  const variantPattern = new RegExp(`^${escapeRegExp(parsed.name)}-(\\d+)w\\.([a-z0-9]+)$`)
+  const basePattern = new RegExp(`^${escapeRegExp(parsed.name)}\\.([a-z0-9]+)$`)
+
+  const variants = []
+  let base = null
+  for (const out of entry.outputs || []) {
+    const file = path.posix.basename(toPosix(out.path))
+    const sitePath = prefixDir ? toPosix(path.join(prefixDir, out.path)) : toPosix(out.path)
+    let match = file.match(variantPattern)
+    if (match) {
+      variants.push({ path: sitePath, width: parseInt(match[1], 10), height: out.height, format: match[2] })
+      continue
+    }
+    match = file.match(basePattern)
+    if (match && !base) {
+      base = { path: sitePath, width: out.width, height: out.height }
+    }
+  }
+
+  const { srcVariant, srcsetVariants } = pickSrcsetAndSrc(variants, originalExt)
+  // Base output fixes the src extension when the source was converted (heic → jpg)
+  const src = srcVariant || base || { path: imagePath }
+
+  return { src: src.path, variants: srcsetVariants, width: src.width, height: src.height }
+}
+
 export function discoverImageVariants(imagePath, outputDir) {
+  const fromCache = discoverImageVariantsFromCache(imagePath, outputDir)
+  if (fromCache) return fromCache
+
   const parsed = path.parse(imagePath)
   const dir = path.join(outputDir, parsed.dir)
   const baseName = parsed.name
@@ -128,44 +232,14 @@ export function discoverImageVariants(imagePath, outputDir) {
     const [, name, widthStr, format] = match
     if (name !== baseName) continue
     variants.push({
-      path: path.join(parsed.dir, file),
+      path: toPosix(path.join(parsed.dir, file)),
       width: parseInt(widthStr, 10),
       format
     })
   }
 
-  variants.sort((a, b) => a.width - b.width)
-
-  // Pick best format for srcset: highest priority format that has variants
-  const availableFormats = new Set(variants.map(v => v.format))
-  let srcsetFormat = null
-  for (const fmt of FORMAT_PRIORITY) {
-    if (availableFormats.has(fmt)) {
-      srcsetFormat = fmt
-      break
-    }
-  }
-  if (!srcsetFormat && availableFormats.has(originalExt)) {
-    srcsetFormat = originalExt
-  }
-  if (!srcsetFormat && availableFormats.size > 0) {
-    srcsetFormat = [...availableFormats][0]
-  }
-
-  const srcsetVariants = srcsetFormat ? variants.filter(v => v.format === srcsetFormat) : []
-
-  // Pick middle-sized variant in original format for src fallback
-  const originalVariants = variants.filter(v => v.format === originalExt)
-  let src = imagePath
-  if (originalVariants.length > 0) {
-    const mid = Math.floor((originalVariants.length - 1) / 2)
-    src = originalVariants[mid].path
-  } else if (srcsetVariants.length > 0) {
-    const mid = Math.floor((srcsetVariants.length - 1) / 2)
-    src = srcsetVariants[mid].path
-  }
-
-  return { src, variants: srcsetVariants }
+  const { srcVariant, srcsetVariants } = pickSrcsetAndSrc(variants, originalExt)
+  return { src: srcVariant ? srcVariant.path : imagePath, variants: srcsetVariants }
 }
 
 export function replaceOutExtensions(outputPath) {
@@ -200,8 +274,9 @@ export function getRelativePathPrefix(outputDir, fromDir, baseURL) {
     return baseURL.endsWith('/') ? baseURL : baseURL + '/'
   }
 
-  let relativeDir = path.relative(process.cwd(), outputDir)
-  const fromRelativeDir = fromDir ? path.relative(process.cwd(), fromDir) : ''
+  // getUpDirPrefix splits on `/`, so normalize away native separators
+  let relativeDir = toPosix(path.relative(process.cwd(), outputDir))
+  const fromRelativeDir = fromDir ? toPosix(path.relative(process.cwd(), fromDir)) : ''
 
   if (fromRelativeDir && relativeDir.startsWith(fromRelativeDir)) {
     relativeDir = relativeDir.replace(fromRelativeDir, '')
@@ -212,10 +287,62 @@ export function getRelativePathPrefix(outputDir, fromDir, baseURL) {
 
 export function getPageUrl(outputPath) {
   outputPath = replaceOutExtensions(outputPath)
-  return /index\.[a-z]+$/.test(path.basename(outputPath)) ? path.relative(process.cwd(), path.dirname(outputPath)) : path.relative(process.cwd(), outputPath)
+  return toPosix(/index\.[a-z]+$/.test(path.basename(outputPath)) ? path.relative(process.cwd(), path.dirname(outputPath)) : path.relative(process.cwd(), outputPath))
 }
 
 export function getPageUrlRelativeToOutput(outputPath, outputDir) {
   const pageUrl = getPageUrl(outputPath)
-  return path.relative(outputDir, pageUrl)
+  return toPosix(path.relative(outputDir, pageUrl))
+}
+
+export function escapeAttr(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+export function buildPaginationTag(pagination, prefix = '') {
+  const totalPages = Number(pagination && pagination.totalPages) || 1
+  if (totalPages <= 1) return ''
+
+  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>`)
+  return parts.join('\n')
+}
+
+// Shared by the nunjucks and liquid `image` tags — attribute values may come
+// from front-matter/user data, so they are escaped here, once for both engines.
+export function buildImageTag(imagePath, prefix, kwargs, getOutputDir) {
+  const alt = (kwargs && kwargs.alt) || ''
+  const loading = (kwargs && kwargs.loading) || 'lazy'
+  const isSvg = imagePath.endsWith('.svg')
+  const attrs = [`alt="${escapeAttr(alt)}"`]
+
+  if (isSvg) {
+    attrs.unshift(`src="${escapeAttr(prefix + imagePath)}"`)
+  } else {
+    const { src, variants, width, height } = discoverImageVariants(imagePath, getOutputDir())
+    const sizes = (kwargs && kwargs.sizes) || '100vw'
+    attrs.unshift(`src="${escapeAttr(prefix + src)}"`)
+    if (width && height && !(kwargs && (kwargs.width || kwargs.height))) {
+      attrs.push(`width="${width}"`, `height="${height}"`)
+    }
+    if (variants.length > 0) {
+      const srcsetVal = variants.map(v => `${prefix}${v.path} ${v.width}w`).join(', ')
+      attrs.push(`srcset="${escapeAttr(srcsetVal)}"`)
+      attrs.push(`sizes="${escapeAttr(sizes)}"`)
+    }
+  }
+
+  attrs.push(`loading="${escapeAttr(loading)}"`)
+  if (kwargs) {
+    const skip = new Set(['alt', 'sizes', 'loading'])
+    for (const [key, val] of Object.entries(kwargs)) {
+      // `__keywords` is nunjucks' kwargs marker, never a real attribute
+      if (key.startsWith('__') || skip.has(key)) continue
+      attrs.push(`${key}="${escapeAttr(val)}"`)
+    }
+  }
+  return `<img ${attrs.join(' ')}>`
 }

package/lib/markup/image-cache.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { toPosix } from '../utils/helpers.js'
+
+// Compile cache written by poops-images (https://github.com/stamat/poops-images)
+// next to the images it generates. Holds exact output paths, dimensions and EXIF.
+const CACHE_FILENAME = '.poops-images-cache.json'
+
+const cacheFileCache = new Map()
+
+function readCacheFile(cachePath) {
+  let stat
+  try {
+    stat = fs.statSync(cachePath)
+  } catch {
+    return null
+  }
+
+  const cached = cacheFileCache.get(cachePath)
+  if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+    return cached.data
+  }
+
+  let data = null
+  try {
+    data = JSON.parse(fs.readFileSync(cachePath, 'utf8'))
+  } catch {
+    return null
+  }
+
+  cacheFileCache.set(cachePath, { mtimeMs: stat.mtimeMs, size: stat.size, data })
+  return data
+}
+
+export function clearImageCache() {
+  cacheFileCache.clear()
+}
+
+// Finds the poops-images cache entry for a site-relative image path.
+// Walks from the image's directory up to outputDir, since the cache file sits
+// at the root of the images output dir, which may be a subdirectory of the
+// site output (e.g. dist/images/.poops-images-cache.json).
+// Returns { entry, prefixDir } where prefixDir is the cache dir relative to
+// outputDir (output paths in the cache are relative to the cache dir), or null.
+export function getImageEntry(imagePath, outputDir) {
+  const root = path.resolve(outputDir)
+  let dir = path.resolve(root, path.dirname(imagePath))
+  if (!dir.startsWith(root)) return null
+
+  const target = toPosix(path.relative(root, path.resolve(root, imagePath)))
+  const targetNoExt = target.replace(/\.[^./]+$/, '')
+
+  while (true) {
+    const data = readCacheFile(path.join(dir, CACHE_FILENAME))
+    if (data && data.entries) {
+      const prefixDir = toPosix(path.relative(root, dir))
+      const rel = prefixDir ? target.slice(prefixDir.length + 1) : target
+      let entry = data.entries[rel]
+      if (!entry) {
+        // Output extension may differ from the source key (heic → jpg, jpeg → jpg)
+        const relNoExt = prefixDir ? targetNoExt.slice(prefixDir.length + 1) : targetNoExt
+        for (const [key, value] of Object.entries(data.entries)) {
+          if (key.replace(/\.[^./]+$/, '') === relNoExt) {
+            entry = value
+            break
+          }
+        }
+      }
+      if (entry) return { entry, prefixDir }
+    }
+    if (dir === root) return null
+    dir = path.dirname(dir)
+  }
+}
+
+export function getImageExif(imagePath, outputDir) {
+  const found = getImageEntry(imagePath, outputDir)
+  return (found && found.entry.exif) || null
+}
+
+// Lists all cache entries under a site-relative directory, gallery-ready:
+// site-relative paths, `date` flattened from EXIF (file mtime fallback) so
+// engine-native sort and the groupby filter work without touching nested exif.
+export function listImages(dirPath, outputDir) {
+  const root = path.resolve(outputDir)
+  const clean = toPosix(dirPath || '').replace(/^\/+|\/+$/g, '')
+  let dir = path.resolve(root, clean)
+  if (!dir.startsWith(root)) return []
+
+  while (true) {
+    const data = readCacheFile(path.join(dir, CACHE_FILENAME))
+    if (data && data.entries) {
+      const prefixDir = toPosix(path.relative(root, dir))
+      const scope = toPosix(path.relative(dir, path.resolve(root, clean)))
+      const sitePath = (p) => prefixDir ? toPosix(path.join(prefixDir, p)) : toPosix(p)
+
+      const images = []
+      for (const [key, entry] of Object.entries(data.entries)) {
+        if (scope && !key.startsWith(scope + '/')) continue
+        images.push({
+          path: sitePath(key),
+          width: entry.width,
+          height: entry.height,
+          date: (entry.exif && entry.exif.dateTime) || (entry.mtime ? new Date(entry.mtime).toISOString() : null),
+          exif: entry.exif || null,
+          outputs: (entry.outputs || []).map(o => ({ ...o, path: sitePath(o.path) }))
+        })
+      }
+      return images
+    }
+    if (dir === root) return []
+    dir = path.dirname(dir)
+  }
+}

package/lib/markup/indexer.js

@@ -116,7 +116,9 @@ export function generateSearchIndex(pageEntries, outputDir, config) {
 
   entries = applyGlobalFrequencyCeiling(entries, config.globalFrequencyCeiling)
 
-  const outputPath = path.join(process.cwd(), outputDir, config.output)
+  // resolve, not join: outputDir may be absolute (join would mangle it,
+  // e.g. cross-drive temp dirs on Windows)
+  const outputPath = path.resolve(process.cwd(), outputDir, config.output)
   fs.writeFileSync(outputPath, JSON.stringify(entries, null, 2))
   log({ tag: 'indexer', text: 'Generated search index:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
 }
@@ -143,12 +145,166 @@ export function generateSitemap(pageEntries, outputDir, siteUrl, config) {
 
   xml += '</urlset>\n'
 
-  const outputPath = path.join(process.cwd(), outputDir, config.output)
+  // resolve, not join: outputDir may be absolute (join would mangle it,
+  // e.g. cross-drive temp dirs on Windows)
+  const outputPath = path.resolve(process.cwd(), outputDir, config.output)
   fs.writeFileSync(outputPath, xml)
   log({ tag: 'indexer', text: 'Generated sitemap:', 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
+}
+
+// Applies the `collections` option (true | false | ["name"] | "index") on top
+// of the base exclusions (nav:false, and isIndex pages which are collection
+// landing/pagination). "index" is the exception that re-admits each
+// collection's first landing page as a single leaf.
+function navFilterEntries(pageEntries, collectionsOpt) {
+  const mode = collectionsOpt === undefined ? true : collectionsOpt
+  const allowlist = Array.isArray(mode) ? new Set(mode) : null
+  const result = []
+
+  for (const e of pageEntries) {
+    if (e.nav === false) continue
+
+    if (e.isIndex) {
+      // collection landing (url === name, no slash) kept only in "index" mode;
+      // 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) })
+      }
+      continue
+    }
+
+    if (e.collection != null) {
+      if (mode === false || mode === 'index') continue
+      if (allowlist && !allowlist.has(e.collection)) continue
+    }
+    result.push(e)
+  }
+
+  return result
+}
+
+function insertNavNode(root, entry) {
+  let cursor = root
+  for (const seg of entry.url.split('/')) {
+    if (!cursor.children.has(seg)) {
+      cursor.children.set(seg, { segment: seg, children: new Map() })
+    }
+    cursor = cursor.children.get(seg)
+  }
+  cursor.hasPage = true
+  cursor.url = entry.url
+  cursor.title = navNodeTitle(entry)
+  if (entry.order != null) cursor.order = entry.order
+}
+
+function getNavNode(root, urlPath) {
+  let cursor = root
+  for (const seg of urlPath.split('/')) {
+    cursor = cursor.children.get(seg)
+    if (!cursor) return null
+  }
+  return cursor
+}
+
+function sortNavSiblings(nodes) {
+  nodes.sort((a, b) => {
+    const oa = a.order != null ? a.order : Infinity
+    const ob = b.order != null ? b.order : Infinity
+    if (oa !== ob) return oa - ob
+    return String(a.title).localeCompare(String(b.title))
+  })
+}
+
+// Post-order: children are serialized (and thus order-resolved) before the
+// parent, so a virtual parent can borrow its first child's order.
+function serializeNavNode(node) {
+  const children = [...node.children.values()].map(serializeNavNode)
+  sortNavSiblings(children)
+
+  const out = { title: node.title != null ? node.title : humanizeSegment(node.segment) }
+  if (node.url != null) out.url = node.url
+
+  let order = node.order
+  if (order == null && !node.hasPage && children.length) order = children[0].order
+  if (order != null) out.order = order
+
+  if (children.length) out.children = children
+  return out
+}
+
+export function buildNavTree(pageEntries, config = {}) {
+  const { collections, home, root } = config
+  let entries = navFilterEntries(pageEntries, collections)
+
+  if (root != null) {
+    const prefix = root + '/'
+    entries = entries.filter(e => e.url === root || e.url.startsWith(prefix))
+  } else if (home === false) {
+    entries = entries.filter(e => e.url !== '')
+  }
+
+  const tree = { children: new Map() }
+  let homeEntry = null
+  for (const entry of entries) {
+    // root index page (url '') can't be segment-split — it would corrupt the
+    // tree; handle it as a top-level leaf instead
+    if (entry.url === '') { homeEntry = entry; continue }
+    insertNavNode(tree, entry)
+  }
+
+  // root scoping: emit the section's children unwrapped to the top level, with
+  // the section's own index page (if any) pinned first as the overview link
+  if (root != null) {
+    const rootNode = getNavNode(tree, root)
+    if (!rootNode) return []
+    const top = [...rootNode.children.values()].map(serializeNavNode)
+    sortNavSiblings(top)
+    if (rootNode.hasPage) {
+      const overview = { title: rootNode.title, url: rootNode.url }
+      if (rootNode.order != null) overview.order = rootNode.order
+      top.unshift(overview)
+    }
+    return top
+  }
+
+  const top = [...tree.children.values()].map(serializeNavNode)
+  if (homeEntry) {
+    const node = { title: navNodeTitle(homeEntry), url: '' }
+    if (homeEntry.order != null) node.order = homeEntry.order
+    top.push(node)
+  }
+  sortNavSiblings(top)
+  return top
+}
+
+export function generateNav(pageEntries, outputDir, config) {
+  config = normalizeConfig(config)
+  if (!config) return
+
+  const tree = buildNavTree(pageEntries, config)
+
+  // resolve, not join: outputDir may be absolute (join would mangle it,
+  // e.g. cross-drive temp dirs on Windows)
+  const outputPath = path.resolve(process.cwd(), outputDir, config.output)
+  fs.writeFileSync(outputPath, JSON.stringify(tree, null, 2))
+  log({ tag: 'indexer', text: 'Generated nav:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
+}
+
 export function generateIndexFiles(pageEntries, outputDir, siteUrl, config) {
   generateSearchIndex(pageEntries, outputDir, config.searchIndex)
   generateSitemap(pageEntries, outputDir, siteUrl, config.sitemap)
+  generateNav(pageEntries, outputDir, config.nav)
 }

package/lib/markup/renderer.js

@@ -0,0 +1,60 @@
+import { Marked } from 'marked'
+import { slugify } from 'book-of-spells'
+import { highlightRenderer, highlightCode } from './highlight.js'
+import { decodeTemplateEntities } from './helpers.js'
+
+const RAW_BLOCK_RE = /\{%-?\s*raw\s*-?%\}([\s\S]*?)\{%-?\s*endraw\s*-?%\}/g
+
+// Applies `outside` to the text between {% raw %} blocks and `inside` to each
+// block's inner content, re-emitting the delimiters untouched so the template
+// engine still sees them. The two places that would otherwise mangle raw
+// content route through this: fence highlighting and entity decoding.
+function mapRawSegments(str, outside, inside) {
+  RAW_BLOCK_RE.lastIndex = 0
+  let out = ''
+  let last = 0
+  for (const m of str.matchAll(RAW_BLOCK_RE)) {
+    out += outside(str.slice(last, m.index))
+    out += `{% raw %}${inside(m[1])}{% endraw %}`
+    last = m.index + m[0].length
+  }
+  return out + outside(str.slice(last))
+}
+
+// The marked renderer used across the markup engines: syntax highlighting
+// (from highlight.js) plus heading slug ids + permalink anchors.
+export const markdownRenderer = {
+  ...highlightRenderer,
+  // Fenced code goes through hljs, which wraps `{`/`%` in their own spans —
+  // splitting a {% raw %} tag so the template engine never sees it and
+  // evaluates the "raw" content (e.g. a {{ name }} in a config sample rendered
+  // as empty). Highlight around/inside each raw block instead, keeping the
+  // fence's language, and pass the delimiters through intact. Inline code
+  // never splits the delimiters, so it needs no special casing.
+  code(code, lang) {
+    const highlighted = mapRawSegments(code, (s) => s && highlightCode(s, lang), (s) => highlightCode(s, lang))
+    const langClass = lang ? ` language-${lang.replace(/[^\w-]/g, '')}` : ''
+    return `<pre><code class="hljs${langClass}">${highlighted}</code></pre>\n`
+  },
+  // Give every heading a slug id + a permalink anchor. The anchor is empty on
+  // purpose — themes reveal a "#" via `.heading-anchor::before`, so a site with
+  // no such CSS renders an invisible anchor instead of a stray "#".
+  // ponytail: no slug dedup — two identical headings on one page share an id;
+  // add a per-parse counter if that ever bites.
+  heading(text, level, raw) {
+    const id = slugify(raw || '')
+    if (!id) return `<h${level}>${text}</h${level}>\n`
+    return `<h${level} id="${id}">${text}<a class="heading-anchor" href="#${id}" aria-label="Permalink" aria-hidden="true"></a></h${level}>\n`
+  }
+}
+
+// One shared instance so both engines render markdown identically.
+export const marked = new Marked({ renderer: markdownRenderer })
+
+// Renders a markdown page source for the template engines. Entity decoding
+// (which un-escapes inside {{ }} / {% %} so template args parse) must skip
+// raw blocks — their content is for display, so its entities have to survive
+// to the browser.
+export function renderMarkdown(source) {
+  return mapRawSegments(marked.parse(source), decodeTemplateEntities, (s) => s)
+}