poops 1.2.3 → 1.3.0

package/lib/images.js

@@ -0,0 +1,57 @@
+import log from './utils/log.js'
+
+// Runs poops-images (https://github.com/stamat/poops-images) as a regular
+// runner when a `config.images` block is present AND the package is installed.
+// poops-images stays an optional peer dependency — sharp never becomes a hard
+// dep of poops. The markup engines read the cache poops-images writes, so this
+// runner must execute before markups.compile().
+export default class Images {
+  constructor(config) {
+    this.config = config
+    this.processor = null // lazily created on first compile()
+    this.disabled = false // no images config, or poops-images not installed
+  }
+
+  async init() {
+    if (this.processor || this.disabled) return
+    if (!this.config.images) { this.disabled = true; return }
+
+    let ImageProcessor
+    try {
+      ImageProcessor = (await import('poops-images')).default
+    } catch (err) {
+      // Native ESM throws ERR_MODULE_NOT_FOUND; CJS-style/jest resolvers throw
+      // MODULE_NOT_FOUND. Either means the optional dep simply isn't installed.
+      if (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND') {
+        log({ tag: 'image', warn: true, text: 'images config found but poops-images is not installed — run: npm i poops-images' })
+        this.disabled = true
+        return
+      }
+      throw err
+    }
+
+    // Quiet by default inside poops — one summary line instead of per-image
+    // logs drowning the other runners. Opt back in with "verbose": true.
+    // A bad images config throws here, propagating to the build's step() so
+    // the build is marked failed rather than silently skipping images.
+    this.processor = new ImageProcessor({ verbose: false, ...this.config.images })
+  }
+
+  async compile() {
+    await this.init()
+    if (!this.processor) return
+    const stats = await this.processor.processAll()
+    // Route through poops' log so hasLoggedErrors() flips the build exit code.
+    // Older poops-images without the errors field: undefined is falsy, no-op.
+    if (stats.errors > 0) {
+      log({ tag: 'image', error: true, text: `${stats.errors} image(s) failed to process` })
+    }
+  }
+
+  // Watch mode: a deleted source image removes its generated variants + cache entry.
+  async remove(file) {
+    await this.init()
+    if (!this.processor) return
+    this.processor.removeSource(file)
+  }
+}

package/lib/markup/collections.js

@@ -2,12 +2,13 @@ import fs from 'node:fs'
 import { globSync } from 'glob'
 import path from 'node:path'
 import log from '../utils/log.js'
-import { mkDir } from '../utils/helpers.js'
-import { replaceOutExtensions, getRelativePathPrefix, getPageUrl, parseFrontMatter, wordcount } from './helpers.js'
+import { mkDir, toPosix } from '../utils/helpers.js'
+import { replaceOutExtensions, getRelativePathPrefix, getPageUrlRelativeToOutput, parseFrontMatter, wordcount } from './helpers.js'
 
 export function getSingleCollectionData(markupInDir, collectionName) {
   const collectionData = []
-  globSync(path.join(process.cwd(), markupInDir, collectionName, '**/*.+(html|njk|liquid|md)'), { ignore: ['**/index.+(html|njk|liquid|md)'] }).forEach((file) => {
+  // glob patterns must use `/` — on Windows `\` is an escape character
+  globSync(toPosix(path.resolve(process.cwd(), markupInDir, collectionName, '**/*.+(html|njk|liquid|md)')), { ignore: ['**/index.+(html|njk|liquid|md)'] }).forEach((file) => {
     let frontMatter = {}
 
     let content = ''
@@ -23,13 +24,16 @@ export function getSingleCollectionData(markupInDir, collectionName) {
     if (frontMatter.published === false) return
 
     if (!frontMatter.date) {
-      frontMatter.date = fs.statSync(file).ctime.toISOString().slice(0, 16)
+      // mtime is only a local-dev approximation — git clone resets it, so CI
+      // builds date undated posts "now". The warning is the real fix.
+      frontMatter.date = fs.statSync(file).mtime.toISOString().slice(0, 16)
+      log({ tag: 'markup', warn: true, text: 'No date in front matter, falling back to file mtime:', link: file })
     }
     frontMatter.wordcount = wordcount(content)
     frontMatter.fileName = path.basename(file)
     frontMatter.filePath = path.relative(process.cwd(), file)
     frontMatter.collection = collectionName
-    frontMatter.url = path.join(collectionName, path.basename(frontMatter.filePath))
+    frontMatter.url = toPosix(path.join(collectionName, path.basename(frontMatter.filePath)))
 
     frontMatter.url = replaceOutExtensions(frontMatter.url)
 
@@ -43,7 +47,7 @@ export function getSingleCollectionData(markupInDir, collectionName) {
 }
 
 export function collectionAutoDiscovery(markupInDir) {
-  const indexFiles = globSync(path.join(process.cwd(), markupInDir, '/**/index.+(html|njk|liquid|md)'))
+  const indexFiles = globSync(toPosix(path.resolve(process.cwd(), markupInDir, '**/index.+(html|njk|liquid|md)')))
 
   const collectionData = {}
 
@@ -180,11 +184,25 @@ export function buildCollectionPaginationData(collectionData) {
 }
 
 export function getCollectionIndexFile(markupInDir, collectionName) {
-  const indexFiles = globSync(path.join(process.cwd(), markupInDir, collectionName, 'index.+(html|njk|liquid|md)'))
+  const indexFiles = globSync(toPosix(path.resolve(process.cwd(), markupInDir, collectionName, 'index.+(html|njk|liquid|md)')))
   if (indexFiles.length === 0) return null
   return indexFiles[0]
 }
 
+export function pruneStalePaginationDirs(collectionName, markupInDir, markupOutDir, keepPages) {
+  const outDir = path.resolve(process.cwd(), markupOutDir, collectionName)
+  if (!fs.existsSync(outDir)) return
+
+  for (const entry of fs.readdirSync(outDir)) {
+    const pageNumber = parseInt(entry, 10)
+    // pagination only ever writes out/<name>/2..totalPages/
+    if (String(pageNumber) !== entry || pageNumber < 2 || pageNumber <= keepPages) continue
+    // numeric dir mirrored from a real source dir — not pagination output
+    if (fs.existsSync(path.resolve(process.cwd(), markupInDir, collectionName, entry))) continue
+    fs.rmSync(path.join(outDir, entry), { recursive: true, force: true })
+  }
+}
+
 export function generateCollectionPaginationPages(collectionData, markupInDir, markupOutDir, compileEntryFn, baseURL) {
   if (!collectionData) return []
 
@@ -199,6 +217,11 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
       collection.pages = [collection.items]
     }
 
+    // a shrunk page count (or removed index) leaves stale out/<name>/N/ dirs
+    pruneStalePaginationDirs(collection.name, markupInDir, markupOutDir, file ? collection.totalPages : 1)
+
+    if (!file) continue
+
     for (let i = 0; i < collection.totalPages; i++) {
       const pageNumber = i + 1
       const pageUrl = pageNumber === 1 ? collection.name : `${collection.name}/${pageNumber}`
@@ -222,24 +245,23 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
         prevPageUrl
       }
 
-      const markupOut = path.join(process.cwd(), markupOutDir, pageUrl, 'index.html')
-      const fromPath = path.join(process.cwd(), markupOutDir)
+      const markupOut = path.resolve(process.cwd(), markupOutDir, pageUrl, 'index.html')
+      const fromPath = path.resolve(process.cwd(), markupOutDir)
       const markupOutDirFull = path.dirname(markupOut)
 
-      mkDir(markupOutDirFull)
-
       const context = {
         ...collectionData,
         [collectionName]: pageSnapshot,
         relativePathPrefix: getRelativePathPrefix(markupOutDirFull, fromPath, baseURL),
-        _url: getPageUrl(markupOut)
-      }
-
-      if (!file) {
-        continue
+        // output-relative so page.url matches nav.json/index urls, same as compileDirectory
+        _url: getPageUrlRelativeToOutput(markupOut, markupOutDir)
       }
 
-      const compilePromise = compileEntryFn(file, context).then(({ result }) => {
+      // 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)
         fs.writeFileSync(markupOut, result)
       })
       compilePromises.push(compilePromise)

package/lib/markup/engines/liquid.js

@@ -1,19 +1,18 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { Liquid } from 'liquidjs'
-import { Marked } from 'marked'
-import { highlightRenderer, highlightCode } from '../highlight.js'
-import { discoverImageVariants, parseFrontMatter, groupby, decodeTemplateEntities } from '../helpers.js'
+import { highlightCode } from '../highlight.js'
+import { marked, renderMarkdown } from '../renderer.js'
+import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc } from '../helpers.js'
+import { getImageExif, listImages } from '../image-cache.js'
 import { slugify } from 'book-of-spells'
 import dayjs from 'dayjs'
 
-const marked = new Marked({ renderer: highlightRenderer })
-
 export default class LiquidEngine {
   constructor(templatesDir, includePaths) {
     const roots = [templatesDir]
     for (const inc of includePaths || []) {
-      roots.push(path.join(templatesDir, inc))
+      roots.push(path.resolve(templatesDir, inc))
     }
     // Also add any _* directories as include roots
     try {
@@ -47,6 +46,7 @@ export default class LiquidEngine {
     engine.registerFilter('slugify', (str) => slugify(str))
     engine.registerFilter('jsonify', (obj) => JSON.stringify(obj))
     engine.registerFilter('markdown', (str) => marked.parse(str))
+    engine.registerFilter('toc', (html) => renderToc(String(html || '')))
     engine.registerFilter('date', (str, template) => {
       const fmt = template || timeDateFormat
       if (!fmt) return str
@@ -70,11 +70,19 @@ export default class LiquidEngine {
       return content
     })
     engine.registerFilter('srcset', (imagePath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       const { variants } = discoverImageVariants(imagePath, outputDir)
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })
+    engine.registerFilter('exif', (imagePath) => {
+      const outputDir = path.resolve(process.cwd(), markupOut)
+      return getImageExif(imagePath, outputDir)
+    })
+    engine.registerFilter('images', (dirPath) => {
+      const outputDir = path.resolve(process.cwd(), markupOut)
+      return listImages(dirPath, outputDir)
+    })
     engine.registerFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
     engine.registerFilter('highlight', (code, lang) => {
       const highlighted = highlightCode(code, lang)
@@ -86,6 +94,7 @@ export default class LiquidEngine {
   registerTags(getOutputDir) {
     registerGoogleFontsTag(this.engine)
     registerImageTag(this.engine, getOutputDir)
+    registerPaginationTag(this.engine)
     registerHighlightTag(this.engine)
   }
 
@@ -93,13 +102,17 @@ export default class LiquidEngine {
     this.globals[key] = value
   }
 
+  removeGlobal(key) {
+    delete this.globals[key]
+  }
+
   async render(templateName, context) {
     let source
     const frontMatterResult = parseFrontMatter(templateName)
     source = frontMatterResult.content
 
     if (path.extname(templateName) === '.md') {
-      source = decodeTemplateEntities(marked.parse(source))
+      source = renderMarkdown(source)
     }
 
     const frontMatter = context.page || {}
@@ -189,32 +202,20 @@ function registerImageTag(engine, getOutputDir) {
       }
 
       const prefix = (yield ctx.get(['relativePathPrefix'])) || ''
-      const alt = kwargs.alt || ''
-      const loading = kwargs.loading || 'lazy'
-      const isSvg = imagePath.endsWith('.svg')
-      const attrs = [`alt="${alt}"`]
-
-      if (isSvg) {
-        attrs.unshift(`src="${prefix}${imagePath}"`)
-      } else {
-        const outputDir = getOutputDir()
-        const { src, variants } = discoverImageVariants(imagePath, outputDir)
-        const sizes = kwargs.sizes || '100vw'
-        attrs.unshift(`src="${prefix}${src}"`)
-        if (variants.length > 0) {
-          const srcsetVal = variants.map(v => `${prefix}${v.path} ${v.width}w`).join(', ')
-          attrs.push(`srcset="${srcsetVal}"`)
-          attrs.push(`sizes="${sizes}"`)
-        }
-      }
+      return buildImageTag(imagePath, prefix, kwargs, getOutputDir)
+    }
+  })
+}
 
-      attrs.push(`loading="${loading}"`)
-      const skip = new Set(['alt', 'sizes', 'loading'])
-      for (const [key, val] of Object.entries(kwargs)) {
-        if (skip.has(key)) continue
-        attrs.push(`${key}="${val}"`)
-      }
-      return `<img ${attrs.join(' ')}>`
+function registerPaginationTag(engine) {
+  engine.registerTag('pagination', {
+    parse(tagToken) {
+      this.value = tagToken.args.trim()
+    },
+    * render(ctx) {
+      const pagination = yield this.liquid.evalValue(this.value, ctx)
+      const prefix = (yield ctx.get(['relativePathPrefix'])) || ''
+      return buildPaginationTag(pagination, prefix)
     }
   })
 }

package/lib/markup/engines/nunjucks.js

@@ -1,16 +1,16 @@
 import fs from 'node:fs'
 import { globSync } from 'glob'
-import { Marked } from 'marked'
 import nunjucks from 'nunjucks'
 import path from 'node:path'
-import { discoverImageVariants, parseFrontMatter, groupby, decodeTemplateEntities } from '../helpers.js'
-import { highlightRenderer, highlightCode } from '../highlight.js'
+import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc } from '../helpers.js'
+import { getImageExif, listImages } from '../image-cache.js'
+import { toPosix } from '../../utils/helpers.js'
+import { highlightCode } from '../highlight.js'
+import { marked, renderMarkdown } from '../renderer.js'
 import { slugify } from 'book-of-spells'
 import dayjs from 'dayjs'
 import log from '../../utils/log.js'
 
-const marked = new Marked({ renderer: highlightRenderer })
-
 class RelativeLoader extends nunjucks.Loader {
   constructor(templatesDir, includePaths) {
     super()
@@ -26,7 +26,7 @@ class RelativeLoader extends nunjucks.Loader {
       if (this.includePaths) {
         pattern = `{${this.includePaths.join(',')}}/${pattern}`
       }
-      fullPath = globSync(path.join(this.templatesDir, pattern))[0]
+      fullPath = globSync(toPosix(path.join(this.templatesDir, pattern)))[0]
     }
     if (!fs.existsSync(fullPath)) {
       log({ tag: 'markup', error: true, text: 'Template not found:', link: name })
@@ -46,7 +46,7 @@ class RelativeLoader extends nunjucks.Loader {
     }
 
     if (path.extname(fullPath) === '.md') {
-      source = decodeTemplateEntities(marked.parse(source))
+      source = renderMarkdown(source)
     }
 
     if (frontMatter.layout) {
@@ -80,6 +80,12 @@ export default class NunjucksEngine {
     env.addFilter('slugify', slugify)
     env.addFilter('jsonify', (obj) => JSON.stringify(obj))
     env.addFilter('markdown', (str) => marked.parse(str))
+    env.addFilter('toc', (html) => {
+      const toc = renderToc(String(html || ''))
+      // plain '' (falsy) when there are no headings, so `{% if x | toc %}` can
+      // skip an empty TOC column; SafeString otherwise to keep the markup raw
+      return toc ? new nunjucks.runtime.SafeString(toc) : ''
+    })
     env.addFilter('concat', (arr, value) => {
       if (!Array.isArray(arr)) return [value]
       return arr.concat(value)
@@ -103,11 +109,19 @@ export default class NunjucksEngine {
       return dayjs(date).format(fmt)
     })
     env.addFilter('srcset', (imagePath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       const { variants } = discoverImageVariants(imagePath, outputDir)
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })
+    env.addFilter('exif', (imagePath) => {
+      const outputDir = path.resolve(process.cwd(), markupOut)
+      return getImageExif(imagePath, outputDir)
+    })
+    env.addFilter('images', (dirPath) => {
+      const outputDir = path.resolve(process.cwd(), markupOut)
+      return listImages(dirPath, outputDir)
+    })
     env.addFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
     env.addFilter('highlight', (code, lang) => {
       const highlighted = highlightCode(code, lang)
@@ -119,6 +133,7 @@ export default class NunjucksEngine {
   registerTags(getOutputDir) {
     this.env.addExtension('GoogleFontsExtension', new GoogleFontsExtension())
     this.env.addExtension('ImageExtension', new ImageExtension(getOutputDir))
+    this.env.addExtension('PaginationExtension', new PaginationExtension())
     this.env.addExtension('HighlightExtension', new HighlightExtension())
   }
 
@@ -126,6 +141,10 @@ export default class NunjucksEngine {
     this.env.addGlobal(key, value)
   }
 
+  removeGlobal(key) {
+    delete this.env.globals[key]
+  }
+
   render(templateName, context) {
     return new Promise((resolve, reject) => {
       this.env.getTemplate(templateName).render(context, (error, result) => {
@@ -208,34 +227,7 @@ export class ImageExtension {
 
   run(context, imagePath, kwargs) {
     const prefix = context.lookup('relativePathPrefix') || ''
-    const alt = (kwargs && kwargs.alt) || ''
-    const loading = (kwargs && kwargs.loading) || 'lazy'
-    const isSvg = imagePath.endsWith('.svg')
-    const attrs = [`alt="${alt}"`]
-
-    if (isSvg) {
-      attrs.unshift(`src="${prefix}${imagePath}"`)
-    } else {
-      const outputDir = this.getOutputDir()
-      const { src, variants } = discoverImageVariants(imagePath, outputDir)
-      const sizes = (kwargs && kwargs.sizes) || '100vw'
-      attrs.unshift(`src="${prefix}${src}"`)
-      if (variants.length > 0) {
-        const srcsetVal = variants.map(v => `${prefix}${v.path} ${v.width}w`).join(', ')
-        attrs.push(`srcset="${srcsetVal}"`)
-        attrs.push(`sizes="${sizes}"`)
-      }
-    }
-
-    attrs.push(`loading="${loading}"`)
-    if (kwargs) {
-      const skip = new Set(['alt', 'sizes', 'loading'])
-      for (const [key, val] of Object.entries(kwargs)) {
-        if (key.startsWith('__') || skip.has(key)) continue
-        attrs.push(`${key}="${val}"`)
-      }
-    }
-    return new nunjucks.runtime.SafeString(`<img ${attrs.join(' ')}>`)
+    return new nunjucks.runtime.SafeString(buildImageTag(imagePath, prefix, kwargs, this.getOutputDir))
   }
 }
 
@@ -260,3 +252,19 @@ export class HighlightExtension {
     )
   }
 }
+
+export class PaginationExtension {
+  constructor() { this.tags = ['pagination'] }
+
+  parse(parser, nodes) {
+    const tok = parser.nextToken()
+    const args = parser.parseSignature(null, true)
+    parser.advanceAfterBlockEnd(tok.value)
+    return new nodes.CallExtension(this, 'run', args)
+  }
+
+  run(context, pagination) {
+    const prefix = context.lookup('relativePathPrefix') || ''
+    return new nunjucks.runtime.SafeString(buildPaginationTag(pagination, prefix))
+  }
+}