ssqch 0.8.0 → 0.10.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 (87) hide show
  1. package/README.md +3 -1
  2. package/bundled/docs/agents.md +70 -0
  3. package/bundled/docs/benchmarks.md +29 -0
  4. package/bundled/docs/build-summary.md +27 -0
  5. package/bundled/docs/comparing-builds.md +51 -0
  6. package/bundled/docs/configuring.md +138 -0
  7. package/bundled/docs/content-schemas.md +54 -0
  8. package/bundled/docs/css-and-javascript.md +33 -0
  9. package/bundled/docs/data-files.md +55 -0
  10. package/bundled/docs/deploying.md +47 -0
  11. package/bundled/docs/field-guide.md +144 -0
  12. package/bundled/docs/footprint.md +27 -0
  13. package/bundled/docs/github-pages.md +41 -0
  14. package/bundled/docs/index.md +26 -0
  15. package/bundled/docs/install.md +27 -0
  16. package/bundled/docs/known-gaps.md +18 -0
  17. package/bundled/docs/markdown.md +114 -0
  18. package/bundled/docs/multilingual.md +14 -0
  19. package/bundled/docs/nav.yml +50 -0
  20. package/bundled/docs/netlify.md +30 -0
  21. package/bundled/docs/new-pages.md +42 -0
  22. package/bundled/docs/plugins.md +13 -0
  23. package/bundled/docs/rust-plugins.md +32 -0
  24. package/bundled/docs/seo.md +19 -0
  25. package/bundled/docs/template-languages.md +106 -0
  26. package/bundled/docs/templates.md +37 -0
  27. package/bundled/docs/themes.md +31 -0
  28. package/bundled/{trailheads → docs/trailheads}/from-component-frameworks.md +7 -3
  29. package/bundled/{trailheads → docs/trailheads}/from-docusaurus.md +7 -4
  30. package/bundled/{trailheads → docs/trailheads}/from-eleventy.md +7 -4
  31. package/bundled/{trailheads → docs/trailheads}/from-hexo.md +7 -4
  32. package/bundled/docs/trailheads/from-jekyll.md +82 -0
  33. package/bundled/{trailheads → docs/trailheads}/from-mkdocs.md +8 -5
  34. package/bundled/{trailheads → docs/trailheads}/from-zola.md +6 -3
  35. package/bundled/docs/trailheads.md +38 -0
  36. package/bundled/docs/where-values-come-from.md +57 -0
  37. package/bundled/ssqch.d.ts +20 -10
  38. package/lib/assets.js +15 -7
  39. package/lib/{chunk-N5QTGQ5N.js → chunk-2LEOPLTZ.js} +2 -2
  40. package/lib/{chunk-AMBFWPZ4.js → chunk-3EPHKJEG.js} +3 -3
  41. package/lib/{chunk-BRK4MXXO.js → chunk-3HHRKG33.js} +65 -18
  42. package/lib/{chunk-EIT4ZDT4.js → chunk-5DNDSNTP.js} +61 -5
  43. package/lib/{chunk-NUKCUDC4.js → chunk-7HXCQEGA.js} +3 -3
  44. package/lib/{chunk-6XYSFG6V.js → chunk-BGCBSQ4A.js} +3067 -3054
  45. package/lib/{chunk-RI2L3VGO.js → chunk-CB6YFUXU.js} +19 -11
  46. package/lib/{chunk-JSPSMIJ2.js → chunk-DMVJ53SM.js} +9 -9
  47. package/lib/{chunk-FYGE634X.js → chunk-DW7VMJEZ.js} +9 -9
  48. package/lib/{chunk-GSKVRAHF.js → chunk-E5UB2YY7.js} +6 -6
  49. package/lib/{chunk-DHHQKW4F.js → chunk-EEJDLCD3.js} +7 -7
  50. package/lib/{chunk-TWCVHOKO.js → chunk-HDQ4SRWM.js} +125 -4
  51. package/lib/{chunk-JRT7TQQP.js → chunk-HGJ5VWUR.js} +1 -1
  52. package/lib/{chunk-C35KIPAR.js → chunk-JWCCVTTR.js} +98 -7
  53. package/lib/{chunk-EZZUUPI4.js → chunk-JXZT5L7W.js} +2 -2
  54. package/lib/{chunk-KBGE5MCY.js → chunk-LAV3DEY4.js} +1 -1
  55. package/lib/{chunk-IRHRK7XB.js → chunk-LCPSKHAV.js} +1 -1
  56. package/lib/{chunk-3PHCFZEU.js → chunk-N4O5MDIB.js} +2 -2
  57. package/lib/{chunk-TDGBQNGW.js → chunk-NFJJKDRI.js} +1 -1
  58. package/lib/{chunk-UGEGUUBT.js → chunk-NUUEOGLZ.js} +8 -8
  59. package/lib/{chunk-VVPZ5PDP.js → chunk-Q4LFTYK2.js} +11 -11
  60. package/lib/{chunk-TN6EEDX2.js → chunk-QMA7CK7B.js} +51 -6
  61. package/lib/{chunk-CDEPYU7W.js → chunk-RJFWTW2Y.js} +2 -2
  62. package/lib/{chunk-YSH2NMIE.js → chunk-RKFZSVNF.js} +6 -6
  63. package/lib/{chunk-GOE4ZSAB.js → chunk-RM5Q3KFB.js} +9 -9
  64. package/lib/{chunk-37KSIVNY.js → chunk-RVBNVGZV.js} +3 -3
  65. package/lib/{chunk-HR2RU2LY.js → chunk-SA5KSJ4Y.js} +11 -7
  66. package/lib/{chunk-BOBPVAX2.js → chunk-SRNLKWXL.js} +424 -78
  67. package/lib/{chunk-WP3RPVUM.js → chunk-Y2ESFAAD.js} +2 -3
  68. package/lib/{chunk-WMOVCQO6.js → chunk-ZM6TU2JB.js} +6 -6
  69. package/lib/cli.js +32 -25
  70. package/lib/elements.js +7 -7
  71. package/lib/image.js +8 -8
  72. package/lib/links.js +10 -10
  73. package/lib/minify.js +7 -7
  74. package/lib/redirects.js +8 -8
  75. package/lib/rss.js +20 -19
  76. package/lib/sass.js +45 -10
  77. package/lib/sitemap.js +36 -11
  78. package/lib/ssqch.js +4 -4
  79. package/package.json +2 -2
  80. package/types/image.d.ts +5 -5
  81. package/types/index.d.ts +12 -4
  82. package/types/rss.d.ts +1 -1
  83. package/types/sitemap.d.ts +2 -0
  84. package/wasm/markdown.wasm +0 -0
  85. package/bundled/README.md +0 -1247
  86. package/lib/{chunk-6XYSFG6V.js.LEGAL.txt → chunk-BGCBSQ4A.js.LEGAL.txt} +3 -3
  87. /package/lib/{chunk-BOBPVAX2.js.LEGAL.txt → chunk-SRNLKWXL.js.LEGAL.txt} +0 -0
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # ssqch
2
2
 
3
+ <img align="right" src="https://raw.githubusercontent.com/reverentgeek/sitesquatch/main/docs/assets/stickers/sitesquatch.svg" alt="SiteSquatch, a Sasquatch with a deadpan stare" width="160">
4
+
3
5
  [SiteSquatch](https://github.com/reverentgeek/sitesquatch) is a fast static site generator, configured with JavaScript (`ssqch.config.js`). It runs on Node.js 22.18 or newer. Install it in a site as a dev dependency, so the lockfile pins the version:
4
6
 
5
7
  ```sh
@@ -13,4 +15,4 @@ The package is JavaScript, with its template and Markdown libraries bundled in,
13
15
 
14
16
  The modules a config imports (`ssqch`, `ssqch/image` and the rest) are in the package's `exports` map, with their types, so editors, TypeScript and ESLint's `n/no-missing-import` find them.
15
17
 
16
- Outside a site, `npm install --global ssqch` puts `ssqch` on your `PATH`, and Homebrew (`brew install reverentgeek/tap/ssqch`) installs this package with Homebrew's own Node. See the [README](https://github.com/reverentgeek/sitesquatch#readme) for everything else.
18
+ Outside a site, `npm install --global ssqch` puts `ssqch` on your `PATH`, and Homebrew (`brew install reverentgeek/tap/ssqch`) installs this package with Homebrew's own Node. The documentation is at [sitesquatch.dev](https://sitesquatch.dev/docs/), and `ssqch docs` prints it for the version you have installed, with no network.
@@ -0,0 +1,70 @@
1
+ ---
2
+ title: "Scripts and coding agents"
3
+ description: "The voice is for people."
4
+ ---
5
+ The voice is for people. The same commands work for a script, a CI job or a coding agent, with JSON in place of the text a person reads, and no jokes in it. Every JSON document has a `schemaVersion`, which changes only when a field is removed or changes meaning.
6
+
7
+ `ssqch build --format json` prints one report on standard output, whether the build worked or not (the exit code is 0 or 1 as usual):
8
+
9
+ ```sh
10
+ ssqch build --format json
11
+ ```
12
+
13
+ ```json
14
+ {
15
+ "schemaVersion": 1,
16
+ "ok": false,
17
+ "environment": "production",
18
+ "output": "dist",
19
+ "warnings": [
20
+ {
21
+ "code": "schema",
22
+ "message": "src/guides/pine.md: `lvl` isn't a field of this schema (did you mean `level`?) (schema `guides`)",
23
+ "file": "src/guides/pine.md",
24
+ "field": "lvl"
25
+ }
26
+ ],
27
+ "errors": [
28
+ {
29
+ "code": "template",
30
+ "message": "rendering index.edge with `edge`: index.edge:4: Cannot read properties of undefined (reading 'toUpperCase') in `guide.data.name`",
31
+ "file": "src/index.edge",
32
+ "line": 7
33
+ }
34
+ ]
35
+ }
36
+ ```
37
+
38
+ - **Each warning and error** has a `code` and the `message` a person would have read. `file` (from the project root) is there when the problem is in a file that exists, `line` when the line is known, `field` for a [schema](content-schemas.md) problem, and `url` for a problem in a written page, like a broken link.
39
+ - **`line` is a line of the file.** Template languages count from the end of the front matter, which is the number in the message (`index.edge:4`); the report adds the front matter back (`"line": 7`).
40
+ - **The codes:** `config`, `data`, `front-matter`, `template`, `schema`, `conflict` (two pages write the same file), `links`, `images`, `assets`, `fetch`, `passthrough`, `last-modified`, `hook`, `console` (`console.warn` in a config), `template-formats` (files in a template language the site doesn't list), `other-generator`, `foreign-key` and `foreign-global` (another generator's config, front matter or template data), `over-budget` (a [footprint budget](footprint.md)), `missing-asset` (from `ssqch serve`), and `build` for anything else.
41
+ - **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](build-summary.md)) and `timings`.
42
+ - **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.
43
+
44
+ `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".
45
+
46
+ `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 these docs say 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`.
47
+
48
+ `ssqch init` writes an `AGENTS.md` for coding agents, with a one-line `CLAUDE.md` that imports it: what each file is, and the commands above for looking a name up, checking a change and comparing builds. It's about 1 KB, since an agent carries it through a whole session, and `init` never replaces one a site already has. For a site that doesn't have one, `ssqch docs agents > AGENTS.md` writes it.
49
+
50
+ `ssqch serve --ready-file <file>` writes a file once the first build is done and the site is being served, so a script can wait for the file instead of reading the server's output or sleeping:
51
+
52
+ ```sh
53
+ ssqch serve --port 0 --ready-file .cache/ready.json &
54
+ ```
55
+
56
+ ```json
57
+ {
58
+ "schemaVersion": 1,
59
+ "url": "http://localhost:60768/",
60
+ "port": 60768,
61
+ "base": "",
62
+ "output": "/home/sam/site/dist",
63
+ "pid": 39675,
64
+ "ok": true
65
+ }
66
+ ```
67
+
68
+ `ok` is whether that first build worked (the server keeps running either way, and rebuilds when a file changes). The file is deleted when the server starts, so one from an earlier run never counts, and it's written again when a changed config loads, since `output` and `base` can change with it.
69
+
70
+ The other commands with JSON are [`ssqch inspect --format json`](where-values-come-from.md) (where a page's data came from) and [`ssqch diff --format json`](comparing-builds.md) (what a change did to the output; it exits with 0, 1 or 2 like `diff`).
@@ -0,0 +1,29 @@
1
+ ---
2
+ title: "Benchmarks"
3
+ description: "No blurry footage here."
4
+ ---
5
+ 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.
6
+
7
+ | Build | Time | Peak memory |
8
+ | --- | --- | --- |
9
+ | **Cold** (every image encoded: 4,985 files, 266 MB) | **25.6 s** (341 s of CPU) | 2.6 GB |
10
+ | **Warm** (images cached, median of 3) | **0.92 s** | 328 MB |
11
+
12
+ - **Warm builds** are what the dev server and cached CI builds do, and the time includes starting Node.
13
+ - **Cold builds** are mostly image encoding, and AVIF is the most expensive format (the blog uses `avifEffort: 3`). They're single runs and vary.
14
+ - **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.
15
+ - Only site generation is measured, not building the CSS and JavaScript.
16
+
17
+ 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.
18
+
19
+ 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:
20
+
21
+ | Layout in | Build | CPU time | Peak memory |
22
+ | --- | --- | --- | --- |
23
+ | Edge | 2.85 s | 7.4 s | 465 MB |
24
+ | Nunjucks | 2.74 s | 7.0 s | 454 MB |
25
+ | Liquid | 9.23 s | 14.3 s | 610 MB |
26
+
27
+ 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.
28
+
29
+ `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.
@@ -0,0 +1,27 @@
1
+ ---
2
+ title: "Reading the build summary"
3
+ description: "Every build ends with a ranger's report."
4
+ ---
5
+ Every build ends with a ranger's report. Here's the ReverentGeek blog with its images cached:
6
+
7
+ ```text
8
+ Built in 110 ms (production)
9
+ Pages 168 written from 140 templates, 6.83 MB
10
+ Copied 0 files, 12 unchanged, 3.88 MB
11
+ Images 4,689 files from 737 sources, 271 MB: 0 encoded, 4,689 reused
12
+ Output dist: 4,872 files, 282 MB
13
+ Time setup 1.11 ms, data 1.31 ms, read 32.3 ms, paginate 2.81 ms, render 7.56 ms, write 55.9 ms, copy 193 µs, after 9.21 ms
14
+ ```
15
+
16
+ - **The first line** is `First confirmed siting. Built in ...` for a site's first build (there's no `.cache/ssqch/output-files.json` yet), which is every build on a CI machine that doesn't keep `.cache`.
17
+ - **Pages** also says what's different from the last build to that folder: `(2 new, 1 gone)` when a page appeared or stopped being written (a post you added, a permalink you changed), and `(3 changed)` in `ssqch serve`, which leaves a page alone when it comes out the same.
18
+ - **Drafts** is in production builds that left `draft: true` pages out: `Drafts 3 unconfirmed (built in development only)`, or `3 left out` when the report's themed line is another one.
19
+ - **Removed** is the stale files `leaveNoTrace` deleted: `Removed 2 stale files, left no trace`, or just `2 stale files`.
20
+ - **One themed line at most:** a report says one thing in the ranger's voice, the one that matters most (in this order: nothing to build, a first build, files removed, drafts, unused templates), and says the rest plainly.
21
+ - **Images** counts the image files this build used, the source images they came from, and how many had to be encoded. With `prune` on, it also says how many stale files it deleted.
22
+ - **Output** is everything in the output folder, including files left from earlier builds.
23
+ - **Time** splits the build into phases. `write` includes layouts, transforms and image encoding, so a build that encodes images spends most of its time there. `after` is the `afterBuild` hooks.
24
+
25
+ With `--verbose`, a line under the summary names the templates in the includes folder that nothing used as a layout, an include or a component in this build: `Uninhabited: 1 template that nothing used in this build (src/_includes/cabin.jinja).` (`Unused:` when the report's themed line is another one.) It covers every template language: Jinja, Nunjucks, Edge, Liquid, Handlebars, Mustache and EJS.
26
+
27
+ `ssqch serve` prints the same summary after every rebuild.
@@ -0,0 +1,51 @@
1
+ ---
2
+ title: "Comparing two builds"
3
+ description: "A build that succeeds isn't proof that an upgrade, a refactor or a migration left the site alone."
4
+ ---
5
+ <img align="right" src="../../../docs/assets/stickers/footprint.svg" alt="" width="96">
6
+
7
+ 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:
8
+
9
+ ```sh
10
+ ssqch build --output dist-before # before the change
11
+ # upgrade ssqch, edit a layout, move to another template language...
12
+ ssqch build
13
+ ssqch diff dist-before dist
14
+ ```
15
+
16
+ ```text
17
+ Comparing dist-before with dist
18
+ Ignoring asset fingerprints, integrity hashes, the generator's version, and whitespace between tags (--exact compares bytes).
19
+
20
+ Added (1)
21
+ + /trails/cedar/
22
+
23
+ Removed (1)
24
+ - /trails/old-growth/
25
+
26
+ Changed (2)
27
+ ~ /trails/ (text and markup)
28
+ ids removed (links to them break): #old-growth
29
+ - <h2 id="old-growth">
30
+ - Old growth
31
+ + <h2 id="cedar">
32
+ + Cedar
33
+ ~ /assets/index.css (index.3f2a1b4c.css -> index.9d8e7f6a.css)
34
+ - body { color: #222 }
35
+ + body { color: #111 }
36
+
37
+ Changes found: 3 pages and 1 other file (2 changed, 1 added, 1 removed); 148 pages and 4,730 other files are the same. The stump has moved.
38
+ ```
39
+
40
+ - **What's ignored:** differences that don't change what a visitor gets. A fingerprinted file (`index.3f2a1b4c.css`: eight hex digits before the extension, unless they read as a date) is matched with its counterpart and compared by content, `integrity` hashes and the generator's version are left out, and HTML is compared as a list of tags and text, so whitespace between block tags doesn't count. A space next to an inline tag (`a <b>b</b>`) does, and so does whitespace inside `<pre>`, `<script>`, `<style>` and `<textarea>` (blank lines and indents included) and inside an attribute's value. `--exact` compares bytes instead.
41
+ - **What each page says:** whether its text, its markup or both changed, a changed `<title>`, any `id`s it no longer has (links to those anchors break), and `only dates changed (2025 -> 2026)` when every change on it is a date or a year.
42
+ - **Dates that changed:** when changed files differ only in dates or years, the summary says how many (`All 94 changed files differ only in dates or years`), and the JSON has `onlyDates: true` for each. The usual cause is a page with no `date` of its own (none in front matter or the file name): its date is the file's modification time, which a fresh checkout, a copy or another generator sets differently (Eleventy uses the file's creation time), so a footer with `{{ page.date.getFullYear() }}` changes on every page. Give pages that print it a `date`, use `{{ now() | dateformat("%Y") }}` for a copyright year, or `--ignore` the pattern while comparing.
43
+ - **Your own noise:** `--ignore <regex>` leaves matching text out of both sides, like a build date in the footer: `--ignore 'Built on [^<]+'`. Repeat it for more patterns. The pattern is a JavaScript regular expression, in its Unicode mode (the `u` flag): flags at the start (`(?i)`) and named groups written `(?P<name>...)` still work, but syntax only Rust had (`(?x)`, `\A`, `\z`, an escaped `-` outside `[...]`) is refused with JavaScript's words, and `\d` and `\w` are ASCII, so write `\p{Nd}` or `\p{L}` for other scripts' digits and letters.
44
+ - **Part of the site:** `--only '**/*.html'` compares only matching files (repeatable).
45
+ - **Longer diffs:** each file shows 10 changed lines; `--lines 0` shows them all.
46
+ - **Nothing to report:** `No differences: 148 pages and 4,730 other files are the same. The stump has not moved.`
47
+ - **Scripts and agents:** `--format json` prints the same report as JSON (`schemaVersion: 1`), and the exit code is 0 when the builds are the same, 1 when they differ and 2 on an error, like `diff`.
48
+
49
+ 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.
50
+
51
+ **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`).
@@ -0,0 +1,138 @@
1
+ ---
2
+ title: "Configuring a site"
3
+ description: "Here's a fuller config, with data, a custom collection and the built-in plugins."
4
+ ---
5
+ > **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.md) in them too.
6
+
7
+ Here's a fuller config, with data, a custom collection and the built-in plugins:
8
+
9
+ ```js
10
+ // ssqch.config.js
11
+ import { defineConfig } from "ssqch";
12
+ import { imagePlugin } from "ssqch/image";
13
+ import { minifyPlugin } from "ssqch/minify";
14
+ import { rssPlugin } from "ssqch/rss";
15
+ import { slugify } from "./src/utils/slugify.js";
16
+ import site from "./src/site.json";
17
+
18
+ export default defineConfig(({ env }) => ({
19
+ dirs: { input: "src", output: "dist" },
20
+ templateFormats: ["jinja", "md"],
21
+ passthrough: [{ "src/assets/fonts": "fonts" }, "src/favicon.ico"],
22
+ watch: ["src/assets/"],
23
+
24
+ filters: {
25
+ slug: (s) => slugify(s),
26
+ isoDate: (d) => d.toISOString().slice(0, 10),
27
+ },
28
+ data: {
29
+ site,
30
+ snacks: async () => [{ name: "Pine Cone Crunch", stars: 5 }],
31
+ },
32
+ collections: {
33
+ favorites: (pages) => pages.byTag("snacks").filter((p) => p.data.stars > 3),
34
+ },
35
+
36
+ plugins: [
37
+ rssPlugin(),
38
+ imagePlugin({ widths: [300, 600, 1200], formats: ["webp", "auto"] }),
39
+ env === "production" && minifyPlugin(),
40
+ ],
41
+ }));
42
+ ```
43
+
44
+ The default export is the config: an object, or a function (sync or async) that gets `{ env, serving }` and returns one. `defineConfig` returns whatever you give it; it's there so the file reads like a config. Every key is optional:
45
+
46
+ | Key | What it does |
47
+ | --- | --- |
48
+ | `dirs` | `input` (default `.`), `output` (`_site`), and `includes` (`_includes`), `layouts` (the includes folder) and `data` (`_data`), relative to the input. |
49
+ | `templateFormats` | File extensions to render (default `["jinja", "md", "html"]`). A file in another template language the site has, like a `.edge` page when `edge` isn't listed, is left out with a warning that names it. |
50
+ | `markdownEngine`, `htmlEngine` | The engine that runs over `.md` and `.html` files first (default `"jinja"`; `false` for none). |
51
+ | `markdown` | Heading IDs, footnotes and the other Markdown extensions; see [Markdown](markdown.md). |
52
+ | `deepMerge` | Merge objects and concatenate arrays through the data cascade (default `true`). |
53
+ | `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). |
54
+ | `filters` | `{ name: function }`, callable from templates: `{{ title | slug }}` or `{{ slug(title) }}`. Async functions are awaited. |
55
+ | `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() }`. |
56
+ | `collections` | `{ name: (pages) => ... }`. `pages` has `all()`, `byTag(tag)`, `byTags(...tags)` and `byGlob(glob or globs)`, oldest first. |
57
+ | `transforms` | `{ name: (content, page) => content }`, run on every output file. `page` has `url`, `inputPath` and `outputPath`. Return the content, changed or not. Async works. |
58
+ | `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. |
59
+ | `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. |
60
+ | `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`). |
61
+ | `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`). |
62
+ | `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. |
63
+ | `watch` | More paths for `ssqch serve` to watch. |
64
+ | `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](footprint.md). |
65
+ | `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.md). In `sitesquatch.toml`, `[serve]` with `run = [...]`. |
66
+ | `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. |
67
+ | `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.md). |
68
+ | `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.md). |
69
+ | `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](deploying.md#serving-a-site-under-a-path). |
70
+ | `dateFallback` | The date of a page with no date of its own (in its data or its file name): `"git"` for the last commit that changed its file, or `"file"` (the default) for the file's modification time. A checkout writes every file at once, so with `"file"`, `page.date` and a sitemap's `<lastmod>` change from one clone to the next; `"git"` is the same in every checkout (a file with uncommitted changes uses its time). Either way the page sorts after the dated pages, by path. `SOURCE_DATE_EPOCH` pins the build's time instead, for every undated page at once. In CI, check out the full history (`fetch-depth: 0`). |
71
+ | `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. |
72
+ | `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. |
73
+ | `plugins` | More config: objects with any of the keys above except the settings (`dirs`, `templateFormats`, `markdownEngine`, `htmlEngine`, `markdown`, `deepMerge`, `leaveNoTrace`, `ignore`, `bundles`, `strict`, `lastModified`, `dateFallback`, `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](rust-plugins.md)). `false`, `null` and `undefined` are skipped, so `env === "production" && minifyPlugin()` works. Give a plugin a `name` and errors will mention it. |
74
+
75
+ 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)`.
76
+
77
+
78
+ ## What you can import
79
+
80
+ 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.
81
+
82
+ 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.
83
+
84
+ Dates and numbers format as Node does, so `toLocaleDateString()`, `Intl.DateTimeFormat` and `localeCompare` use Node's own ICU, and their results can differ between Node releases (22.18 ships an older ICU than 24 and 26). ssqch's own date filters and sorting don't use `Intl`, so a build's output doesn't change with the Node version, the time zone or the locale unless your code asks it to ([Known gaps](known-gaps.md)).
85
+
86
+ > **Note:** `ssqch serve` builds in a process of its own, and starts it again when the config changes, or when a module it imports does (your own files: ES modules, CommonJS ones and what they `require`, JSON, and JavaScript data files). Everything the site's code loaded is read again, and what a module kept in memory starts over, packages in `node_modules` included, though a change to a file inside `node_modules` isn't watched. If the new config has a mistake, the error is printed and the server carries on with the last configuration that loaded.
87
+
88
+ The globals are Node's: `fetch` (with `Headers`, `Request`, `Response`, `AbortController` and `AbortSignal.timeout()`), `URL`, `URLSearchParams`, `TextEncoder`, `TextDecoder`, `EventTarget`, `Buffer`, `process` and the timers. A config or data file can use `await` above its `export` (top-level `await`) on every Node ssqch supports. `fetch` follows redirects and decompresses gzip, and rejects with a `TypeError` that names the URL when a request fails, with Node's reason after it (`fetch failed: http://127.0.0.1:9/: connect ECONNREFUSED 127.0.0.1:9`; the original error is the `cause`). Up to 8 requests are in flight at once, and the rest wait their turn, so `await Promise.all(urls.map(u => fetch(u)))` fetches in parallel without opening a thousand connections. Only `http:` and `https:` URLs can be fetched.
89
+
90
+ A data file that fetches runs on every build, including each rebuild in `ssqch serve`. To keep an API from being asked every time, give the request a `cache`:
91
+
92
+ ```js
93
+ // src/_data/snacks.js
94
+ export default async function () {
95
+ const response = await fetch("https://api.example.com/snacks", { cache: "1h" });
96
+ return response.json();
97
+ }
98
+ ```
99
+
100
+ - **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.
101
+ - **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.
102
+ - **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).
103
+ - **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.
104
+ - **Seeing it:** a response from a copy has an `x-ssqch-cache` header (`hit`, or `stale` after a failed refresh), and the build summary counts them: `Fetch 12 requests, 9 from the cache`.
105
+
106
+ CI starts without `.cache/`, so production builds fetch fresh data unless you restore that folder.
107
+
108
+
109
+ ## npm packages
110
+
111
+ Install packages with npm, pnpm or yarn as usual, and import them: `import { DateTime } from "luxon"`. Node finds them as it always does, in `node_modules` folders from the importing file's folder up (so monorepos and pnpm's symlinks work), using `package.json`'s `exports`, `imports` (`#internal`) and `main`. CommonJS works too: `.cjs` files, and `.js` files in packages without `"type": "module"`, run with `require`, `module.exports`, `__dirname` and `__filename`, and importing one gives `module.exports` as the default export and, where Node can read the names from its source, its properties as named exports (`import legacy from "legacy"; const { twice } = legacy;` is the safe way for a package whose exports are built at run time). Your own `.js` files follow Node's rules: `"type"` in your `package.json` decides, and without one Node 22 reads a file with `import` or `export` as an ES module and any other as CommonJS, so `module.exports = { ... }` in `_data/site.js` works. In an ES module, `createRequire(import.meta.url)` from `node:module` gives you a `require`.
112
+
113
+ Packages run on Node, as they are, so anything that works in a Node script works here: servers, child processes, streams, native addons and the file system. Eleventy's own libraries (liquidjs, nunjucks, markdown-it and its plugins, gray-matter), luxon, dayjs, date-fns, lodash, slugify, js-yaml, marked, highlight.js, prismjs, sanitize-html, html-minifier-terser, clean-css, feed, cheerio and @lit-labs/ssr all run, at Node's speed. Some have a faster built-in in ssqch (the `markdown` filter, `readingTime`, `ssqch/minify`, and `markdown: { highlight: true }` for highlighting), so reach for those packages when you need their particular output.
114
+
115
+ Every page is rendered on one thread, one call at a time (there are no worker threads), so module-level state in your config behaves as it would in any Node script: a counter in a filter counts every page in order. A filter or template gets your real objects, not copies, so a filter that sorts `collections.posts` in place reorders it for the pages rendered after it: copy first (`[...posts].sort()`).
116
+
117
+
118
+ ## Configuring with TOML
119
+
120
+ A site that needs no code at all can use a `sitesquatch.toml` instead (one or the other, not both). Every key is optional, they're the config's settings in snake case (`template_formats`, `leave_no_trace`, `before_build`), and an unknown key is an error that lists all of them.
121
+
122
+ ```toml
123
+ input = "src"
124
+ output = "public"
125
+ template_formats = ["jinja", "md", "html"]
126
+
127
+ ignore = ["drafts/**"]
128
+ leave_no_trace = true # or `clean = true`, its other name
129
+
130
+ [serve]
131
+ run = ["npx postcss src/app.css -o public/app.css --watch"]
132
+
133
+ [markdown]
134
+ heading_ids = "blackfriday"
135
+
136
+ [passthrough]
137
+ "src/robots.txt" = "" # empty keeps the path relative to the input directory
138
+ ```
@@ -0,0 +1,54 @@
1
+ ---
2
+ title: "Content schemas"
3
+ description: "Front matter is easy to get wrong."
4
+ ---
5
+ <img align="right" src="../../../docs/assets/stickers/ranger-mary.svg" alt="" width="96">
6
+
7
+ 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:
8
+
9
+ ```js
10
+ export default defineConfig({
11
+ schemas: {
12
+ posts: {
13
+ fields: {
14
+ title: "string",
15
+ date: "date",
16
+ description: "string?",
17
+ status: "'draft' | 'published'",
18
+ topics: "string[]",
19
+ hero: { src: "file", alt: "string" },
20
+ "author?": { name: "string", url: "string?" },
21
+ slug: (value) => /^[a-z0-9-]+$/.test(value) || "must be lowercase letters, digits and dashes",
22
+ },
23
+ unknown: "error",
24
+ },
25
+ docs: { files: "docs/**/*.md", fields: { title: "string", order: "integer?" } },
26
+ },
27
+ });
28
+ ```
29
+
30
+ ```text
31
+ error: 3 content errors:
32
+ - src/posts/cedar.md: `status` must be "draft" or "published", not "drfat" (schema `posts`)
33
+ - src/posts/cedar.md: `hero.src` is "cedar.jpg", but there's no such file next to the page (schema `posts`)
34
+ - src/posts/cedar.md: `descripton` isn't a field of this schema (did you mean `description`?) (schema `posts`)
35
+
36
+ --> src/posts/cedar.md:5
37
+ 3 | date: 2026-03-02
38
+ 4 | tags: posts
39
+ 5 | status: drfat
40
+ | ^^^^^^
41
+ 6 | hero: { src: cedar.jpg, alt: A cedar }
42
+ ```
43
+
44
+ (The other two get their lines pointed at too.)
45
+
46
+ - **Which pages:** a schema covers the pages tagged with its name (the pages in `collections.posts`; `all` is every page in collections), or the files matching `files`, globs relative to the input folder.
47
+ - **What's checked:** each page's data after the data cascade and `computed`, so a value from a directory data file counts. Every problem in every page is reported in one go, with the file and the field.
48
+ - **Types:** `string`, `number`, `integer`, `boolean`, `date` (a date, or a string that reads as one), `file` (a path to a file that exists: next to the page, or from the input folder with a leading `/`), `object`, `array` and `any`. A quoted value, number, `true`, `false` or `null` is that exact value, `|` is either-or, `[]` is a list, and a `?` at the end makes the field optional.
49
+ - **Nested data:** an object of fields, or a one-item array for a list of them: `links: [{ href: "string", text: "string" }]`. A key that ends in `?` is optional too.
50
+ - **Your own rules:** a function gets the value and the page's data, and returns `true`, `false`, or what's wrong (`` `slug` must be lowercase letters, digits and dashes ``).
51
+ - **`unknown`:** what to do about keys in a page's own front matter that aren't fields: `"allow"` (the default), `"warn"` or `"error"`. Keys ssqch reads itself (`layout`, `tags`, `permalink`, `date` and the like) are always fine, and so is data from the rest of the cascade.
52
+ - **Editor types:** `ssqch types` adds the schemas to `ssqch.d.ts`, so `pages.byTag("posts")` in a collection function knows each page's fields.
53
+
54
+ In `sitesquatch.toml`, a schema is a table: `[schemas.posts]` with `fields = { title = "string", date = "date" }`.
@@ -0,0 +1,33 @@
1
+ ---
2
+ title: "CSS and JavaScript"
3
+ description: "ssqch doesn't bundle CSS or JavaScript."
4
+ ---
5
+ 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:
6
+
7
+ - **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.
8
+ - **Sass:** `sassPlugin()` from `ssqch/sass` compiles it on each build, with a compiler built into ssqch ([Built-in plugins](plugins.md)).
9
+ - **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.
10
+ - **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.
11
+
12
+ `assetsPlugin()` from `ssqch/assets` then fingerprints what the tools wrote, for production builds (`app.css` becomes `app.3dc88db1.css`, and every link to it is rewritten).
13
+
14
+ Tailwind, for example, built once for `ssqch build` and watched for `ssqch serve`:
15
+
16
+ ```js
17
+ import { defineConfig } from "ssqch";
18
+ import { assetsPlugin } from "ssqch/assets";
19
+
20
+ const tailwind = "npx @tailwindcss/cli -i src/app.css -o dist/assets/app.css";
21
+
22
+ export default defineConfig(({ serving }) => ({
23
+ dirs: { input: "src", output: "dist" },
24
+ // A build runs it once; the server keeps it watching instead of running it on every rebuild.
25
+ beforeBuild: serving ? [] : { run: `${tailwind} --minify` },
26
+ serve: { run: [`${tailwind} --watch`] },
27
+ plugins: [assetsPlugin({ files: ["/assets/app.css"] })],
28
+ }));
29
+ ```
30
+
31
+ The layout links `/assets/app.css`. Tailwind reads the templates for class names on its own; `@source "../src";` in `app.css` tells it where they are if it doesn't find them.
32
+
33
+ When a page links a stylesheet or script that isn't in the output, `ssqch serve` says so instead of leaving an unstyled page to explain itself: a note in the corner of the page, and a warning in the terminal that names the `serve.run` tool that should have written it (or suggests one), repeated after each build until the file turns up.
@@ -0,0 +1,55 @@
1
+ ---
2
+ title: "JavaScript data files"
3
+ navTitle: "Data files"
4
+ description: "_data/*.js files are global data, and *.data.js files next to a template or in a folder (posts/posts.data.js) are template and directory data."
5
+ ---
6
+ `_data/*.js` files are global data, and `*.data.js` files next to a template or in a folder (`posts/posts.data.js`) are template and directory data. The default export is the data, or a function (sync or async) that returns it:
7
+
8
+ ```js
9
+ // src/_data/snacks.js
10
+ import { readFile } from "node:fs/promises";
11
+
12
+ export default async function () {
13
+ return JSON.parse(await readFile("data/snacks.json", "utf8"));
14
+ }
15
+ ```
16
+
17
+ ```js
18
+ // src/posts/posts.data.js
19
+ export default {
20
+ tags: "posts",
21
+ computed: {
22
+ permalink: (data) => `/snacks/${data.page.fileSlug}/`,
23
+ },
24
+ };
25
+ ```
26
+
27
+ Data functions run on every build. `ssqch serve` reloads a data file when it changes, and the modules it imports too. Data files work in TOML-configured sites too.
28
+
29
+ **Files as data:** `files()` from `ssqch` lists the files a glob matches, for a photo album made from a folder or a page of downloads, without `readdirSync` and a date parser of your own:
30
+
31
+ ```js
32
+ // src/_data/campPhotos.js
33
+ import { files } from "ssqch";
34
+
35
+ export default files("images/camp/*.{jpg,png}", { dimensions: true }).map((photo) => ({
36
+ src: photo.url,
37
+ width: photo.width,
38
+ height: photo.height,
39
+ taken: photo.date,
40
+ }));
41
+ ```
42
+
43
+ - `files(pattern, { dimensions })`: the files `pattern` matches, from the project root, sorted by path. Each is `{ path, url, name, stem, ext, date, dateFrom, size }`: `path` from the project root (`images/camp/20011222_08.JPG`); `url` where a passthrough copy to the same path is served, from the input folder when the file is inside it (`src/images/a.jpg` is `/images/a.jpg`), otherwise from the project root (`/images/camp/20011222_08.JPG`); `name` (`20011222_08.JPG`), `stem` (`20011222_08`) and `ext` (`jpg`, lowercase); `date`, a date from the start of the name (`20011222_08.JPG` or `2001-12-22-camp.jpg`, at midnight UTC) or else the file's modification time; `dateFrom`, which says which (`"name"` or `"modified"`: a modification time is when the file was copied or edited, not when a photo was taken, so test `photo.dateFrom === "name"` before captioning one with its date); and `size` in bytes. The glob ignores case, so `*.jpg` finds `.JPG`, and `*` stops at `/` (`**` crosses folders). `{ dimensions: true }` adds `width` and `height`, read from each image's header: PNG, JPEG, GIF, TIFF, WebP, HEIF and AVIF, BMP, PSD, ICO and QOI files have them, and every other file (an EXR, a JPEG XL, a TGA, a text file) gets `null`. The first read takes a moment for a thousand photos (about 100 ms from a cold disk), so it's off by default; the sizes are kept in `.cache/ssqch/image-sizes.json` by path, size and modification time, so later builds read only new and changed files. No match is an empty list; a glob that isn't one, or that leaves the project (`../`, an absolute path), is an error naming the call. It lists files, nothing more: copy them to the output with `passthrough`, and resize them with `imagePlugin()`. In `ssqch.config.js` before the first build, `url` is from the project root, since the input folder isn't known yet.
44
+
45
+ **Unique slugs:** two items with the same title (two albums called "Misc Pictures") give a paginated template the same permalink, and the build stops with `output conflicts`, naming both. Make the slugs different in the data, with `slugger()` from `ssqch`, so the page's permalink and every link to it use the same one:
46
+
47
+ ```js
48
+ // src/_data/albums.js
49
+ import { readData, slugger } from "ssqch";
50
+
51
+ const slug = slugger();
52
+ export default readData("data/albums.json").map((album) => ({ ...album, slug: slug(album.name) }));
53
+ ```
54
+
55
+ - `slugger({ separator })`: a function that slugifies like `slugify(text, { separator })` and counts what it has made: the first `Misc Pictures` is `misc-pictures`, the next `misc-pictures-1`, then `misc-pictures-2`, skipping a number another title already took. Each `slugger()` counts on its own, so make one per list. In the template, `permalink: "photos/{{ album.slug }}/"` and the index page's `<a href="/photos/{{ album.slug }}/">` agree. `slugify(text, { separator })` from `ssqch` is the template filter, for data files.
@@ -0,0 +1,47 @@
1
+ ---
2
+ title: "Deploying"
3
+ description: "Encoding images is by far the slowest part of a build, so it's worth never doing it twice."
4
+ ---
5
+ <img align="right" src="../../../docs/assets/stickers/canoe.svg" alt="" width="96">
6
+
7
+
8
+ ## Keep the image cache between builds
9
+
10
+ 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.
11
+
12
+ ssqch also remembers each source image's hash, size and modification time in `.cache/ssqch/image-hashes.json`, so unchanged images aren't read again. (A fresh clone gives every file a new modification time, so its first build re-hashes everything, which takes about 20 ms on the blog's 420 MB of images.) Add `.cache/` to your `.gitignore`, or turn the hash cache off with `hashCache: false`. It's kept outside the output folder because it names your source paths, and the output gets published.
13
+
14
+ Set `prune: true` on `imagePlugin()` to delete image files the build didn't use, in the output and in the cache, so the cache doesn't keep growing as images change. Only turn it on for full builds, where every image goes through the image plugin.
15
+
16
+
17
+ ## Serving a site under a path
18
+
19
+ A GitHub Pages project site lives at `https://you.github.io/repo/`, not at the root of a domain, so a link to `/about/` would miss. Set `base` and leave the templates alone:
20
+
21
+ ```js
22
+ export default defineConfig({
23
+ base: "/repo/",
24
+ });
25
+ ```
26
+
27
+ - **HTML:** in every page ssqch writes, a URL that starts with `/` gets the base in front: `href`, `src`, `srcset`, `action`, `poster` and the other URL attributes, a meta refresh, and `url()` in `style` attributes and `<style>` elements. That covers Markdown links, images from `imagePlugin()`, fingerprinted assets, redirect pages and Sass output. Relative URLs, `#fragments` and URLs with a domain aren't changed, so a link to something else on the same domain needs the whole address (`https://you.github.io/other-project/`).
28
+ - **Everywhere else:** in an inline script, a JSON file or a feed, call `withBase("/search.json")`, or print `ssqch.base` (`/repo`, or an empty string without a base). The feed filters add it for you: `absoluteUrl(post.url, site.url)` is `https://example.com/repo/posts/pine/`, with or without the path in `site.url`, and a URL that already has the base keeps one. Don't use `withBase()` inside an HTML attribute, or the URL gets the base twice (the link checker reports it).
29
+ - **`page.url` and collections:** unchanged, so `page.url == item.url` and the navigation helpers work the same with or without a base.
30
+ - **The output folder:** unchanged too. `dist/about/index.html` is what the host serves at `/repo/about/`.
31
+ - **Plugins:** `linksPlugin()` checks links under the base (other paths on the domain count as external), and `sitemapPlugin({ url })` takes the address with or without the base in it.
32
+ - **`ssqch serve`:** serves the site at `http://localhost:8080/repo/`, so what you click through locally is what the host will serve.
33
+
34
+ `ssqch build --base /repo/` sets it from the command line (for a preview deployed under another path, say) and wins over the config. In `sitesquatch.toml` it's `base = "/repo/"`.
35
+
36
+
37
+ ## Search
38
+
39
+ ssqch doesn't build a search index itself; [Pagefind](https://pagefind.app) does it well and runs after the build. Add it as a command (`npx` comes with Node, or install Pagefind's own binary):
40
+
41
+ ```js
42
+ export default defineConfig(({ env }) => ({
43
+ afterBuild: env === "production" ? [{ run: "npx -y pagefind --site dist" }] : [],
44
+ }));
45
+ ```
46
+
47
+ Then load `/pagefind/pagefind-ui.js` and `pagefind-ui.css` in your layout and add a `<div id="search">` for its search box. The `docs-sidebar` example does this.