poops 1.3.0 → 1.4.1

package/README.md

@@ -24,6 +24,37 @@ Intuitive with a minimal learning curve and minimal docs, utilizing the most eff
 
 It uses a simple config file where you define your input and output paths and it poops out your bundled files. Simple as that.
 
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Scripts](#scripts)
+    - [JSX/TSX (React) Example](#jsxtsx-react-example)
+  - [Reactor (React Pre-rendering)](#reactor-react-pre-rendering)
+  - [Styles](#styles)
+    - [Design Tokens](#design-tokens)
+  - [PostCSS (optional)](#postcss-optional)
+    - [Tailwind CSS Example](#tailwind-css-example)
+  - [Markups](#markups)
+    - [Nunjucks vs Liquid](#nunjucks-vs-liquid)
+    - [Custom Engines](#custom-engines)
+    - [Collections & Pagination](#collections--pagination)
+    - [Custom Tags](#custom-tags)
+      - [image](#image)
+      - [googleFonts](#googlefonts)
+      - [highlight](#highlight)
+    - [Custom Filters](#custom-filters)
+    - [Search Index, Sitemap & Navigation](#search-index-sitemap--navigation)
+  - [Images (optional)](#images-optional)
+  - [Copy](#copy)
+  - [Banner (optional)](#banner-optional)
+  - [Local Server (optional)](#local-server-optional)
+  - [Live Reload (optional)](#live-reload-optional)
+  - [Watch (optional)](#watch-optional)
+  - [Include Paths (optional)](#include-paths-optional)
+- [Why?](#why)
+
 ## Features
 
 - Bundles SCSS/SASS to CSS
@@ -174,8 +205,8 @@ You can freely remove the properties that you don't need. For example, if you do
 
 Scripts are bundled with [esbuild](https://esbuild.github.io/). Supports `.js`, `.ts`, `.jsx`, and `.tsx` files out of the box — including React and other JSX frameworks. You can specify multiple scripts to bundle. Each script has the following properties:
 
-- `in` - the input path, can be an array of file paths, but please just use one file path per script
-- `out` - the output path, can be a directory or a file path, but please just use it as a filename
+- `in` - the input path, can be a file path, an array of file paths, or a glob pattern (e.g. `"src/js/*.js"`). Globs must use `/` separators (even on Windows)
+- `out` - the output path, can be a directory or a file path. With multiple inputs it must be a directory — entry points from different directories nest their output under the common ancestor (esbuild's `outbase`)
 - `options` - the options for the bundler. You can apply most of the esbuild options that are not in conflict with Poops. See [esbuild's options](https://esbuild.github.io/api/#build-api) for more info.
 
 **Options:**
@@ -308,8 +339,8 @@ Poops does not need `react` or `react-dom` as its own dependency — they are re
 
 Styles are bundled with [Dart Sass](https://sass-lang.com/dart-sass). You can specify multiple styles to bundle. Each style has the following properties:
 
-- `in` - the input path, accepts only a path to a file
-- `out` - the output path, can be a directory or a file path, but please just use it as a filename
+- `in` - the input path, can be a file path, an array of file paths, or a glob pattern (e.g. `"src/scss/*.scss"`). Globs must use `/` separators (even on Windows) and skip Sass partials (`_*.scss`). Each matched file is compiled separately
+- `out` - the output path, can be a directory or a file path. With multiple inputs it must be a directory — each input compiles to `<out>/<basename>.css`, so inputs sharing a basename (e.g. `a/main.scss` and `b/main.scss`) will overwrite each other
 - `options` - the options for the bundler.
 
 **Options:**
@@ -465,37 +496,34 @@ You can also pass options to plugins using the tuple form:
 
 #### Tailwind CSS Example
 
-The `example-tailwind/` directory demonstrates using Tailwind CSS v4 with Poops. To run it:
+Install the deps, then use a config like this:
 
 ```bash
 npm i -D postcss @tailwindcss/postcss tailwindcss
-node poops.js -c example-tailwind/poops.json
 ```
 
-The example config (`example-tailwind/poops.json`):
-
 ```json
 {
   "postcss": {
-    "in": "example-tailwind/src/css/main.css",
-    "out": "example-tailwind/dist/css/main.css",
+    "in": "src/css/main.css",
+    "out": "dist/css/main.css",
     "options": {
       "plugins": ["@tailwindcss/postcss"],
       "minify": true
     }
   },
   "markup": {
-    "in": "example-tailwind/src/markup",
-    "out": "example-tailwind/dist",
+    "in": "src/markup",
+    "out": "dist",
     "site": {
       "title": "Poops + Tailwind",
       "description": "A Tailwind CSS example for Poops"
     },
     "includePaths": ["_layouts", "_partials"]
   },
-  "serve": { "port": 4041, "base": "/example-tailwind/dist" },
+  "serve": { "port": 4040, "base": "/dist" },
   "livereload": true,
-  "watch": ["example-tailwind/src"]
+  "watch": ["src"]
 }
 ```
 
@@ -592,16 +620,26 @@ An engine class implements this contract (see [`lib/markup/engines/`](lib/markup
 
 ```js
 export default class MyEngine {
-  constructor(templatesDir, includePaths, options) {}      // options: { autoescape }
-  get fileExtension() { return '.liquid' }                 // native template extension
-  get indexableExtensions() { return new Set(['.html']) }  // extensions eligible for search index/nav
-  get markupExtensions() { return 'html|liquid|md' }       // glob alternation of processed extensions
+  constructor(templatesDir, includePaths, options) {} // options: { autoescape }
+  get fileExtension() {
+    return ".liquid";
+  } // native template extension
+  get indexableExtensions() {
+    return new Set([".html"]);
+  } // extensions eligible for search index/nav
+  get markupExtensions() {
+    return "html|liquid|md";
+  } // glob alternation of processed extensions
   registerFilters({ timeDateFormat, markupOut }) {}
   registerTags(getOutputDir) {}
   setGlobal(key, value) {}
   removeGlobal(key) {}
-  async render(templatePath, context) { return 'html' }    // templatePath is an absolute file path
-  async renderString(source, context) { return 'html' }
+  async render(templatePath, context) {
+    return "html";
+  } // templatePath is an absolute file path
+  async renderString(source, context) {
+    return "html";
+  }
 }
 ```
 
@@ -610,12 +648,12 @@ Optionally, an engine may implement `replaceOutExtensions(outputPath)` to contro
 The easiest starting point is extending a built-in engine — deep imports are intentionally supported for this:
 
 ```js
-import LiquidEngine from 'poops/lib/markup/engines/liquid.js'
+import LiquidEngine from "poops/lib/markup/engines/liquid.js";
 
 export default class MyEngine extends LiquidEngine {
   registerFilters(opts) {
-    super.registerFilters(opts)
-    this.engine.registerFilter('shout', (str) => String(str).toUpperCase())
+    super.registerFilters(opts);
+    this.engine.registerFilter("shout", (str) => String(str).toUpperCase());
   }
 }
 ```
@@ -858,7 +896,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. Usage: `{{ "**bold**" | markdown }}`
+- `markdown` — renders a markdown string to HTML with GitHub-style emoji shortcodes (e.g. `:rocket:` → 🚀). 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") }}`
@@ -1088,12 +1126,23 @@ The string shorthand sets the output filename. For docs sites, use the object fo
 
 ```json
 [
-  { "title": "Guide", "url": "guide", "order": 1, "children": [
-    { "title": "Getting Started", "url": "guide/getting-started", "order": 1 },
-    { "title": "Advanced", "url": "guide/advanced", "children": [
-      { "title": "Config", "url": "guide/advanced/config" }
-    ]}
-  ]}
+  {
+    "title": "Guide",
+    "url": "guide",
+    "order": 1,
+    "children": [
+      {
+        "title": "Getting Started",
+        "url": "guide/getting-started",
+        "order": 1
+      },
+      {
+        "title": "Advanced",
+        "url": "guide/advanced",
+        "children": [{ "title": "Config", "url": "guide/advanced/config" }]
+      }
+    ]
+  }
 ]
 ```
 

package/lib/markup/engines/liquid.js

@@ -45,7 +45,7 @@ export default class LiquidEngine {
     const engine = this.engine
     engine.registerFilter('slugify', (str) => slugify(str))
     engine.registerFilter('jsonify', (obj) => JSON.stringify(obj))
-    engine.registerFilter('markdown', (str) => marked.parse(str))
+    engine.registerFilter('markdown', (str) => marked.parse(String(str || '')))
     engine.registerFilter('toc', (html) => renderToc(String(html || '')))
     engine.registerFilter('date', (str, template) => {
       const fmt = template || timeDateFormat

package/lib/markup/engines/nunjucks.js

@@ -79,7 +79,7 @@ export default class NunjucksEngine {
     const env = this.env
     env.addFilter('slugify', slugify)
     env.addFilter('jsonify', (obj) => JSON.stringify(obj))
-    env.addFilter('markdown', (str) => marked.parse(str))
+    env.addFilter('markdown', (str) => marked.parse(String(str || '')))
     env.addFilter('toc', (html) => {
       const toc = renderToc(String(html || ''))
       // plain '' (falsy) when there are no headings, so `{% if x | toc %}` can

package/lib/markup/renderer.js

@@ -1,4 +1,6 @@
 import { Marked } from 'marked'
+import { markedGithubEmoji } from 'marked-github-emoji'
+import { markedGithubAlerts } from 'marked-github-alerts'
 import { slugify } from 'book-of-spells'
 import { highlightRenderer, highlightCode } from './highlight.js'
 import { decodeTemplateEntities } from './helpers.js'
@@ -50,6 +52,12 @@ export const markdownRenderer = {
 
 // One shared instance so both engines render markdown identically.
 export const marked = new Marked({ renderer: markdownRenderer })
+marked.use(markedGithubEmoji())
+marked.use(markedGithubAlerts({
+  alerts: {
+    info: { title: 'Info', icon: 'info' }
+  }
+}))
 
 // 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

@@ -223,6 +223,7 @@ export default class Markups {
     try {
       const frontMatterResult = parseFrontMatter(templateName)
       context.page = frontMatterResult.frontMatter
+      context.page.content = frontMatterResult.content
       context.page.wordcount = wordcount(frontMatterResult.content)
     } catch (err) {
       log({ tag: 'error', text: 'Failed parsing front matter:', link: templateName })

package/lib/styles.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs'
+import { globSync, hasMagic } from 'glob'
 import {
   pathExists,
   mkPath,
+  pathForFile,
   buildStyleOutputFilePath,
   fillBannerTemplate,
   buildTime,
@@ -25,12 +27,35 @@ export default class Styles {
     this.config.styles = Array.isArray(this.config.styles) ? this.config.styles : [this.config.styles]
     for (const styleEntry of this.config.styles) {
       if (!styleEntry.in || !styleEntry.out) continue
-      if (!pathExists(styleEntry.in)) {
-        log({ tag: 'style', error: true, text: 'Entry does not exist:', link: styleEntry.in })
-        continue
+      // `in` may be an array of entry points and/or globs — same resolution as scripts
+      const configured = Array.isArray(styleEntry.in) ? styleEntry.in : [styleEntry.in]
+      const entryPoints = []
+      let missing = false
+      for (const entry of configured) {
+        if (hasMagic(entry)) {
+          // Globs must use `/` even on Windows; sort for deterministic build order.
+          // Skip sass partials (_*.scss) — they are imports, not entry points.
+          const matches = globSync(entry, { posix: true }).filter(match => !path.basename(match).startsWith('_')).sort()
+          if (!matches.length) {
+            log({ tag: 'style', error: true, text: 'Entry does not exist:', link: entry })
+            missing = true
+          }
+          entryPoints.push(...matches)
+        } else if (!pathExists(entry)) {
+          log({ tag: 'style', error: true, text: 'Entry does not exist:', link: entry })
+          missing = true
+        } else {
+          entryPoints.push(entry)
+        }
+      }
+      if (missing) continue
+      if (entryPoints.length > 1 && pathForFile(styleEntry.out)) {
+        log({ tag: 'error', text: 'Cannot output multiple style files to a single file. Please specify an output directory path instead.' })
+        process.exit(1)
+      }
+      for (const entryPoint of entryPoints) {
+        await this.compileEntry(entryPoint, styleEntry.out, styleEntry.options)
       }
-      mkPath(styleEntry.out)
-      await this.compileEntry(styleEntry.in, styleEntry.out, styleEntry.options)
     }
   }
 
@@ -58,6 +83,7 @@ export default class Styles {
     }
 
     outfilePath = buildStyleOutputFilePath(infilePath, outfilePath)
+    mkPath(outfilePath) // resolved file path — mkPath on a dir out is a no-op
 
     const stylesStart = performance.now()
     let compiledSass

package/lib/utils/helpers.js

@@ -181,3 +181,33 @@ export function doesFileBelongToPath(filePath, configPaths) {
   }
   return false
 }
+
+// Derive the watch list from every task's `in` path when watch is `true`.
+// File entries (scripts/styles/reactor) resolve to their parent dir so sibling
+// imports still retrigger a rebuild; dir entries (markup/copy/images) are
+// watched as-is. Imports that reach outside a task's own dir aren't covered —
+// use an explicit `watch` array for that. includePaths is skipped on purpose:
+// it defaults to node_modules, which must never be watched.
+export function deriveWatchDirs(config) {
+  const paths = []
+  const collect = (task) => {
+    if (!task) return
+    for (const entry of [].concat(task)) {
+      if (!entry || typeof entry !== 'object') continue
+      if (entry.in) paths.push(...(Array.isArray(entry.in) ? entry.in : [entry.in]))
+      if (entry.component) paths.push(entry.component) // reactor source component
+      const tokenPaths = entry.options && entry.options.tokenPaths
+      if (tokenPaths) paths.push(...[].concat(tokenPaths))
+    }
+  }
+  collect(config.scripts)
+  collect(config.styles)
+  collect(config.reactor)
+  collect(config.markup)
+  collect(config.copy)
+  collect(config.images)
+  // ponytail: extname()-based dir/file split misreads dot-named dirs (rare);
+  // the escape hatch is an explicit watch array.
+  return [...new Set(paths.map((p) => (path.extname(p) ? path.dirname(p) : p)))]
+    .filter((p) => p && p !== '.')
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops",
   "description": "Straightforward, no-bullshit bundler for the web.",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "license": "MIT",
   "type": "module",
   "main": "poops.js",
@@ -62,6 +62,8 @@
     "liquidjs": "^10.24.0",
     "livereload": "^0.9.3",
     "marked": "^9.0.3",
+    "marked-github-alerts": "^1.0.1",
+    "marked-github-emoji": "^1.0.2",
     "nunjucks": "^3.2.4",
     "portscanner": "^2.2.0",
     "printstyle": "^1.0.0",

package/poops.js

@@ -3,7 +3,7 @@
 import chokidar from 'chokidar'
 import connect from 'connect'
 import Copy from './lib/copy.js'
-import { pathExists, doesFileBelongToPath, pathContainsPathSegment } from './lib/utils/helpers.js'
+import { pathExists, doesFileBelongToPath, pathContainsPathSegment, deriveWatchDirs } from './lib/utils/helpers.js'
 import http from 'node:http'
 import os from 'node:os'
 import fs from 'node:fs'
@@ -249,7 +249,9 @@ if (!pathExists(configPath)) {
 // Load poops.json
 const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
 
-if (config.watch) {
+if (config.watch === true) {
+  config.watch = deriveWatchDirs(config)
+} else if (config.watch) {
   config.watch = Array.isArray(config.watch) ? config.watch : [config.watch]
 }