poops 1.4.1 → 1.5.1

package/README.md

@@ -797,11 +797,25 @@ Output:
 - Defaults: `sizes="100vw"`, `loading="lazy"`
 - Falls back to a plain `<img src="...">` if no variants are found
 
+**Named crops with `size`** — pass a `size` kwarg to build the `<img>` from a named crop/resize group instead of the default responsive widths. The whole group becomes its own srcset (each crop has its own aspect ratio), so a square thumbnail set, a wide banner set, etc. each get correct `srcset`/`width`/`height`:
+
+```nunjucks
+{% image 'static/photo.jpg', size='thumb', alt='', sizes='240px' %}
+```
+
+```html
+<img src="static/photo-thumb-480w.webp"
+     srcset="static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w"
+     width="480" height="480" sizes="240px" alt="" loading="lazy">
+```
+
+This requires the [poops-images](https://github.com/stamat/poops-images) compile cache (named-size widths are read from it). The `size` name matches a named entry in your `images.sizes` config. The largest member of the group is written without a width suffix (`photo-thumb.webp`) — poops still srcsets it at its real width from the cache.
+
 **[poops-images](https://github.com/stamat/poops-images) integration:** if a `.poops-images-cache.json` compile cache is found in the output directory (poops-images writes one next to the images it generates), Poops reads variants from it instead of scanning the directory. On top of the scan behavior above, the cache gives you:
 
 - `width` and `height` attributes on the `<img>` element (exact dimensions from the cache — prevents layout shift). Pass your own `width`/`height` kwargs to override.
 - Correct `src` when the source format was converted (e.g. `photo.heic` → `photo.jpg`), even when there are no size variants.
-- Named sizes (`photo-thumb-200w.jpg`) and preprocessed outputs (`photo-blurred-640w.jpg`) are kept out of the srcset — they are crops and effects with their own aspect ratios. Only plain `{name}-{width}w.{ext}` variants (from the poops-images `widths` option) are used.
+- By default the srcset is built only from the plain `{name}-{width}w.{ext}` width variants. Named sizes (`photo-thumb-480w.webp`) and preprocessed outputs (`photo-blurred-640w.jpg`) are kept out of it — they are crops and effects with their own aspect ratios. Reach a named crop group on purpose with the `size` kwarg above (or the `srcset` filter's second argument).
 - EXIF metadata via the `exif` filter (see below).
 
 ##### googleFonts
@@ -896,7 +910,7 @@ All filters are available in both engines. The only syntax difference is how arg
 
 - `jsonify` — serializes a value to JSON. Usage: `{{ myObject | jsonify }}`
 
-- `markdown` — renders a markdown string to HTML with GitHub-style emoji shortcodes (e.g. `:rocket:` → 🚀). Usage: `{{ "**bold** :rocket:" | markdown }}`
+- `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 }}`
 
 - `date` — formats a date string. Uses [dayjs](https://day.js.org/) format tokens. A default format can be set via the `timeDateFormat` config option.
   - Nunjucks: `{{ "2024-01-15" | date("MMMM D, YYYY") }}`
@@ -945,6 +959,8 @@ All filters are available in both engines. The only syntax difference is how arg
 
 Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo-960w.webp 960w`
 
+  Pass a named crop/resize group as the second argument to get that group's srcset instead of the default widths: `{{ 'static/photo.jpg' | srcset: 'thumb' }}` → `static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w`.
+
 - `exif` — returns the EXIF metadata object for an image from the [poops-images](https://github.com/stamat/poops-images) compile cache (`.poops-images-cache.json` in the output directory), or `null` if there is no cache or no EXIF data. The object includes camera (`make`, `model`, `lensModel`), exposure (`fNumber`, `exposure.formatted`, `iso`, `focalLength35mm`), `dateTime`, and `gps` (`latitude.formatted`, `longitude.formatted`, `altitude`, and a ready-made `googleMapsUrl`).
 
   Example — a photo with date and location caption:
@@ -969,19 +985,21 @@ Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo
   - `path` — site-relative source path, feeds straight into the `{% image %}` tag
   - `date` — `exif.dateTime` when the photo has EXIF, file modification time otherwise — so sorting and grouping work for every image
   - `outputs` — every generated file for the image (site-relative), useful for picking LQIP or preprocessed variants
-  - Pass a subdirectory (`'images/2025'`) to scope the list
+  - Pass a subdirectory (`'static/images/2025'`) to scope the list
+
+  **The path is relative to your markup `out` dir, not to `images.in`.** It mirrors where the generated images land — i.e. `images.out` made relative to markup `out`. So if `images.out` is `_site/static/images` and markup `out` is `_site`, the images live at `static/images` on the site and you call `'static/images' | images` (**not** `'images'`, which would look in `_site/images` and return `[]`). This is the same path you already pass to the `{% image %}` tag.
 
-  Combined with `groupby`, engine-native sorting and the `{% image %}` tag, a photo gallery is a pure template concern:
+  Combined with `groupby`, engine-native sorting and the `{% image %}` tag, a photo gallery is a pure template concern. This is the Instagram-style square grid — `size='thumb'` pulls the named crop group and its auto-generated srcset (define a `thumb` crop in `images.sizes`):
 
   Nunjucks:
 
   ```nunjucks
-  {% for group in 'images' | images | sort(reverse=true, attribute='date') | groupby("date", "year") %}
+  {% for group in 'static/images' | images | sort(reverse=true, attribute='date') | groupby("date", "year") %}
     <h2>{{ group.key }}</h2>
     <div class="grid">
       {% for img in group.items %}
         <figure>
-          {% image img.path, alt='', sizes='(max-width: 640px) 50vw, 25vw' %}
+          {% image img.path, size='thumb', alt='', sizes='(max-width: 640px) 50vw, 240px' %}
           {% if img.exif and img.exif.gps %}
             <figcaption>
               <a href="{{ img.exif.gps.googleMapsUrl }}">📍</a> {{ img.date | date("MMM D, YYYY") }}
@@ -996,13 +1014,13 @@ Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo
   Liquid:
 
   ```liquid
-  {% assign imgs = 'images' | images | sort: 'date' | reverse %}
+  {% assign imgs = 'static/images' | images | sort: 'date' | reverse %}
   {% assign groups = imgs | groupby: "date", "year" %}
   {% for group in groups %}
     <h2>{{ group.key }}</h2>
     <div class="grid">
       {% for img in group.items %}
-        <figure>{% image img.path, alt: '' %}</figure>
+        <figure>{% image img.path, size: 'thumb', alt: '' %}</figure>
       {% endfor %}
     </div>
   {% endfor %}

package/lib/markup/engines/liquid.js

@@ -27,7 +27,11 @@ export default class LiquidEngine {
     this.engine = new Liquid({
       root: roots,
       extname: '.liquid',
-      cache: false,
+      // Parsed-template cache: without it every {% render %}/{% include %}
+      // re-resolves (realpath per root) and re-parses the partial on every
+      // page — dominates build time on partial-heavy sites. Cleared per
+      // compile (clearCache) so watch-mode edits are picked up.
+      cache: true,
       dynamicPartials: true,
       strictFilters: false,
       strictVariables: false,
@@ -69,9 +73,9 @@ export default class LiquidEngine {
       if (!/^(<\?xml[^?]*\?>\s*)?<svg[\s>]/i.test(content)) return ''
       return content
     })
-    engine.registerFilter('srcset', (imagePath) => {
+    engine.registerFilter('srcset', (imagePath, size) => {
       const outputDir = path.resolve(process.cwd(), markupOut)
-      const { variants } = discoverImageVariants(imagePath, outputDir)
+      const { variants } = discoverImageVariants(imagePath, outputDir, size)
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })
@@ -106,6 +110,10 @@ export default class LiquidEngine {
     delete this.globals[key]
   }
 
+  clearCache() {
+    if (this.engine.options.cache) this.engine.options.cache.clear()
+  }
+
   async render(templateName, context) {
     let source
     const frontMatterResult = parseFrontMatter(templateName)

package/lib/markup/engines/nunjucks.js

@@ -30,6 +30,7 @@ class RelativeLoader extends nunjucks.Loader {
     }
     if (!fs.existsSync(fullPath)) {
       log({ tag: 'markup', error: true, text: 'Template not found:', link: name })
+      // noCache so a template created mid-watch is found on the next compile
       return { src: '', path: fullPath, noCache: true }
     }
 
@@ -53,7 +54,10 @@ class RelativeLoader extends nunjucks.Loader {
       source = `{% extends '${frontMatter.layout}.html' %}\n{% block content %}\n${source}\n{% endblock %}`
     }
 
-    return { src: source, path: fullPath, noCache: true }
+    // Cached: getSource does glob resolution + front matter + markdown per
+    // call, so re-running it per include per page dominates builds. Cleared
+    // per compile (clearCache) so watch-mode edits are picked up.
+    return { src: source, path: fullPath, noCache: false }
   }
 
   resolve(from, to) {
@@ -67,10 +71,15 @@ export default class NunjucksEngine {
 
     this.env = new nunjucks.Environment(
       new RelativeLoader(templatesDir, includePaths),
-      { autoescape, watch: false, noCache: true }
+      { autoescape, watch: false }
     )
   }
 
+  clearCache() {
+    // nunjucks keeps compiled templates on each loader's cache object
+    for (const loader of this.env.loaders) loader.cache = {}
+  }
+
   get fileExtension() { return '.njk' }
   get indexableExtensions() { return new Set(['.html', '.md', '.njk']) }
   get markupExtensions() { return 'html|xml|rss|atom|json|njk|md' }
@@ -108,9 +117,9 @@ export default class NunjucksEngine {
       const date = !str || str.trim() === '' ? new Date() : new Date(str)
       return dayjs(date).format(fmt)
     })
-    env.addFilter('srcset', (imagePath) => {
+    env.addFilter('srcset', (imagePath, size) => {
       const outputDir = path.resolve(process.cwd(), markupOut)
-      const { variants } = discoverImageVariants(imagePath, outputDir)
+      const { variants } = discoverImageVariants(imagePath, outputDir, size)
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })

package/lib/markup/helpers.js

@@ -88,15 +88,20 @@ export function decodeTemplateEntities(html) {
 // 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;).
+// `.sr-only` headings are visually hidden, so they're skipped — a visible TOC
+// linking to invisible content is confusing.
 export function renderToc(html) {
   if (!html) return ''
-  const re = /<h([23])\b[^>]*\sid="([^"]*)"[^>]*>([\s\S]*?)<\/h\1>/gi
+  const re = /<h([23])\b([^>]*)>([\s\S]*?)<\/h\1>/gi
   let items = ''
   let match
   while ((match = re.exec(html)) !== null) {
+    const attrs = match[2]
+    if (/\bclass="[^"]*\bsr-only\b/i.test(attrs)) continue
+    const id = (attrs.match(/\sid="([^"]*)"/i) || [])[1]
     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 (!id || !text) continue
+    items += `<li class="toc-h${match[1]}"><a href="#${id}">${text}</a></li>`
   }
   if (!items) return ''
   return `<nav class="toc" aria-label="On this page"><ul>${items}</ul></nav>`
@@ -172,16 +177,32 @@ function pickSrcsetAndSrc(variants, originalExt) {
 }
 
 // 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) {
+// and dimensions, no directory scan. By default only `{name}-{width}w.{ext}`
+// outputs are srcset material. Pass `size` to instead build the srcset from a
+// named crop/resize group (`thumb`) — poops-images tags each named variant with
+// its size name in the cache, and the largest of the group drops the width
+// suffix (`{name}-thumb.{ext}`), so widths come from the cache, not the filename.
+function discoverImageVariantsFromCache(imagePath, outputDir, size) {
   const found = getImageEntry(imagePath, outputDir)
   if (!found) return null
 
   const { entry, prefixDir } = found
   const parsed = path.parse(imagePath)
   const originalExt = parsed.ext.replace('.', '')
+  const sitePath = (p) => prefixDir ? toPosix(path.join(prefixDir, p)) : toPosix(p)
+  const extOf = (p) => path.posix.extname(toPosix(p)).replace('.', '')
+
+  if (size) {
+    // Named group — every output tagged with this size name; widths from the cache
+    const variants = (entry.outputs || [])
+      .filter(o => o.name === size && o.width)
+      .map(o => ({ path: sitePath(o.path), width: o.width, height: o.height, format: extOf(o.path) }))
+    if (variants.length === 0) return null
+    const { srcVariant, srcsetVariants } = pickSrcsetAndSrc(variants, originalExt)
+    const src = srcVariant || srcsetVariants[srcsetVariants.length - 1] || variants[variants.length - 1]
+    return { src: src.path, variants: srcsetVariants, width: src.width, height: src.height }
+  }
+
   const variantPattern = new RegExp(`^${escapeRegExp(parsed.name)}-(\\d+)w\\.([a-z0-9]+)$`)
   const basePattern = new RegExp(`^${escapeRegExp(parsed.name)}\\.([a-z0-9]+)$`)
 
@@ -189,15 +210,17 @@ function discoverImageVariantsFromCache(imagePath, outputDir) {
   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)
+    // Named / preprocessed variants (they carry a `name`) are crops or effects
+    // with their own aspect ratio — never mix them into the default width srcset.
+    if (out.name) continue
     let match = file.match(variantPattern)
     if (match) {
-      variants.push({ path: sitePath, width: parseInt(match[1], 10), height: out.height, format: match[2] })
+      variants.push({ path: sitePath(out.path), 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 }
+      base = { path: sitePath(out.path), width: out.width, height: out.height }
     }
   }
 
@@ -208,9 +231,11 @@ function discoverImageVariantsFromCache(imagePath, outputDir) {
   return { src: src.path, variants: srcsetVariants, width: src.width, height: src.height }
 }
 
-export function discoverImageVariants(imagePath, outputDir) {
-  const fromCache = discoverImageVariantsFromCache(imagePath, outputDir)
+export function discoverImageVariants(imagePath, outputDir, size) {
+  const fromCache = discoverImageVariantsFromCache(imagePath, outputDir, size)
   if (fromCache) return fromCache
+  // A named size only exists in the compile cache — no directory-scan fallback.
+  if (size) return { src: imagePath, variants: [] }
 
   const parsed = path.parse(imagePath)
   const dir = path.join(outputDir, parsed.dir)
@@ -322,7 +347,7 @@ export function buildImageTag(imagePath, prefix, kwargs, getOutputDir) {
   if (isSvg) {
     attrs.unshift(`src="${escapeAttr(prefix + imagePath)}"`)
   } else {
-    const { src, variants, width, height } = discoverImageVariants(imagePath, getOutputDir())
+    const { src, variants, width, height } = discoverImageVariants(imagePath, getOutputDir(), kwargs && kwargs.size)
     const sizes = (kwargs && kwargs.sizes) || '100vw'
     attrs.unshift(`src="${escapeAttr(prefix + src)}"`)
     if (width && height && !(kwargs && (kwargs.width || kwargs.height))) {
@@ -337,7 +362,7 @@ export function buildImageTag(imagePath, prefix, kwargs, getOutputDir) {
 
   attrs.push(`loading="${escapeAttr(loading)}"`)
   if (kwargs) {
-    const skip = new Set(['alt', 'sizes', 'loading'])
+    const skip = new Set(['alt', 'sizes', 'loading', 'size'])
     for (const [key, val] of Object.entries(kwargs)) {
       // `__keywords` is nunjucks' kwargs marker, never a real attribute
       if (key.startsWith('__') || skip.has(key)) continue

package/lib/markup/highlight.js

@@ -69,8 +69,8 @@ export function highlightCode(code, language) {
 }
 
 export const highlightRenderer = {
-  code(code, lang) {
-    const highlighted = highlightCode(code, lang)
+  code({ text, lang }) {
+    const highlighted = highlightCode(text, lang)
     const langClass = lang ? ` language-${escapeHtml(lang)}` : ''
     return `<pre><code class="hljs${langClass}">${highlighted}</code></pre>\n`
   }

package/lib/markup/renderer.js

@@ -1,6 +1,7 @@
 import { Marked } from 'marked'
 import { markedGithubEmoji } from 'marked-github-emoji'
 import { markedGithubAlerts } from 'marked-github-alerts'
+import { markedGithubFootnote } from 'marked-github-footnote'
 import { slugify } from 'book-of-spells'
 import { highlightRenderer, highlightCode } from './highlight.js'
 import { decodeTemplateEntities } from './helpers.js'
@@ -33,8 +34,8 @@ export const markdownRenderer = {
   // 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))
+  code({ text, lang }) {
+    const highlighted = mapRawSegments(text, (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`
   },
@@ -43,10 +44,11 @@ export const markdownRenderer = {
   // 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) {
+  heading({ tokens, depth, text: raw }) {
+    const text = this.parser.parseInline(tokens)
     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`
+    if (!id) return `<h${depth}>${text}</h${depth}>\n`
+    return `<h${depth} id="${id}">${text}<a class="heading-anchor" href="#${id}" aria-label="Permalink" aria-hidden="true"></a></h${depth}>\n`
   }
 }
 
@@ -58,6 +60,7 @@ marked.use(markedGithubAlerts({
     info: { title: 'Info', icon: 'info' }
   }
 }))
+marked.use(markedGithubFootnote())
 
 // Renders a markdown page source for the template engines. Entity decoding
 // (which un-escapes inside {{ }} / {% %} so template args parse) must skip

package/lib/markups.js

@@ -375,6 +375,9 @@ export default class Markups {
       throw err
     } finally {
       clearFrontMatterCache()
+      // Engine template caches live for one compile: fast within a build,
+      // watch-mode edits always picked up on the next one
+      if (typeof this.engine.clearCache === 'function') this.engine.clearCache()
     }
   }
 
@@ -426,6 +429,7 @@ export default class Markups {
       throw err
     } finally {
       clearFrontMatterCache()
+      if (typeof this.engine.clearCache === 'function') this.engine.clearCache()
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops",
   "description": "Straightforward, no-bullshit bundler for the web.",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "license": "MIT",
   "type": "module",
   "main": "poops.js",
@@ -34,8 +34,8 @@
     "static-site-generator"
   ],
   "peerDependencies": {
-    "postcss": "^8.0.0",
-    "poops-images": ">=1.2.0"
+    "poops-images": ">=1.2.1",
+    "postcss": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "postcss": {
@@ -61,9 +61,10 @@
     "highlight.js": "^11.11.1",
     "liquidjs": "^10.24.0",
     "livereload": "^0.9.3",
-    "marked": "^9.0.3",
+    "marked": "^18.0.6",
     "marked-github-alerts": "^1.0.1",
     "marked-github-emoji": "^1.0.2",
+    "marked-github-footnote": "^1.0.0",
     "nunjucks": "^3.2.4",
     "portscanner": "^2.2.0",
     "printstyle": "^1.0.0",
@@ -88,4 +89,4 @@
   "overrides": {
     "minimatch": ">=10.2.1"
   }
-}
+}