poops 1.2.2 → 1.2.3

package/README.md

@@ -68,6 +68,22 @@ or pass a custom config. This is useful when you have multiple environments:
 
 `poops yourAwesomeConfig.json` or `💩 yourAwesomeConfig.json`
 
+**CLI Options:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--build` | `-b` | Build the project and exit |
+| `--config <path>` | `-c` | Specify the config file |
+| `--port <number>` | `-p` | Specify the server port, overrides config |
+| `--livereload-port <number>` | `-l` | Specify the livereload port, overrides config |
+| `--base-url <path>` | `-u` | Set the base URL prefix for markup, overrides config |
+
+The `--base-url` flag is particularly useful for CI/CD pipelines where the deploy path may differ per environment:
+
+```bash
+poops --build --base-url /blog
+```
+
 If you have installed Poops locally you can run it with `npx poops` or `npx 💩` or add a script to your `package.json`:
 
 ```json
@@ -728,6 +744,21 @@ All filters are available in both engines. The only syntax difference is how arg
   - Nunjucks: `{{ someCodeVariable | highlight('javascript') }}`
   - Liquid: `{{ someCodeVariable | highlight: 'javascript' }}`
 
+- `groupby` — groups an array of objects by a field value. Returns an array of `{ key, items }` objects. Supports an optional second argument for date part extraction (`year`, `month`, `day`). Groups preserve insertion order, so if items are sorted by date descending, groups will be too.
+  - Nunjucks: `{{ changelog.items | groupby("author") }}` or `{{ changelog.items | groupby("date", "year") }}`
+  - Liquid: `{{ changelog.items | groupby: "author" }}` or `{{ changelog.items | groupby: "date", "year" }}`
+
+  Example — group posts by year:
+  ```nunjucks
+  {% set byYear = changelog.items | groupby("date", "year") %}
+  {% for group in byYear %}
+    <h2>{{ group.key }}</h2>
+    {% for post in group.items %}
+      <p>{{ post.title }}</p>
+    {% endfor %}
+  {% endfor %}
+  ```
+
 - `srcset` — returns just the srcset attribute value:
 
 ```html

package/lib/markup/collections.js

@@ -3,16 +3,18 @@ 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 } from './helpers.js'
+import { replaceOutExtensions, getRelativePathPrefix, getPageUrl, 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) => {
     let frontMatter = {}
 
+    let content = ''
     try {
       const frontMatterResult = parseFrontMatter(file)
       frontMatter = frontMatterResult.frontMatter
+      content = frontMatterResult.content
     } catch (err) {
       log({ tag: 'error', text: 'Failed parsing front matter:', link: file })
       console.error(err)
@@ -23,6 +25,7 @@ export function getSingleCollectionData(markupInDir, collectionName) {
     if (!frontMatter.date) {
       frontMatter.date = fs.statSync(file).ctime.toISOString().slice(0, 16)
     }
+    frontMatter.wordcount = wordcount(content)
     frontMatter.fileName = path.basename(file)
     frontMatter.filePath = path.relative(process.cwd(), file)
     frontMatter.collection = collectionName

package/lib/markup/engines/liquid.js

@@ -3,7 +3,7 @@ import path from 'node:path'
 import { Liquid } from 'liquidjs'
 import { Marked } from 'marked'
 import { highlightRenderer, highlightCode } from '../highlight.js'
-import { discoverImageVariants, parseFrontMatter } from '../helpers.js'
+import { discoverImageVariants, parseFrontMatter, groupby, decodeTemplateEntities } from '../helpers.js'
 import { slugify } from 'book-of-spells'
 import dayjs from 'dayjs'
 
@@ -75,6 +75,7 @@ export default class LiquidEngine {
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })
+    engine.registerFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
     engine.registerFilter('highlight', (code, lang) => {
       const highlighted = highlightCode(code, lang)
       const langClass = lang ? ` language-${lang}` : ''
@@ -98,7 +99,7 @@ export default class LiquidEngine {
     source = frontMatterResult.content
 
     if (path.extname(templateName) === '.md') {
-      source = marked.parse(source)
+      source = decodeTemplateEntities(marked.parse(source))
     }
 
     const frontMatter = context.page || {}

package/lib/markup/engines/nunjucks.js

@@ -3,7 +3,7 @@ import { globSync } from 'glob'
 import { Marked } from 'marked'
 import nunjucks from 'nunjucks'
 import path from 'node:path'
-import { discoverImageVariants, parseFrontMatter } from '../helpers.js'
+import { discoverImageVariants, parseFrontMatter, groupby, decodeTemplateEntities } from '../helpers.js'
 import { highlightRenderer, highlightCode } from '../highlight.js'
 import { slugify } from 'book-of-spells'
 import dayjs from 'dayjs'
@@ -46,7 +46,7 @@ class RelativeLoader extends nunjucks.Loader {
     }
 
     if (path.extname(fullPath) === '.md') {
-      source = marked.parse(source)
+      source = decodeTemplateEntities(marked.parse(source))
     }
 
     if (frontMatter.layout) {
@@ -108,6 +108,7 @@ export default class NunjucksEngine {
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })
+    env.addFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
     env.addFilter('highlight', (code, lang) => {
       const highlighted = highlightCode(code, lang)
       const langClass = lang ? ` language-${lang}` : ''
@@ -152,7 +153,7 @@ export default class NunjucksEngine {
 
 // --- Nunjucks Extensions ---
 
-class GoogleFontsExtension {
+export class GoogleFontsExtension {
   constructor() { this.tags = ['googleFonts'] }
 
   parse(parser, nodes) {
@@ -195,7 +196,7 @@ class GoogleFontsExtension {
   }
 }
 
-class ImageExtension {
+export class ImageExtension {
   constructor(getOutputDir) { this.tags = ['image']; this.getOutputDir = getOutputDir }
 
   parse(parser, nodes) {
@@ -238,7 +239,7 @@ class ImageExtension {
   }
 }
 
-class HighlightExtension {
+export class HighlightExtension {
   constructor() { this.tags = ['highlight'] }
 
   parse(parser, nodes) {

package/lib/markup/helpers.js

@@ -58,6 +58,53 @@ export function clearFrontMatterCache(filePath) {
   frontMatterCache.delete(filePath)
 }
 
+export function wordcount(text) {
+  if (!text) return 0
+  // eslint-disable-next-line no-useless-escape
+  const stripped = text.replace(/<[^>]*>/g, ' ').replace(/[#*_`~\[\]()>|{}\\-]/g, ' ')
+  const words = stripped.match(/\S+/g)
+  return words ? words.length : 0
+}
+
+// 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
+// &amp;lt; doesn't double-decode into <.
+export function decodeTemplateEntities(html) {
+  return html.replace(/(\{\{[\s\S]*?\}\}|\{%[\s\S]*?%\})/g, (tag) =>
+    tag
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&amp;/g, '&')
+  )
+}
+
+export function groupby(arr, key, datePart) {
+  if (!Array.isArray(arr)) return []
+
+  const map = new Map()
+  for (const item of arr) {
+    let value = item[key]
+    if (datePart && value) {
+      const date = new Date(value)
+      if (!isNaN(date)) {
+        switch (datePart) {
+          case 'year': value = date.getUTCFullYear(); break
+          case 'month': value = date.getUTCMonth() + 1; break
+          case 'day': value = date.getUTCDate(); break
+        }
+      }
+    }
+    const groupKey = value != null ? String(value) : ''
+    if (!map.has(groupKey)) map.set(groupKey, [])
+    map.get(groupKey).push(item)
+  }
+
+  return Array.from(map, ([key, items]) => ({ key, items }))
+}
+
 const FORMAT_PRIORITY = ['avif', 'webp']
 
 export function discoverImageVariants(imagePath, outputDir) {

package/lib/markups.js

@@ -1,5 +1,5 @@
 import { pathExists, pathIsDirectory, readDataFile, mkDir, buildTime } from './utils/helpers.js'
-import { replaceOutExtensions, getRelativePathPrefix, getPageUrl, getPageUrlRelativeToOutput, parseFrontMatter, clearFrontMatterCache } from './markup/helpers.js'
+import { replaceOutExtensions, getRelativePathPrefix, getPageUrl, getPageUrlRelativeToOutput, parseFrontMatter, clearFrontMatterCache, wordcount } from './markup/helpers.js'
 import { collectionAutoDiscovery, getCollectionDataBasedOnConfig, buildCollectionPaginationData, generateCollectionPaginationPages } from './markup/collections.js'
 import { generateIndexFiles } from './markup/indexer.js'
 import NunjucksEngine from './markup/engines/nunjucks.js'
@@ -152,6 +152,7 @@ export default class Markups {
     try {
       const frontMatterResult = parseFrontMatter(templateName)
       context.page = frontMatterResult.frontMatter
+      context.page.wordcount = wordcount(frontMatterResult.content)
     } catch (err) {
       log({ tag: 'error', text: 'Failed parsing front matter:', link: templateName })
       console.error(err)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops",
   "description": "Straightforward, no-bullshit bundler for the web.",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "license": "MIT",
   "type": "module",
   "main": "poops.js",

package/poops.js

@@ -28,6 +28,7 @@ const cli = new Argoyle(pkg.version)
   .option('config', { short: 'c', value: '<path>', description: 'Specify the config file' })
   .option('port', { short: 'p', value: '<number>', description: 'Specify the port for the server, overrides the config file' })
   .option('livereload-port', { short: 'l', value: '<number>', description: 'Specify the port for the livereload server, overrides the config file' })
+  .option('base-url', { short: 'u', value: '<path>', description: 'Set the base URL prefix for markup, overrides the config file' })
 
 let flags, positionals
 try {
@@ -41,6 +42,7 @@ const build = flags.build
 const defaultConfigPath = flags.config || positionals[0] || 'poops.json'
 const overridePort = flags.port
 const overrideLivereloadPort = flags['livereload-port']
+const overrideBaseURL = flags['base-url']
 
 let configPath = path.join(cwd, defaultConfigPath)
 if (!pathExists(configPath)) configPath = path.join(cwd, '💩.json') // TODO: Ok dude, I know it's late, but you can do better than this.
@@ -82,7 +84,13 @@ function setupWatchers(config, modules) {
 
   // TODO: think about watching the updates of the config file itself, we can reload the config and recompile everything.
   // TODO: ability to automatically create a watch list of directories if watch is set to true. The list will be generated from the `in` property of each task.
-  chokidar.watch(config.watch, { ignoreInitial: true }).on('change', (file) => {
+  // awaitWriteFinish: wait for saves to finish writing before recompiling, so a
+  // mid-write (truncated/partial) file is never read. Fixes intermittent broken
+  // builds on editor save. ponytail: default thresholds are fine; bump if slow disks flake.
+  chokidar.watch(config.watch, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 50 }
+  }).on('change', (file) => {
     if (/(\.m?jsx?|\.tsx?)$/i.test(file)) {
       modules.scripts.compile().catch(err => console.error(err))
 
@@ -179,6 +187,10 @@ if (!config.reactor && config.ssg) {
   config.reactor = config.ssg
 }
 
+if (overrideBaseURL && config.markup) {
+  config.markup.baseURL = overrideBaseURL
+}
+
 async function getAvailablePort(port, max) {
   while (port < max) {
     const status = await portscanner.checkPortStatus(port, 'localhost')