poops 1.9.5 → 1.9.7

package/README.md

@@ -217,7 +217,7 @@ 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 a file path, an array of file paths, or a glob pattern (e.g. `"src/js/*.js"`, `"src/elements/*/index.{js,mjs,cjs,jsx,ts,tsx}"`). 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`). A **glob-matched** `index.*` is named after its directory instead, placed relative to the glob's static prefix: `"src/elements/*/index.js"` gives `<out>/accordion.js`, while `"src/*/accordion/index.js"` keeps the differing segment as `<out>/blocks/accordion.js`. A literal `in: "src/index.js"` keeps its own basename
+- `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`). A **glob-matched** `index.*` is named after its directory instead, placed relative to the glob's static prefix: `"src/elements/*/index.js"` gives `<out>/accordion.js`, while `"src/*/accordion/index.js"` keeps the differing segment as `<out>/blocks/accordion.js`. A literal `in: "src/index.js"` keeps its own basename. To name outputs yourself, `out` can be a **template**: `{{dir}}` is the input's directory relative to the glob's static prefix, `{{name}}` its basename without extension. `"src/elements/*/widget.ts"` with `out: "dist/js/{{dir}}-{{name}}.js"` gives `dist/js/accordion-widget.js` and `dist/js/tabs-widget.js` — one bundle per match, named by you instead of by the common ancestor. The template's extension is honoured too, so `out: "dist/esm/{{dir}}.mjs"` writes `.mjs` files
 - `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:**
@@ -351,7 +351,7 @@ 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, can be a file path, an array of file paths, or a glob pattern (e.g. `"src/scss/*.scss"`, `"src/elements/*/index.{scss,sass,css}"`). 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. A **glob-matched** `index.*` is named after its directory instead, placed relative to the glob's static prefix: `"src/elements/*/index.scss"` gives `<out>/accordion.css`, while `"src/*/accordion/index.scss"` keeps the differing segment as `<out>/blocks/accordion.css`. A literal `in: "src/scss/index.scss"` keeps its own basename
+- `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. A **glob-matched** `index.*` is named after its directory instead, placed relative to the glob's static prefix: `"src/elements/*/index.scss"` gives `<out>/accordion.css`, while `"src/*/accordion/index.scss"` keeps the differing segment as `<out>/blocks/accordion.css`. A literal `in: "src/scss/index.scss"` keeps its own basename. To name outputs yourself, `out` can be a **template**: `{{dir}}` is the input's directory relative to the glob's static prefix, `{{name}}` its basename without extension. `"src/elements/*/theme.scss"` with `out: "dist/{{dir}}-theme.css"` gives `dist/accordion-theme.css` and `dist/tabs-theme.css` — one output per match, instead of every `theme.scss` overwriting the same `theme.css`
 - `options` - the options for the bundler.
 
 **Options:**
@@ -1093,6 +1093,18 @@ All filters are available in both engines. The only syntax difference is how arg
   ---
   ```
 
+  The same `jsonld` object works in your `site` data, as a site-wide default — useful when every page on the site is one type. A docs site is `TechArticle`, not `WebPage`:
+
+  ```json
+  "markup": {
+    "site": {
+      "jsonld": { "@type": "TechArticle" }
+    }
+  }
+  ```
+
+  Precedence is defaults → `site.jsonld` → `page.jsonld`, so a single page can still opt out (a `FAQPage` inside a `TechArticle` site). A site-wide `@type` also overrides the auto-detected `BlogPosting` on dated pages, so on a site mixing docs and a blog set the type per page instead. Both merge into the page's own block only — the auto-emitted `WebSite` and `BreadcrumbList` blocks are untouched.
+
   poops auto-picks `BlogPosting` (page has a `date`) or `WebPage`. Override `@type` with the `jsonld` object for any schema.org type — common ones search/generative engines act on: `Article`, `NewsArticle`, `HowTo`, `FAQPage`, `QAPage`, `Product`, `Recipe`, `Event`, `Course`, `VideoObject`, `SoftwareApplication`, `Organization`, `Person`, `BreadcrumbList`, `WebSite`. Full list at [schema.org/docs/full](https://schema.org/docs/full.html); validate with the [Rich Results Test](https://search.google.com/test/rich-results). A per-`@type` table with the notable fields is in the [Templating docs](example/src/markup/docs/quick-start/templating-html.md).
 
 - `breadcrumb` — generates a visible breadcrumb `<nav class="breadcrumb"><ol>…</ol></nav>` trail for the page body (blog posts, nested pages), from the same URL-depth data the `jsonld` `BreadcrumbList` uses: the site root, each ancestor folder (humanized, e.g. `docs/static-site` → _Static Site_), then the current page as `aria-current` text. Pass `relativePathPrefix` so links resolve against the current output location (localhost in dev, your deployed subpath in prod) — not the absolute domain.

package/lib/markup/helpers.js

@@ -532,10 +532,12 @@ export function buildBreadcrumb(page, site = {}, prefix = '') {
 // gains a `logo` ImageObject when `site.logo` is set — Google Article rich
 // results require it. On the homepage (page has no `url`) a second `WebSite`
 // block is emitted, declaring the site name for search results.
-// Anything in `page.jsonld` (an object) is merged over the generated defaults,
-// so a page can add or replace any field — including @type — as a full escape
-// hatch. Values come from front matter, so the JSON is escaped for a <script>
-// context to prevent a `</script>` break-out (XSS).
+// `site.jsonld` and `page.jsonld` (objects) are merged over the generated
+// defaults — site-wide first, then the page — so a site can set a default
+// @type (a docs site is TechArticle, not WebPage) and a page can still add or
+// replace any field as a full escape hatch. Values come from front matter, so
+// the JSON is escaped for a <script> context to prevent a `</script>`
+// break-out (XSS).
 export function buildJsonLd(page, site = {}) {
   page = page || {}
   site = site || {}
@@ -577,8 +579,10 @@ export function buildJsonLd(page, site = {}) {
     if (page.wordcount) data.wordCount = page.wordcount
   }
 
-  // page.jsonld extends/overrides. Shallow merge — nested schema is rare and
-  // the escape hatch is meant for whole-key replacement.
+  // site.jsonld then page.jsonld extend/override — the page wins. Shallow
+  // merge — nested schema is rare and the escape hatch is meant for whole-key
+  // replacement.
+  if (site.jsonld && typeof site.jsonld === 'object') Object.assign(data, site.jsonld)
   if (page.jsonld && typeof page.jsonld === 'object') Object.assign(data, page.jsonld)
 
   const blocks = [jsonLdScript(data)]

package/lib/scripts.js

@@ -3,15 +3,21 @@ import { globSync, hasMagic } from 'glob'
 import { deepMerge } from 'book-of-spells'
 import {
   pathExists,
+  mkDir,
   mkPath,
   pathForFile,
   isIndexEntry,
   globBase,
   indexEntryOut,
+  entryBase,
+  hasOutTemplate,
+  outTemplateBase,
+  fillOutTemplateEntry,
   fillBannerTemplate,
   buildTime,
   fileSize
 } from './utils/helpers.js'
+import path from 'node:path'
 import minifyToFile from './utils/minify.js'
 import log from './utils/log.js'
 
@@ -30,6 +36,11 @@ export default class Scripts {
       // `in` may be an array of entry points — pathExists on an array throws
       const configured = Array.isArray(scriptEntry.in) ? scriptEntry.in : [scriptEntry.in]
       const entryPoints = []
+      // A templated `out` names one output per entry point. esbuild already
+      // takes a per-entry `out` relative to `outdir` — the same door the
+      // `index.*` rename goes through — so the template resolves into that.
+      const templated = hasOutTemplate(scriptEntry.out)
+      const outBase = templated ? outTemplateBase(scriptEntry.out) : null
       let missing = false
       for (const entry of configured) {
         if (hasMagic(entry, { magicalBraces: true })) {
@@ -44,19 +55,31 @@ export default class Scripts {
           // `index.js` or nests a level deep under esbuild's outbase. Literal
           // entries keep their basename — see `isIndexEntry`.
           const base = globBase(entry)
-          entryPoints.push(...matches.map(match => (
-            isIndexEntry(match) ? { in: match, out: indexEntryOut(match, base) } : match
-          )))
+          entryPoints.push(...matches.map(match => {
+            if (templated) return { in: match, out: fillOutTemplateEntry(scriptEntry.out, match, base, outBase) }
+            return isIndexEntry(match) ? { in: match, out: indexEntryOut(match, base) } : match
+          }))
         } else if (!pathExists(entry)) {
           log({ tag: 'script', error: true, text: 'Entry does not exist:', link: entry })
           missing = true
+        } else if (templated) {
+          entryPoints.push({ in: entry, out: fillOutTemplateEntry(scriptEntry.out, entry, entryBase(entry), outBase) })
         } else {
           entryPoints.push(entry)
         }
       }
       if (missing) continue
-      mkPath(scriptEntry.out)
-      await this.compileEntry(entryPoints, scriptEntry.out, scriptEntry.options)
+      let options = scriptEntry.options
+      if (templated) {
+        mkDir(outBase)
+        // esbuild appends its own extension, so a template asking for one other
+        // than `.js` has to be honoured through `outExtension` or it's ignored
+        const ext = path.posix.extname(scriptEntry.out)
+        if (ext && ext !== '.js') options = { outExtension: { '.js': ext }, ...options }
+      } else {
+        mkPath(scriptEntry.out)
+      }
+      await this.compileEntry(entryPoints, templated ? outBase : scriptEntry.out, options)
     }
   }
 

package/lib/styles.js

@@ -8,6 +8,9 @@ import {
   isIndexEntry,
   globBase,
   indexEntryOut,
+  entryBase,
+  hasOutTemplate,
+  fillOutTemplate,
   fillBannerTemplate,
   buildTime,
   fileSize
@@ -23,10 +26,15 @@ export default class Styles {
   constructor(config) {
     this.config = config
     this.banner = config.banner ? fillBannerTemplate(config.banner) : null
+    // The css files the last compile wrote. Globs and templated `out` name a
+    // file per match, so the config alone can't say what landed where — the
+    // livereload chain reads this to hot-swap exactly the stylesheets rebuilt.
+    this.outputs = []
   }
 
   async compile() {
     if (!this.config.styles) return
+    this.outputs = []
     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
@@ -34,6 +42,8 @@ export default class Styles {
       const configured = Array.isArray(styleEntry.in) ? styleEntry.in : [styleEntry.in]
       const entryPoints = []
       const indexEntries = new Map()
+      const bases = new Map()
+      const templated = hasOutTemplate(styleEntry.out)
       let missing = false
       for (const entry of configured) {
         if (hasMagic(entry, { magicalBraces: true })) {
@@ -50,25 +60,29 @@ export default class Styles {
           const base = globBase(entry)
           for (const match of matches) {
             if (isIndexEntry(match)) indexEntries.set(match, indexEntryOut(match, base))
+            bases.set(match, base)
           }
           entryPoints.push(...matches)
         } else if (!pathExists(entry)) {
           log({ tag: 'style', error: true, text: 'Entry does not exist:', link: entry })
           missing = true
         } else {
+          bases.set(entry, entryBase(entry))
           entryPoints.push(entry)
         }
       }
       if (missing) continue
-      if (entryPoints.length > 1 && pathForFile(styleEntry.out)) {
+      // A templated `out` resolves to a different file per entry point, so the
+      // single-file guard doesn't apply to it
+      if (!templated && 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) {
         // Resolve the index rename here, where `out` is still known to be a dir
-        const out = indexEntries.has(entryPoint) && !pathForFile(styleEntry.out)
-          ? path.join(styleEntry.out, `${indexEntries.get(entryPoint)}.css`)
-          : styleEntry.out
+        let out = styleEntry.out
+        if (templated) out = fillOutTemplate(out, entryPoint, bases.get(entryPoint))
+        else if (indexEntries.has(entryPoint) && !pathForFile(out)) out = path.join(out, `${indexEntries.get(entryPoint)}.css`)
         await this.compileEntry(entryPoint, out, styleEntry.options)
       }
     }
@@ -113,6 +127,7 @@ export default class Styles {
     const mapsrc = options.sourcemap ? `\n/*# sourceMappingURL=${path.basename(outfilePath)}.map */` : ''
     if (this.banner) compiledSass.css = this.banner + '\n' + compiledSass.css
     fs.writeFileSync(outfilePath, compiledSass.css + mapsrc)
+    this.outputs.push(outfilePath) // after the write — a failed compile has nothing to reload
     const stylesEnd = performance.now()
     if (!options.justMinified) log({ tag: 'style', text: 'Compiled:', link: outfilePath, size: fileSize(outfilePath), time: buildTime(stylesStart, stylesEnd) })
 

package/lib/utils/helpers.js

@@ -62,6 +62,45 @@ export function indexEntryOut(inputPath, base) {
   return rel || path.posix.basename(dir)
 }
 
+// The `index.*` rename only saves entry points named `index` — every other
+// glob match still collapses onto its own basename, so `src/elements/*/theme.scss`
+// writes `theme.css` once per element and the last one wins. An `out` carrying
+// `{{dir}}`/`{{name}}` names one output per match instead.
+export function hasOutTemplate(outputPath) {
+  return /{{\s*(dir|name)\s*}}/.test(outputPath)
+}
+
+// `{{dir}}` is the match's directory relative to the glob's static prefix (the
+// same name `index.*` entries get), `{{name}}` its extension-less basename.
+export function fillOutTemplate(template, inputPath, base) {
+  const { name } = path.parse(inputPath)
+  return template
+    .replace(/{{\s*dir\s*}}/g, indexEntryOut(inputPath, base))
+    .replace(/{{\s*name\s*}}/g, name)
+}
+
+// What an entry's outputs are named relative to: a glob's static prefix, or a
+// literal entry's own directory (so `{{dir}}` is that directory's name).
+export function entryBase(entry) {
+  return hasMagic(entry, { magicalBraces: true }) ? globBase(entry) : path.posix.dirname(toPosix(entry))
+}
+
+// The fixed directory a templated `out` writes into — everything before its
+// first token. Only the tail varies per entry point, so this is the one part
+// esbuild (and the watcher's output zones) can be handed up front.
+export function outTemplateBase(outputPath) {
+  return path.posix.dirname(toPosix(outputPath).replace(/\{\{.*$/, ''))
+}
+
+// esbuild names an entry point's output itself, from an `out` that is relative
+// to `outdir` and carries no extension. Resolve the `out` template into that
+// shape so a templated scripts `out` goes through the same machinery the
+// `index.*` rename already uses.
+export function fillOutTemplateEntry(template, inputPath, base, outBase) {
+  const filled = toPosix(fillOutTemplate(template, inputPath, base))
+  return path.posix.relative(outBase, filled).replace(/\.[^./]*$/, '')
+}
+
 export function buildStyleOutputFilePath(inputPath, outputPath) {
   if (pathForFile(outputPath)) return outputPath
   const { name } = path.parse(inputPath)

package/package.json

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

package/poops.js

@@ -3,7 +3,7 @@
 import chokidar from 'chokidar'
 import Copy from './lib/copy.js'
 import runExec, { validateExec } from './lib/exec.js'
-import { pathExists, doesFileBelongToPath, pathContainsPathSegment, deriveWatchDirs, toPosix } from './lib/utils/helpers.js'
+import { pathExists, doesFileBelongToPath, pathContainsPathSegment, deriveWatchDirs, toPosix, hasOutTemplate, outTemplateBase } from './lib/utils/helpers.js'
 import http from 'node:http'
 import net from 'node:net'
 import os from 'node:os'
@@ -89,17 +89,15 @@ function reload(file) {
   }, 500)
 }
 
-// The css output paths of the styles entries — what the styles chain reports
-// to reload() so style edits hot-swap. A directory `out` maps to the entry
-// point's basename, mirroring how the styles compiler names its output file.
+// The css files the last styles compile actually wrote — what the styles chain
+// reports to reload() so style edits hot-swap. Read off the compiler rather
+// than guessed from the config: a glob or a templated `out` names one output
+// per match, and a guessed path the browser has no stylesheet for silently
+// downgrades the hot-swap to a full page reload.
 // toPosix: the livereload client matches these against URL paths, so Windows
 // backslashes would silently break the CSS hot-swap.
-function styleOutputs(config) {
-  return [config.styles].flat()
-    .filter((entry) => entry && entry.in && entry.out)
-    .map((entry) => toPosix(path.extname(entry.out)
-      ? entry.out
-      : path.join(entry.out, path.basename(entry.in).replace(/\.(sass|scss)$/i, '.css'))))
+function styleOutputs(styles) {
+  return styles.outputs.map(toPosix)
 }
 
 // Per-stage shell hooks (config.exec). Runs after a stage compiles in both
@@ -135,7 +133,11 @@ function setupWatchers(config, modules) {
   // the watch list, or every compile retriggers itself.
   const outputZones = [config.scripts, config.styles].flat()
     .filter((entry) => entry && entry.out)
-    .map((entry) => (path.extname(entry.out) ? path.dirname(entry.out) : entry.out))
+    // A templated `out` is only static up to its first token, so zone on that
+    // prefix — `dist/{{dir}}/theme.css` writes into `dist`, not `dist/{{dir}}`
+    .map((entry) => (hasOutTemplate(entry.out)
+      ? outTemplateBase(entry.out)
+      : (path.extname(entry.out) ? path.dirname(entry.out) : entry.out)))
     .filter((zone) => zone && zone !== '.')
   const isBuildOutput = (file) => outputZones.some((zone) => pathContainsPathSegment(file, zone))
 
@@ -161,7 +163,7 @@ function setupWatchers(config, modules) {
 
   const recompileStyles = coalesce(() => {
     modules.styles.compile().then(() => modules.postcss.compile())
-      .then(() => { hook('styles'); styleOutputs(config).forEach((out) => reload(out)) })
+      .then(() => { hook('styles'); styleOutputs(modules.styles).forEach((out) => reload(out)) })
       .catch(err => console.error(err))
   })