ssqch 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +2 -0
  2. package/bundled/README.md +144 -77
  3. package/bundled/ssqch.d.ts +17 -9
  4. package/bundled/trailheads/from-jekyll.md +79 -0
  5. package/lib/assets.js +7 -7
  6. package/lib/{chunk-RI2L3VGO.js → chunk-3A647I3N.js} +19 -11
  7. package/lib/{chunk-AMBFWPZ4.js → chunk-3K3ANWZ2.js} +3 -3
  8. package/lib/{chunk-WMOVCQO6.js → chunk-47P4YREZ.js} +6 -6
  9. package/lib/{chunk-C35KIPAR.js → chunk-76NTVE34.js} +98 -7
  10. package/lib/{chunk-TWCVHOKO.js → chunk-7PWCYHTJ.js} +125 -4
  11. package/lib/{chunk-JSPSMIJ2.js → chunk-7RDRZHJD.js} +9 -9
  12. package/lib/{chunk-JRT7TQQP.js → chunk-7SD7K567.js} +1 -1
  13. package/lib/{chunk-IRHRK7XB.js → chunk-7XLK2GEG.js} +1 -1
  14. package/lib/{chunk-YSH2NMIE.js → chunk-BEGC7YP6.js} +6 -6
  15. package/lib/{chunk-HR2RU2LY.js → chunk-CZ4XQC56.js} +6 -6
  16. package/lib/{chunk-DHHQKW4F.js → chunk-D2XE2GTY.js} +7 -7
  17. package/lib/{chunk-BOBPVAX2.js → chunk-DELWRJAO.js} +373 -52
  18. package/lib/{chunk-6XYSFG6V.js → chunk-GRWMGC7D.js} +15 -3
  19. package/lib/{chunk-N5QTGQ5N.js → chunk-GUKSZ2XM.js} +1 -1
  20. package/lib/{chunk-TDGBQNGW.js → chunk-HPXAZ2HU.js} +1 -1
  21. package/lib/{chunk-3PHCFZEU.js → chunk-II5DEH3Q.js} +2 -2
  22. package/lib/{chunk-FYGE634X.js → chunk-IJWHOFRP.js} +9 -9
  23. package/lib/{chunk-UGEGUUBT.js → chunk-LPHNACE4.js} +8 -8
  24. package/lib/{chunk-KBGE5MCY.js → chunk-MI6EJWA2.js} +1 -1
  25. package/lib/{chunk-EIT4ZDT4.js → chunk-NCWFYT74.js} +61 -5
  26. package/lib/{chunk-VVPZ5PDP.js → chunk-NNUKIGOO.js} +11 -11
  27. package/lib/{chunk-TN6EEDX2.js → chunk-R7K3D5W5.js} +28 -6
  28. package/lib/{chunk-37KSIVNY.js → chunk-RNJFPFXE.js} +3 -3
  29. package/lib/{chunk-CDEPYU7W.js → chunk-SF4I6Z7S.js} +2 -2
  30. package/lib/{chunk-GSKVRAHF.js → chunk-SURPOAW7.js} +6 -6
  31. package/lib/{chunk-BRK4MXXO.js → chunk-SXMJ52IK.js} +18 -11
  32. package/lib/{chunk-EZZUUPI4.js → chunk-TICWN55Z.js} +2 -2
  33. package/lib/{chunk-NUKCUDC4.js → chunk-TVU3OPPK.js} +3 -3
  34. package/lib/{chunk-GOE4ZSAB.js → chunk-XMXBHXZR.js} +9 -9
  35. package/lib/{chunk-WP3RPVUM.js → chunk-YTHQBMDJ.js} +1 -1
  36. package/lib/cli.js +32 -25
  37. package/lib/elements.js +7 -7
  38. package/lib/image.js +8 -8
  39. package/lib/links.js +7 -7
  40. package/lib/minify.js +7 -7
  41. package/lib/redirects.js +7 -7
  42. package/lib/rss.js +8 -8
  43. package/lib/sass.js +45 -10
  44. package/lib/sitemap.js +36 -11
  45. package/lib/ssqch.js +4 -4
  46. package/package.json +1 -1
  47. package/types/image.d.ts +5 -5
  48. package/types/index.d.ts +10 -4
  49. package/types/sitemap.d.ts +2 -0
  50. package/wasm/markdown.wasm +0 -0
  51. /package/lib/{chunk-BOBPVAX2.js.LEGAL.txt → chunk-DELWRJAO.js.LEGAL.txt} +0 -0
  52. /package/lib/{chunk-6XYSFG6V.js.LEGAL.txt → chunk-GRWMGC7D.js.LEGAL.txt} +0 -0
package/bundled/README.md CHANGED
@@ -4,7 +4,9 @@
4
4
  [![Latest release](https://img.shields.io/github/v/release/reverentgeek/sitesquatch)](https://github.com/reverentgeek/sitesquatch/releases/latest)
5
5
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
6
6
 
7
- SiteSquatch (`ssqch`) is a static site generator that runs on Node.js: large, quick, and rarely photographed. You write templates in [Jinja](https://jinja.palletsprojects.com/) (the default), [Edge.js](https://edgejs.dev), [Liquid](https://shopify.github.io/liquid/), [Nunjucks](https://mozilla.github.io/nunjucks/), [Handlebars](https://handlebarsjs.com/), [Mustache](https://mustache.github.io/) or [EJS](https://ejs.co/), plus Markdown, configure the site in JavaScript, and `ssqch build` turns it all into plain HTML. Install it from npm (Node 22.18 or newer), into a site's `package.json` or globally, or with Homebrew. The JavaScript in your config and data files runs on Node itself, so any npm package that runs there works, and the libraries behind the template languages are the real ones.
7
+ <img align="right" src="docs/assets/stickers/sitesquatch.svg" alt="SiteSquatch, a Sasquatch with a deadpan stare" width="180">
8
+
9
+ SiteSquatch (`ssqch`) is a static site generator for Node.js: large, quick, and rarely photographed. Write your pages in Markdown and [Jinja](https://jinja.palletsprojects.com/) (the default), [Edge.js](https://edgejs.dev), [Liquid](https://shopify.github.io/liquid/), [Nunjucks](https://mozilla.github.io/nunjucks/), [Handlebars](https://handlebarsjs.com/), [Mustache](https://mustache.github.io/) or [EJS](https://ejs.co/), configure the site in JavaScript, and `ssqch build` turns it all into plain HTML. Your config runs on Node, so any npm package you already know works in it.
8
10
 
9
11
  It moves fast for its size. [reverentgeek.com](https://reverentgeek.com) (168 pages, a feed, a sitemap and about 4,700 responsive image files) rebuilds in **under a second** once its images are cached, which is gone before you've found your camera. [Benchmarks](#benchmarks) has the measurements.
10
12
 
@@ -20,40 +22,25 @@ What's in the pack:
20
22
  - **Errors that point at the spot:** the line a problem is on, with carets under it, and a guess at what you meant (`did you mean /contact/?`) for a link, a layout, an include or an option that's nearly right.
21
23
  - **Themes without a package manager, custom elements that load only where they're used**, Sass (yes, Sassquatch), a sitemap, redirects, RSS helpers, HTML minification and asset fingerprinting.
22
24
  - **A quick start and a way in:** `ssqch init` (a blog, or a docs site with a sidebar and search), `ssqch import` for Eleventy and Zola sites, [`ssqch new`](#starting-a-new-page) for the next post, and a dev server (it answers to Squatch Watch) that reloads only the page you changed, swaps stylesheets in place, and shows a broken build in the browser.
23
- - **Plugins in Rust** for when JavaScript isn't enough: heavy transforms, filters and template languages written in Rust build to one `.wasm` file that runs on every platform, with nothing to compile when a site installs it.
25
+ - **Plugins in Rust** for the heavy lifting: transforms, filters and template languages built to one `.wasm` file that runs on every platform.
24
26
 
25
27
  SiteSquatch is a young one (0.x), so expect some breaking changes between minor versions. Each is listed in the [changelog](CHANGELOG.md) with what you'd need to change.
26
28
 
27
29
  ## Install
28
30
 
29
- ssqch is a program for [Node.js](https://nodejs.org) 22.18 or newer, published on npm. In a site with a `package.json`, install it from **npm** as a dev dependency, so the lockfile pins the version: `npm install --save-dev ssqch` (or `pnpm add -D ssqch`, `yarn add -D ssqch`), then run `npx ssqch build`, or `ssqch build` in a `package.json` script. [sharp](https://sharp.pixelplumbing.com), which encodes images, is the package's one dependency: ssqch's template libraries are inside it, and so are its Markdown, highlighter, minifier and Sass, which are WebAssembly, so the package is the same on every platform, Alpine and Linux on ARM included.
30
-
31
- **Without a `package.json`:** `npm install --global ssqch` puts `ssqch` on your `PATH`, and `npx ssqch@0.8.0 build` runs one version without installing it. With [Homebrew](https://brew.sh) (macOS or Linux), `brew install reverentgeek/tap/ssqch` installs the npm package with Homebrew's own Node, which it brings along if you don't have it.
32
-
33
- **npm is the only way it ships:** there's no standalone executable for 0.8 and no installer script. 0.7's were a Rust binary; 0.8 is JavaScript, and it runs on the Node you have. If 0.7's installer put `ssqch` in `~/.cargo/bin`, delete it there, so the old one doesn't stand in front of the new one on your `PATH` (`which ssqch` says which one answers). There is no `cargo install ssqch` for 0.8 either: the crates end at 0.7, apart from [`ssqch-plugin`](#plugins-in-rust), which is for writing plugins.
31
+ <img align="right" src="docs/assets/stickers/backpack.svg" alt="" width="96">
34
32
 
35
- **A release from today and pnpm's release age:** pnpm 11 and later wait a day (`minimumReleaseAge`) before installing a new version, so `pnpm add -D ssqch` on the day of a release fails, or settles for the version before it. To take releases as they come out, list `ssqch` under `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`, by name, which trusts every version of it. It is the only package of ssqch's own (0.7 had a platform package for each system), so nothing else needs a line:
33
+ You'll need [Node.js](https://nodejs.org) 22.18 or newer. In a site with a `package.json`, add ssqch as a dev dependency, so the lockfile pins the version you built with:
36
34
 
37
- ```yaml
38
- minimumReleaseAgeExclude:
39
- - ssqch
35
+ ```sh
36
+ npm install --save-dev ssqch
40
37
  ```
41
38
 
42
- **Excluding only one release** (`ssqch@<version>`) trusts that version and no other, but when the next release comes within a day, swapping the line for the new version locks pnpm out: every install fails with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`, because the lockfile still has the old version, which is under a day old too and no longer excluded (`pnpm clean --lockfile` re-resolves every dependency, not only ssqch). To upgrade, add the new version's line beside the old one, install, then delete the old one; the lockfile no longer has the old version, so the new line is enough.
39
+ (Or `pnpm add -D ssqch`, or `yarn add -D ssqch`.) Then run `npx ssqch build`, or `ssqch build` from a `package.json` script.
43
40
 
44
- The npm package carries the modules built into ssqch (`ssqch`, `ssqch/image` and the rest) in its `exports` map, with their types, so editors, TypeScript and ESLint's `n/no-missing-import` find them without `ssqch types`. They load in plain Node too, which 0.7's stubs didn't: a test or a script can `import { markdown, slugify } from "ssqch"`. ESLint's `n/no-unpublished-import` flags imports of a dev dependency in files a package publishes, so turn it off for build-time files (`ssqch.config.js`, data files, and modules they import), which a site never ships.
41
+ A site whose `.npmrc` holds new releases back (`min-release-age=2`, a supply-chain cooldown) gets a new ssqch that many days after it's published, and until then npm says `ETARGET No matching version found for ssqch@<version> with a date before ...`: install the version before it, or wait. `ignore-scripts=true` is fine: ssqch runs no install script, and sharp, its one dependency, comes with its binaries prebuilt.
45
42
 
46
- In **GitHub Actions**, set up Node with `actions/setup-node` and install ssqch from npm. A site with a `package.json` runs `npm ci`, and its lockfile pins the version; one without installs a pinned version (or runs it with `npx --yes ssqch@0.7.0 build`):
47
-
48
- ```yaml
49
- - uses: actions/setup-node@v4
50
- with:
51
- node-version: 24
52
- - run: npm install --global ssqch@0.8.0
53
- - run: ssqch build
54
- ```
55
-
56
- > **Note:** AVIF needs no setup. sharp writes it, so there's no feature to turn on and no assembler to install first (0.7 needed `--features avif` and, on x86_64, nasm).
43
+ To have `ssqch` everywhere instead, install it globally with `npm install --global ssqch`, or with [Homebrew](https://brew.sh) on macOS or Linux: `brew install reverentgeek/tap/ssqch` (it brings Node along if you don't have it).
57
44
 
58
45
  Confirm the sighting:
59
46
 
@@ -61,10 +48,14 @@ Confirm the sighting:
61
48
  ssqch --version
62
49
  ```
63
50
 
51
+ **pnpm's release age:** pnpm 11 and newer hold a version back for a day after it's published (`minimumReleaseAge`). If `pnpm add -D ssqch` fails on a release day, or installs the version before, list `ssqch` under `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`.
52
+
64
53
  For Tab completion of commands and options, `ssqch completions zsh` (or `bash`, `fish`, `powershell`, `elvish`) prints a script for your shell, and `ssqch completions --help` says where each shell wants it.
65
54
 
66
55
  ## Field guide: build your first site
67
56
 
57
+ <img align="right" src="docs/assets/stickers/compass.svg" alt="" width="96">
58
+
68
59
  The quickest way in is `ssqch init`, which sets up camp (a config, a layout, a home page, five posts, a 404 page, a data file, a blueprint for the next post, editor types, and an `AGENTS.md` for coding agents) and then leaves you to it:
69
60
 
70
61
  ```sh
@@ -72,7 +63,7 @@ ssqch init my-site
72
63
  cd my-site && ssqch serve
73
64
  ```
74
65
 
75
- Open <http://localhost:8080>, edit `src/posts/i-know-what-i-saw.md`, and watch the page reload. (The starter is an amateur investigator's field notes: a sighting, a correction, a stump, an old map and a raccoon's cache. The posts are short, and each one shows you something.) `ssqch init` never overwrites a file that's already there, so it's safe to run in a folder you've started.
66
+ Haven't installed it yet? `npx ssqch init my-site`, then `npx ssqch serve` in the new folder, works too. Open <http://localhost:8080>, edit `src/posts/i-know-what-i-saw.md`, and watch the page reload. (The starter is an amateur investigator's field notes: a sighting, a correction, a stump, an old map and a raccoon's cache. The posts are short, and each one shows you something.) `ssqch init` never overwrites a file that's already there, so it's safe to run in a folder you've started.
76
67
 
77
68
  The layout and home page are [Jinja](#jinja-and-nunjucks) templates, ssqch's default language. To start in another one, pass `--engine edge`, `--engine liquid`, `--engine njk` (Nunjucks) or `--engine hbs` (Handlebars); the config then lists that engine in `templateFormats` and runs Markdown through it. `--engine` works with `--starter docs` too.
78
69
 
@@ -189,11 +180,11 @@ The address comes after each build's report, so it's on the last line however lo
189
180
  - **A stylesheet is swapped in place,** without a reload, so the page keeps its scroll position and a half-filled form. That goes for CSS another tool writes into the output folder too (a PostCSS watcher, say): the browser hears about it without a rebuild, once the tool has finished writing it, so a page never reloads before its new CSS is there. The old stylesheet stays until the new one has loaded, so the page is never unstyled in between, and a new one that doesn't load (or comes back empty) leaves the old one in place. A changed script or image reloads the page.
190
181
  - **A build that fails shows up in the browser,** over the page, with the error and the lines it's about. The tab's title and icon say so too, which is how you find out from another window. "Copy diagnostic" copies the error to paste into an issue or a chat, and Escape (or "Hide") puts it away until the error changes. The page underneath is from the last build that worked, and the next good build clears the error and says so in the terminal: `Build recovered. Back on the trail.`
191
182
  - **A URL that isn't there** gets the site's `404.html`, or, when the site has none, a page of the server's own that says where the trail went cold and suggests the closest URL.
192
- - **A site without a `favicon.ico`** gets a map-paper footprint on a pine circle in the tab, where there used to be a 404 on every page load. While the build is broken, the circle turns burnt orange.
183
+ - **A site without a `favicon.ico`** gets a map-paper footprint on a pine circle in the tab. While the build is broken, the circle turns burnt orange.
193
184
 
194
185
  None of that is written to the output folder: the server adds it to pages as it sends them.
195
186
 
196
- **How the server runs:** `ssqch serve` builds in a second process, so it answers requests while a build runs. A site whose code ends the process (`process.exit()`, or an error nothing catches in a timer) fails that one build, shown in the browser like any other, and the next change builds in a new process: the server stays up. The build process starts again when the config changes, or a module it imports (including CommonJS ones), so everything the site's JavaScript loaded is read again and what it kept in memory starts over. It watches the input folder, the config's `watch` paths, a theme's folder, the config's own files and the files plugins read (a Sass partial in a folder the config never named), and a page that comes out the same as last time isn't read from the disk again. `node_modules` isn't watched. On Linux the server watches each folder itself and leaves out `.cache`, `.git` and `node_modules`; when the system has no watches left (`fs.inotify.max_user_watches`), a warning names the first folder that wasn't watched, and the server goes on. It listens on `127.0.0.1` only, and there's no `--host`.
187
+ **What it watches:** the input folder, a theme's folder, the config and the modules it imports, the config's `watch` paths, and the files plugins read (a Sass partial in a folder the config never named). A change to the config, or to code it imports, reloads all of it, so a filter you edited is the new one on the next build. Builds run in a process of their own, so the server keeps answering while a build runs, and a site's code that crashes or calls `process.exit()` fails that one build rather than the server. It listens on `127.0.0.1` only.
197
188
 
198
189
  To look at a production build the way a host will serve it (for Lighthouse, or a last check before deploying), run `ssqch build`, then `ssqch serve --built`: it serves the output folder as the build left it, with no build, no watching and nothing added to pages, and compresses text with gzip as hosts do. `ssqch preview` is the same command, for people coming from Vite or Astro.
199
190
 
@@ -201,7 +192,7 @@ To look at a production build the way a host will serve it (for Lighthouse, or a
201
192
 
202
193
  ## Configuring a site
203
194
 
204
- > **Pro tip:** run `ssqch types` to write `ssqch.d.ts`, and list it in `jsconfig.json`'s `"include"` (`ssqch init` does both). Your editor then autocompletes config keys and plugin options, and underlines mistakes like `ouput` or `linksPlugin({ fail: "yes" })`, without any npm packages. Run it again after upgrading ssqch. (With ssqch from npm, the package has the same types, and you don't need both.)
195
+ > **Pro tip:** with ssqch as a dev dependency, your editor finds its types in the package: it autocompletes config keys and plugin options, and underlines mistakes like `ouput` or `linksPlugin({ fail: "yes" })`. With ssqch installed globally, `ssqch types` writes the same types to `ssqch.d.ts` for `jsconfig.json`'s `"include"` (`ssqch init` does both), with your [content schemas](#content-schemas) in them too.
205
196
 
206
197
  Here's a fuller config, with data, a custom collection and the built-in plugins:
207
198
 
@@ -251,29 +242,30 @@ The default export is the config: an object, or a function (sync or async) that
251
242
  | `deepMerge` | Merge objects and concatenate arrays through the data cascade (default `true`). |
252
243
  | `leaveNoTrace` | Delete stale files from the output: pages and passthrough files an earlier build wrote that this one didn't, like a deleted post (default `false`). ssqch keeps a list of what it writes in `.cache/ssqch/output-files.json`, so files other tools write into the output (your CSS build, say) are never touched: it packs out only what it packed in. `clean` is another name for the same option (set one of them). |
253
244
  | `filters` | `{ name: function }`, callable from templates: `{{ title | slug }}` or `{{ slug(title) }}`. Async functions are awaited. |
254
- | `data` | `{ name: value }` for every template. A function (sync or async) is called on each build. |
245
+ | `data` | `{ name: value }` for every template. A value that's a function (sync or async) is called on each build, and what it answers is that name's value: `data: { snacks: async () => fetchSnacks() }`. |
255
246
  | `collections` | `{ name: (pages) => ... }`. `pages` has `all()`, `byTag(tag)`, `byTags(...tags)` and `byGlob(glob or globs)`, oldest first. |
256
247
  | `transforms` | `{ name: (content, page) => content }`, run on every output file. `page` has `url`, `inputPath` and `outputPath`. Return the content, changed or not. Async works. |
257
248
  | `engines` | Template engines of your own: `{ extension: (source, data) => html }`, or an object with a `render(source, data)` method (async is fine). Add the extension to `templateFormats` to render those files; layouts in that extension work too, and `markdownEngine` can name one. `edge`, `md`, `html` and `txt` can't be replaced. |
258
- | `ignore` | Globs, relative to the input folder, of files that aren't pages: `["drafts/**", "**/README.md"]`. |
249
+ | `ignore` | Globs, relative to the input folder, of files that aren't pages: `["drafts/**", "**/README.md"]`. Folders starting with `.`, `node_modules` and a folder Bundler installed gems into (`vendor/bundle`, with `ruby/<version>/gems/` inside) are skipped without it. |
259
250
  | `bundles` | Page bundles: a folder whose page is `index.md` (or any `index.*` template) gets its other files, like photos and downloads, copied next to the page, so `![](photo.jpg)` just works. Subfolders with templates of their own, and data files, are left out (default `false`). |
260
251
  | `strict` | Printing an undefined value (`{{ titel }}`) is an error that names the template and line, in every template language. Conditionals and defaults (`@if(subtitle)`, `{% if subtitle %}`, `x ?? "none"`) still work (default `false`). |
261
- | `passthrough` | Files or folders to copy: a path, or `{ from: to }`, or an array of them. A path can be a glob: `"src/**/*.pdf"` keeps each file's own path, and `{ "assets/**/*.png": "images" }` puts them under `images/` by their path below `assets/`. Linked files and folders (symlinks) are followed and copied as files, and a link to nothing is an error that names it. |
252
+ | `passthrough` | Files or folders to copy: a path, or `{ from: to }`, or an array of them. A path can be a glob: `"src/**/*.pdf"` keeps each file's own path, and `{ "assets/**/*.png": "images" }` puts them under `images/` by their path below `assets/`. Linked files and folders (symlinks) are followed and copied as files, and a link to nothing is an error that names it. When two sources copy to the same file, the one listed later is written, with a warning if the two differ. |
262
253
  | `watch` | More paths for `ssqch serve` to watch. |
263
254
  | `budgets` | Size budgets by kind of file, checked after each build: `budgets: { pages: "150 KB", images: "500 KB", total: "300 MB" }`. A file over its kind's budget is a warning (`bigfootprint`). The kinds are `ssqch footprint`'s: `pages`, `images`, `css`, `javascript`, `fonts`, `media`, `documents`, `data` and `other`, plus `total`. See [A build's footprint](#a-builds-footprint). |
264
255
  | `serve` | `serve: { run: ["npx postcss src/app.css -o dist/app.css --watch"] }`: programs `ssqch serve` starts with the server and stops with it, such as the watchers of your CSS and JavaScript tools. Their output is shown with the tool's name in front (`[postcss] ...`). The first build waits for their first compile, and each update waits until they have stopped writing. Builds don't run them. See [CSS and JavaScript](#css-and-javascript). In `sitesquatch.toml`, `[serve]` with `run = [...]`. |
265
- | `beforeBuild`, `afterBuild` | Build hooks (a function or an array). They get `{ env, serving, dirs }`, plus `written` (the files written) after the build. Async works. A hook can also run a program: `afterBuild: { run: "npx -y pagefind --site dist" }` runs it in the project root (through `sh -c`, or `cmd /C` on Windows) with its output shown, and a failure fails the build. It gets `SSQCH_ENV`, `SSQCH_SERVING`, `SSQCH_INPUT` and `SSQCH_OUTPUT`, and each `node_modules/.bin` from the project's folder up goes in front of its `PATH`, as in an npm script, so a tool the site installed runs by name (`{ run: "postcss src/app.css -o $SSQCH_OUTPUT/app.css" }`) whether the build started from `npm run build` or a global `ssqch`. `serve.run` commands get the same. In `sitesquatch.toml`, `before_build` and `after_build` take lists of commands. |
256
+ | `beforeBuild`, `afterBuild` | Build hooks (a function or an array). They get `{ env, serving, quiet, verbose, dirs }`, plus `written` (the files written) after the build; `quiet` and `verbose` say whether the build was run with `--quiet` or `--verbose`, so a hook's own messages can follow them. Async works. A hook can also run a program: `afterBuild: { run: "npx -y pagefind --site dist" }` runs it in the project root (through `sh -c`, or `cmd /C` on Windows) with its output shown, and a failure fails the build. It gets `SSQCH_ENV`, `SSQCH_SERVING`, `SSQCH_QUIET` (`true` with `--quiet`), `SSQCH_INPUT` and `SSQCH_OUTPUT`, and each `node_modules/.bin` from the project's folder up goes in front of its `PATH`, as in an npm script, so a tool the site installed runs by name (`{ run: "postcss src/app.css -o $SSQCH_OUTPUT/app.css" }`) whether the build started from `npm run build` or a global `ssqch`. `serve.run` commands get the same (`SSQCH_QUIET` from `ssqch serve --quiet`). In `sitesquatch.toml`, `before_build` and `after_build` take lists of commands. |
266
257
  | `theme` | A theme under the site: a folder (`"themes/docs"`), or a git repository pinned to a commit or tag (`"https://github.com/you/theme#v1.2.0"`). The site's own files win over the theme's, one by one. See [Themes](#themes). |
267
258
  | `schemas` | What each kind of page's data has to look like, checked on every build: `{ posts: { fields: { title: "string", date: "date" } } }`. See [Content schemas](#content-schemas). |
268
259
  | `base` | The path the site is served under, when that isn't the root of its domain: `base: "/repo/"` for a GitHub Pages project site at `https://you.github.io/repo/`. Templates, Markdown links and `page.url` stay as they are (`/about/`); ssqch adds the base to every URL from the site's root in the HTML it writes. See [Serving a site under a path](#serving-a-site-under-a-path). |
269
260
  | `lastModified` | `page.lastModified`: `"git"` for when the page's file last changed in a commit (its modification time if it has uncommitted changes), or `"file"` for the modification time. Off by default. In CI, check out the full history (`fetch-depth: 0` in GitHub Actions), or every page gets the date of the last commit; the build warns about a shallow clone. |
261
+ | `timeZone` | The time zone the site's own JavaScript runs in, as an IANA name: `timeZone: "UTC"`. `Date`'s local methods (`getHours()`, `toLocaleDateString()`) and libraries that use the local zone (luxon, date-fns), in data files, filters and hooks, follow it, so a laptop in New York and CI in UTC build the same pages. ssqch's own date filters are UTC whatever it says. Default: the machine's zone. An unknown name is an error. The config file's own top-level code runs before it applies, so work dates out in a function or a data file. |
270
262
  | `plugins` | More config: objects with any of the keys above except the settings (`dirs`, `templateFormats`, `markdownEngine`, `htmlEngine`, `markdown`, `deepMerge`, `leaveNoTrace`, `ignore`, `bundles`, `strict`, `lastModified`, `base`, `schemas`, `theme`), or functions that return one, or a plugin written in Rust (`{ name, rust: { wasm, options } }`, what its npm package's function returns: see [Plugins in Rust](#plugins-in-rust)). `false`, `null` and `undefined` are skipped, so `env === "production" && minifyPlugin()` works. Give a plugin a `name` and errors will mention it. |
271
263
 
272
264
  Mistakes get caught at the trailhead. A misspelled key or option is an error that says what you probably meant (`"templateFormat" isn't a config option (did you mean "templateFormats"?)`, or `unknown option "widhts" (did you mean "widths"?)` for a plugin), and so are two plugins that define the same filter, data or collection name (the message names both). When something in your code throws, you get `ssqch.config.js: too many pine cones` and a stack trace that points at your file, like `at bad (lib/filters.js:3:9)`.
273
265
 
274
266
  ### What you can import
275
267
 
276
- Config and data files are loaded by Node, by its rules for ES modules and CommonJS, so they can import what Node can: relative files (`./lib/filters.js`, with or without the extension), JSON (`import site from "./site.json"`; ssqch adds the `with { type: "json" }` that Node wants if you leave it off), npm packages from `node_modules`, every Node built-in (`node:fs`, `node:path`, `node:child_process`, `node:http` and the rest, with or without the `node:` prefix), and the modules built into ssqch: `ssqch` (which has `defineConfig`, `markdown(text, { inline })`, `readData(path)` for JSON, YAML and TOML files, and `files(pattern)` for the files a glob matches), `ssqch/image`, `ssqch/rss`, `ssqch/minify`, `ssqch/assets`, `ssqch/links`, `ssqch/sitemap`, `ssqch/redirects`, `ssqch/sass` and `ssqch/elements`. The config itself can be `ssqch.config.js` or `.mjs`, `.cjs`, or `.ts` or `.mts` (Node strips the types, so only syntax that erases to JavaScript works: no `enum` or `namespace`).
268
+ Config and data files are loaded by Node, by its rules for ES modules and CommonJS, so they can import what Node can: relative files (`./lib/filters.js`, with or without the extension), your own files through the path aliases in `tsconfig.json` or `jsconfig.json` (`compilerOptions.paths`, as Astro, Vite and Next.js sites have them: `import { menu } from "@/config/menu"`), JSON (`import site from "./site.json"`; ssqch adds the `with { type: "json" }` that Node wants if you leave it off), npm packages from `node_modules`, every Node built-in (`node:fs`, `node:path`, `node:child_process`, `node:http` and the rest, with or without the `node:` prefix), and the modules built into ssqch: `ssqch` (which has `defineConfig`, `markdown(text, { inline })`, `readData(path)` for JSON, YAML and TOML files, and `files(pattern)` for the files a glob matches), `ssqch/image`, `ssqch/rss`, `ssqch/minify`, `ssqch/assets`, `ssqch/links`, `ssqch/sitemap`, `ssqch/redirects`, `ssqch/sass` and `ssqch/elements`. The config itself can be `ssqch.config.js` or `.mjs`, `.cjs`, or `.ts` or `.mts` (Node strips the types, so only syntax that erases to JavaScript works: no `enum` or `namespace`). The modules load in plain Node too, so a test or a script can `import { markdown, slugify } from "ssqch"`. ESLint's `n/no-unpublished-import` flags imports of a dev dependency, so turn it off for build-time files like `ssqch.config.js` and data files, which a site never ships.
277
269
 
278
270
  A site's code runs in its project root (ssqch changes into it before loading anything), so `process.cwd()` and `readFileSync("data/snacks.json")` are from there. Relative paths in `fs` calls are Node's own, and so are its errors (`err.code === "ENOENT"`). On Windows, `node:path` joins with `\`, as Node does there; what ssqch hands your code (`page.inputPath`, `page.url`, a hook's `dirs`) has `/` everywhere.
279
271
 
@@ -293,7 +285,7 @@ export default async function () {
293
285
  }
294
286
  ```
295
287
 
296
- - **A duration** (`"90s"`, `"30m"`, `"1h"`, `"7d"`, `"2w"`, or seconds as a number): a successful response is saved in `.cache/ssqch/fetch/`, and requests reuse it until it's that old. The key is the method, URL, request headers and body, so another query or token is another entry. The URL, request headers and cookies aren't written to disk (an API key is usually in one of them), only the response. The folder is the same format 0.7 used, so a copy saved by 0.7 is still good.
288
+ - **A duration** (`"90s"`, `"30m"`, `"1h"`, `"7d"`, `"2w"`, or seconds as a number): a successful response is saved in `.cache/ssqch/fetch/`, and requests reuse it until it's that old. The key is the method, URL, request headers and body, so another query or token is another entry. The URL, request headers and cookies aren't written to disk (an API key is usually in one of them), only the response.
297
289
  - **When a refresh fails** (the network is down, or the server answers 5xx or 429) and there's an older copy, the build uses it and warns: `warn: fetch: https://api.example.com/snacks answered 503; using the copy saved 3 hours ago`. Without a copy, the failure is the response, as usual. `cache: "0s"` asks every time and keeps the copy only for that.
298
290
  - **The standard modes** work too: `"force-cache"` (a copy of any age, else ask), `"reload"` (ask, and save), `"only-if-cached"` (a copy, or fail) and `"no-store"` (the default).
299
291
  - **Offline:** `ssqch build --offline` (or `SSQCH_OFFLINE=1`) answers every request from its saved copy, whatever its age, and fails a request that has none, so a build on a plane or in a sandbox never touches the network.
@@ -364,13 +356,13 @@ export default readData("data/albums.json").map((album) => ({ ...album, slug: sl
364
356
 
365
357
  ### Built-in plugins
366
358
 
367
- - **`ssqch/image`:** `imagePlugin(options)` turns every local `<img>` in HTML output into a `<picture>`. Options: `formats` (`avif`, `webp`, `jpeg`, `png`, `auto`), `widths`, `defaultAttributes`, `outputDir`, `urlPath`, `webpQuality`, `avifQuality`, `avifEffort`, `jpegQuality`, `minimumThreshold`, `prune`, `hashCache`, `linkedImages` and `cacheDir` (where images are encoded and kept, default `.cache/ssqch/img`; see [Keep the image cache between builds](#keep-the-image-cache-between-builds)). The quality options are sharp's own numbers, which go to its encoders as they are (libvips, with libaom for AVIF, libwebp, and mozjpeg for JPEG): `webpQuality` 75, `avifQuality` 41 and `jpegQuality` 89 by default (whole numbers from 1 to 100), and `avifEffort` 2 (0 is fastest, 9 slowest with the smallest files). Those are 0.7's defaults (WebP 75, AVIF 50 at speed 8, JPEG 80) converted at equal measured picture quality, so a site that sets none gets the pictures it had. Moving numbers from 0.7: WebP's are the same; AVIF 40 is 34, 50 is 41, 60 is 48, 70 is 55, 80 is 61 and 90 is 86; JPEG 60 is 72, 70 is 80, 80 is 89, 85 is 93 and 90 is 97 (from 0.7's JPEG 92 and AVIF 98 up it's sharp's 100, its best, a little short of 0.7's there); 0.7's `avifSpeed` is `avifEffort`, where speed 8 is effort 2 and speed 4 is effort 3 (0.8.0's changelog has the whole table). `avifSpeed`, or a number that isn't a whole one in range, fails the build and says what to use. A converted number keeps 0.7's image names, so an image cache from 0.7 in `.cache/ssqch/img` is used as it is (delete it to encode everything again); the files' bytes are sharp's, not 0.7's, and their widths and heights are 0.7's. PNGs are written without adaptive filtering (sharp's default), at zlib's level 6. AVIF is always there: sharp writes it, with no build feature. `[ssqch] Encoded ...` lines come as each image's files are done, while pages go on rendering, so they're among the `Writing` lines; the build waits for every file before the link checker, the other plugins' files, `afterBuild` hooks and the summary. Images are encoded on libuv's thread pool, as many at once as there are cores; the `ssqch` command sizes the pool to the number of cores plus 4 so page writes keep threads (set `UV_THREADPOOL_SIZE` to choose another size; with a smaller one, encodes wait their turn). Each file is encoded on one thread, so its bytes don't depend on the machine's cores. A file that can't be made after a page that points at it was written (sharp failing on a source that read well, a full disk) fails the build with an `images` error that names the source and the pages, rather than publish markup for a file that isn't there; a source ssqch can't decode is found before any page points at it, and is a warning that leaves its tag as written. On an `<img>`, `ssqch:widths="300,600"` picks that image's widths, a plain `width` attribute pins it to one width, and `ssqch:ignore` leaves it alone. `ssqch:preload` is for the image that's the page's largest paint (a banner): a `<link rel="preload" as="image">` with its `imagesrcset` and `imagesizes` goes in `<head>` before the first stylesheet, for the first of `formats`, and the image loads eagerly with `fetchpriority="high"` (`sizes="auto"` only works for lazy images, so `auto` is left out of its `sizes`). Images with a color profile other than sRGB (Display P3, Adobe RGB) are converted to sRGB first, so their colors stay true. A link to a local image (`<a href="/photos/big.jpg">`, the click-to-enlarge pattern) is pointed at a generated copy in the image's own format, at its own width capped at the largest of `widths`, so the link works without publishing the source file; `ssqch:ignore` on the `<a>`, or `linkedImages: false`, leaves links alone. `image(src, { widths, formats })` makes one image's files with the same settings and cache, returning `{ webp: [{ url, width, height, srcset, sourceType, ... }] }`; with `"auto"` in `formats`, the files are under `auto` too, next to the format it became (`png`). Its files are named after a hash of the source; `name` gives them a name and folder of your own, for URLs other things link to (`image("logos/acme.png", { widths: [200], name: "/assets/sponsors/acme" })` writes `/assets/sponsors/acme-200.webp`, and a name without a leading `/` is inside the image folder). Data files can call it even without the plugin. `imageUrl(src, { width, format })` is one generated copy, for URLs outside an `<img>` (`og:image`, JSON-LD, a feed): `{{ imageUrl(site.logo, { width: 1200 }).url }}` gives `{ url, width, height, type, format }`, at most `width` pixels wide (`"auto"`, the default, is the original's) in `format` (default `"auto"`, the source's own, which every reader can show). `src` is a site path, from the input folder, the way an `<img src>` starting with `/` is, and a remote URL comes back as `{ url }`. It's a template function on every site, and a named export of `ssqch/image` for data files.
368
- - **`ssqch/minify`:** `minifyPlugin(options)` minifies HTML output, after the image transform. `minify(html, options)` does the same for a string. Options: `collapseWhitespace`, `removeComments`, `shortDoctype` and `shortenAttributes` (all `true` by default). `shortenAttributes` drops the values of boolean attributes (`defer="defer"` becomes `defer`) and whitespace that doesn't matter in `class`, `srcset`, `sizes`, URL attributes and the viewport `<meta>`. The minifier is ssqch's own, written in Rust and built into the package as WebAssembly (it minifies the blog's 169 pages in about 0.1 s). It doesn't write the same bytes as [html-minifier-terser](https://github.com/terser/html-minifier-terser): a site from Eleventy that wants those exact bytes, to compare with [`ssqch diff --exact`](#comparing-two-builds), keeps the package as a transform of its own, `transforms: { minify: async (content, page) => page.outputPath.endsWith(".html") ? await minify(content, options) : content }`, with `import { minify } from "html-minifier-terser"`, and moves to `minifyPlugin()` when the bytes stop mattering.
359
+ - **`ssqch/image`:** `imagePlugin(options)` turns every local `<img>` in HTML output into a `<picture>`. Options: `formats` (`avif`, `webp`, `jpeg`, `png`, `auto`), `widths`, `defaultAttributes`, `outputDir`, `urlPath`, `webpQuality`, `avifQuality`, `avifEffort`, `jpegQuality`, `minimumThreshold`, `prune`, `hashCache`, `linkedImages` and `cacheDir` (where images are encoded and kept, default `.cache/ssqch/img`; see [Keep the image cache between builds](#keep-the-image-cache-between-builds)). Images are encoded with [sharp](https://sharp.pixelplumbing.com), and the quality options are its own numbers, whole numbers from 1 to 100: `webpQuality` 75, `avifQuality` 41 and `jpegQuality` 89 (mozjpeg) by default, and `avifEffort` 2 (0 is fastest, 9 is slowest with the smallest files). A number out of range fails the build and says what to use. PNGs are written at zlib's level 6. `[ssqch] Encoded ...` lines come as each image's files are done, while pages go on rendering; the build waits for every file before the link checker, the other plugins' files, `afterBuild` hooks and the summary. Images are encoded as many at once as there are cores, each on one thread, so a file's bytes don't depend on the machine (set `UV_THREADPOOL_SIZE` to change how many threads the pool has). A file that can't be made after a page that points at it was written (sharp failing on a source that read well, a full disk) fails the build with an `images` error that names the source and the pages, rather than publish markup for a file that isn't there; a source ssqch can't decode is found before any page points at it, and is a warning that leaves its tag as written. On an `<img>`, `ssqch:widths="300,600"` picks that image's widths, a plain `width` attribute pins it to one width, and `ssqch:ignore` leaves it alone. `ssqch:preload` is for the image that's the page's largest paint (a banner): a `<link rel="preload" as="image">` with its `imagesrcset` and `imagesizes` goes in `<head>` before the first stylesheet, for the first of `formats`, and the image loads eagerly with `fetchpriority="high"` (`sizes="auto"` only works for lazy images, so `auto` is left out of its `sizes`). Images with a color profile other than sRGB (Display P3, Adobe RGB) are converted to sRGB first, so their colors stay true. A link to a local image (`<a href="/photos/big.jpg">`, the click-to-enlarge pattern) is pointed at a generated copy in the image's own format, at its own width capped at the largest of `widths`, so the link works without publishing the source file; `ssqch:ignore` on the `<a>`, or `linkedImages: false`, leaves links alone. `image(src, { widths, formats })` makes one image's files with the same settings and cache, returning `{ webp: [{ url, width, height, srcset, sourceType, ... }] }`; with `"auto"` in `formats`, the files are under `auto` too, next to the format it became (`png`). Its files are named after a hash of the source; `name` gives them a name and folder of your own, for URLs other things link to (`image("logos/acme.png", { widths: [200], name: "/assets/sponsors/acme" })` writes `/assets/sponsors/acme-200.webp`, and a name without a leading `/` is inside the image folder). Data files can call it even without the plugin. `imageUrl(src, { width, format })` is one generated copy, for URLs outside an `<img>` (`og:image`, JSON-LD, a feed): `{{ imageUrl(site.logo, { width: 1200 }).url }}` gives `{ url, width, height, type, format }`, at most `width` pixels wide (`"auto"`, the default, is the original's) in `format` (default `"auto"`, the source's own, which every reader can show). `src` is a site path, from the input folder, the way an `<img src>` starting with `/` is, and a remote URL comes back as `{ url }`. It's a template function on every site, and a named export of `ssqch/image` for data files.
360
+ - **`ssqch/minify`:** `minifyPlugin(options)` minifies HTML output, after the image transform. `minify(html, options)` does the same for a string. Options: `collapseWhitespace`, `removeComments`, `shortDoctype` and `shortenAttributes` (all `true` by default). `shortenAttributes` drops the values of boolean attributes (`defer="defer"` becomes `defer`) and whitespace that doesn't matter in `class`, `srcset`, `sizes`, URL attributes and the viewport `<meta>`. The minifier is ssqch's own, built into the package as WebAssembly, and it minifies the ReverentGeek blog's 169 pages in about 0.1 s. Its output isn't byte for byte [html-minifier-terser](https://github.com/terser/html-minifier-terser)'s, so a site that needs those exact bytes can run that package as a transform instead.
369
361
  - **`ssqch/rss`:** `rssPlugin()` adds the filters `getNewestCollectionItemDate`, `dateToRfc3339`, `dateToRfc822`, `absoluteUrl`, `htmlToAbsoluteUrls` and `feedHtml`. They're also named exports, for your own code. `feedHtml(post.templateContent, absolutePostUrl)` is a post's HTML ready for a feed: a feed's HTML never goes through the image plugin, so each local `<img src>` is pointed at one generated copy (a single URL, not a `<picture>` or `srcset`, which many readers drop), a link to a local image at the copy a page's link gets, `loading`, `decoding`, `sizes`, `srcset`, `fetchpriority` and `ssqch:*` attributes go, and every URL is made absolute. Options, as a third argument: `width` (default 1200, never wider than the original; an `<img width>` that's smaller wins) and `format` (default `"auto"`, the source's). `feedHtml` makes the copies with the image plugin, so the config needs `imagePlugin()` as well; without it the build fails with `the image processor isn't set up`.
370
362
  - **`ssqch/assets`:** `assetsPlugin({ files })` fingerprints CSS and JS for long-lived caching. Templates link the plain paths (`<link rel="stylesheet" href="/assets/index.css">`). In a production build, each listed file in the output folder (written there by your CSS or JS tool before `ssqch build`) is renamed to `index.<hash>.css`, older fingerprinted copies are deleted, and every `href` and `src` in the HTML that points at it is rewritten, keeping any query string. `ssqch serve` leaves the plain paths alone, unless the plain file isn't there but the last production build left a fingerprinted copy: then pages link to that copy (with a warning), so serving after a build without running your CSS and JS watchers still has styles. A listed file that's missing fails a production build. `assetUrl("/assets/index.css")` returns the URL to use, for places outside an `href` or `src`. Imports in inline module scripts are rewritten too (`<script type="module">import { setup } from "/assets/pco.js"</script>`, and `import("/assets/pco.js")` with a plain string), and a listed file can be a passthrough copy: it's copied into the output before it's fingerprinted. `url()` references inside CSS and imports inside JavaScript files aren't rewritten. Options: `files` (URL paths, required), `fingerprint` (`true` or `false`; on for production builds by default) and `integrity` (add `integrity="sha384-..."` to the `<link>` and `<script>` elements that load a fingerprinted file; default `false`).
371
363
  - **`ssqch/links`:** `linksPlugin(options)` checks the built site's internal links after each build. Every `href` (on `a`, `link` and `area`), `src` (images, scripts, iframes, media), `srcset` and `imagesrcset` URL has to point at something in the output, and a `#fragment` has to match an `id` on the page it points to. URLs outside attributes are checked too, when they're on the site (from its root, or absolute on its address): `<meta>` values that are URLs (`og:image`, `og:url`, `twitter:image`), strings in `application/ld+json` blocks (without their `#fragment`, which names a thing there), and in `.xml` output (feeds, the sitemap), URLs in attributes and in elements like `<loc>` and `<id>`, including the escaped HTML of a feed entry's content. That's where an image URL the image plugin never saw shows up: a feed's `<img>` pointing at a source file that isn't published. The site's address is the `url` option, or the one `sitemap.xml` uses; links to it (`https://example.com/about/`, `http` or `https`) are checked like links from the root. Other external links aren't checked, and neither are paths a Netlify `_redirects` file in the output covers. Broken links fail production builds, listing each page and link (the first 20, then `... and N more (--verbose lists them all)`; `--verbose` lists every one), and are warnings in `ssqch serve`. One that's nearly right says what it probably meant: `/about/ -> /contactt/ (not found; did you mean /contact/?)`, and the same for an `id`. Options: `anchors` (check `#fragments`; default `true`), `ignore` (URL path prefixes to skip, like `["/downloads/"]`), `fail` (`true` or `false`; production builds only by default) and `url` (the site's address, like `"https://example.com"`; default: the address in `sitemap.xml`).
372
- - **`ssqch/sass`:** `sassPlugin({ files: { "src/scss": "/css" } })` compiles Sass with [grass](https://github.com/connorskees/grass), a Rust compiler built into the package as WebAssembly (no Dart Sass to install). It's 0.7's compiler, so stylesheets come out as 0.7 wrote them; Dart Sass writes some CSS differently, and a site that needs its bytes can run the `sass` package from `beforeBuild` instead (`{ run: "sass src/scss:dist/css" }`). A folder compiles every `.scss` and `.sass` file in it that doesn't start with `_`, keeping their paths; a file (`{ "src/app.scss": "/app.css" }`) compiles to the path given. The CSS is written at the start of each build, so `ssqch/assets` can fingerprint it and the link checker sees it, and `ssqch serve` rebuilds when a source changes. Options: `files` (required), `style` (`"compressed"` for production builds and `"expanded"` otherwise, by default) and `loadPaths`. (Yes, that makes it Sassquatch.)
373
- - **`ssqch/sitemap`:** `sitemapPlugin({ url: "https://example.com" })` writes `sitemap.xml` listing every HTML page with its absolute URL and its date as `<lastmod>`. Left out: pages with `sitemap: false` in their data, 404 pages, pages 2 and on of a list split into pages (pagination with a `size` over 1; a page per tag is still listed), and URLs matching `exclude` globs (`["/tags/**"]`). Options: `url` (required), `exclude`, `lastmod` (default `true`), `output` (default `"/sitemap.xml"`) and `paginated` (list every page of a split list).
364
+ - **`ssqch/sass`:** `sassPlugin({ files: { "src/scss": "/css" } })` compiles Sass with [grass](https://github.com/connorskees/grass), built into the package as WebAssembly, so there's no Dart Sass to install. grass writes a few things differently from Dart Sass; a site that needs Dart Sass's exact output can run the `sass` package from `beforeBuild` instead (`{ run: "sass src/scss:dist/css" }`). A folder compiles every `.scss` and `.sass` file in it that doesn't start with `_`, keeping their paths; a file (`{ "src/app.scss": "/app.css" }`) compiles to the path given. The CSS is written at the start of each build, so `ssqch/assets` can fingerprint it and the link checker sees it, and `ssqch serve` rebuilds when a source changes. Options: `files` (required), `style` (`"compressed"` for production builds and `"expanded"` otherwise, by default) and `loadPaths`. An import that names its extension (`@import "primer-core/index.scss"`) is found in the load paths too, as Dart Sass finds it, and a stylesheet that starts with Jekyll's front matter (`---` lines) compiles, the lines left blank. (Yes, that makes it Sassquatch.)
365
+ - **`ssqch/sitemap`:** `sitemapPlugin({ url: "https://example.com" })` writes `sitemap.xml` listing every HTML page with its absolute URL and its date as `<lastmod>`. Left out: pages with `sitemap: false` in their data, 404 pages, pages 2 and on of a list split into pages (pagination with a `size` over 1; a page per tag is still listed), and URLs matching `exclude` globs (`["/tags/**"]`). Options: `url` (required), `exclude`, `lastmod` (default `true`), `output` (default `"/sitemap.xml"`), `paginated` (list every page of a split list) and `alternates`, a page's translations as hreflang links: a function that gets each page (`url`, `inputPath`, `outputPath`, `date`, `data`) and returns `[{ hreflang: "fr", href: "/fr/guide/" }]`, the page itself included (`x-default` too, if you have one), or nothing. An `href` from the site's root gets the address and `base` in front, and the sitemap gets the `xhtml` namespace only when a page has some: `alternates: (page) => page.data.translations?.map((t) => ({ hreflang: t.lang, href: t.url }))`. It's called at once, so work the translations out in data or a collection first.
374
366
  - **`ssqch/elements`:** `elementsPlugin()` is interactivity without a framework. A custom element is a tag with a hyphen (`<like-button>`) and a script that defines it. Put `like-button.js` in `src/elements/` (and `like-button.css` next to it, if it has styles), write the tag in any page or layout, and that page gets the script and the stylesheet; pages without the tag get neither, so a page with no elements loads no JavaScript. What's inside the tag is the fallback a visitor sees before the script runs, or without JavaScript: `<like-button><a href="/likes/">3 likes</a></like-button>`. `ssqch:load` on a tag says when its script loads: `eager` (with the page, the default), `idle` (when the browser has a quiet moment) or `visible` (when the element scrolls into view), which is the "islands" idea without a framework to run it. The whole folder is copied to `/elements/`, so elements can import shared modules (a file without a hyphen in its name isn't an element). Options: `dir` (default: `elements` in the input folder, which has to exist), `url` (default `/elements/`) and `load` (`eager`, `idle` or `visible`: the default for tags without `ssqch:load`; any other value is an error that says so). The [`islands` example](examples/sites/islands/) has three small elements.
375
367
 
376
368
  - **`ssqch/redirects`:** `redirectsPlugin(options)` keeps old URLs working. A page lists its old URLs in front matter (`aliases: [/2019/pine-cones/, /pine.html]`), and the `redirects` option adds others (`{ "/feed/": "/feed.xml" }`, where the new URL can be on another site). Each old URL gets a small page that sends visitors on (a meta refresh, a canonical link and `noindex`), and with `netlify: true`, a `/old /new 301` line is appended to `_redirects`, after any lines your own `_redirects` template writes, and [`linksPlugin()`](#built-in-plugins) honors those lines. An old URL that's another page's URL is an error. For redirect pages in your own markup, add `_includes/hooks/redirect.*` (any engine): it gets `redirect.from` and `redirect.to` with the site's global data. Options: `pages` (default `true`), `netlify` (default `false`) and `redirects`.
@@ -402,7 +394,7 @@ heading_ids = "blackfriday"
402
394
  ssqch doesn't bundle CSS or JavaScript. It gets them into a site in one of four ways, and the tools you already use stay in charge of the rest:
403
395
 
404
396
  - **Plain CSS and ES modules:** copy them with `passthrough` (`passthrough: [{ "src/assets": "assets" }]`). Browsers load modules and `@import` without a bundler, which is often all a small site needs.
405
- - **Sass:** `sassPlugin()` from `ssqch/sass` compiles it on each build, with a Rust compiler built into ssqch ([Built-in plugins](#built-in-plugins)).
397
+ - **Sass:** `sassPlugin()` from `ssqch/sass` compiles it on each build, with a compiler built into ssqch ([Built-in plugins](#built-in-plugins)).
406
398
  - **Any other tool, for builds:** run it in `beforeBuild` (`{ run: "npx esbuild src/app.js --bundle --outfile=dist/app.js" }`), so `ssqch build` writes the CSS and JavaScript before it checks links and fingerprints them.
407
399
  - **Any other tool, while serving:** list its watcher in `serve.run`. `ssqch serve` starts it with the server, shows its output, and stops it (and whatever it started) when the server stops. When the watcher writes a file, the page picks it up: stylesheets swap without a reload. The server waits for the watchers' first compile before its first build (up to 2 seconds, then it says they wrote nothing and builds anyway), so the first page has its CSS, and after a rebuild it holds the browser's update until they have finished writing (150 ms of quiet), so an edit that adds Tailwind classes is one reload with the new CSS, not the page first and its CSS a moment later. If something else deletes what the watchers wrote (a production build into the same folder), the server starts them again and rebuilds.
408
400
 
@@ -431,7 +423,7 @@ When a page links a stylesheet or script that isn't in the output, `ssqch serve`
431
423
 
432
424
  ## Trailheads: moving from another generator
433
425
 
434
- Everything migrates eventually. The trailheads map another generator's config, front matter and templates onto ssqch's, and `ssqch docs --from <generator>` prints the one you need: [from Zola](docs/trailheads/from-zola.md), [from Eleventy](docs/trailheads/from-eleventy.md), [from Docusaurus](docs/trailheads/from-docusaurus.md), [from MkDocs](docs/trailheads/from-mkdocs.md), [from Hexo](docs/trailheads/from-hexo.md) and [from component frameworks](docs/trailheads/from-component-frameworks.md) (Astro, VitePress, Next.js, Gatsby). [`examples/sites/`](examples/sites/) has small, complete sites to start from or copy parts of, each built in CI: `blog-tags`, `blog-categories`, `docs-sidebar`, `glossary-docs`, `versioned-docs`, `component-docs`, `reference-pages` and `islands`.
426
+ Everything migrates eventually. The trailheads map another generator's config, front matter and templates onto ssqch's, and `ssqch docs --from <generator>` prints the one you need: [from Zola](docs/trailheads/from-zola.md), [from Eleventy](docs/trailheads/from-eleventy.md), [from Docusaurus](docs/trailheads/from-docusaurus.md), [from MkDocs](docs/trailheads/from-mkdocs.md), [from Hexo](docs/trailheads/from-hexo.md), [from Jekyll](docs/trailheads/from-jekyll.md) and [from component frameworks](docs/trailheads/from-component-frameworks.md) (Astro, VitePress, Next.js, Gatsby). [`examples/sites/`](examples/sites/) has small, complete sites to start from or copy parts of, each built in CI: `blog-tags`, `blog-categories`, `docs-sidebar`, `glossary-docs`, `versioned-docs`, `component-docs`, `reference-pages` and `islands`.
435
427
 
436
428
  For a Zola site, `ssqch import zola` moves `tags` out of `[taxonomies]` and turns `path` into `permalink` in each page's front matter, writes a first `ssqch.config.js` from `config.toml` (the site's data, Markdown options, Sass, redirects, a sitemap), and lists what the Tera templates, shortcodes and sections need.
437
429
 
@@ -471,15 +463,17 @@ The lay of the land:
471
463
 
472
464
  - **The data cascade:** a page's data comes from several places, and each one replaces what the ones before it set: global data, the front matter of its layouts, directory data, the page's data file, its front matter, then `computed`. [Where a value comes from](#where-a-value-comes-from) has the exact order, and `ssqch inspect` shows it for any page.
473
465
  - **Collections:** tags become collections, sorted by date, plus your custom ones. `excludeFromCollections: true` keeps a page out.
474
- - **Pagination:** `data`, `size`, `alias`, `reverse`, `filter`, `addAllPagesToCollections` and hrefs. `data: collections` goes over the collections' names, for a page per tag (`filter: [all]` leaves `all` out).
466
+ - **Pagination:** one template makes a page for each item, or each group of items, in a list. In its front matter, `pagination: { data: "collections.posts", size: 10, alias: "posts" }` and a `permalink` with the page number (`/blog/{% if pagination.pageNumber > 0 %}{{ pagination.pageNumber + 1 }}/{% endif %}`). `data` names the list: global data (`snacks`), a collection (`collections.posts`, a custom collection included, even one that returns plain objects, so one template can write a page per route of a route table), or `collections` itself, the collections' names, for a page per tag (`filter: [all]` leaves `all` out). `size: 1` gives a page per item, and `alias` names the item (`alias: post`, then `{{ post.data.title }}`). Each page gets `pagination.items` (its items), `pageNumber` (from 0), `pages` (every page's items), `hrefs` (every page's URL), `href.previous`, `href.next`, `href.first` and `href.last`. More options: `reverse`, `filter` (values to leave out) and `addAllPagesToCollections` (every page in the template's collections, not just the first). A `computed` value in a data file beside the template sees the alias, so each page's data can come from its item.
475
467
  - **Permalinks:** dynamic permalinks, `permalink: false` and `dynamicPermalink`. A permalink (or `computed` value) with `{{ }}` renders in the page's own template language, so a Liquid page can write `permalink: "/{{ title | slugify }}/"`; Markdown and HTML pages use their `markdownEngine` or `htmlEngine` (Edge when that's `false`).
476
468
  - **Front matter:** YAML between `---` lines, TOML between `+++` lines, or JSON after `---json` (`---yaml` and `---toml` work too). `.markdown` files are Markdown, like `.md`.
477
469
  - **Navigation:** `navTree(nav, page.url)` takes a tree from data (`_data/nav.yml`: entries with `title`, `url`, and children under `children`, `items` or `pages`) and marks each entry `current`, `ancestor` or `open`, for a sidebar that highlights where you are. `navPager(nav, page.url)` returns `{ previous, next }` in reading order, and `navBreadcrumbs(nav, page.url)` the entries from the top down to the page. To build the tree from front matter instead, give pages `nav: { title, parent, order }` (or `nav: true`; `parent` names another entry's title, or its `key` when it has one) and use `pagesTree(collections.docs)`. URLs match with or without `index.html` and the last `/`.
478
- - **Dates:** a page's `date` comes from its data, then from the start of its file name (`2024-06-01-post.md`), then from when the file last changed. `computed.date` works too.
470
+ - **Dates:** a page's `date` comes from its data, then from the start of its file name (`2024-06-01-post.md`), then from when the file last changed. `computed.date` works too. Collections are oldest first; undated pages come after the dated ones, in path order, so a fresh checkout or an edit (which changes file times) doesn't reorder them.
471
+ - **`SOURCE_DATE_EPOCH`:** set it (whole seconds since 1970, the reproducible-builds convention: `SOURCE_DATE_EPOCH=1767225600 ssqch build`) to pin the build's time, as Jekyll's `time:` does. `now()` in every engine, Liquid's `"now"`, Edge's `new Date()` and the date of every page without one become that time, so two builds of the same files write the same pages. A value that isn't a number is an error before the build starts. A site's own JavaScript (`Date.now()` in a filter) isn't changed.
479
472
  - **Drafts:** `draft: true` builds the page in development (`ssqch serve`, or `--env development`) and leaves it out of production builds, collections included.
480
473
  - **Excerpts and reading time:** `page.excerpt` is the HTML before a `<!-- more -->` comment, or else the first paragraph, for layouts and collections (`post.page.excerpt` in a list of posts). `readingTime(content)` is the minutes it takes to read some HTML at 200 words a minute (`readingTime(content, 250)` for another pace), at least 1.
481
474
  - **Slugs:** `slugify("Pine Cone Crunch!")` is `pine-cone-crunch`: lowercase letters and digits, with a dash for each run of anything else (apostrophes are dropped, and letters outside ASCII are kept). It's the same function in every template language (`{{ title | slugify }}` in Jinja, Nunjucks and Liquid), and a config filter named `slugify` replaces it. `slugify(title, { separator: "_" })` (or `slugify(title, "_")`, `{{ title | slugify: "_" }}` in Liquid) puts another separator between the words, for URLs like `/recipes/taco_bake/`. Apostrophes are dropped (`Drew's Brownies` is `drews-brownies`); `apostrophes: "separate"` splits words there instead (`drew-s-brownies`), for a site whose URLs were made that way. Another option is an error. Before replacing a site's own slug filter with `slugify`, build with both and compare with `ssqch diff`: one changed URL is a broken link. Data files can import it, and `slugger()`, from `ssqch`.
482
475
  - **Choosing engines:** pages are Jinja (`.jinja`) unless you list other languages in `templateFormats`, and `.md` files run through Jinja first, then Markdown (change that with `markdownEngine` and `htmlEngine`). Layouts follow the same rules, so a `.html` layout is a Jinja template by default. A template's `render` front matter overrides it: `render: md` for Markdown only (handy for a post full of `{{ }}` code samples), `render: [edge, md]` for a chain, or `render: false` to write the body as it is. A layout chain can mix languages (a Markdown post in a Liquid layout that sits in an Edge one). Around here that's called trail mix.
476
+ - **Text files with front matter** (Jekyll renders any file that starts with `---`, like a `.js` or `.txt` file): give the extension an engine that hands the text back, `engines: { js: (s) => s }`, add it to `templateFormats`, and in that folder's directory data (`assets/js/js.json`) set `"render": "liquid,js"` (Liquid first, or the engine you use) and `"permalink": "/{{ page.filePathStem }}.js"`, so the file keeps its name instead of becoming `app/index.html`. The config and the modules it imports are never pages, so `lib/filters.js` stays code. A `.scss` file with front matter needs nothing: `sassPlugin()` blanks it.
483
477
  - **Everything else:** layout chaining, `page.*`, `templateContent` in collections, and an error when two pages would write the same file. Every template can read `ssqch.version`, `ssqch.env`, `ssqch.serving` and `ssqch.generator`.
484
478
 
485
479
  Templates are [Jinja](#jinja-and-nunjucks) by default; [Edge](#edge), [Liquid](#liquid), [Nunjucks](#jinja-and-nunjucks), [Handlebars and Mustache](#handlebars-and-mustache) and [EJS](#ejs) are a `templateFormats` entry away, and one site can use several.
@@ -514,7 +508,7 @@ export default defineConfig({
514
508
 
515
509
  | Option | Default | What it does |
516
510
  | --- | --- | --- |
517
- | `headingIds` | `"github"` | Automatic heading `id`s. `"github"` matches GitHub's anchors (`Hello, World!` becomes `hello-world`); `"blackfriday"` matches Hugo's older ones (`A -- B` becomes `a-b`, not `a----b`); `"ascii"` transliterates first (`Straße 🦀` becomes `strasse-crab`, like Zola's). A function of the heading's text makes your own: `headingIds: (text) => ...`. A repeated heading gets `-1`, `-2` and so on. `false` turns them off. |
511
+ | `headingIds` | `"github"` | Automatic heading `id`s. `"github"` matches GitHub's anchors and github-slugger's (rehype-slug's, so Astro's, VitePress's and Docusaurus's) character for character (`Hello, World!` becomes `hello-world`; letters in any script, combining accents and emoji joiners stay); `"blackfriday"` matches Hugo's older ones (`A -- B` becomes `a-b`, not `a----b`); `"ascii"` transliterates first (`Straße 🦀` becomes `strasse-crab`, like Zola's). A function of the heading's text makes your own: `headingIds: (text) => ...`. A repeated heading gets `-1`, `-2` and so on. `false` turns them off. |
518
512
  | `headingAttributes` | `true` | `## Install {#setup .wide}` sets the heading's `id` and `class`. An `id` given this way always wins. Markdown that runs through Jinja or Nunjucks first (the default) keeps it: `{#` at the end of a line, closed by `}` rather than `#}`, isn't a comment there. |
519
513
  | `footnotes` | `true` | `[^1]` references, with the notes in a `<section class="footnotes">` at the end and links back to each reference. |
520
514
  | `taskLists` | `true` | `- [ ]` and `- [x]` items, as disabled checkboxes. |
@@ -536,7 +530,7 @@ const trailnotes = code => code.split( /(^!.*$|@\w+)/m ).filter( Boolean ).map(
536
530
  export default { markdown: { highlight: { languages: { trailnotes, trail: "trailnotes" } } } };
537
531
  ```
538
532
 
539
- **A table of contents:** after a page's content renders, `page.headings` lists its headings (`level`, `id` and `text`), so its layouts can build a table of contents. The built-in `toc` filter does it for you: `{{{ toc(page.headings) }}}` writes nested `<ul>` links to the `h2` and `h3` headings, and `toc(page.headings, { from: 2, to: 4, ordered: true })` changes the levels or uses `<ol>`. In Liquid that's `{{ page.headings | toc: 2, 4 }}`, and in Nunjucks, `{{ toc(page.headings) | safe }}`. The headings come from the HTML, so they work for pages in any template language. Collections have them too (`post.page.headings`).
533
+ **A table of contents:** after a page's content renders, `page.headings` lists its headings (`level`, `id` and `text`), so its layouts can build a table of contents. The built-in `toc` filter does it for you: `{{{ toc(page.headings) }}}` writes nested `<ul>` links to the `h2` and `h3` headings, and `toc(page.headings, { from: 2, to: 4, ordered: true })` changes the levels or uses `<ol>`. `id` and `class` go on the outer list, `sublistClass` on the lists inside it, `itemClass` on each `<li>` (with `{level}` replaced by the heading's level) and `linkClass` on each link, so jekyll-toc's markup is `toc(page.headings, { class: "section-nav", itemClass: "toc-entry toc-h{level}" })`, and an unknown option is an error that lists them. In Liquid that's `{{ page.headings | toc: 2, 4 }}`, or `{{ page.headings | toc: class: "section-nav" }}` with options, and in Nunjucks, `{{ toc(page.headings) | safe }}`. The headings come from the HTML, so they work for pages in any template language. Collections have them too (`post.page.headings`). They're there once the page has rendered: in its layouts, and in a collection item after that item's `templateContent` has been read. Read in `computed`, which runs before any page renders, they're an empty list.
540
534
 
541
535
  **Highlighting anywhere:** `highlight(code, lang)` returns the highlighted HTML for the inside of a `<code>` (escaped text for a language without a grammar), for code that isn't a Markdown fence: an example container's source, a snippet from a data file.
542
536
 
@@ -544,7 +538,7 @@ export default { markdown: { highlight: { languages: { trailnotes, trail: "trail
544
538
 
545
539
  **Markdown anywhere:** the `markdown` filter renders a string, such as a description from front matter: `{{{ markdown(summary) }}}`, or `markdown(title, "inline")` (in Liquid, `{{ title | markdown: "inline" }}`) to leave out the `<p>`. Config and data files can `import { markdown } from "ssqch"`.
546
540
 
547
- **Containers:** a block between `::: name` and `:::` renders through `_includes/containers/name.*`, a template in any engine. It gets the page's data plus `container.name`, `container.args` (the rest of the opening line, without `[` `]` around it: `:::tip[Watch out]` works), `container.content` (the block's Markdown, rendered) and `container.source` (the block's lines as written, for an example that shows its own code). One template covers admonitions, tabs, figures or anything else that wraps content:
541
+ **Containers:** a block between `::: name` and `:::` renders through `_includes/containers/name.*`, a template in any engine. It gets the page's data plus `container.name`, `container.args` (the rest of the opening line, without `[` `]` around it: `:::tip[Watch out]` works), `container.props` (the arguments read as a component's attributes: `::: card type="tip" open items='["a","b"]'` is `{ type: "tip", open: true, items: ["a", "b"] }`, where a single-quoted value that starts with `{` or `[` is JSON, an unquoted one like `size=3` is the text `3`, and a word on its own is `true`), `container.slots` (below), `container.content` (the block's Markdown, rendered) and `container.source` (the block's lines as written, for an example that shows its own code). One template covers admonitions, tabs, figures or anything else that wraps content:
548
542
 
549
543
  ```markdown
550
544
  ::: warning Hot pine cones
@@ -562,6 +556,26 @@ They're **very** crunchy.
562
556
 
563
557
  Containers nest: an outer one opens with more colons (`::::`) and closes with as many. Without a template, a container renders as `<div class="name">` (with the arguments as a `<p class="container-title">`). An alert renders through a container template with its name, if there is one, so `containers/warning.njk` styles `> [!WARNING]` too.
564
558
 
559
+ **Named slots:** a `::: slot <name>` block (or `::: slot name="<name>"`) inside another container is that container's `container.slots.<name>`, its Markdown rendered, and is left out of `container.content`, as MDX's `<Fragment slot="title">` and a component's named slots are. Two slots with the same name are joined. A slot with no container template around it to take it (the container renders as a `<div>`, or the slot is on its own) stays where it is, as its content. `slot` is ssqch's: `_includes/containers/slot.*` is an error.
560
+
561
+ ```markdown
562
+ :::: card type="tip"
563
+ Squatch Snacks, **crunchy**.
564
+
565
+ ::: slot title
566
+ Pine Cone Crunch
567
+ :::
568
+ ::::
569
+ ```
570
+
571
+ ```njk
572
+ {# src/_includes/containers/card.njk #}
573
+ <div class="card {{ container.props.type }}">
574
+ <h3>{{ container.slots.title | safe }}</h3>
575
+ {{ container.content | safe }}
576
+ </div>
577
+ ```
578
+
565
579
  **Render hooks:** templates in `_includes/hooks/` take over how parts of Markdown render, in any engine. Each gets the page's data plus one value:
566
580
 
567
581
  | Template | Gets | For example |
@@ -580,6 +594,18 @@ Containers nest: an outer one opens with more colons (`::::`) and closes with as
580
594
 
581
595
  Put `aria-hidden="true"` on decoration like that `#`, and `page.headings` leaves it out of the heading's text.
582
596
 
597
+ A fence hook writes the whole block, so it has to write `<pre><code>` itself: `fence.highlighted` is only what goes inside it (spans, already escaped), and `fence.code` is the raw text, which the template escapes (Nunjucks and Jinja do it by themselves; in Liquid write `{{ fence.code | escape }}`). With `highlight` off, `highlighted` is empty:
598
+
599
+ ```njk
600
+ {# src/_includes/hooks/fence.njk #}
601
+ <div class="code-block">
602
+ <button class="copy" data-code="{{ fence.code }}">Copy</button>
603
+ <pre><code class="language-{{ fence.lang }}">
604
+ {%- if fence.highlighted %}{{ fence.highlighted | safe }}{% else %}{{ fence.code }}{% endif -%}
605
+ </code></pre>
606
+ </div>
607
+ ```
608
+
583
609
  ### Jinja and Nunjucks
584
610
 
585
611
  Jinja is ssqch's default template language: `.jinja` (and `.j2`) pages and layouts render with ssqch's own fork of [Nunjucks](https://mozilla.github.io/nunjucks/), the library Eleventy's Nunjucks templates run on, with Jinja's filters, tests, functions and string, list and dict methods on top, so templates written for Jinja (MkDocs themes, say) run too. Markdown and HTML files run through it first. `ssqch init` starts a site in it. `.njk` files render with the same library, printing values as Nunjucks does. Add `"njk"` (Nunjucks) or `"j2"` to `templateFormats` for those extensions, `markdownEngine: "njk"` to run Markdown through the Nunjucks flavor, and `render: [njk, md]` to do that for one post. A home page, `src/index.jinja`, that lists the posts:
@@ -620,7 +646,7 @@ export default defineConfig({
620
646
 
621
647
  All of edge.js is there: `{{ }}`, `{{{ }}}`, `{{-- --}}`, `@{{ }}`, `@if/@elseif/@else/@unless`, `@each` (with index, objects, `@else` and `$loop`), `@let` (destructuring included) and `@assign`, `@include` and `@includeIf`, `@component` and `@!component` with named slots and isolated scope, `@eval`, `@inject`, `@stack` and `@pushTo`, `~` whitespace control, and edge.js's helpers (`excerpt`, `html.attrs`, `nl2br` and the rest; `nl2br` gives HTML to print as it is, so escape what it's given: `{{{ nl2br(html.escape(text)) }}}`). Expressions are JavaScript: object and array literals, template literals, optional chaining, arrow functions with block bodies, regular expressions, the `in` operator, `await`, and Node's globals (`process`, `URL`; a page's value or a config function of the same name wins). `await` waits for a promise, and an async function (an async config filter) is awaited when it's called in a mustache or `@let`. Inside a callback it's awaited in `map` (`posts.map(p => cover(p))`), and in `filter`, `find` and the others it's an error that says to call it first with `@let`.
622
648
 
623
- ssqch keeps what its Edge did in 0.7 around edge.js, so a template that rendered then renders now: an undefined value prints nothing (edge.js prints `undefined`), a call reaches the config filter when the page has a field of the same name (`{{ image(...) }}` beside `image:` in front matter), a mustache can start with an object literal (`{{ { tip: 'T' }[kind] }}`), `@let(n = n - 1)` reads the value it replaces, `reverse()` and `sort()` give copies (so a page can't reorder a collection under the next one), dates are in UTC and print as ISO 8601, strings index by character, and numbers never print in exponent notation. `{{ safe(html) }}` prints `html` as it is, as edge.js's `html.safe` does. A variable an include declares with `@let` stays in the include unless the including template declares it first. Errors report `template:line` through the include and component chain, a parse error is in edge.js's words (`parse error in page.edge: line 2: Unexpected token`), and a function that isn't there says which one you probably meant (``index.edge:2: `uper` is not a function (did you mean `upper`?)``), or ssqch's name for another generator's (`slug`).
649
+ ssqch smooths a few of edge.js's corners: an undefined value prints nothing (edge.js prints `undefined`), a call reaches the config filter when the page has a field of the same name (`{{ image(...) }}` beside `image:` in front matter), a mustache can start with an object literal (`{{ { tip: 'T' }[kind] }}`), `@let(n = n - 1)` reads the value it replaces, `reverse()` and `sort()` give copies (so a page can't reorder a collection under the next one), dates are in UTC and print as ISO 8601, strings index by character, and numbers never print in exponent notation. `{{ safe(html) }}` prints `html` as it is, as edge.js's `html.safe` does. A variable an include declares with `@let` stays in the include unless the including template declares it first. Errors report `template:line` through the include and component chain, a parse error is in edge.js's words (`parse error in page.edge: line 2: Unexpected token`), and a function that isn't there says which one you probably meant (``index.edge:2: `uper` is not a function (did you mean `upper`?)``), or ssqch's name for another generator's (`slug`).
624
650
 
625
651
  ### Liquid
626
652
 
@@ -636,11 +662,14 @@ export default defineConfig({
636
662
  });
637
663
  ```
638
664
 
639
- - **Data:** Liquid templates get the same data as the other engines: front matter, the cascade, `page`, `collections` and `content` in layouts. Unknown variables and properties print nothing, as in Jekyll.
665
+ - **Data:** Liquid templates get the same data as the other engines: front matter, the cascade, `page`, `collections` and `content` in layouts. Unknown variables and properties print nothing, as in Jekyll. Front matter is at the top level (`{{ title }}`), not under `page` as in Jekyll: a template that reads `page.title` gets nothing, and the build warns once for each such name, naming the page.
640
666
  - **Filters:** liquidjs' standard filters and tags (`where_exp`, `sum`, `{% liquid %}`, `{% echo %}`), Jekyll's `push`, `pop`, `shift`, `unshift`, `array_to_sentence_string`, `date_to_xmlschema`, `date_to_rfc822`, `date_to_string` and `date_to_long_string`, and Shopify's `pluralize`. `slugify` is ssqch's, the same as in the other languages. Your config `filters` work too: `{{ title | shout }}` calls `shout(title)`, and `{{ x | wrap: "[", "]" }}` calls `wrap(x, "[", "]")`. A config filter replaces a built-in one with the same name.
641
- - **Dates** print as ssqch's Liquid has always printed them (`2026-01-02 00:00:00 +0000`, in UTC, whatever the machine's time zone) in every filter, and `date` reads ISO 8601 text (`2024-03-04`).
667
+ - **Dates** print as `2026-01-02 00:00:00 +0000`, in UTC, whatever the machine's time zone, in every filter, and `date` reads ISO 8601 text (`2024-03-04`).
642
668
  - **Objects:** `{{ some_object }}` prints `[object Object]`, so write `{{ some_object | json }}`; `{{ some_object.size }}` is its number of keys, and a string's `size` counts as JavaScript does (`café` is 4). A variable named `empty` or `blank` is Liquid's keyword (`{% if empty %}`), so rename it.
643
669
  - **Includes:** `{% include "nav.html" %}` and Jekyll's `{% include nav.html section="home" %}` (read as `include.section`) see the page's variables. `{% render "footer", year: 2026 %}` sees only what it's given, and prints nothing for a variable it wasn't given (with `strict`, that is an error). Both read from `_includes`, adding `.liquid` when the name has none.
670
+ - **`include_relative`:** Jekyll's `{% include_relative parts/intro.md who="rangers" %}` reads a file beside the template that has the tag (or in a folder below it), not in `_includes`, and renders it with the page's variables and `include.who`. The name can have `{{ }}` in it (`parts/{{ lang }}.md`); `..` is refused, as in Jekyll. The file is read as it is, front matter and all, and a Markdown file there is a page of its own too, so give it `permalink: false` in directory data (not in its front matter) or keep it out with `ignore`.
671
+ - **Your own tags:** a config filter is a tag too, as in Nunjucks, so a Jekyll plugin's tag can be a function: `{% seo %}` prints what `seo()` returns, without escaping it. Arguments are values, by commas or spaces (`{% image "/a.png", "A pine" %}`), and `name: value` or Jekyll's `name=value` arrive as one object at the end (`{% seo title=false %}` calls `seo({ title: false })`). With a closing tag, the function gets what's between them first: `{% callout "tip" %}...{% endcallout %}` calls `callout(content, "tip")`. A function can be async. Liquid's own tags keep their names: a filter called `include` is a filter only. Arguments are plain values: a filter inside a tag's arguments (`{% image page.cover | url %}`) is an error, so `assign` it first.
672
+ - **Ruby's Liquid:** math, `split` and blank blocks follow Ruby's Liquid (4.0.4, Jekyll's and GitHub Pages'): `plus`, `minus`, `times`, `divided_by`, `modulo` and the rest read text as Ruby does (`"3.5"` is a float, `"3.5x"` is 3, `"r>"` and nothing are 0); `split` drops empty strings at the end and splits `" "` at every run of whitespace; and an `if`, `unless`, `for` or `case` whose bodies are only whitespace, `assign`, `capture` and comments writes nothing, so a layout that computes in blocks doesn't fill with blank lines. Dividing by zero is still an error.
644
673
  - **Mixing engines:** a Liquid page can use a Jinja layout and the other way around.
645
674
  - **Errors** name the file and line, and an unknown filter gets the closest name (`did you mean`).
646
675
 
@@ -675,8 +704,40 @@ Add `"hbs"` (or `"handlebars"`) or `"mustache"` to `templateFormats`, and those
675
704
  - **Errors** name the template and line, and the lines under them are the file's own. A variable nothing defines is a `ReferenceError`, as in EJS (`typeof x` is still safe).
676
705
  - **Starters:** `ssqch init --engine ejs` (and `--starter docs --engine ejs`) writes the starters' layouts, render hook and containers in EJS.
677
706
 
707
+ ### Multilingual sites: translations, i18n and hreflang
708
+
709
+ ssqch has no built-in i18n yet ([TODO.md](TODO.md), "Internationalization"). What two real sites (one from Jekyll, one from Astro) did instead, with what ssqch has:
710
+
711
+ - **A folder per language** (`content/fr/guide.md`), and the language from directory data (`content/fr/fr.json`: `{ "lang": "fr" }`) or front matter. A key that groups a page's translations (the file's path below the language folder, or a front matter key like `translationKey`).
712
+ - **A page's translations** are a lookup in a collection: `collections.docs | where: "data.key", key` in Liquid, or a filter of your own that groups pages by key once.
713
+ - **Fallback pages** (the default language's page at another language's URL): a collection function that returns one object per URL (`{ lang, slug, page }`), choosing the translation when there is one, and one template with `pagination: { data: "collections.routes", size: 1, alias: "route" }` and `permalink: "/{{ route.lang }}/{{ route.slug }}/"` that writes `route.page.templateContent`. The content pages get `permalink: false`, so they're written only where the routes put them.
714
+ - **Strings:** `_data/i18n/<lang>.json`, read in templates as `i18n[lang].nav.about`, or a `t(lang, key)` filter that falls back to the default language.
715
+ - **hreflang:** a loop over the page's translations in the layout's `<head>`, with `x-default` for the default language; `sitemapPlugin({ url, alternates })` lists the same translations in the sitemap.
716
+ - **Direction:** `dir` on `<html>` from a language list in data (`{ "ar": { "dir": "rtl" } }`).
717
+ - **Old language codes:** `aliases` on each page, or `redirectsPlugin({ redirects })`.
718
+
719
+ ### SEO tags
720
+
721
+ ssqch writes no `<head>` tags of its own, so a site's title, description, canonical link, Open Graph and Twitter tags are a partial in its layout. A starting point (Nunjucks):
722
+
723
+ ```njk
724
+ {# _includes/seo.njk #}
725
+ <title>{{ title ~ " · " ~ site.title if title else site.title }}</title>
726
+ <meta name="description" content="{{ description or site.description }}">
727
+ <link rel="canonical" href="{{ site.url ~ page.url }}">
728
+ <meta property="og:title" content="{{ title or site.title }}">
729
+ <meta property="og:description" content="{{ description or site.description }}">
730
+ <meta property="og:url" content="{{ site.url ~ page.url }}">
731
+ <meta property="og:image" content="{{ site.url ~ (image or "/og.png") }}">
732
+ <meta name="twitter:card" content="summary_large_image">
733
+ ```
734
+
735
+ Jekyll's `{% seo %}` (jekyll-seo-tag) becomes this include. JSON-LD, if the site wants it, is a `json` (Liquid), `tojson` (Jinja) or `dump` (Nunjucks) of an object built in the template or by a filter.
736
+
678
737
  ## Themes
679
738
 
739
+ <img align="right" src="docs/assets/stickers/tent.svg" alt="" width="96">
740
+
680
741
  A theme is a folder shaped like a site's input folder: `_includes/` (layouts, partials, render hooks, containers), `_data/`, pages, and files to copy, like stylesheets and fonts. Your site sits on top of it:
681
742
 
682
743
  ```js
@@ -705,6 +766,8 @@ To change something in a git theme, copy that one file from `.cache/ssqch/themes
705
766
 
706
767
  ## Content schemas
707
768
 
769
+ <img align="right" src="docs/assets/stickers/ranger-mary.svg" alt="" width="96">
770
+
708
771
  Front matter is easy to get wrong: a misspelled key, a date that isn't one, a hero image that was renamed. A schema says what a kind of page's data has to look like, and every build checks it:
709
772
 
710
773
  ```js
@@ -804,7 +867,7 @@ A page's data is a cascade. From the lowest level to the highest:
804
867
  3. **Directory data:** `posts/posts.json` (or `.yaml`, `.toml`, `posts.data.js`) applies to everything in `posts/` and below it. The outermost folder goes first.
805
868
  4. **The page's data file:** `pine.json` or `pine.data.js` next to `pine.md`.
806
869
  5. **Front matter.**
807
- 6. **`computed`:** worked out last, from everything above.
870
+ 6. **`computed`:** worked out last, from everything above. It can't set `layout` from the page's data (the layout is chosen first) or `page` (ssqch's own: a computed `page` is an error); both name the file.
808
871
 
809
872
  A higher level replaces what a lower one set. Objects merge key by key and lists are joined (a post's `tags` add to its folder's), unless `deepMerge` is off. `page` and `ssqch` are built in.
810
873
 
@@ -879,6 +942,8 @@ With `--verbose`, a line under the summary names the templates in the includes f
879
942
 
880
943
  ## Comparing two builds
881
944
 
945
+ <img align="right" src="docs/assets/stickers/footprint.svg" alt="" width="96">
946
+
882
947
  A build that succeeds isn't proof that an upgrade, a refactor or a migration left the site alone. `ssqch diff` compares two output folders and says what changed, which is better evidence than most sightings get:
883
948
 
884
949
  ```sh
@@ -923,6 +988,8 @@ Changes found: 3 pages and 1 other file (2 changed, 1 added, 1 removed); 148 pag
923
988
 
924
989
  It works on any two folders of HTML, so it can also compare another generator's output with ssqch's while you move a site over.
925
990
 
991
+ **Several builds:** give it three or more folders and it lists what varies between them instead: `ssqch diff ref-1 ref-2 ref-3`. Build the same site the same way into each (from fresh copies), and it names each file that isn't the same in all of them, which builds agree (`ref-1, ref-2 agree; ref-3 differs`, or `only in ref-2`), and the lines that differ between the most common version and the next. "The same" is what a diff of two calls the same, so fingerprints and whitespace between tags don't count (`--exact`, `--ignore` and `--only` work as above). Do it first when moving a site from another generator: if its own build changes by itself (Jekyll printing the build's time, ids from `Math.random()`), pin that or `--ignore` it before comparing its output with ssqch's. The exit code is 0 when every build is the same and 1 when something varies; `--format json` has `runs`, `same`, `summary` (`varies`, `steadyPages`, `steadyFiles`) and `varies` (each file's `url`, `path`, `kind`, `versions` with their `runs` and `missing`, `changedLines` and `hunks`).
992
+
926
993
  ## A build's footprint
927
994
 
928
995
  `ssqch footprint` says how much the last build weighs, by kind of file, and which pages and files leave the largest footprints:
@@ -990,7 +1057,7 @@ ssqch build --format json
990
1057
  - **A build that works** also has `durationMs`, `pages` (`written`, `templates`, `bytes`, and `new` and `gone` since the last build to that folder, or `null` when there wasn't one), `copied`, `removed`, `drafts` (the `draft: true` pages a production build left out), `written` (each page's file, from the output folder), `summary` (the lines plugins add to the [build summary](#reading-the-build-summary)) and `timings`.
991
1058
  - **Standard output is only the report.** The lines a person would have read (`[ssqch] Writing ...`), `console.log` from your config and the output of `beforeBuild` commands go to standard error; `--quiet` leaves the progress lines out.
992
1059
 
993
- `ssqch capabilities --format json` says what the installed ssqch supports, so nothing has to be guessed from the documentation of another version: its `version`, `commands`, `features` (`avif`, `fetch`, `sass` and each template language, listed only when this build can do them), `templateLanguages` with their extensions, `configFiles`, `configOptions`, the built-in `modules` with what each exports, `nodeModules` (they're Node's own, so all 32 are `available` and `stubs` is an empty list), `globals` and `imageFormats`. Without `--format json` it prints the same as text, under "What's in the pack".
1060
+ `ssqch capabilities --format json` says what the installed ssqch supports, so nothing has to be guessed from the documentation of another version: its `version`, `commands`, `features` (`avif`, `fetch`, `sass` and each template language, listed only when this build can do them), `templateLanguages` with their extensions, `configFiles`, `configOptions`, the built-in `modules` with what each exports, `nodeModules` (Node's built-in modules), `globals` and `imageFormats`. Without `--format json` it prints the same as text, under "What's in the pack".
994
1061
 
995
1062
  `ssqch docs` is this documentation, from the package, so it matches the version that's installed and works without the network. Alone, it lists every command, config option, template function and module export with one line each. `ssqch docs base` (or `imagePlugin`, `toc`, `serve`) prints what this README says about that name and which other sections mention it, `ssqch docs "content schemas"` prints a section, and other words search the text. Another generator's word gets ssqch's (`ssqch docs pathPrefix`), and `ssqch docs --from eleventy` lists that generator's words with ssqch's for each, then its trailhead. `--format json` has the same, with each answer's `names`, `section` and `also`.
996
1063
 
@@ -1020,6 +1087,8 @@ The other commands with JSON are [`ssqch inspect --format json`](#where-a-value-
1020
1087
 
1021
1088
  ## Deploying
1022
1089
 
1090
+ <img align="right" src="docs/assets/stickers/canoe.svg" alt="" width="96">
1091
+
1023
1092
  ### Keep the image cache between builds
1024
1093
 
1025
1094
  Encoding images is by far the slowest part of a build, so it's worth never doing it twice. Each image file is named by a hash of the source image's contents and the encoder settings, not its path or modification time, and it's encoded into `.cache/ssqch/img/`, outside the output. Each build links the files it uses into the output's `img/` folder (a hard link, so no extra space, or a copy where links don't work), so you can delete the output folder whenever you like and the next build encodes nothing. Restore `.cache/ssqch` from the last build in CI, and a build with no new images encodes nothing there either, even on a fresh clone. (An output folder from before the cache, or one a deploy cache restored, is taken in as it is: its files move into the cache instead of being encoded again.) `cacheDir` on `imagePlugin()` puts the cache somewhere else, and `cacheDir: false` encodes straight into the output, which then has to be kept to keep the images.
@@ -1077,19 +1146,17 @@ Netlify can build the site itself, with no deploy token to manage. With `ssqch`
1077
1146
  paths = [".cache/ssqch"]
1078
1147
  ```
1079
1148
 
1080
- - **The `ssqch` dev dependency** pins the version, so a new SiteSquatch release can't surprise a deploy. Pin it exactly (`pnpm add -D ssqch@0.8.0`) and bump it when you're ready. On the day of a release, pnpm's release age holds a new version back: list `ssqch` (the only package of ssqch's own) under `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`, as [Install](#install) shows.
1081
- - **`NODE_VERSION`** is the Node that runs the build: anything from 22.18 on. ssqch builds to the same bytes on 22.18, 24 and 26, so pick the one your other build tools like.
1149
+ - **The `ssqch` dev dependency** pins the version, so a new SiteSquatch release can't surprise a deploy. Pin it exactly (`pnpm add -D ssqch@0.9.0`) and bump it when you're ready.
1150
+ - **`NODE_VERSION`** is the Node that runs the build: anything from 22.18 on. ssqch builds the same bytes on every supported Node, so pick the one your other build tools like.
1082
1151
  - **[`netlify-plugin-cache`](https://github.com/jakejarvis/netlify-plugin-cache)** carries `.cache/ssqch` (the encoded images and their hashes, highlighted code, and any `fetch` copies) over to the next build. Add it to your `devDependencies`.
1083
1152
 
1084
- A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.8.0"` under `[build.environment]` to pin it (and `NODE_VERSION` there as well):
1153
+ A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.9.0"` under `[build.environment]` to pin it (and `NODE_VERSION` there as well):
1085
1154
 
1086
1155
  ```toml
1087
1156
  [build]
1088
1157
  command = "npx --yes ssqch@$SSQCH_VERSION build"
1089
1158
  ```
1090
1159
 
1091
- On the blog, the first Netlify build (which encoded every image) took about 4 minutes with 0.7, and the next one took 18 seconds, including Netlify's own setup. 0.8 encodes the blog's images in less than half 0.7's time on the same machine (see [Benchmarks](#benchmarks)).
1092
-
1093
1160
  ### GitHub Pages
1094
1161
 
1095
1162
  A project site is served at `https://you.github.io/<repository>/`, so the build needs that path as its [`base`](#serving-a-site-under-a-path). This workflow builds on every push to `main` and deploys with GitHub's own Pages actions (in the repository's settings, set Pages' source to "GitHub Actions"):
@@ -1132,24 +1199,19 @@ jobs:
1132
1199
 
1133
1200
  ## Benchmarks
1134
1201
 
1135
- No blurry footage here: these numbers come from building the ReverentGeek blog (161 HTML pages plus a feed, a sitemap and Netlify files) on an Apple M5 Pro (15 cores), in production mode with HTML minification on, with ssqch 0.8 on Node 26. Each build wrote to its own output folder, so no image cache was shared.
1202
+ No blurry footage here: these numbers come from building the ReverentGeek blog (161 HTML pages plus a feed, a sitemap and Netlify files) on an Apple M5 Pro (15 cores), in production mode with HTML minification on, with ssqch 0.8.0 on Node 26.
1136
1203
 
1137
- | Build | `ssqch` 0.8 (Node) | `ssqch` 0.7 (Rust) |
1204
+ | Build | Time | Peak memory |
1138
1205
  | --- | --- | --- |
1139
- | **Cold** (no images cached) | **25.6 s** | 60.2 s |
1140
- | CPU time, cold (user + sys) | 341 s | 737 s |
1141
- | Peak memory, cold | 2.6 GB | 1.8 GB |
1142
- | **Warm** (images cached, median of 3) | **0.92 s** | 0.38 s |
1143
- | Peak memory, warm | 328 MB | 239 MB |
1144
- | Image files written | 4,985 (266 MB) | 4,985 (298 MB) |
1145
-
1146
- - **Warm builds** are what the dev server and cached CI builds do. Wall times include starting the process: Node starts, and ssqch loads from its compile cache, in a few dozen milliseconds.
1147
- - **The JavaScript config** runs on Node's V8, with a JIT, so the blog's collections, filters and data files cost what they would in any Node script. (0.7 ran them in QuickJS, an interpreter.)
1148
- - **Cold builds** are mostly image encoding, and AVIF is the most expensive format. sharp encodes with libaom, at the blog's `avifEffort: 3` (0.7's speed 4): the files are smaller and quicker to make than 0.7's, which used rav1e. They're single runs and vary.
1206
+ | **Cold** (every image encoded: 4,985 files, 266 MB) | **25.6 s** (341 s of CPU) | 2.6 GB |
1207
+ | **Warm** (images cached, median of 3) | **0.92 s** | 328 MB |
1208
+
1209
+ - **Warm builds** are what the dev server and cached CI builds do, and the time includes starting Node.
1210
+ - **Cold builds** are mostly image encoding, and AVIF is the most expensive format (the blog uses `avifEffort: 3`). They're single runs and vary.
1149
1211
  - **One thread renders, the thread pool encodes:** pages render one at a time on one thread (there are no worker threads), written as they render, and image encoding runs on libuv's thread pool, which uses every core. A site with heavy per-page JavaScript uses one core for it.
1150
1212
  - Only site generation is measured, not building the CSS and JavaScript.
1151
1213
 
1152
- The speed check ssqch runs on itself is a synthetic site of 10,000 pages, built on one thread (`node packages/ssqch/bench/bench.ts` in the repository), plus v8.dev's exact port from Eleventy: on the same machine, the 10,000 pages build in 1.12 s and 370 MB (0.7 took 2.70 s on one thread), and v8.dev in 0.58 s. CI compares each commit with its parent on the same runner and fails a change that makes the 10,000-page build more than 15% slower.
1214
+ The speed check ssqch runs on itself is a synthetic site of 10,000 pages, built on one thread (`node packages/ssqch/bench/bench.ts` in the repository), plus v8.dev's exact port from Eleventy: on the same machine, the 10,000 pages build in 1.12 s and 370 MB, and v8.dev in 0.58 s. CI compares each commit with its parent on the same runner and fails a change that makes the 10,000-page build more than 15% slower.
1153
1215
 
1154
1216
  For a bigger site, `scripts/synthetic-site.py <folder> [pages] [engine]` writes a synthetic documentation site: 9,001 Markdown pages by default (about the size of kubernetes.io's English docs) in 60 sections, each page with a 9,000-entry sidebar from a data file, a table of contents, a highlighted code fence, a schema check and the link checker. On the same machine, production builds of it take:
1155
1217
 
@@ -1159,13 +1221,13 @@ For a bigger site, `scripts/synthetic-site.py <folder> [pages] [engine]` writes
1159
1221
  | Nunjucks | 2.74 s | 7.0 s | 454 MB |
1160
1222
  | Liquid | 9.23 s | 14.3 s | 610 MB |
1161
1223
 
1162
- Each build writes 156 MB of HTML and checks 1.4 million links. 0.7 built it in 1.68, 1.75 and 12.6 s on all 15 cores, with 12, 12 and 159 s of CPU time: 0.8 does less work, on one thread for the pages. Templates get your real objects, not copies, so handing the whole sidebar to a filter on every page copies nothing in any language.
1224
+ Each build writes 156 MB of HTML and checks 1.4 million links. Templates get your real objects, not copies, so handing the whole sidebar to a filter on every page copies nothing in any language.
1163
1225
 
1164
- `scripts/bench.sh [path/to/blog] [warm-runs]` runs the blog's table on macOS (the blog defaults to `../blog`) on a copy-on-write clone in a temporary folder, so your copy is never touched, and writes `results.csv`, `bench.log` and `summary.txt` to `bench-results/<timestamp>/`. It times the npm package as it's published, with ssqch 0.7's binary beside it when `target/release/ssqch` is there, and needs pnpm for the blog's CSS and JavaScript.
1226
+ `scripts/bench.sh [path/to/blog] [warm-runs]` runs the blog's table on macOS (the blog defaults to `../blog`) on a copy-on-write clone in a temporary folder, so your copy is never touched, and writes `results.csv`, `bench.log` and `summary.txt` to `bench-results/<timestamp>/`. It times the npm package as it's published, and needs pnpm for the blog's CSS and JavaScript.
1165
1227
 
1166
1228
  ## Plugins in Rust
1167
1229
 
1168
- Most plugins should be JavaScript: a piece of config, in the config or an npm package (see [Configuring a site](#configuring-a-site)). When a plugin does heavy work, it can be written in Rust instead, with the [`ssqch-plugin`](https://crates.io/crates/ssqch-plugin) crate, the plugin SDK. It builds one `.wasm` file (for `wasm32-wasip1`) that ssqch runs in Node's own WebAssembly: the same file on macOS, Linux and Windows, with nothing to compile when a site installs it, no native code, and no files, network or environment for the plugin to reach. ssqch's own minifier (`ssqch/minify`) is built this way, and its Markdown and Sass are Rust compiled to WebAssembly too. (0.7's Rust API, a site as its own Rust program, ended with 0.7.)
1230
+ Most plugins should be JavaScript: a piece of config, in the config or an npm package (see [Configuring a site](#configuring-a-site)). When a plugin does heavy work, it can be written in Rust instead, with the [`ssqch-plugin`](https://crates.io/crates/ssqch-plugin) crate, the plugin SDK. It builds one `.wasm` file (for `wasm32-wasip1`) that ssqch runs in Node's own WebAssembly: the same file on macOS, Linux and Windows, with nothing to compile when a site installs it, no native code, and no files, network or environment for the plugin to reach. ssqch's own minifier (`ssqch/minify`) is built this way, and its Markdown and Sass are Rust compiled to WebAssembly too.
1169
1231
 
1170
1232
  A Rust plugin can give a site a **transform** (every HTML page the build writes, after the image transform), **filters** (functions every template language can call) and **engines** (template languages of its own, by file extension). A site adds it as it adds any plugin; its npm package's function returns `{ name, rust: { wasm, options } }`, with `wasm` the absolute path to its file and `options` JSON for the plugin (`ssqch.d.ts` has the type, `RustPlugin`):
1171
1233
 
@@ -1189,11 +1251,14 @@ What a plugin gets: a filter gets the template's values as JSON (a date as ISO 8
1189
1251
 
1190
1252
  Each call copies its text into the plugin's memory and the answer back out, and WebAssembly runs at most at native speed, so Rust pays for work that's heavy for each byte, not for a few edits.
1191
1253
 
1192
- - **Heavy work pays:** minifying, parsing a real grammar (a template language, a highlighter), work on images or fonts, hashing, compression, a search index. In the study behind ssqch 0.8, minify-html as a plugin minified 10,000 pages in 0.28 of html-minifier-terser's time (0.82 s against 2.97 s), and ssqch's own minifier minifies the ReverentGeek blog's 169 pages (7.9 MB) in about 0.1 s.
1254
+ - **Heavy work pays:** minifying, parsing a real grammar (a template language, a highlighter), work on images or fonts, hashing, compression, a search index. Measured on 10,000 pages, minify-html as a plugin minified them in 0.28 of html-minifier-terser's time (0.82 s against 2.97 s), and ssqch's own minifier minifies the ReverentGeek blog's 169 pages (7.9 MB) in about 0.1 s.
1193
1255
  - **A regex doesn't.** Adding `loading="lazy"` to images, swapping a word, counting words: JavaScript's regular expressions compile to machine code. Adding attributes to 200,000 images on 10,000 pages took a JavaScript regex 53 ms, the same scan in Rust 81 ms as a plugin, and a real HTML tokenizer (lol_html) 311 ms. Write those as a transform in the config.
1194
1256
  - **Many small calls cost.** A filter call costs about 0.25 µs besides its work (its arguments and answer cross as JSON): fifty a page on 10,000 pages is a tenth of a second. A filter that's called for every item of every list is better in JavaScript.
1257
+
1195
1258
  ## Working on SiteSquatch
1196
1259
 
1260
+ <img align="right" src="docs/assets/stickers/axe-stump.svg" alt="" width="96">
1261
+
1197
1262
  ```text
1198
1263
  packages/ssqch ssqch itself: TypeScript on Node (src/, bin/, scripts/, bundled/ and wasm/)
1199
1264
  packages/ssqch/vendor The Nunjucks fork that renders Jinja and Nunjucks
@@ -1206,7 +1271,7 @@ examples/rust-plugin A plugin written in Rust with all three hooks, and its n
1206
1271
  tests/oracle Black-box tests that run any ssqch (SSQCH_BIN) against frozen output
1207
1272
  ```
1208
1273
 
1209
- The Rust crates exist to build the `.wasm` files, which are committed (so a clone needs `npm ci` and nothing else, and CI's Node jobs have no Rust); `node packages/ssqch/scripts/build-wasm.ts` builds them again after the Rust changes (`rustup target add wasm32-wasip1` first), and a test fails until you do. `cargo test --workspace` tests them as plain Rust. ssqch 0.7, the Rust implementation, isn't in this repository any more: it's on the `release/0.7` branch and the `v0.7.x` tags.
1274
+ The Rust crates exist to build the `.wasm` files, which are committed (so a clone needs `npm ci` and nothing else, and CI's Node jobs have no Rust); `node packages/ssqch/scripts/build-wasm.ts` builds them again after the Rust changes (`rustup target add wasm32-wasip1` first), and a test fails until you do. `cargo test --workspace` tests them as plain Rust.
1210
1275
 
1211
1276
  From `packages/ssqch/`, after `npm ci`:
1212
1277
 
@@ -1216,7 +1281,7 @@ node --test # the package's
1216
1281
  npx tsc --noEmit # type-checks; keep it clean
1217
1282
  ```
1218
1283
 
1219
- The oracle is the definition of done for the commands and the output: from `tests/oracle/`, `node --test` runs it with ssqch from its source (add a test file's path to run only that one; `SSQCH_BIN` runs another ssqch). Its frozen output is what 0.7.0 built, and a site whose output changes on purpose is frozen again with `node freeze.js <site>` ([its README](tests/oracle/README.md) says how). [CI](.github/workflows/ci.yml) runs it, the unit tests and the type check on Linux, macOS and Windows, on Node 22.18, 24 and 26.
1284
+ The oracle is the definition of done for the commands and the output: from `tests/oracle/`, `node --test` runs it with ssqch from its source (add a test file's path to run only that one; `SSQCH_BIN` runs another ssqch). It compares each example, starter and test site with its frozen output, and a site whose output changes on purpose is frozen again with `node freeze.js <site>` ([its README](tests/oracle/README.md) says how). [CI](.github/workflows/ci.yml) runs it, the unit tests and the type check on Linux, macOS and Windows, on Node 22.18, 24 and 26.
1220
1285
 
1221
1286
  The ReverentGeek blog is the real-world test site. To build it with your changes, clone it next to this repository and point its build script at your checkout's `ssqch` (the script runs `$SSQCH_BIN` when it is set), which also builds the CSS and JavaScript:
1222
1287
 
@@ -1233,15 +1298,17 @@ Releases are built by a hand-written workflow (`.github/workflows/release.yml`)
1233
1298
 
1234
1299
  ## Known gaps
1235
1300
 
1301
+ <img align="right" src="docs/assets/stickers/direction-sign.svg" alt="" width="96">
1302
+
1236
1303
  The uncharted parts of the map, as of this release:
1237
1304
 
1238
- - **JavaScript:** a site's code runs on Node, so it has Node's limits and none of 0.7's. There are no worker threads: pages render one at a time on one thread (image encoding uses every core), so a site with heavy per-page JavaScript doesn't spread it across cores, and module-level state in your config (a counter in a filter) is one counter. `Intl`, `toLocaleDateString()` and `localeCompare` are Node's, and their results can differ between Node releases (Node 22.18 ships an older ICU than 24 and 26: one of 91 formats the study compared, compact numbers in en-GB, came out differently). ssqch's own date filters and sorting never use `Intl`, so only a site's own `Intl` calls can make a build's output depend on the Node version; pin `NODE_VERSION` where that matters.
1305
+ - **JavaScript:** there are no worker threads: pages render one at a time on one thread (image encoding uses every core), so a site with heavy per-page JavaScript doesn't spread it across cores, and module-level state in your config (a counter in a filter) is one counter. `Intl`, `toLocaleDateString()` and `localeCompare` are Node's, and their results can differ between Node releases (Node 22.18 ships an older ICU than 24 and 26). ssqch's own date filters and sorting never use `Intl`, so only a site's own `Intl` calls can make a build's output depend on the Node version; pin `NODE_VERSION` where that matters.
1239
1306
  - **Async functions and Markdown:** a page's own Markdown waits for an async `headingIds` function or highlighter, but Markdown made while a template renders can't: `markdown()` and `highlight()` in a template, `markdown()` from `"ssqch"`, a render hook or a container whose template calls an async function are errors that name the function when it answers with a promise. Make those functions synchronous. A page whose own templates are async can't be rendered on demand either: reading its `templateContent` before it has rendered is an error that names it.
1240
1307
  - **Edge:** the async functions inside a callback of `filter`, `find` and the other array methods aren't awaited (an error says to call them first with `@let`).
1241
1308
  - **Markdown:** containers have to close inside the block they opened in (the same list item, say). Highlighting parses more slowly than tree-sitter would: the blog's 350 fences add about 60 ms to a build, and a process's first highlight compiles each grammar it uses (about 0.3 s for the blog's first build), unless [the highlighting cache](#markdown) has the fence, and not again for the rebuilds of `ssqch serve`. A site with `.sublime-syntax` grammars of its own (or an alias to a built-in grammar, `jsx: "js"`) still loads the set of built-in grammars when its config is read, a few dozen milliseconds, though the cache spares it each grammar's patterns.
1242
- - **Images:** no SVG rasterizing, and HDR photos (the PQ, gain-map profiles of newer iPhones) can't be converted to sRGB, so they look washed out; the build warns about them, and converting the source to sRGB once fixes it. SVGs are served as they are, and GIFs are copied for `auto` output, so animations keep working. The files' bytes are sharp's, not 0.7's, so a site that compared image bytes with `ssqch diff --exact` sees them change once.
1309
+ - **Images:** no SVG rasterizing, and HDR photos (the PQ, gain-map profiles of newer iPhones) can't be converted to sRGB, so they look washed out; the build warns about them, and converting the source to sRGB once fixes it. SVGs are served as they are, and GIFs are copied for `auto` output, so animations keep working.
1243
1310
  - **The dev server:** it listens on `127.0.0.1` only (no `--host`), doesn't watch `node_modules`, and rebuilds the whole site on a change, on one thread: after one edit, a 10,000-page site takes about 0.9 s.
1244
1311
  - **Collections:** custom collections don't see pages that are paginated over collections. Those pages are added to `all` and their tags afterwards.
1245
- - **Platforms:** ssqch needs Node 22.18 or newer, and runs wherever that Node and sharp do (Linux, Alpine and Linux on ARM included, macOS and Windows). There's no standalone executable, so a machine without Node needs it first (Homebrew's formula brings it). See [TODO.md](TODO.md) for what's next.
1312
+ - **Platforms:** ssqch needs Node 22.18 or newer, and runs wherever that Node and sharp do: macOS, Windows and Linux, Alpine and ARM included. See [TODO.md](TODO.md) for what's next.
1246
1313
 
1247
1314
  Found a bug, or have an idea? [Open an issue](https://github.com/reverentgeek/sitesquatch/issues). Happy building, and may your pages load faster than a Squatch sighting disappears.