poops 1.2.1 → 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
@@ -507,6 +523,7 @@ Then use Tailwind utility classes directly in your markup templates. Tailwind v4
 - `site` (optional) - global data that will be available to all templates in the markup directory. Like site title, description, social media links, etc. You can then use this data in your templates `{{ site.title }}` for instance.
 - `data` (optional) - is an array of JSON or YAML data files, that once loaded will be available to all templates in the markup directory. If you provide a path to a file for instance `links.json` with a `facebook` property, you can then use this data in your templates `{{ links.facebook }}`. The base name of the file will be used as the variable name, with spaces, dashes and dots replaced with underscores. So `the awesome-links.json` will be available as `{{ the_awesome_links.facebook }}` in your templates. The root directory of the data files is `in` directory. So if you have a `data` directory in your `in` directory, you can specify the data files like this `data: ["data/links.json"]`. The same goes for the YAML files.
 - `includePaths` - an array of paths to directories that will be added to the template engine's include paths. Useful if you want to separate template partials and layouts. For instance, if you have a `_includes` directory with a `header.njk` (or `header.liquid`) partial that you want to include in your markup, you can add it to the include paths and then include the templates like this `{% include "header.njk" %}`, without specifying the full path to the partial.
+- `baseURL` (optional) - a base URL prefix to use instead of relative path prefixes. When set, `{{ relativePathPrefix }}` will always resolve to this value (with a trailing slash ensured) instead of being computed relative to each page's depth. Useful when deploying under a subdirectory (e.g. `"/blog"` for `domain.com/blog/`). When not set, relative prefixes (`./`, `../`, etc.) are used, which work for any deployment location including subdirectories and `file://` URLs.
 
 **💡 NOTE:** If, for instance, you are building a simple static onepager for your library, and want to pass a version variable from your `package.json`, Poops automatically reads your `package.json` if it exists in your working directory and sets the global variable `package` to the parsed JSON. So you can use it in your markup files, for example like this: `{{ package.version }}`.
 
@@ -527,7 +544,8 @@ Here is a sample markup configuration using the default Nunjucks engine:
     ],
     "includePaths": [
       "_includes"
-    ]
+    ],
+    "baseURL": "/blog"
   }
 }
 ```
@@ -726,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
@@ -182,7 +185,7 @@ export function getCollectionIndexFile(markupInDir, collectionName) {
   return indexFiles[0]
 }
 
-export function generateCollectionPaginationPages(collectionData, markupInDir, markupOutDir, compileEntryFn) {
+export function generateCollectionPaginationPages(collectionData, markupInDir, markupOutDir, compileEntryFn, baseURL) {
   if (!collectionData) return []
 
   const compilePromises = []
@@ -201,7 +204,7 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
       const pageUrl = pageNumber === 1 ? collection.name : `${collection.name}/${pageNumber}`
       const nextPage = pageNumber === collection.totalPages ? null : pageNumber + 1
       const nextPageUrl = pageNumber === collection.totalPages ? null : `${collection.name}/${pageNumber + 1}`
-      let prevPage = pageNumber === 1 ? null : pageNumber - 1
+      const prevPage = pageNumber === 1 ? null : pageNumber - 1
       let prevPageUrl = pageNumber === 1 ? null : `${collection.name}/${pageNumber - 1}`
       if (prevPage === 1) {
         prevPageUrl = collection.name
@@ -228,7 +231,7 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
       const context = {
         ...collectionData,
         [collectionName]: pageSnapshot,
-        relativePathPrefix: getRelativePathPrefix(markupOutDirFull, fromPath),
+        relativePathPrefix: getRelativePathPrefix(markupOutDirFull, fromPath, baseURL),
         _url: getPageUrl(markupOut)
       }
 

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) {
@@ -148,7 +195,11 @@ export function getUpDirPrefix(relativeDir) {
   return upDir
 }
 
-export function getRelativePathPrefix(outputDir, fromDir) {
+export function getRelativePathPrefix(outputDir, fromDir, baseURL) {
+  if (baseURL != null) {
+    return baseURL.endsWith('/') ? baseURL : baseURL + '/'
+  }
+
   let relativeDir = path.relative(process.cwd(), outputDir)
   const fromRelativeDir = fromDir ? path.relative(process.cwd(), fromDir) : ''
 
@@ -156,7 +207,7 @@ export function getRelativePathPrefix(outputDir, fromDir) {
     relativeDir = relativeDir.replace(fromRelativeDir, '')
   }
 
-  return getUpDirPrefix(relativeDir)
+  return getUpDirPrefix(relativeDir) || './'
 }
 
 export function getPageUrl(outputPath) {

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'
@@ -35,6 +35,7 @@ export default class Markups {
     this.includePaths = moduleConfig.includePaths || moduleConfig.options.includePaths || []
     this.searchIndexConfig = moduleConfig.options.searchIndex || moduleConfig.searchIndex
     this.sitemapConfig = moduleConfig.options.sitemap || moduleConfig.sitemap
+    this.baseURL = moduleConfig.baseURL || moduleConfig.options.baseURL || null
     this.dataFiles = []
 
     // Instantiate engine
@@ -151,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)
@@ -196,7 +198,7 @@ export default class Markups {
 
       const fileContext = {
         ...collectionData,
-        relativePathPrefix: getRelativePathPrefix(markupOutDir, fromPath),
+        relativePathPrefix: getRelativePathPrefix(markupOutDir, fromPath, this.baseURL),
         _url: getPageUrl(markupOut)
       }
 
@@ -254,7 +256,7 @@ export default class Markups {
 
     const fileContext = {
       ...collectionData,
-      relativePathPrefix: getRelativePathPrefix(markupOutDir),
+      relativePathPrefix: getRelativePathPrefix(markupOutDir, null, this.baseURL),
       _url: getPageUrl(markupOut)
     }
 
@@ -321,7 +323,7 @@ export default class Markups {
     const pageEntries = shouldIndex ? [] : null
 
     buildCollectionPaginationData(collectionData)
-    const collectionPromises = generateCollectionPaginationPages(collectionData, this.markupIn, this.markupOut, this.compileEntry.bind(this))
+    const collectionPromises = generateCollectionPaginationPages(collectionData, this.markupIn, this.markupOut, this.compileEntry.bind(this), this.baseURL)
 
     await Promise.all(collectionPromises)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops",
   "description": "Straightforward, no-bullshit bundler for the web.",
-  "version": "1.2.1",
+  "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')