poops 1.9.7 → 2.0.0

package/README.md

@@ -54,6 +54,7 @@ It uses a simple config file where you define your input and output paths and it
   - [Live Reload (optional)](#live-reload-optional)
   - [Watch (optional)](#watch-optional)
   - [Include Paths (optional)](#include-paths-optional)
+- [Contributing](#contributing)
 - [Why?](#why)
 
 ## Features
@@ -81,6 +82,8 @@ It uses a simple config file where you define your input and output paths and it
 
 > For a superfast start, you can use the Poops template repository: [💩🌪️Shitstorm](https://github.com/stamat/shitstorm)
 
+Poops requires **Node.js 22 or newer**.
+
 You can install Poops globally:
 
 ```bash
@@ -108,7 +111,6 @@ or pass a custom config. This is useful when you have multiple environments:
 | `--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 |
 | `--quiet`                    | `-q`  | Hide the header and the server/livereload info lines |
 
@@ -118,7 +120,7 @@ The `--base-url` flag is particularly useful for CI/CD pipelines where the deplo
 poops --build --base-url /blog
 ```
 
-The `--quiet` flag drops the `💩 Poops — vX.Y.Z` header (and its terminal bell) plus the `Local server` / `Network` / `LiveReload` lines. Handy when you run several Poops instances side by side and only want to see which one is compiling:
+The `--quiet` flag drops the `💩 Poops — vX.Y.Z` header (and its terminal bell) plus the `Local server` / `Network` / `Live reload` lines. Handy when you run several Poops instances side by side and only want to see which one is compiling:
 
 ```bash
 poops -q & poops -q -c site/poops.json
@@ -181,15 +183,17 @@ Just create a `poops.json` file in the root of your project and add the followin
     }
   ],
   "markup": {
-    "engine": "nunjucks",
     "in": "example/src/markup",
     "out": "/",
-    "site": {
-      "title": "Poops",
-      "description": "A super simple bundler for simple web projects."
-    },
-    "data": ["data/links.json", "data/poops.yaml"],
-    "includePaths": ["_layouts", "_partials"]
+    "options": {
+      "engine": "nunjucks",
+      "site": {
+        "title": "Poops",
+        "description": "A super simple bundler for simple web projects."
+      },
+      "data": ["data/links.json", "data/poops.yaml"],
+      "includePaths": ["_layouts", "_partials"]
+    }
   },
   "copy": [
     {
@@ -226,7 +230,7 @@ Scripts are bundled with [esbuild](https://esbuild.github.io/). Supports `.js`,
 - `minify` - whether to minify the output or not, minification is performed by `esbuild` and is only applied to non-minified files. Default is `false`
 - `justMinified` - whether you want to have a minified file as output only. Removes the non-minified file from the output. Useful for production builds. Default is `false`
 - `format` - the output format, can be `iife` or `esm` or `cjs` - this is a direct esbuild option
-- `target` - the target for the output, can be `es2018` or `es2019` or `es2020` or `esnext` for instance - this is a direct esbuild option
+- `target` - the target for the output, can be `es2018` or `es2019` or `es2020` or `esnext` for instance - this is a direct esbuild option. Default is `es2020`
 - `jsx` - the JSX transform mode, can be `transform` (default) or `automatic`. Use `automatic` for React 17+ JSX runtime which doesn't require importing React in every file - this is a direct esbuild option
 
 `scripts` property can accept an array of script configurations or just a single script configuration. If you want to bundle multiple scripts, just add them to the `scripts` array:
@@ -313,8 +317,6 @@ Each reactor entry has the following properties:
 }
 ```
 
-For backwards compatibility, `"ssg"` is also accepted as a config key — it is treated as an alias for `"reactor"`.
-
 In your templates, use the `inject` name to insert the rendered HTML:
 
 ```html
@@ -526,11 +528,13 @@ npm i -D postcss @tailwindcss/postcss tailwindcss
   "markup": {
     "in": "src/markup",
     "out": "dist",
-    "site": {
-      "title": "Poops + Tailwind",
-      "description": "A Tailwind CSS example for Poops"
-    },
-    "includePaths": ["_layouts", "_partials"]
+    "options": {
+      "site": {
+        "title": "Poops + Tailwind",
+        "description": "A Tailwind CSS example for Poops"
+      },
+      "includePaths": ["_layouts", "_partials"]
+    }
   },
   "serve": { "port": 4040, "base": "/dist" },
   "livereload": true,
@@ -550,9 +554,31 @@ Then use Tailwind utility classes directly in your markup templates. Tailwind v4
 
 ### Markups
 
+`markup` has the same shape as a `scripts` or `styles` entry: `in`, `out`, and
+everything else under `options`.
+
+```json
+{
+  "markup": {
+    "in": "src/markup",
+    "out": "dist",
+    "options": {
+      "engine": "nunjucks",
+      "site": { "title": "My Awesome Site" }
+    }
+  }
+}
+```
+
+> **Deprecated:** Poops 1.x also read these keys directly on `markup`
+> (`"markup": { "site": … }`). That still works in 2.x and warns; it stops
+> working in 3.0. Move them into `options`.
+
+**Options:**
+
 - `engine` (optional) - the template engine to use. Can be `"nunjucks"` (default) or `"liquid"`. [Nunjucks](https://mozilla.github.io/nunjucks/) is a Mozilla template engine inspired by Jinja2. [Liquid](https://liquidjs.com/) is a Shopify-compatible template engine. Both engines support the same tags, filters, collections, search index, sitemap, and navigation tree features documented below.
-- `in` - the input path, can be a directory or a file path, but please just use it as a directory path for now. All files in this directory will be processed and the structure of the directory will be preserved in the output directory with exception to directories that begin with an underscore `_` will be ignored.
-- `out` - the output path, can be only a directory path (for now)
+- `in` (entry, not an option) - the input path, can be a directory or a file path, but please just use it as a directory path for now. All files in this directory will be processed and the structure of the directory will be preserved in the output directory with exception to directories that begin with an underscore `_` will be ignored.
+- `out` (entry, not an option) - the output path, can be only a directory path (for now)
 - `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.
@@ -578,13 +604,15 @@ Here is a sample markup configuration using the default Nunjucks engine:
   "markup": {
     "in": "src/markup",
     "out": "dist",
-    "site": {
-      "title": "My Awesome Site",
-      "description": "This is my awesome site"
-    },
-    "data": ["data/links.json", "data/other.yaml"],
-    "includePaths": ["_includes"],
-    "baseURL": "/blog"
+    "options": {
+      "site": {
+        "title": "My Awesome Site",
+        "description": "This is my awesome site"
+      },
+      "data": ["data/links.json", "data/other.yaml"],
+      "includePaths": ["_includes"],
+      "baseURL": "/blog"
+    }
   }
 }
 ```
@@ -594,15 +622,17 @@ To use Liquid instead, set the `engine` property:
 ```json
 {
   "markup": {
-    "engine": "liquid",
     "in": "src/liquid",
     "out": "dist",
-    "site": {
-      "title": "My Awesome Site",
-      "description": "This is my awesome site"
-    },
-    "data": ["_data/links.json", "_data/other.yaml"],
-    "includePaths": ["_layouts", "_partials"]
+    "options": {
+      "engine": "liquid",
+      "site": {
+        "title": "My Awesome Site",
+        "description": "This is my awesome site"
+      },
+      "data": ["_data/links.json", "_data/other.yaml"],
+      "includePaths": ["_layouts", "_partials"]
+    }
   }
 }
 ```
@@ -661,7 +691,7 @@ The `engine` option also accepts a module specifier — an npm package name or a
   "markup": {
     "in": "src/markup",
     "out": "dist",
-    "engine": "poops-shopify"
+    "options": { "engine": "poops-shopify" }
   }
 }
 ```
@@ -680,7 +710,7 @@ export default class MyEngine {
   get markupExtensions() {
     return "html|liquid|md";
   } // glob alternation of processed extensions
-  registerFilters({ timeDateFormat, markupOut }) {}
+  registerFilters({ dateFormat, markupOut }) {}
   registerTags(getOutputDir) {}
   setGlobal(key, value) {}
   removeGlobal(key) {}
@@ -734,14 +764,16 @@ sort: date
   "markup": {
     "in": "src/markup",
     "out": "dist",
-    "collections": [
-      "changelog",
-      {
-        "name": "blog",
-        "paginate": 5,
-        "sort": { "by": "title", "order": "asc" }
-      }
-    ]
+    "options": {
+      "collections": [
+        "changelog",
+        {
+          "name": "blog",
+          "paginate": 5,
+          "sort": { "by": "title", "order": "asc" }
+        }
+      ]
+    }
   }
 }
 ```
@@ -806,12 +838,14 @@ Pages 2..N automatically get a distinct `<title>` — `Changelog — Page 2` —
 ```json
 {
   "markup": {
-    "site": {
-      "pagination": {
-        "title": "{title} — Seite {n}",
-        "prev": "Zurück",
-        "next": "Weiter",
-        "of": "von"
+    "options": {
+      "site": {
+        "pagination": {
+          "title": "{title} — Seite {n}",
+          "prev": "Zurück",
+          "next": "Weiter",
+          "of": "von"
+        }
       }
     }
   }
@@ -1023,6 +1057,20 @@ The language argument is optional. If omitted, highlight.js will attempt to auto
 
 Registered languages: `javascript`/`js`, `typescript`/`ts`, `css`, `scss`, `html`, `xml`, `json`, `bash`/`sh`, `shell`, `python`/`py`, `ruby`/`rb`, `php`, `java`, `c`, `cpp`, `csharp`/`cs`, `go`, `rust`/`rs`, `yaml`/`yml`, `markdown`/`md`, `sql`, `diff`.
 
+**Fence info strings.** Only the first word names the language. Anything after it is carried onto the `<code>` element instead of being dropped: a bare word becomes a class, a `key=value` token becomes a `data-` attribute. This is how a fence marks itself for a later stage — a post-`markup` `exec` script that turns `code.preview` blocks into live demos, for example — without a marker comment in the markdown.
+
+````md
+```html preview tab=options widths=375,768
+<my-element></my-element>
+```
+````
+
+```html
+<pre><code class="hljs language-html preview" data-tab="options" data-widths="375,768">…</code></pre>
+```
+
+Values are single tokens — no quotes, no spaces. A trailing `=` with nothing after it emits a valueless attribute (`expanded=` → `data-expanded=""`), for a flag you want to read with `hasAttribute` rather than as a class. The same applies to the `{% highlight %}` tag and the `highlight` filter.
+
 #### Custom Filters
 
 All filters are available in both engines. The only syntax difference is how arguments are passed: Nunjucks uses parentheses `| filter("arg")`, Liquid uses a colon `| filter: "arg"`.
@@ -1035,7 +1083,7 @@ All filters are available in both engines. The only syntax difference is how arg
 
 - `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.
+- `date` — formats a date string. Uses [dayjs](https://day.js.org/) format tokens. A default format can be set via the `dateFormat` config option.
   - Nunjucks: `{{ "2024-01-15" | date("MMMM D, YYYY") }}`
   - Liquid: `{{ "2024-01-15" | date: "MMMM D, YYYY" }}`
 
@@ -1097,8 +1145,8 @@ All filters are available in both engines. The only syntax difference is how arg
 
   ```json
   "markup": {
-    "site": {
-      "jsonld": { "@type": "TechArticle" }
+    "options": {
+      "site": { "jsonld": { "@type": "TechArticle" } }
     }
   }
   ```
@@ -1235,17 +1283,17 @@ The string shorthand sets the output filename with default options. For more con
 ```json
 {
   "searchIndex": {
-    "output": "search-index.json",
+    "out": "search-index.json",
     "minWordLength": 3,
     "maxKeywords": 20,
     "globalFrequencyCeiling": 0.8,
     "stopWords": "path/to/custom-stop-words.json"
   },
   "sitemap": {
-    "output": "sitemap.xml"
+    "out": "sitemap.xml"
   },
   "llms": {
-    "output": "llms.txt",
+    "out": "llms.txt",
     "title": "My Site",
     "description": "One-line summary of the site.",
     "intro": "src/llms-intro.md",
@@ -1256,7 +1304,7 @@ The string shorthand sets the output filename with default options. For more con
 
 **Search Index options:**
 
-- `output` — output filename, written to the markup output directory
+- `out` — output filename, written to the markup output directory
 - `minWordLength` — minimum word length to consider as a keyword (default: `3`)
 - `maxKeywords` — maximum keywords per page (default: `20`)
 - `globalFrequencyCeiling` — drop words appearing in more than this fraction of all pages (default: `0.8`, meaning words found in 80%+ of pages are dropped as non-discriminating)
@@ -1288,14 +1336,14 @@ All front matter fields are passed through to the index automatically. Internal
 
 **llms.txt** generates an [`llms.txt`](https://llmstxt.org) — a Markdown index of your pages that LLMs and generative engines (GEO) read to understand your site. It has an `# H1` title, a `> ` blockquote summary, then `- [title](url): description` links grouped by URL path: the first folder is a `## section`, a second folder nests as a `### subsection` under it, and root-level pages fall under a lead "Pages" section. So `docs/config-reference.html` lands directly under `## Docs` while `docs/quick-start/x.html` lands under `### Quick Start` inside it. Collection items (which live under `collection/…`) group the same way and are ordered newest-first by their `date`; other sections keep file order. Set `intro` to a Markdown file path (relative to the project root) to insert free-form context between the blockquote and the link sections — a file authored for LLMs, e.g. `llms-intro.md`. Avoid `##` headings in it; they read as sections. (A raw README is a poor fit — badges, install noise and its own headings collide.) `title` and `description` default to your `site.title`/`site.description`; override them (and the lead section name via `sectionTitle`) with the object form. `site.url` makes the links absolute. Collection index/pagination pages are skipped, like the search index.
 
-Set `full` to also write a companion full-content file — every page's Markdown body concatenated into one file an LLM can ingest whole (the index is the link map; this is the corpus). `true` names it after `output` with a `-full` suffix (`llms.txt` → `llms-full.txt`, `ai.txt` → `ai-full.txt`); pass a string to set the path yourself. The file opens with a `# Full Documentation Archive for {title}` header, a one-line intro naming the site and a `> ` blockquote of the `description` so a whole-file ingest starts with context, then each page becomes an `# title` (its own leading H1 if it has one) + `URL:` line + body, joined by `---`. Set `fullIntro` to a Markdown file path (from the project root) to insert your own preamble after that header — the `full` counterpart to `intro` (inserted verbatim; a missing file warns and is skipped). Only `.md`/`.markdown` sources qualify (a `.njk`/`.liquid` source is template code, not prose); `noindex` and collection-index pages are dropped. Content is the Markdown **source**, so unrendered `{% raw %}{% … %}{% endraw %}` tags or shortcodes in a body pass through verbatim.
+Set `full` to also write a companion full-content file — every page's Markdown body concatenated into one file an LLM can ingest whole (the index is the link map; this is the corpus). `true` names it after `out` with a `-full` suffix (`llms.txt` → `llms-full.txt`, `ai.txt` → `ai-full.txt`); pass a string to set the path yourself. The file opens with a `# Full Documentation Archive for {title}` header, a one-line intro naming the site and a `> ` blockquote of the `description` so a whole-file ingest starts with context, then each page becomes an `# title` (its own leading H1 if it has one) + `URL:` line + body, joined by `---`. Set `fullIntro` to a Markdown file path (from the project root) to insert your own preamble after that header — the `full` counterpart to `intro` (inserted verbatim; a missing file warns and is skipped). Only `.md`/`.markdown` sources qualify (a `.njk`/`.liquid` source is template code, not prose); `noindex` and collection-index pages are dropped. Content is the Markdown **source**, so unrendered `{% raw %}{% … %}{% endraw %}` tags or shortcodes in a body pass through verbatim.
 
-**robots.txt** generates a `robots.txt`. The string shorthand writes an allow-all file (`User-agent: *`, empty `Disallow:`) with a `Sitemap:` line pointing at your generated sitemap — absolute when `site.url` is set. The object form takes `output`, `userAgent`, `allow`/`disallow` (a path or array of paths), and `sitemap` (an explicit URL, or `false` to omit the line):
+**robots.txt** generates a `robots.txt`. The string shorthand writes an allow-all file (`User-agent: *`, empty `Disallow:`) with a `Sitemap:` line pointing at your generated sitemap — absolute when `site.url` is set. The object form takes `out`, `userAgent`, `allow`/`disallow` (a path or array of paths), and `sitemap` (an explicit URL, or `false` to omit the line):
 
 ```json
 {
   "robots": {
-    "output": "robots.txt",
+    "out": "robots.txt",
     "disallow": ["/admin", "/drafts"],
     "sitemap": false
   }
@@ -1330,7 +1378,7 @@ The string shorthand sets the output filename. For docs sites, use the object fo
 ```json
 {
   "nav": {
-    "output": "nav.json",
+    "out": "nav.json",
     "root": "docs",
     "collections": "index",
     "home": false
@@ -1340,7 +1388,7 @@ The string shorthand sets the output filename. For docs sites, use the object fo
 
 **Navigation options:**
 
-- `output` — output filename, written to the markup output directory
+- `out` — output filename, written to the markup output directory
 - `collections` — how to treat collection pages (default `true`):
   - `true` — include every collection page, nested under its collection
   - `false` — exclude all collection pages (drops a blog's posts from the sidebar)
@@ -1431,7 +1479,7 @@ Generate a subscription feed for a [collection](#collections) — no hand-author
     "in": "src/markup",
     "out": "dist",
     "options": {
-      "feed": { "collection": "blog", "output": "blog/feed.rss" }
+      "feed": { "collection": "blog", "out": "blog/feed.rss" }
     }
   }
 }
@@ -1440,7 +1488,7 @@ Generate a subscription feed for a [collection](#collections) — no hand-author
 **Feed options:**
 
 - `collection` — the collection to build the feed from. Omit it to emit a feed for **every** collection.
-- `output` — the file to write. A bare filename (`feed.xml`, the default) is placed inside the collection's own folder (`blog/feed.xml`); a value with a slash is used as-is under the output directory.
+- `out` — the file to write. A bare filename (`feed.xml`, the default) is placed inside the collection's own folder (`blog/feed.xml`); a value with a slash is used as-is under the output directory.
 - `type` — `"rss"` (default) or `"atom"`.
 - `limit` — max items, newest first (default `20`).
 - `title` — channel title (default `"<Collection> | <site.title>"`).
@@ -1583,69 +1631,37 @@ Sets up a local server for your project.
 Server options:
 
 - `port` - the port on which the server will run
-- `base` - the base path of the server, where your HTML files are located
+- `base` - the base path of the server, where your HTML files are located. Defaults to the markup `out` directory, so most configs can leave it out
 
 If you don't want to run a local server, just remove the `serve` property from the config.
 
 ### Live Reload (optional)
 
-Sets up a livereload server for your project.
-
-Live reload options:
-
-- `port` - the port on which the livereload server will run
-- `exclude` - an array of files and directories to exclude from livereload
-- `extraExts` - an array of extra file extensions (without the dot) that trigger a browser refresh, added to the defaults
-- `exts` - an array of file extensions that replaces the default list entirely
-
-By default a refresh is triggered by changes to: `html`, `css`, `js`, `png`, `gif`, `jpg`, `php`, `php5`, `py`, `rb`, `erb`, `coffee`. If you work with other file types, for example Slim or Nunjucks templates, add them:
-
-```json
-{
-  "livereload": {
-    "extraExts": ["slim", "njk"]
-  }
-}
-```
-
-`livereload` can only be `true`, which means that it will run on the default port (`35729`) or you can specify a port:
-
-```json
-{
-  "livereload": {
-    "port": whateverPortYouWant
-  }
-}
-```
-
-You can also exclude files and directories from livereload:
+Reloads the browser when a build finishes. It is a switch, nothing more:
 
 ```json
 {
-  "livereload": {
-    "exclude": ["some_directory/**/*", "some_other_directory/**/*"]
-  }
+  "serve": { "base": "dist" },
+  "livereload": true
 }
 ```
 
-In order for Livereload to work, you need to add the following script snippet to your HTML files in your development environment:
+Live reload rides the `serve` port — there is no second server and no port to
+configure, so it needs `serve` to be on. With both set, Poops answers
+`/__poops_reload` as a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
+stream and appends a small client script to every HTML page it serves. **Your
+templates need no snippet.** Nothing is injected into your build output — the
+script exists only in the response the dev server writes.
 
-```html
-<script>
-  document.write(
-    '<script src="http://' +
-      (location.host || "localhost").split(":")[0] +
-      ':35729/livereload.js?snipver=1"></' +
-      "script>",
-  );
-</script>
-```
+A save triggers exactly one reload, after the build that follows it has
+finished. When everything a build wrote is CSS, the stylesheets are swapped in
+place instead: the page is not reloaded, so scroll position, open dialogs and
+form state survive a style edit.
 
-Be mindful of the port, if you have specified a custom port, you need to change the port in the snippet as well.
+The browser reconnects on its own, so restarting Poops picks the open tabs back
+up without touching them.
 
-You can also use a browser extension for livereload, for instance here is one for [Chrome](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei?hl=en). You can find also extensions for Firefox and Opera, but NOT for Safari.
-
-If you don't want to run livereload, just remove the `livereload` property from the config, or set it to false.
+To turn it off, remove the `livereload` property or set it to `false`.
 
 ### Watch (optional)
 
@@ -1673,6 +1689,14 @@ Same as `watch` property, `includePaths` accepts an array of paths to include. I
 }
 ```
 
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
+for how to set up, what a PR needs, and how releases are cut.
+
+Released changes are in [CHANGELOG.md](CHANGELOG.md), written up in full on the
+[changelog site](https://stamat.info/poops/changelog/).
+
 ## Why?
 
 Why doesn't anyone maintain GULP anymore? Why does Parcel hate config files? Why are Rollup and Webpack so complex to setup for simple tasks? Vite???? What's going on?

package/lib/markup/collections.js

@@ -33,7 +33,10 @@ export function getSingleCollectionData(markupInDir, collectionName) {
     frontMatter.wordcount = wordcount(content)
     frontMatter.excerpt = excerpt(content)
     frontMatter.fileName = path.basename(file)
-    frontMatter.filePath = path.relative(process.cwd(), file)
+    // posix, like the page.filePath a template gets for a non-collection page —
+    // both feed "edit this page on GitHub" links, and a Windows backslash in one
+    // would produce a broken URL for collection items only
+    frontMatter.filePath = toPosix(path.relative(process.cwd(), file))
     frontMatter.collection = collectionName
     frontMatter.url = toPosix(path.join(collectionName, path.basename(frontMatter.filePath)))
 

package/lib/markup/engines/liquid.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { Liquid } from 'liquidjs'
-import { highlightCode } from '../highlight.js'
+import { highlightCode, codeBlock } from '../highlight.js'
 import { marked, renderMarkdownCached } from '../renderer.js'
 import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc, buildJsonLd, buildOpenGraph, buildCanonical, buildBreadcrumb } from '../helpers.js'
 import { getImageExif, listImages } from '../image-cache.js'
@@ -83,7 +83,7 @@ export default class LiquidEngine {
   get indexableExtensions() { return new Set(['.html', '.md', '.liquid']) }
   get markupExtensions() { return 'html|xml|rss|atom|json|liquid|md' }
 
-  registerFilters({ timeDateFormat, markupOut }) {
+  registerFilters({ dateFormat, markupOut }) {
     const engine = this.engine
     engine.registerFilter('slugify', (str) => slugify(str))
     engine.registerFilter('humanize', (str) => humanize(str))
@@ -91,7 +91,7 @@ export default class LiquidEngine {
     engine.registerFilter('markdown', (str) => marked.parse(String(str || '')))
     engine.registerFilter('toc', (html) => renderToc(String(html || '')))
     engine.registerFilter('date', (str, template) => {
-      const fmt = template || timeDateFormat
+      const fmt = template || dateFormat
       if (!fmt) return str
       const date = !str || (typeof str === 'string' && str.trim() === '') ? new Date() : new Date(str)
       return dayjs(date).format(fmt)
@@ -131,11 +131,7 @@ export default class LiquidEngine {
     engine.registerFilter('canonical', (page, site) => buildCanonical(page, site))
     engine.registerFilter('breadcrumb', (page, site, prefix) => buildBreadcrumb(page, site, prefix))
     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}` : ''
-      return `<pre><code class="hljs${langClass}">${highlighted}</code></pre>`
-    })
+    engine.registerFilter('highlight', (code, lang) => codeBlock(highlightCode(code, lang), lang))
   }
 
   registerTags(getOutputDir) {
@@ -347,10 +343,7 @@ function registerHighlightTag(engine) {
     },
     * render(ctx) {
       const code = yield this.liquid.renderer.renderTemplates(this.templates, ctx)
-      const lang = this.lang
-      const highlighted = highlightCode(code, lang)
-      const langClass = lang ? ` language-${lang}` : ''
-      return `<pre><code class="hljs${langClass}">${highlighted}</code></pre>`
+      return codeBlock(highlightCode(code, this.lang), this.lang)
     }
   })
 }

package/lib/markup/engines/nunjucks.js

@@ -6,7 +6,7 @@ import path from 'node:path'
 import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc, buildJsonLd, buildOpenGraph, buildCanonical, buildBreadcrumb } from '../helpers.js'
 import { getImageExif, listImages } from '../image-cache.js'
 import { toPosix } from '../../utils/helpers.js'
-import { highlightCode } from '../highlight.js'
+import { highlightCode, codeBlock } from '../highlight.js'
 import { marked, renderMarkdownCached } from '../renderer.js'
 import { slugify, humanize } from 'book-of-spells'
 import dayjs from 'dayjs'
@@ -144,7 +144,7 @@ export default class NunjucksEngine {
   get indexableExtensions() { return new Set(['.html', '.md', '.njk']) }
   get markupExtensions() { return 'html|xml|rss|atom|json|njk|md' }
 
-  registerFilters({ timeDateFormat, markupOut }) {
+  registerFilters({ dateFormat, markupOut }) {
     const env = this.env
     env.addFilter('slugify', slugify)
     env.addFilter('humanize', humanize)
@@ -173,7 +173,7 @@ export default class NunjucksEngine {
       return new nunjucks.runtime.SafeString(content)
     })
     env.addFilter('date', (str, template) => {
-      const fmt = template || timeDateFormat
+      const fmt = template || dateFormat
       if (!fmt) return str
       const date = !str || str.trim() === '' ? new Date() : new Date(str)
       return dayjs(date).format(fmt)
@@ -197,11 +197,7 @@ export default class NunjucksEngine {
     env.addFilter('canonical', (page, site) => new nunjucks.runtime.SafeString(buildCanonical(page, site)))
     env.addFilter('breadcrumb', (page, site, prefix) => new nunjucks.runtime.SafeString(buildBreadcrumb(page, site, prefix)))
     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}` : ''
-      return new nunjucks.runtime.SafeString(`<pre><code class="hljs${langClass}">${highlighted}</code></pre>`)
-    })
+    env.addFilter('highlight', (code, lang) => new nunjucks.runtime.SafeString(codeBlock(highlightCode(code, lang), lang)))
   }
 
   registerTags(getOutputDir) {
@@ -335,12 +331,7 @@ export class HighlightExtension {
   }
 
   run(context, lang, body) {
-    const code = body()
-    const highlighted = highlightCode(code, lang)
-    const langClass = lang ? ` language-${lang}` : ''
-    return new nunjucks.runtime.SafeString(
-      `<pre><code class="hljs${langClass}">${highlighted}</code></pre>`
-    )
+    return new nunjucks.runtime.SafeString(codeBlock(highlightCode(body(), lang), lang))
   }
 }
 

package/lib/markup/highlight.js

@@ -58,20 +58,53 @@ function escapeHtml(str) {
   return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
 }
 
-export function highlightCode(code, language) {
-  if (language) {
-    const lang = language.toLowerCase().trim()
-    if (hljs.getLanguage(lang)) {
-      return hljs.highlight(code, { language: lang }).value
+// A fence's info string is everything after the backticks — the language plus
+// any meta words (```html preview). Only the first word names the language, so
+// the rest has to come off before a hljs lookup or a `language-` class: with it
+// attached, getLanguage misses and the block silently falls to auto-detection.
+export function fenceLang(info) {
+  return String(info || '').trim().split(/\s+/)[0].toLowerCase()
+}
+
+// Everything after the language is the fence's own markup for a later stage:
+// a bare word becomes a class (```html preview → code.preview), `key=value`
+// becomes a data attribute (tab=options → data-tab="options"). Values are
+// single tokens — no quotes, no spaces — which keeps the parser a split and is
+// enough for settings; anything longer belongs in the markdown around the fence.
+export function fenceAttrs(info) {
+  const [lang, ...rest] = String(info || '').trim().split(/\s+/).filter(Boolean)
+  const classes = ['hljs']
+  if (lang) classes.push(`language-${lang.toLowerCase().replace(/[^\w-]/g, '')}`)
+  let data = ''
+  for (const token of rest) {
+    const eq = token.indexOf('=')
+    if (eq < 0) {
+      const name = token.replace(/[^\w-]/g, '')
+      if (name) classes.push(name)
+      continue
     }
+    const key = token.slice(0, eq).replace(/[^\w-]/g, '')
+    if (key) data += ` data-${key}="${escapeHtml(token.slice(eq + 1))}"`
+  }
+  return ` class="${classes.join(' ')}"${data}`
+}
+
+// The one place a highlighted fence becomes html. Every renderer and engine
+// goes through it, so they cannot drift on what a fence produces again.
+export function codeBlock(highlighted, info) {
+  return `<pre><code${fenceAttrs(info)}>${highlighted}</code></pre>`
+}
+
+export function highlightCode(code, language) {
+  const lang = fenceLang(language)
+  if (lang && hljs.getLanguage(lang)) {
+    return hljs.highlight(code, { language: lang }).value
   }
   return hljs.highlightAuto(code).value
 }
 
 export const highlightRenderer = {
   code({ text, lang }) {
-    const highlighted = highlightCode(text, lang)
-    const langClass = lang ? ` language-${escapeHtml(lang)}` : ''
-    return `<pre><code class="hljs${langClass}">${highlighted}</code></pre>\n`
+    return `${codeBlock(highlightCode(text, lang), lang)}\n`
   }
 }