ssqch 0.10.1 → 0.11.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.
- package/bundled/completions/bash +61 -15
- package/bundled/completions/elvish +27 -12
- package/bundled/completions/fish +35 -23
- package/bundled/completions/powershell +29 -12
- package/bundled/completions/zsh +39 -19
- package/bundled/docs/agents.md +11 -0
- package/bundled/docs/comparing-builds.md +37 -5
- package/bundled/docs/configuring.md +30 -5
- package/bundled/docs/field-guide.md +1 -1
- package/bundled/docs/github-pages.md +1 -1
- package/bundled/docs/index.md +1 -1
- package/bundled/docs/known-gaps.md +1 -1
- package/bundled/docs/markdown.md +63 -5
- package/bundled/docs/multilingual.md +20 -3
- package/bundled/docs/nav.yml +1 -0
- package/bundled/docs/netlify.md +2 -2
- package/bundled/docs/plugins.md +4 -4
- package/bundled/docs/seo.md +39 -1
- package/bundled/docs/template-languages.md +6 -4
- package/bundled/docs/templates.md +3 -3
- package/bundled/docs/trailheads/from-eleventy.md +25 -13
- package/bundled/docs/trailheads/from-hugo.md +103 -0
- package/bundled/docs/trailheads/from-jekyll.md +49 -15
- package/bundled/docs/trailheads/from-mkdocs.md +54 -9
- package/bundled/docs/trailheads/from-zola.md +2 -2
- package/bundled/docs/trailheads.md +22 -5
- package/bundled/docs/where-values-come-from.md +1 -1
- package/bundled/mkdocs/404.jinja +6 -0
- package/bundled/ssqch.d.ts +71 -16
- package/lib/assets.js +10 -9
- package/lib/{chunk-MUYWL4ZX.js → chunk-2L3HR67O.js} +71 -18
- package/lib/{chunk-ERNVEZOK.js → chunk-2QTJTEBV.js} +1 -1
- package/lib/{chunk-CXRHH5P5.js → chunk-3HZZY3Y7.js} +5 -5
- package/lib/{chunk-G67W2FTJ.js → chunk-3K237XAX.js} +9 -8
- package/lib/{chunk-6RSZV5O2.js → chunk-443ZQLVX.js} +3 -3
- package/lib/{chunk-ZZBHBLDB.js → chunk-5ELAUHRL.js} +18 -16
- package/lib/{chunk-MDG5A4NI.js → chunk-A75EVUJX.js} +5 -5
- package/lib/{chunk-JFPLNHEQ.js → chunk-AIMEXBTK.js} +28 -5
- package/lib/{chunk-6OUT5VFK.js → chunk-B5E27PLU.js} +10 -39
- package/lib/{chunk-R2YGC3VE.js → chunk-CMJ7X5WW.js} +3 -2
- package/lib/{chunk-MDB3D3LP.js → chunk-ERAIEV3O.js} +2 -2
- package/lib/{chunk-DTSTCVRX.js → chunk-FCM3NYFR.js} +11 -8
- package/lib/{chunk-X7C6GFUM.js → chunk-GJNIQAIH.js} +8 -8
- package/lib/{chunk-FYRC2HBU.js → chunk-GLJQ4C76.js} +39 -18
- package/lib/{chunk-BXARVN5Z.js → chunk-GS5B3CBW.js} +1 -1
- package/lib/chunk-H5K2ZE7B.js +219 -0
- package/lib/{chunk-DNWA7WNO.js → chunk-HFSWUTXX.js} +1 -1
- package/lib/{chunk-7JGYYAKI.js → chunk-HWW5NCVJ.js} +1 -1
- package/lib/{chunk-BT3NVQOD.js → chunk-I3HYKEEW.js} +1 -1
- package/lib/{chunk-RFNLZM7W.js → chunk-IOBC665M.js} +1 -1
- package/lib/chunk-JC54PHIT.js +7992 -0
- package/lib/{chunk-3BQJY6GF.js → chunk-KCF2Z6N7.js} +1 -1
- package/lib/{chunk-HMVYNV6M.js → chunk-KZZS4W2V.js} +14 -12
- package/lib/{chunk-XR7GFL4B.js → chunk-LJOURBYT.js} +14 -12
- package/lib/chunk-OQGXZYZS.js +45 -0
- package/lib/chunk-OSBEH67S.js +6296 -0
- package/lib/{chunk-FYU22VDK.js → chunk-QJ5ZFTML.js} +14 -12
- package/lib/{chunk-LU73FTIR.js → chunk-QLUTNR37.js} +11 -10
- package/lib/{chunk-DUGGZ4EE.js → chunk-RBNPBTDP.js} +1 -1
- package/lib/{chunk-F65YUXZ7.js → chunk-RIAOXEXC.js} +10 -4
- package/lib/chunk-RVXGUMFI.js +21 -0
- package/lib/{chunk-FZGJUJAL.js → chunk-RYIWYWRQ.js} +3 -3
- package/lib/{chunk-LYPKL524.js → chunk-RZYAIX2R.js} +12 -10
- package/lib/{chunk-3NDFUMV2.js → chunk-V2FSMOFX.js} +3 -3
- package/lib/{chunk-26SHWRC6.js → chunk-X2GAVYV2.js} +524 -72
- package/lib/chunk-XS4EJSEK.js +279 -0
- package/lib/chunk-YCOTX2VM.js +37 -0
- package/lib/{chunk-P2TRR6XK.js → chunk-Z44IAMNG.js} +85 -16
- package/lib/chunk-Z5OP43HU.js +2945 -0
- package/lib/{chunk-3LODFCCH.js → chunk-ZINLHOX4.js} +2 -2
- package/lib/{chunk-HNG372DW.js → chunk-ZR3JYLFB.js} +814 -12347
- package/lib/cli.js +78 -37
- package/lib/elements.js +10 -9
- package/lib/image.js +11 -10
- package/lib/links.js +10 -9
- package/lib/minify.js +71 -12
- package/lib/redirects.js +10 -9
- package/lib/rss.js +13 -10
- package/lib/sass.js +13 -243
- package/lib/sitemap.js +18 -15
- package/lib/ssqch.js +6 -4
- package/package.json +1 -1
- package/types/index.d.ts +52 -11
- package/types/minify.d.ts +15 -3
- package/types/sass.d.ts +2 -0
- package/types/sitemap.d.ts +2 -2
- package/wasm/markdown.wasm +0 -0
- package/wasm/minify.wasm +0 -0
- package/wasm/sass.wasm +0 -0
- package/lib/chunk-II7ZRIAC.js +0 -1285
- package/lib/chunk-IOXCGMSF.js +0 -1539
- /package/lib/{chunk-JFPLNHEQ.js.LEGAL.txt → chunk-AIMEXBTK.js.LEGAL.txt} +0 -0
- /package/lib/{chunk-HNG372DW.js.LEGAL.txt → chunk-ZR3JYLFB.js.LEGAL.txt} +0 -0
|
@@ -15,7 +15,7 @@ ssqch diff dist-before dist
|
|
|
15
15
|
|
|
16
16
|
```text
|
|
17
17
|
Comparing dist-before with dist
|
|
18
|
-
Ignoring asset fingerprints, integrity hashes, the generator's version,
|
|
18
|
+
Ignoring asset fingerprints, image ids, integrity hashes, the generator's version, whitespace between tags, and how tags are written where browsers read them the same (attribute order, quotes, entities, `<br/>`) (--exact compares bytes).
|
|
19
19
|
|
|
20
20
|
Added (1)
|
|
21
21
|
+ /trails/cedar/
|
|
@@ -34,18 +34,50 @@ Changed (2)
|
|
|
34
34
|
- body { color: #222 }
|
|
35
35
|
+ body { color: #111 }
|
|
36
36
|
|
|
37
|
+
If a folder held an earlier build, its leftover files are among the added and removed: to rule that out, build each side into an empty folder.
|
|
38
|
+
|
|
37
39
|
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
40
|
```
|
|
39
41
|
|
|
40
42
|
- **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.
|
|
43
|
+
- **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), a changed canonical link (`canonical link: https://example.com/a/ -> https://example.com/a`) or refresh redirect (`redirects to: /new/ -> /newer/`), where search engines and readers end up, and `only dates changed (2025 -> 2026)` when every change on it is a date or a year. A feed (RSS or Atom) says which entries went and came, by their `<guid>` or `<id>` (else their link), since readers' apps track them by it: `feed entries removed (readers see them go): tag:a`.
|
|
42
44
|
- **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
|
+
- **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. It works with `--exact` too, for "byte for byte, but this": `--exact --ignore 'object at 0x[0-9a-f]+'` checks every byte except a Python memory address. 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.
|
|
46
|
+
- **Part of the site:** `--only '**/*.html'` compares only matching files, and `--exclude 'img/**'` leaves matching files out (both repeatable; `--exclude` applies after `--only`). A glob that ends in `/` is that folder (`--only /posts/pine/`, as the page's URL is written), and `--only` that matches no file in either build is an error. A file left in an output folder by an earlier build is an added or removed file too, so build each side into an empty folder.
|
|
47
|
+
- **Where on the page:** a page's changes say which heading they're under, `@ under #its-id` (or its text in quotes when it has no id), when that's another heading than the change before's; the JSON has it as each hunk's `at`.
|
|
45
48
|
- **Longer diffs:** each file shows 10 changed lines; `--lines 0` shows them all.
|
|
46
49
|
- **Nothing to report:** `No differences: 148 pages and 4,730 other files are the same. The stump has not moved.`
|
|
47
50
|
- **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
51
|
|
|
49
52
|
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
53
|
|
|
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`).
|
|
54
|
+
**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: `ssqch baseline`, below, does that for another generator's build), 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`).
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
## Reference builds
|
|
58
|
+
|
|
59
|
+
**Reference builds:** before comparing a move's output with the site its old generator built, make that build trustworthy: `ssqch baseline "<command>"` runs the old generator's build command in fresh copies of the site, three times, and compares the builds, so what changes by itself (the build's time, ids from `Math.random()`) is known before anything is compared with ssqch's:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
ssqch baseline "npx @11ty/eleventy" # .cache/ssqch/baseline/ref-1 to ref-3
|
|
63
|
+
ssqch baseline "bundle exec jekyll build" --commit main # the commit before the move
|
|
64
|
+
ssqch build && ssqch diff .cache/ssqch/baseline/ref-1 dist
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- **The copies:** each build runs in a copy of its own in `.cache/ssqch/baseline-copies/` (removed afterwards): the files git would commit (tracked files, and new ones it doesn't ignore), or with `--commit <rev>`, that commit, checked out as a worktree. `--patch <file>` applies a patch (as `git diff > fix.patch` writes it) to each copy before it's built, for a commit that needs a fix to build at all (a dependency that moved, a script that broke); a patch that doesn't apply stops the run, with git's reason. Outside git, every file but `node_modules`, `.cache` and the output. What the site has installed, which git ignores, is linked into each copy, not installed again: `node_modules`, Bundler's `.bundle` and the folder its config gives gems (`BUNDLE_PATH`, or `vendor/bundle`), and a Python `.venv`; `--link <path>` (repeatable) links another folder of the site. A tool that won't follow a link out of its folder gets copies instead: Hugo's `js.Build` refuses a `node_modules` that resolves outside the project, so for a `hugo` command they're copied, and `--copy-installs` copies them for any other. The copy is copy-on-write where the file system has it (APFS, Btrfs, XFS), so it's quick even for a large `node_modules`. The command runs with the `PATH` ssqch has, so put the version of a language the installs were made with first on it (gems installed for Ruby 3.3 don't load in Ruby 4: `PATH=<ruby 3.3's bin>:$PATH ssqch baseline "bundle exec jekyll build"`).
|
|
68
|
+
- **The pinned clock:** every file's time is set to the commit's (2026-01-01 outside git), so pages dated by their file's time agree, and the command runs with `TZ=UTC` and `SOURCE_DATE_EPOCH` set to that time. A generator that reads its own clock doesn't see those: Jekyll's `site.time` is pinned for it (`jekyll build` gets `--config _config.yml,<a time: file>`, or the time file last in the `--config` list it gives, and the summary says so; and when its build has GitHub Pages' placeholder `https://github.com/pages/...` URLs, which jekyll-github-metadata writes when it can't tell which repository the site is, `baseline` warns: give it `PAGES_REPO_NWO=owner/repo`); for another, set the time in its config and give the command. On Linux, a file's creation time can't be set, so a generator that dates an undated page by when its file was created (Eleventy does) gives it the copy's time: give those pages a `date`, or let `ssqch diff` say `only dates changed`.
|
|
69
|
+
- **The builds:** `--from <dir>` is the folder the command writes, `_site` unless you say (Eleventy's and Jekyll's; Hugo writes `public` and Astro `dist`), and each is moved to `.cache/ssqch/baseline/ref-1`, `-2` and `-3`, where neither generator reads them as pages (`--to .refs/jekyll` makes `.refs/jekyll-1` and so on, and the folder it needs). `--runs 1` makes one build and compares nothing; a build of that name an earlier, longer run left is removed. The command's own output goes to standard error, and `--quiet` leaves it out.
|
|
70
|
+
- **`ref-common`, the most common version of each file:** with three builds or more and something that varies, `baseline` also writes `.cache/ssqch/baseline/ref-common` (beside the builds, named after `--to`): the build most like the others, with each varying file's most common version put in (and a file most builds lack left out). The `Next:` line compares with it, and so should you: a race (a11yproject.com's style guide needed 170 builds to settle) has no one build to trust. `--runs 20` or more counts the versions better.
|
|
71
|
+
- **The comparison:** the builds are compared as `ssqch diff a b c` compares them (**Several builds**, above), grouped: opensource.guide's three Jekyll builds vary on 380 files, all of them one group, the build's time in each page's `article:published_time` and JSON-LD. With more than four builds in a version, the list is a count (`34 of 50 builds (ref-1, ref-2, ref-4, ...) agree`), so `--runs 50` shows how often a race comes out each way, and the summary names the build most like the others (the most common version of the most files that vary; `ssqch diff a b c --format json` has it as `typical`), and the files no two builds agree on. The exit code is 0 when they're the same, 1 when something varies, and 2 when a build couldn't be made: the command failed (with its exit code) or wrote no `--from` folder, the commit isn't there, or the patch didn't apply.
|
|
72
|
+
|
|
73
|
+
## Comparing another generator's output
|
|
74
|
+
|
|
75
|
+
**Markup browsers read the same:** two generators write the same page in different ways, and a browser reads them alike, so the diff doesn't list them. Each tag is compared in one form: element and attribute names in lower case, attributes in alphabetical order (the first of two with one name, as a browser keeps it), values with their entities decoded and in double quotes, a boolean attribute without a value (`defer`, `defer=""` and `defer="defer"`), no `/` before the `>` (`<br/>` is `<br>`), and in an SVG or MathML, `<path/>` as `<path></path>`. Spacing inside `class`, `rel`, `srcset` and `sizes` doesn't count (`a.jpg 1x,b.jpg 2x` is `a.jpg 1x, b.jpg 2x`). In text, and inside `<pre>` and `<textarea>`, an entity and its character are the same (`'` and `'`, `>` and `>`, `&` and a lone `&`), apart from ` `, which stays different from a space. What a browser reads differently still counts: an attribute's value, the order of `class` names, `<div/>` in HTML (which doesn't close the `div`), and entities in a `<script>` or `<style>`. The ReverentGeek blog's comparison with its Eleventy build went from 24,659 changed lines to 225 with it, and from 161 changed pages to 14.
|
|
76
|
+
|
|
77
|
+
**Image ids:** `imagePlugin()` and eleventy-img name an image by an id from a hash and its width (`/img/LeC3bj9CzE-256.webp`), and two builds that hash differently (another generator, other image settings) name every image differently. In pages and feeds the id reads as `{id}` (`/img/{id}-256.webp`), so a page compares by its widths and formats; the files keep their own names, so a replaced image is still a removed and an added file. More than five such images in the Added or Removed list are one counted line (`4,689 images named by an id`); `--format json` lists each. An id is ten letters, digits, `-` and `_` before `-<width>.<ext>`, and not a plain lower-case word or a number, so `screenshot-1200.png` keeps its name.
|
|
78
|
+
|
|
79
|
+
**Feeds and sitemaps:** an XML file is compared as tags and text too, with its names' case kept, and the HTML a feed carries in `<content>`, `<description>` or `<summary>`, escaped (`<p>`) or in CDATA, is compared as HTML. A file whose changes are only dates says `only dates changed`, as a page does, and one whose lines only moved says `the same lines, in another order` (a sitemap that lists its pages in another order).
|
|
80
|
+
|
|
81
|
+
**Groups:** when the same change is on more than one file, it's listed once, the most files first, with how many files have it, the first three, and its lines as the first file has them: `~ 102 pages, the same but for attribute values: /ar/building-community/, ... and 99 more`. A group's tags can differ in their attribute values from file to file (each link moved to another anchor), but its text is the same, and `the same but for attribute values` says when the values differ. A run of three changed lines or more also joins a group with the same tags (`the same tags with other attributes`): a `<picture>` with two widths and one with three, or an `<img>` with a `fetchpriority` the others don't have. One changed line never does, since one `<meta>` that changed looks like any other. A change that's only dates groups by the form of the dates that changed (`the same dates in other text`), so a build's time printed in each page's own JSON-LD is one group though each page's description around it differs, and so are feeds stamped a few milliseconds apart; a date of another form (`19 Nov 2026`) is another group. After the groups, each file is listed with what's left (its changes no group holds), and a file whose changes are all in groups isn't listed again. That's the order to fix them in: one cause is often hundreds of pages. `--ungrouped` lists each file with all its changes instead. Several builds are grouped the same way: a build's time printed on every page varies the same way on each, so it's one group, and each file is listed after the groups with its versions and what's left (`--ungrouped` here too). With `--format json`, `groups` (in a diff of two, and of several builds) has each one's `files` (how many), `urls`, `same`, `match` (`lines`, `values`, `tags` or `dates`: how alike its files' changes are), `kind` (`dates`, `order`, `markup`, `text` or `markup and text`) and `hunk`, and each changed file's `groups` are places in that list. opensource.guide's comparison has 12 groups, one of them on 102 of its 172 changed pages.
|
|
82
|
+
|
|
83
|
+
**Links:** a symbolic link is compared by where it points, not by what's there (that file is compared on its own): two links to the same target are the same, a link that points elsewhere shows `- -> old.html` and `+ -> new.html` (`a link, to somewhere else`), and a link in one build that's a file in the other says so.
|
|
@@ -51,15 +51,15 @@ The default export is the config: an object, or a function (sync or async) that
|
|
|
51
51
|
| `markdown` | Heading IDs, footnotes and the other Markdown extensions; see [Markdown](markdown.md). |
|
|
52
52
|
| `deepMerge` | Merge objects and concatenate arrays through the data cascade (default `true`). |
|
|
53
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. |
|
|
54
|
+
| `filters` | `{ name: function }`, callable from templates: `{{ title | slug }}` or `{{ slug(title) }}`. Async functions are awaited. A function gets text where a template holds HTML marked safe (a layout's `content`), and a value it gives back unchanged stays safe, so `{{ content | myFilter }}` prints HTML; one that returns new text prints it escaped in Nunjucks and Jinja, unless `| safe` or the function returns `safe(html)`. A filter written as a `function` sees the page being rendered as `this.page` (see [What a filter sees](#what-a-filter-sees)). |
|
|
55
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
56
|
| `collections` | `{ name: (pages) => ... }`. `pages` has `all()`, `byTag(tag)`, `byTags(...tags)` and `byGlob(glob or globs)`, oldest first. |
|
|
57
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, context) => html }`, or an object with a `render(source, data, context)` method (async is fine). `context` says what's being rendered: `{ kind, path }`, where `kind` is `"body"` (a page), `"layout"`, `"hook"` (a Markdown render hook), `"permalink"` or `"computed"`, and `path` is the file as `page.inputPath` names it (`./src/posts/pine.md`). Add the extension to `templateFormats` to render those files; layouts in that extension work too, and `markdownEngine` can name one. A page's `permalink` and `computed` strings never go through an engine of your own (it's usually a Markdown renderer): they render with the first of ssqch's template languages in the page's chain, then the `markdownEngine`, then Edge. `
|
|
59
|
-
| `ignore` | Globs, relative to the input folder, of files that aren't pages: `["drafts/**", "**/README.md"]`. Folders starting with `.`, `node_modules`
|
|
58
|
+
| `engines` | Template engines of your own: `{ extension: (source, data, context) => html }`, or an object with a `render(source, data, context)` method (async is fine). `context` says what's being rendered: `{ kind, path }`, where `kind` is `"body"` (a page), `"layout"`, `"hook"` (a Markdown render hook), `"permalink"` or `"computed"`, and `path` is the file as `page.inputPath` names it (`./src/posts/pine.md`). Add the extension to `templateFormats` to render those files; layouts in that extension work too, and `markdownEngine` can name one. A page's `permalink` and `computed` strings never go through an engine of your own (it's usually a Markdown renderer): they render with the first of ssqch's template languages in the page's chain, then the `markdownEngine`, then Edge. `md` replaces ssqch's Markdown with your own library (a markdown-it instance works as it is), and `cache: true` keeps the pages an engine renders by their source ([Your own Markdown library](markdown.md#your-own-markdown-library)). `edge`, `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` a folder Bundler installed gems into (`vendor/bundle`, with `ruby/<version>/gems/` inside), and `_site` at the top of the input folder (where Jekyll and Eleventy write their builds, so the old generator's output isn't read as pages while ssqch writes elsewhere) are skipped without it. |
|
|
60
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 `` just works. Subfolders with templates of their own, and data files, are left out (default `false`). |
|
|
61
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. |
|
|
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/`. A file's `to` is the file it's copied to (`{ "docs/CNAME": "CNAME" }`), or a folder it goes into by its own name: `"."` (the output's root), a path that ends with `/` (`"well-known/"`), or a folder that's there. 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
63
|
| `watch` | More paths for `ssqch serve` to watch. |
|
|
64
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
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 = [...]`. |
|
|
@@ -67,17 +67,42 @@ The default export is the config: an object, or a function (sync or async) that
|
|
|
67
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
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
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
|
+
| `trimAfterFrontMatter` | `true` starts each template's body (pages, layouts and includes with front matter) at its first line with text, dropping the blank lines after the closing `---`, as Jekyll does, so a layout prints no blank line where Jekyll's printed none. Off (the default), the body starts on the line after `---`, as in Eleventy. Error lines still count from the top of the file. |
|
|
71
|
+
| `jekyllTemplates` | `true` gives templates Jekyll's `page` and `site`, so a Jekyll site's layouts and includes run as they're written. `page` has the page's front matter too (`page.title`, `page.lang`; ssqch's own keys, like `url`, `date` and `headings`, win), and `page.path` and `page.categories` (the folders above `_posts`, then its own). `site` keeps the site's own keys and gets `posts` (newest first), each collection by its tag (`site.articles`), `pages`, `html_pages`, `categories`, `tags`, `data` (the global data, so `site.data.locales` works) and `time`. Their items read in Jekyll's shape: `post.title`, `post.content` (the rendered page), `post.excerpt` and `post.path`, and `where: "lang"` and `sort: "title"` read front matter. It applies to every template language. Off (the default), front matter is at the top level (`{{ title }}`) and items keep it under `data` (`post.data.title`). `ssqch scout`'s draft for a Jekyll site turns it on. |
|
|
72
|
+
| `mkdocsTemplates` | `true` gives templates what MkDocs gives a theme's, so an MkDocs theme's Jinja templates (Material for MkDocs') run as written: `config` (`mkdocs.yml`, with the theme's `mkdocs_theme.yml` under its `theme`), `nav` (Sections, Pages and Links, with `active` on the page being rendered and its sections), `page` in a layout (MkDocs' page: `title`, `url` without its first `/`, `abs_url`, `canonical_url`, `edit_url`, `content`, `toc`, `meta`, `previous_page`, `next_page`, `ancestors`, `is_homepage`), `base_url`, `mkdocs_version` and `build_date_utc`, and the `url` and `script_tag` filters, which write URLs relative to the page. A Markdown page's layout is the theme's `main.html` (or the one its front matter's `template` names), the theme's `404.html` makes `/404.html` with no page, and Jinja doesn't escape, as MkDocs' doesn't (`jinja: { autoescape: true }` turns it back on). A string names another file: `mkdocsTemplates: "docs/mkdocs.yml"`. The search index and `sitemap.xml.gz` aren't written. See [moving from MkDocs](trailheads/from-mkdocs.md). |
|
|
73
|
+
| `jinja` | Jinja's settings, for `.jinja` and `.j2` templates (and `.html` read as Jinja): `{ autoescape: false }` prints values as they are, as MkDocs' Jinja does, where they're HTML-escaped by default (`| e` still escapes; `.njk` always does). `mkdocsTemplates` turns it off. |
|
|
70
74
|
| `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
75
|
| `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
76
|
| `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. |
|
|
77
|
+
| `layoutAliases` | Other names for layouts, as Eleventy's `addLayoutAlias` gave them: `layoutAliases: { post: "layouts/post.njk" }` makes `layout: post` that file, where it would otherwise be `_includes/post.*` (a partial, on a site moving from Eleventy). A page's `layout` is still the name it gave, so a template that tests `layout == "post"` keeps working. An alias can name another alias; a loop of them is an error, and so is a value that isn't a layout's name. `ssqch scout`'s draft for an Eleventy site writes it from `addLayoutAlias`. |
|
|
73
78
|
| `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
79
|
|
|
75
80
|
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
81
|
|
|
77
82
|
|
|
83
|
+
## What a filter sees
|
|
84
|
+
|
|
85
|
+
A filter's arguments are what the template passes it. Two more things make the filters a theme from another generator calls (MkDocs' page-relative `url`, Hugo's `relURL`, a `toc` that writes HTML) work as they're written:
|
|
86
|
+
|
|
87
|
+
- `this.page` and `this.data`: in a filter written as a `function` (not an arrow function, which has no `this`), `this.page` is the page being rendered, as its templates see `page` (`url`, `inputPath`, `outputPath`, `date`, and in a layout `headings` and `excerpt`), and `this.data` everything the template sees (front matter, the cascade, `collections`, and in a layout `content`). In a layout it's the page the layout is rendering. It works in every template language, in an async filter too, and in a filter called from an include. Outside a render (a collection, a data file, a hook calling the function) `this` is `undefined`.
|
|
88
|
+
- `safe(html)`, from `ssqch`: marks a function's answer as HTML, so every template language prints it as it is (Jinja and Nunjucks without `| safe`, Edge in `{{ }}`, Handlebars in `{{ }}`, EJS in `<%= %>`). It's still a string to JavaScript (`String(x)`, `x.length`, `"<h1" in x` in Jinja). Escape what you put in it that isn't yours.
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
import { defineConfig, safe } from "ssqch";
|
|
92
|
+
import path from "node:path/posix";
|
|
93
|
+
|
|
94
|
+
export default defineConfig({
|
|
95
|
+
filters: {
|
|
96
|
+
// `{{ "assets/app.css" | url }}`: a URL relative to the page, as MkDocs writes them.
|
|
97
|
+
url: function (to) { return path.relative(this.page.url, `/${to}`) || "."; },
|
|
98
|
+
badge: (text) => safe(`<span class="badge">${text}</span>`),
|
|
99
|
+
},
|
|
100
|
+
});
|
|
101
|
+
```
|
|
102
|
+
|
|
78
103
|
## What you can import
|
|
79
104
|
|
|
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,
|
|
105
|
+
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, `files(pattern)` for the files a glob matches, and `safe(html)`), `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
106
|
|
|
82
107
|
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
108
|
|
|
@@ -141,4 +141,4 @@ None of that is written to the output folder: the server adds it to pages as it
|
|
|
141
141
|
|
|
142
142
|
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.
|
|
143
143
|
|
|
144
|
-
`ssqch build` uses production mode and `ssqch serve` uses development mode, unless you pass `--env development|production` (or set `$SSQCH_ENV` or `$NODE_ENV`). The other options are `--output DIR`, `--base /path/` to serve the site [under a path](deploying.md#serving-a-site-under-a-path), `--offline` to answer `fetch()` from saved copies only, `--port N` for `serve` (0 picks a free port), `--quiet` to print only warnings and errors, and `--verbose` to also list the slowest images to encode and the templates nothing used. Errors are red on a terminal and plain in a pipe, a log, or anywhere `NO_COLOR` is set. The other commands are `ssqch init`, `ssqch types`, `ssqch completions`, [`ssqch new`](new-pages.md), [`ssqch inspect`](where-values-come-from.md), [`ssqch diff`](comparing-builds.md), [`ssqch footprint`](footprint.md), [`ssqch
|
|
144
|
+
`ssqch build` uses production mode and `ssqch serve` uses development mode, unless you pass `--env development|production` (or set `$SSQCH_ENV` or `$NODE_ENV`). The other options are `--output DIR`, `--base /path/` to serve the site [under a path](deploying.md#serving-a-site-under-a-path), `--offline` to answer `fetch()` from saved copies only, `--port N` for `serve` (0 picks a free port), `--quiet` to print only warnings and errors, and `--verbose` to also list the slowest images to encode and the templates nothing used. Errors are red on a terminal and plain in a pipe, a log, or anywhere `NO_COLOR` is set. The other commands are `ssqch init`, `ssqch types`, `ssqch completions`, [`ssqch new`](new-pages.md), [`ssqch inspect`](where-values-come-from.md), [`ssqch diff`](comparing-builds.md), [`ssqch footprint`](footprint.md), [`ssqch scout`](trailheads.md#scouting-a-site), [`ssqch capabilities`](agents.md) and [`ssqch docs`](agents.md), and `ssqch build --format json` reports to a [script or a coding agent](agents.md).
|
|
@@ -36,6 +36,6 @@ jobs:
|
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
- **`--base`** takes the repository's name from the workflow, so the config doesn't have to know it and `ssqch serve` on your machine still serves the site at `/`. A user site (`you.github.io`) or one with a custom domain is at the root: leave `--base` off.
|
|
39
|
-
- **The version** is the site's `ssqch` dev dependency, pinned by its lockfile, so a new release can't surprise a deploy. `node-version` can be any Node from 22.18 on. A site without a `package.json` replaces `npm ci` with `npm install --global ssqch@0.
|
|
39
|
+
- **The version** is the site's `ssqch` dev dependency, pinned by its lockfile, so a new release can't surprise a deploy. `node-version` can be any Node from 22.18 on. A site without a `package.json` replaces `npm ci` with `npm install --global ssqch@0.11.0` (drop `cache: npm`, which looks for a lockfile) and runs `ssqch build` instead of `npx ssqch build`.
|
|
40
40
|
- **A 404 page:** GitHub Pages serves `404.html` from the site's root, so give your 404 page `permalink: /404.html`.
|
|
41
41
|
- **Images:** to keep encoded images between builds, cache `.cache/ssqch` with `actions/cache` (see [Keep the image cache between builds](deploying.md#keep-the-image-cache-between-builds)).
|
package/bundled/docs/index.md
CHANGED
|
@@ -20,7 +20,7 @@ What's in the pack:
|
|
|
20
20
|
- **Checks that run with every build:** [content schemas](content-schemas.md) for front matter, a link checker, [`ssqch diff`](comparing-builds.md) to see what a change did to the output, and [`ssqch inspect`](where-values-come-from.md) to see where a page's data came from.
|
|
21
21
|
- **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.
|
|
22
22
|
- **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.
|
|
23
|
-
- **A quick start and a way in:** `ssqch init` (a blog, or a docs site with a sidebar and search), `ssqch
|
|
23
|
+
- **A quick start and a way in:** `ssqch init` (a blog, or a docs site with a sidebar and search), `ssqch scout` for what moving an Eleventy, Jekyll, Hugo, MkDocs or Zola site takes, [`ssqch new`](new-pages.md) 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.
|
|
24
24
|
- **Plugins in Rust** for the heavy lifting: transforms, filters and template languages built to one `.wasm` file that runs on every platform.
|
|
25
25
|
|
|
26
26
|
SiteSquatch is a young one (0.x), so expect some breaking changes between minor versions. Each is listed in the [changelog](https://github.com/reverentgeek/sitesquatch/blob/main/CHANGELOG.md) with what you'd need to change.
|
|
@@ -13,6 +13,6 @@ The uncharted parts of the map, as of this release:
|
|
|
13
13
|
- **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.
|
|
14
14
|
- **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.
|
|
15
15
|
- **Collections:** custom collections don't see pages that are paginated over collections. Those pages are added to `all` and their tags afterwards.
|
|
16
|
-
- **Platforms:** ssqch needs Node 22.18 or newer, and runs wherever that Node and sharp do: macOS, Windows and Linux, Alpine and ARM included.
|
|
16
|
+
- **Platforms:** ssqch needs Node 22.18 or newer, and runs wherever that Node and sharp do: macOS, Windows and Linux, Alpine and ARM included.
|
|
17
17
|
|
|
18
18
|
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.
|
package/bundled/docs/markdown.md
CHANGED
|
@@ -15,17 +15,26 @@ export default defineConfig({
|
|
|
15
15
|
|
|
16
16
|
| Option | Default | What it does |
|
|
17
17
|
| --- | --- | --- |
|
|
18
|
-
| `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. |
|
|
18
|
+
| `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). `"kramdown"` matches Jekyll's: kramdown's GFM ids for the page's headings (like GitHub's, but emoji and symbols are dropped: `😭 No reply` becomes `-no-reply`), and with `htmlMarkdown`, kramdown's own for headings inside HTML (ASCII letters and digits from the first letter on, `section` when none are left: `Café` becomes `caf`, `中文` becomes `section`). `"python-markdown"` matches MkDocs' (Python-Markdown's `toc` default: ASCII from the text, word characters and hyphens, lowercased, so `Café notes` becomes `cafe-notes`; and a repeated heading gets toc's `_1`, `_2`, with the page's links to it). `"markdown-it-anchor"` matches that plugin's default ids, which Eleventy sites with markdown-it-anchor have (the lowercase text with each run of spaces as `-`, then percent-encoded as `encodeURIComponent` does: `What’s new?` becomes `what%E2%80%99s-new%3F`); its `tabindex="-1"` and permalink markup are a heading hook's (`_includes/hooks/heading.*`, below). 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. |
|
|
19
19
|
| `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. |
|
|
20
20
|
| `footnotes` | `true` | `[^1]` references, with the notes in a `<section class="footnotes">` at the end and links back to each reference. |
|
|
21
21
|
| `taskLists` | `true` | `- [ ]` and `- [x]` items, as disabled checkboxes. |
|
|
22
|
-
| `autolinks` | `true` | Bare `https://` and `www.` URLs become links. |
|
|
22
|
+
| `autolinks` | `true` | Bare `https://` and `www.` URLs become links. `"fuzzy"` links bare domains and email addresses too (`example.com`, `ranger@example.com`), as markdown-it's `linkify` does ([below](#markdown-its-habits)). |
|
|
23
23
|
| `alerts` | `true` | GitHub's `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` and `[!CAUTION]`, as `<div class="markdown-alert markdown-alert-note">` with a title, the same markup GitHub uses (or a container template of that name, below). |
|
|
24
24
|
| `containers` | `true` | `::: name args` blocks (below). |
|
|
25
25
|
| `definitionLists` | `false` | A term, then `: definition` lines, as `<dl>`. |
|
|
26
26
|
| `smartPunctuation` | `false` | Curly quotes, `--` and `---` as dashes, `...` as an ellipsis. A `--` that follows a space and runs into a word stays as it is, so `run it with --fix` keeps its flag. |
|
|
27
|
+
| `breaks` | `false` | A single newline inside a paragraph or a list item becomes a `<br>`, as markdown-it's `breaks: true` makes it ([below](#markdown-its-habits)). |
|
|
28
|
+
| `figures` | `false` | An image, or a linked image, alone in a paragraph becomes a `<figure>` with its alt text as the `<figcaption>`, as markdown-it-implicit-figures makes it ([below](#markdown-its-habits)). |
|
|
29
|
+
| `htmlMarkdown` | `false` | Markdown inside HTML, as Jekyll's kramdown reads it. `"kramdown"` renders the content of an HTML element with `markdown="1"` and drops the attribute: span-level (no paragraphs or lists) for `p`, the headings, `td`, `th`, `dt` and inline elements such as `span`, block-level for the others (`div`, `aside`, `section`); `markdown="block"` and `markdown="span"` choose. kramdown's HTML rules come along: a block-level element is raw HTML to its end tag, blank lines and all (CommonMark ends it at a blank line, and a line indented four spaces after one becomes code), a block tag counts only at the start of a line (up to three spaces in), an element without an end tag closes at the end of what holds it, and a line right after a block's end tag starts new Markdown. It applies to pages and to the `markdown` function (Jekyll's `markdownify`). `false` leaves HTML as CommonMark does, Markdown inside it as text. opensource.guide's 3,791 elements come out as Jekyll's. |
|
|
30
|
+
| `admonitions` | `false` | MkDocs' admonitions. `"mkdocs"` writes `!!! note "Title"`, with its body indented four spaces, as Python-Markdown's admonition extension does: `<div class="admonition note"><p class="admonition-title">Title</p>...</div>`. `??? note` (pymdownx.details) is `<details class="note"><summary>Note</summary>...</details>`, and `???+` is open. Without a title the type's name is the title (`Note`), and `""` leaves it out; more words after the type are more classes (`!!! note inline end`). They nest, work in list items, and leave code fences alone. The title is text: Markdown in it stays as written. |
|
|
31
|
+
| `tabs` | `false` | MkDocs' content tabs. `"mkdocs"` writes `=== "Tab"` blocks, each with its body indented four spaces, as pymdownx.tabbed's `alternate_style` does (the markup Material for MkDocs styles): tabs one after another, with only blank lines between, are one set, `===+` is the one selected, and `===!` starts a new set. The sets are numbered on each page (`__tabbed_1_1`). |
|
|
32
|
+
| `shortcodes` | `false` | Hugo's shortcodes. `"hugo"` reads a shortcode on a line of its own as a container (below): `{{< note type="tip" >}}` to `{{< /note >}}` (or `{{% note %}}` to `{{% /note %}}`) renders `_includes/containers/note.*` with `container.args` (`type="tip"`), `container.props.type` `container.content` (the inside, as Markdown) and `container.source` (the inside as written, for a `{{< >}}` shortcode, whose inside Hugo doesn't read as Markdown), and one with no closing tag (`{{< youtube abc >}}`, `{{< img src="a.png" />}}`) is a container with no content. Write each shortcode's template as a container template. A shortcode inside a line of text is left as written, and so is one in a code fence; `{{</* note */>}}` prints `{{< note >}}`, as in Hugo. Set `markdownEngine: false` too, since Hugo doesn't run template code in content. `ssqch scout` lists each shortcode and its calls. |
|
|
33
|
+
| `sourceLinks` | `false` | Links to `.md` files go to the page built from that file, as GitHub, MkDocs and jekyll-relative-links read them: `[Setup](setup/install.md#first-steps)` links to that page's URL with its `#` part. `true` writes the URL from the site's root (`/setup/install/#first-steps`); `"relative"` writes it from the page, as MkDocs does (`setup/install/#first-steps`, `../../` back to the home page). A link to a `.md` file that isn't a page is left as it is, so the link checker reports it. It applies to pages' Markdown, not the `markdown` filter. |
|
|
34
|
+
| `dialect` | `false` | Another Markdown's ways, where they're CommonMark's otherwise, for pages written for it. `"python-markdown"` (MkDocs'): a raw HTML block runs to its closing tag, blank lines and all, and is written as it is (CommonMark's ends at the first blank line, and Markdown after it is Markdown again); a list nests at four spaces, so an item indented two is the next item of the same list; a line that ends in one space keeps it; and the HTML is Python-Markdown's: `"` as it is in text, `<hr />`, `<br />`, `<img alt="" src="" />`, a tight item's nested list right after its text, and nothing after the last tag. With `admonitions`, `tabs`, `sourceLinks` and `headingIds: "python-markdown"`, the httpx docs' pages match MkDocs' byte for byte but for highlighted code, whose tokens are Pygments'. It applies to pages' Markdown, not the `markdown` filter. |
|
|
35
|
+
| `encodeUrls` | `true` | Link and image URLs are percent-encoded, as CommonMark's reference renderer writes them (`#كتابة` as `#%D9%83...`, `café.png` as `caf%C3%A9.png`). `false` writes them as the page has them, HTML-escaped only (`&` as `&`), as kramdown (Jekyll) does, so a move compares clean; browsers go to the same place either way. A link or image hook gets the URL as written in both. |
|
|
27
36
|
| `indentedCode` | `true` | Lines indented four spaces are code. `false` makes them ordinary Markdown, for HTML indented inside Markdown; fences are still code. |
|
|
28
|
-
| `highlight` | `false` | Syntax highlighting at build time (below). `true`, or `{ css: "/assets/code.css" }` to put the stylesheet somewhere else, or `{ css: false }` to leave it out. `languages` adds languages or replaces built-in ones: `{ languages: { chordpro: code => tokens, cho: "chordpro", snack: "grammars/snack.sublime-syntax" } }` (below). |
|
|
37
|
+
| `highlight` | `false` | Syntax highlighting at build time (below). `true`, or `{ css: "/assets/code.css" }` to put the stylesheet somewhere else, or `{ css: false }` to leave it out. `languages` adds languages or replaces built-in ones: `{ languages: { chordpro: code => tokens, cho: "chordpro", snack: "grammars/snack.sublime-syntax" } }` (below). `classes` names the tokens as another highlighter does: `{ classes: "prism" }` ([below](#another-highlighters-classes)). |
|
|
29
38
|
|
|
30
39
|
**Syntax highlighting:** with `highlight: true`, fenced code is highlighted while the site builds, so pages need no highlighting script. The grammars are Sublime Text's and TextMate's (about 200 languages, from [syntect](https://github.com/trishume/syntect) and [bat](https://github.com/sharkdp/bat)), plus ssqch's own for the template languages those don't cover (`edge`, `liquid`, `hbs`, `mustache` and `ejs`: the tags, over highlighted HTML) and for ChordPro songs (`chordpro` and `cho`: directives, `[G7]` chords and comments), and each token gets one class for what it is: `hl-keyword`, `hl-string`, `hl-comment`, `hl-function`, `hl-type`, `hl-number` and so on. The build writes a stylesheet for them to `/highlight.css` (link it from your layout) with GitHub's colors, light and dark. Each color is a CSS custom property, like `--hl-keyword`, so a theme switch or your own palette only has to set those. Mark lines with braces in the fence's info string, ```` ```js {1,4-6} ````, and those lines get `class="line highlighted"`. A language without a grammar renders as plain `<pre><code class="language-x">`.
|
|
31
40
|
|
|
@@ -37,13 +46,13 @@ const trailnotes = code => code.split( /(^!.*$|@\w+)/m ).filter( Boolean ).map(
|
|
|
37
46
|
export default { markdown: { highlight: { languages: { trailnotes, trail: "trailnotes" } } } };
|
|
38
47
|
```
|
|
39
48
|
|
|
40
|
-
**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.
|
|
49
|
+
**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. `page.headings` are the page's own; for headings a layout adds around them, give `toc` the HTML instead, `toc(content)` in an outer layout (the same options), as eleventy-plugin-nesting-toc took it.
|
|
41
50
|
|
|
42
51
|
**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.
|
|
43
52
|
|
|
44
53
|
**The highlighting cache:** each build keeps the code it highlighted in `.cache/ssqch/highlight/fences.json`, beside `fetch`'s copies and the images, and the next build takes the HTML from there instead of loading the grammars, which is most of what highlighting costs a new process: the ReverentGeek blog's `ssqch build` takes 0.64 s with it and 1.0 s without (rendering, 48 ms against 390 ms). `ssqch serve` keeps the same fences in memory between rebuilds, so the file is for its first build and for `ssqch build`. A fence is kept by its language, code and marked lines, the site's `languages` (a `.sublime-syntax` file by its contents), and the highlighter's own version: a hash of what ssqch's highlighter is built from, so a release that changes highlighting starts afresh by itself. Fences a site's own function highlights aren't kept, because a function can answer differently each time, and `highlight(code, lang)` in a template uses the cache too. The file holds the fences the last build used and no others, it's written only when they change (beside its place, then moved in), and a build that fails doesn't write it. A file that's damaged or from another version of ssqch is ignored and written again, never an error, and the cache never changes a page: a build with it writes the same bytes as a build without. `leaveNoTrace` cleans the output, not `.cache`; delete the file (or `.cache/`) to highlight everything again, and restore `.cache/ssqch` in CI to keep it, as for images.
|
|
45
54
|
|
|
46
|
-
**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"
|
|
55
|
+
**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"`, which takes the same `"inline"` (or `{ inline: true }`); another option is an error naming the two.
|
|
47
56
|
|
|
48
57
|
**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:
|
|
49
58
|
|
|
@@ -92,6 +101,7 @@ Pine Cone Crunch
|
|
|
92
101
|
| `image.*` | `image.src`, `alt` and `title` | `<figure>` with a caption |
|
|
93
102
|
| `footnote-ref.*` | `footnote.number`, `label`, `id` (the note's), `refId` (this reference's) and `index` (1 for a note's first reference) | Footnote links in another generator's markup |
|
|
94
103
|
| `footnotes.*` | `footnotes`: a list of `number`, `label`, `id`, `content` (the note's HTML) and `refs` (the ids of its references) | The notes as a `<div>` each, or as sidenotes |
|
|
104
|
+
| `code.*` | `code.code` (the code span's text, which the template escapes) | Rouge's `highlighter-rouge` classes on code spans, as GitHub Pages writes them |
|
|
95
105
|
| `fence.*`, or `fence-<lang>.*` for one language | `fence.lang`, `info` (the whole line after the backticks, like `js {1,3} title="app.js"`), `code`, and `highlighted` (the highlighted HTML, with `highlight` on) | Diagrams from `mermaid` fences, titled code blocks |
|
|
96
106
|
|
|
97
107
|
```jinja
|
|
@@ -112,3 +122,51 @@ A fence hook writes the whole block, so it has to write `<pre><code>` itself: `f
|
|
|
112
122
|
</code></pre>
|
|
113
123
|
</div>
|
|
114
124
|
```
|
|
125
|
+
|
|
126
|
+
**Code spans:** a `code.*` hook writes each inline code span (`` `ssqch build` ``) from its text, `code.code`, which the template escapes as a fence hook's does (Jinja and Nunjucks do it by themselves; in Liquid, `{{ code.code | escape }}`). A site moving from GitHub Pages keeps its CSS for Rouge's markup with `<code class="language-plaintext highlighter-rouge">{{ code.code }}</code>`. Fences don't go through it; they have `fence.*`.
|
|
127
|
+
|
|
128
|
+
## Another highlighter's classes
|
|
129
|
+
|
|
130
|
+
**Another highlighter's classes:** a site that styles its code with a Prism theme, or another highlighter's CSS, can keep it: `classes`, in `highlight: { classes }`, names the tokens as that highlighter does. `classes: "prism"` gives every token Prism's names (`token keyword`, `token string`, `token class-name` for a type, `token regex`, `token attr-name` for an attribute, `token title` for a heading, `token url` for a link, and so on), puts the language on the `<pre>` as Prism's plugins do (`<pre class="language-js"><code class="language-js">`, a language with no grammar too, its code as it is), and writes a marked line (```` ```js {2} ````) as `<mark class="highlight-line highlight-line-active">`, Eleventy's syntax-highlight plugin's markup, with the other lines unwrapped. `classes: "pygments"` (or `"chroma"`, the same names) gives Pygments' short names, which MkDocs' and Hugo's themes style and Chroma (Hugo's highlighter) writes too: `k` for a keyword, `s` a string, `c` a comment, `nf` a function, `nc` a type, `m` a number, `nt` a tag, `na` an attribute, `nb` a builtin, `o` an operator, inside ssqch's `<pre class="highlight">` (the wrapper MkDocs or Hugo wrote around it, such as `<div class="highlight">`, is a fence hook's). An object names some kinds yourself and leaves the rest `hl-*`, inside ssqch's own `<pre class="highlight">`: lit.dev's CodeMirror theme is `classes: { keyword: "tok-keyword", string: "tok-string", type: "tok-typeName" }`. The kinds are the `hl-*` names without the prefix (above); another key is an error that names them, and so is a value that isn't class names. The tokens are still ssqch's (its grammars cut the code), so a theme colors them the way it colors that highlighter's, not always the same characters. `/highlight.css` uses the same names (`.token.keyword`), so it still colors the code; with a theme of your own, leave it out: `highlight: { classes: "prism", css: false }`. A fence hook's `fence.highlighted` and `highlight(code, lang)` have the same names.
|
|
131
|
+
|
|
132
|
+
```js
|
|
133
|
+
export default defineConfig({
|
|
134
|
+
markdown: { highlight: { classes: "prism", css: false } },
|
|
135
|
+
});
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## markdown-it's habits
|
|
139
|
+
|
|
140
|
+
**markdown-it's habits:** a site moving from a generator that used markdown-it can keep three of its habits without keeping markdown-it, and each one writes the bytes markdown-it 13 writes:
|
|
141
|
+
|
|
142
|
+
- **`breaks: true`:** a single newline inside a paragraph or a list item is a line break, `<br>` and the newline, as markdown-it's `breaks` option and GitHub's comments have it. A site written by many people often depends on it without knowing: 374 of a11yproject.com's line breaks did. Without it, a newline is a space, as CommonMark says.
|
|
143
|
+
- **`autolinks: "fuzzy"`:** besides `https://` and `www.` URLs, bare domains (`example.com`, `docs.example.org/a?b=1`) link to `http://` and bare email addresses (`ranger@example.com`) to `mailto:`, as markdown-it's `linkify` does with its defaults. A domain counts when its last part is one of linkify-it's top-level domains (`com`, `org`, `net`, `edu`, `gov`, `info`, `biz`, `name`, `pro`, `shop` and a few others, and every two-letter country code), so `node.js` stays text, but `README.md` (Moldova's `md`) becomes a link, as it does in markdown-it.
|
|
144
|
+
- **`figures: true`:** an image alone in a paragraph, or an image inside a link alone in one, is a `<figure>`: `` is `<figure><img src="/cone.jpg" alt=""><figcaption>A pine cone</figcaption></figure>`. The alt text moves into the `<figcaption>` (with its Markdown, so `*pine*` is `<em>pine</em>`) and the image's `alt` is left empty, so a screen reader reads the caption once; an image with no alt text gets no caption. An image beside other text stays in its paragraph. It's markdown-it-implicit-figures with `figcaption: true`, which 74 of v8.dev's pages used. An image render hook (`hooks/image`) still writes the image, with `image.alt` empty.
|
|
145
|
+
|
|
146
|
+
```js
|
|
147
|
+
export default defineConfig({
|
|
148
|
+
markdown: { breaks: true, autolinks: "fuzzy", figures: true },
|
|
149
|
+
});
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## Your own Markdown library
|
|
153
|
+
|
|
154
|
+
**Your own Markdown:** to keep a Markdown library you already use (markdown-it and its plugins, say, while a move from another generator is checked byte for byte), give it to `engines` as `md`. Every `.md` file, and every `md` in a `render` chain, then renders with it instead of ssqch's Markdown, in one line of the config rather than `render` in every folder's data. The `markdownEngine` still runs first (Jinja, unless you change it), so a post's tags are rendered before your library sees the text, and `.njk`, `.jinja` and `.html` pages beside it don't change. A markdown-it instance works as it is: its `render(source, env)` gets the page's data as `env`, as Eleventy's `setLibrary("md", ...)` gave it. So does a function, `(source, data, context) => html`, or any object with a `render` method, and `context.kind` says whether it's rendering a page's body (`"body"`), a `.md` layout (`"layout"`) or a `.md` render hook (`"hook"`):
|
|
155
|
+
|
|
156
|
+
```js
|
|
157
|
+
import markdownIt from "markdown-it";
|
|
158
|
+
import markdownItAnchor from "markdown-it-anchor";
|
|
159
|
+
import { defineConfig } from "ssqch";
|
|
160
|
+
|
|
161
|
+
const md = markdownIt({ html: true, breaks: true }).use(markdownItAnchor);
|
|
162
|
+
|
|
163
|
+
export default defineConfig({
|
|
164
|
+
markdownEngine: "liquid",
|
|
165
|
+
engines: { md },
|
|
166
|
+
filters: { markdown: (text) => md.render(String(text ?? "")) },
|
|
167
|
+
});
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
With your own Markdown, the `markdown` options, containers and render hooks no longer apply to pages: they're how ssqch's Markdown renders, and your library has its own plugins for them. Fences are your library's to highlight; `highlight: true` still writes `/highlight.css` and gives templates `highlight(code, lang)`. `page.headings` and `toc()` still work, because they read the HTML. The `markdown` filter and `markdown()` from `ssqch` stay ssqch's Markdown, so a site that wants its library there too defines a `markdown` filter of its own, as above, which takes the built-in one's place (and `markdownify`'s, Jekyll's name for it). `edge`, `html` and `txt` can't be replaced: `engines: { edge }` is an error.
|
|
171
|
+
|
|
172
|
+
**Caching an engine's pages:** a Markdown library written in JavaScript can be most of a rebuild in `ssqch serve`, which renders every page again when one changes. With `cache: true`, an engine keeps the page bodies it renders by their source, and a page whose text (after the `markdownEngine` ran over it) is the same as a page's in this build or the build before isn't rendered again: `engines: { md: { render: (source) => md.render(source), cache: true } }`. Layouts and render hooks render each time, because the same text prints something else on every page. It's for an engine whose output depends on the source alone: one that reads the page's data (a markdown-it plugin that reads `env.page.url`) would give a page another page's HTML. The cache is in memory and holds the last two builds' pages, no more: `ssqch build` saves only on pages with the same text, and `ssqch serve` keeps it from one rebuild to the next, until the config changes. `cache` works on any engine in `engines`, and anything but `true` or `false` is an error. v8.dev's rebuilds went from 1.8 s to 0.28 s with a cache like it in its config.
|
|
@@ -1,12 +1,29 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Multilingual sites: translations, i18n and hreflang"
|
|
3
3
|
navTitle: "Multilingual sites"
|
|
4
|
-
description: "ssqch has no built-in i18n yet
|
|
4
|
+
description: "ssqch has no built-in i18n yet."
|
|
5
5
|
---
|
|
6
|
-
ssqch has no built-in i18n yet
|
|
6
|
+
ssqch has no built-in i18n yet. What two real sites (one from Jekyll, one from Astro) did instead, with what ssqch has:
|
|
7
7
|
|
|
8
8
|
- **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`).
|
|
9
|
-
- **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.
|
|
9
|
+
- **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. A loop over every page on every page (a language menu built with `where`) is the slow way on a big site; a filter that groups them once is fast, and the same in every template language:
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
// ssqch.config.js: each page's translations, by its key and language, worked out once a build.
|
|
13
|
+
const groups = new WeakMap();
|
|
14
|
+
const byKey = (pages) => {
|
|
15
|
+
let map = groups.get(pages);
|
|
16
|
+
if (!map) {
|
|
17
|
+
map = new Map();
|
|
18
|
+
for (const p of pages) if (p.data.key) map.set(p.data.key, { ...map.get(p.data.key), [p.data.lang]: p });
|
|
19
|
+
groups.set(pages, map);
|
|
20
|
+
}
|
|
21
|
+
return map;
|
|
22
|
+
};
|
|
23
|
+
export default { filters: { translation: (pages, key, lang) => byKey(pages).get(key)?.[lang] } };
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`{% assign fr = collections.docs | translation: key, "fr" %}` is the French page, or nothing.
|
|
10
27
|
- **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.
|
|
11
28
|
- **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.
|
|
12
29
|
- **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.
|
package/bundled/docs/nav.yml
CHANGED
package/bundled/docs/netlify.md
CHANGED
|
@@ -18,11 +18,11 @@ Netlify can build the site itself, with no deploy token to manage. With `ssqch`
|
|
|
18
18
|
paths = [".cache/ssqch"]
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
- **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.
|
|
21
|
+
- **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.11.0`) and bump it when you're ready.
|
|
22
22
|
- **`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.
|
|
23
23
|
- **[`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`.
|
|
24
24
|
|
|
25
|
-
A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.
|
|
25
|
+
A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.11.0"` under `[build.environment]` to pin it (and `NODE_VERSION` there as well):
|
|
26
26
|
|
|
27
27
|
```toml
|
|
28
28
|
[build]
|
package/bundled/docs/plugins.md
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
title: "Built-in plugins"
|
|
3
3
|
---
|
|
4
4
|
- **`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](deploying.md#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.
|
|
5
|
-
- **`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
|
|
6
|
-
- **`ssqch/rss`:** `rssPlugin()` adds the filters `getNewestCollectionItemDate`, `dateToRfc3339`, `dateToRfc822`, `absoluteUrl`, `htmlToAbsoluteUrls` and `feedHtml`. They're also named exports, for your own code. Under a [`base`](deploying.md#serving-a-site-under-a-path), the filters put it in front of a URL from the site's root that doesn't have it yet (`absoluteUrl(post.url, site.url)` is `https://example.com/repo/posts/pine/`), and so do `htmlToAbsoluteUrls` and `feedHtml` for every URL in the HTML; the named exports resolve a URL as `new URL(url, address)` does, so call `withBase` first there. `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`.
|
|
5
|
+
- **`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), and, off by default as html-minifier's are, `css` (each page's `<style>` elements compressed, as `minifyCss` does), `xml` (the whitespace between tags out of `.xml`, `.rss` and `.atom` files, such as feeds and sitemaps, but not inside text, CDATA or comments) and `json` (`.json` and `.webmanifest` files without spaces). `minifyCss(css)` compresses CSS text with ssqch's Sass, as a compressed stylesheet is written (`.a { color: #ffffff; }` becomes `.a{color:#fff}`), for CSS a template inlines: `filters: { minifyCss }`. It reads the text as plain CSS, so Sass's own syntax, and CSS it can't read (native CSS nesting among it), is an error naming the line; with `css: true`, such a `<style>` stays as it is and the build warns once for the page. Each text is compressed once and kept, so a stylesheet inlined in every page costs one compression. `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>`, whose numbers it writes as html-minifier-terser does (`initial-scale=1.0` becomes `initial-scale=1`). 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 with `collapseWhitespace`, `removeComments`, `useShortDoctype` and `collapseBooleanAttributes`, in two ways: it keeps each attribute's quotes as written (`class='a'`, `href=x`), where html-minifier-terser writes every value in double quotes, and it leaves an unclosed element as it is (`<p>one<p>two`), where html-minifier-terser closes it. It has none of html-minifier-terser's other options (`removeOptionalTags`, `removeAttributeQuotes`, `sortAttributes`, `decodeEntities`, `minifyCSS`, `minifyJS`): a site that needs those bytes runs that package as a transform instead, and `ssqch diff` (not `--exact`) reads the two minifiers' output as the same where only quotes differ.
|
|
6
|
+
- **`ssqch/rss`:** `rssPlugin()` adds the filters `getNewestCollectionItemDate`, `dateToRfc3339`, `dateToRfc822`, `rssDate` and `rssLastUpdatedDate` (the Eleventy RSS plugin's first names for `dateToRfc3339` and for the newest item's date in that form), `absoluteUrl`, `htmlToAbsoluteUrls` and `feedHtml`. They're also named exports, for your own code. Under a [`base`](deploying.md#serving-a-site-under-a-path), the filters put it in front of a URL from the site's root that doesn't have it yet (`absoluteUrl(post.url, site.url)` is `https://example.com/repo/posts/pine/`), and so do `htmlToAbsoluteUrls` and `feedHtml` for every URL in the HTML; the named exports resolve a URL as `new URL(url, address)` does, so call `withBase` first there. `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`.
|
|
7
7
|
- **`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`).
|
|
8
8
|
- **`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`).
|
|
9
|
-
- **`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 `
|
|
10
|
-
- **`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` (
|
|
9
|
+
- **`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), `loadPaths`, and `charset`: `false` leaves out what grass (as Dart Sass) starts CSS with when it has a character outside ASCII, a byte order mark when compressed and `@charset "UTF-8";` when expanded, so the file starts as a Jekyll site's did (jekyll-sass-converter takes the mark out). 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.)
|
|
10
|
+
- **`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` (the site's address; without one, or with `""` as a Jekyll site's `url` often is, each `<loc>` is a path from the root, as jekyll-sitemap writes it, and every build warns, since search engines read only whole addresses), `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.
|
|
11
11
|
- **`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](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/islands/) has three small elements.
|
|
12
12
|
|
|
13
13
|
- **`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()`](#) 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`.
|
package/bundled/docs/seo.md
CHANGED
|
@@ -16,4 +16,42 @@ ssqch writes no `<head>` tags of its own, so a site's title, description, canoni
|
|
|
16
16
|
<meta name="twitter:card" content="summary_large_image">
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
**From jekyll-seo-tag:** Jekyll's `{% seo %}` becomes an include, `{% include seo.liquid %}` in the layout. This one writes what jekyll-seo-tag 2.8 writes, in its order and its bytes, for a site whose `_config.yml` is read as `site` (`data: { site: readData("_config.yml") }`) and whose pages have `title`, `description` and `image` in front matter. As jekyll-seo-tag does, the title and description go through `markdownify` for their quotes and dashes; the canonical link and `og:url` need `site.url`; a dated page (front matter `date`, or a post's or collection's `tags`) is an `article` with its `published_time` and a `BlogPosting`; the home page (`/` or `/about/`) is a `WebSite` with a `name`; `site.twitter.username`, `site.facebook.publisher` and `site.logo` add their tags; and the generator is ssqch's (`ssqch scout`'s draft for a Jekyll site writes Jekyll's version there instead, from `Gemfile.lock`, so the first build matches). Add the tags for options this leaves out (authors, `fb:app_id`, webmaster verifications):
|
|
22
|
+
|
|
23
|
+
```liquid
|
|
24
|
+
{%- comment -%} _includes/seo.liquid {%- endcomment -%}
|
|
25
|
+
{%- assign site_title = site.title | default: site.name | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
26
|
+
{%- assign page_title = title | markdownify | strip_html | normalize_whitespace | escape_once | default: site_title -%}
|
|
27
|
+
{%- assign about = description | default: site.description | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
28
|
+
{%- if page_title != site_title -%}{%- assign full_title = page_title | append: " | " | append: site_title -%}{%- elsif site.description -%}{%- assign full_title = site_title | append: " | " | append: about -%}{%- else -%}{%- assign full_title = site_title -%}{%- endif -%}
|
|
29
|
+
{%- assign canonical = site.url | append: page.url -%}
|
|
30
|
+
{%- if image -%}{%- assign image_url = site.url | append: image -%}{%- endif -%}
|
|
31
|
+
{%- if date or tags -%}{%- assign published = page.date | date_to_xmlschema -%}{%- endif -%}
|
|
32
|
+
{%- if page.url == "/" or page.url == "/about/" -%}{%- assign ld_type = "WebSite" -%}{%- elsif published -%}{%- assign ld_type = "BlogPosting" -%}{%- else -%}{%- assign ld_type = "WebPage" -%}{%- endif -%}
|
|
33
|
+
<!-- Begin Jekyll SEO tag v2.8.0 -->
|
|
34
|
+
<title>{{ full_title }}</title>
|
|
35
|
+
<meta name="generator" content="{{ ssqch.generator }}" />
|
|
36
|
+
<meta property="og:title" content="{{ page_title }}" />
|
|
37
|
+
<meta property="og:locale" content="{{ lang | default: site.lang | default: "en_US" | replace: "-", "_" }}" />
|
|
38
|
+
{% if about %}<meta name="description" content="{{ about }}" />
|
|
39
|
+
<meta property="og:description" content="{{ about }}" />
|
|
40
|
+
{% endif %}{% if site.url %}<link rel="canonical" href="{{ canonical }}" />
|
|
41
|
+
<meta property="og:url" content="{{ canonical }}" />
|
|
42
|
+
{% endif %}<meta property="og:site_name" content="{{ site_title }}" />
|
|
43
|
+
{% if image_url %}<meta property="og:image" content="{{ image_url }}" />
|
|
44
|
+
{% endif %}{% if published %}<meta property="og:type" content="article" />
|
|
45
|
+
<meta property="article:published_time" content="{{ published }}" />
|
|
46
|
+
{% else %}<meta property="og:type" content="website" />
|
|
47
|
+
{% endif %}<meta name="twitter:card" content="{% if image_url %}summary_large_image{% else %}summary{% endif %}" />
|
|
48
|
+
{% if image_url %}<meta property="twitter:image" content="{{ image_url }}" />
|
|
49
|
+
{% endif %}<meta property="twitter:title" content="{{ page_title }}" />
|
|
50
|
+
{% if site.twitter.username %}<meta name="twitter:site" content="@{{ site.twitter.username | remove: "@" }}" />
|
|
51
|
+
{% endif %}{% if site.facebook.publisher %}<meta property="article:publisher" content="{{ site.facebook.publisher }}" />
|
|
52
|
+
{% endif %}<script type="application/ld+json">
|
|
53
|
+
{"@context":"https://schema.org","@type":{{ ld_type | jsonify }}{% if published %},"dateModified":{{ published | jsonify }},"datePublished":{{ published | jsonify }}{% endif %}{% if about %},"description":{{ about | jsonify }}{% endif %},"headline":{{ page_title | jsonify }}{% if image_url %},"image":{{ image_url | jsonify }}{% endif %}{% if ld_type == "BlogPosting" %},"mainEntityOfPage":{"@type":"WebPage","@id":{{ canonical | jsonify }}}{% endif %}{% if ld_type == "WebSite" %},"name":{{ site_title | jsonify }}{% endif %}{% if site.logo %},"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":{{ site.url | append: site.logo | jsonify }}}}{% endif %},"url":{{ canonical | jsonify }}}</script>
|
|
54
|
+
<!-- End Jekyll SEO tag -->
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
A function can write all of it instead, when the template passes it what it needs: functions are Liquid tags too, so `{% seo page, title, description %}` calls `seo(page, title, description)` (a function doesn't see the page unless it's given). opensource.guide's port did that, writing jekyll-seo-tag's bytes, JSON-LD included, in 100 lines.
|
|
@@ -19,16 +19,18 @@ title: Squatch Snacks
|
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
- **Data:** front matter, the cascade, `page`, `collections` and `content` in layouts, the same as in the other engines. Undefined values, and properties of undefined values, print nothing (`strict: true` makes printing one an error).
|
|
22
|
-
- **Escaping:** output is HTML-escaped, as in Nunjucks and Jinja; use `| safe` to opt out. A layout's `content` is already marked safe, so `{{ content }}` works.
|
|
22
|
+
- **Escaping:** output is HTML-escaped, as in Nunjucks and Jinja; use `| safe` to opt out. A layout's `content` is already marked safe, so `{{ content }}` works, and so is what a config filter returns with `safe(html)`. `jinja: { autoescape: false }` prints `.jinja` values as they are, as MkDocs' Jinja does (`mkdocsTemplates` does that too); `| e` still escapes.
|
|
23
23
|
- **Filters and functions:** Jinja's built-in filters, plus Nunjucks' own (`dump`, `truncate`, `forceescape`, `nl2br`, `urlize`, `wordcount`, `center`, `random`), and `pluralize`, `filesizeformat`, `striptags`, `cycler()` and `joiner()`. Your config `filters` work both ways: `{{ title | shout }}` and `{{ shout(title) }}`. On a page whose data has a field with a function's name, the call finds the field first, so use the filter form there. An async function is awaited.
|
|
24
24
|
- **JavaScript properties and methods:** Nunjucks templates use JavaScript's, and they work in `.njk` and `.jinja` files alike. `.length` counts a list's items or a string's characters (`{{ collections.posts.length }}`, the same as `| length`); `loop.length` and an object's own `length` key keep their meaning, and on any other object `.length` is undefined, as in JavaScript. Strings and lists also have `startsWith()`, `endsWith()`, `includes()`, `indexOf()`, `toLowerCase()`, `toUpperCase()` and `trim()`, beside Python's (`startswith()`, `lower()`).
|
|
25
25
|
- **Dates:** `{{ page.date | dateformat }}` prints `Mar 14 2026`. `dateformat`, `timeformat` and `datetimeformat` take `"short"`, `"medium"`, `"long"`, `"full"`, `"iso"`, `"unix"`, or a `strftime` pattern (`dateformat("%B %-d, %Y")`), in UTC. Dates also have Python's `strftime()` and `isoformat()` and JavaScript's `toISOString()` and friends, and `now()` is the build's time.
|
|
26
26
|
- **Your own tags:** a config filter is a tag too, in `.njk` and `.jinja` files alike. `{% image "/a.png", "A pine" %}` prints what `image("/a.png", "A pine")` returns, without escaping it. With a closing tag, the function gets what's between them first: `{% callout "tip" %}...{% endcallout %}` calls `callout(content, "tip")`. That covers the built-in filters as well, so `{% markdown %}...{% endmarkdown %}` renders Markdown inside a template.
|
|
27
|
-
- **Includes and inheritance:** `{% include %}`, `{% extends %}` with `{% block %}`, `{% import %}` and `{% from ... import %}` read from `_includes`. Front-matter `layout` works too.
|
|
27
|
+
- **Includes and inheritance:** `{% include %}`, `{% extends %}` with `{% block %}`, `{% import %}` and `{% from ... import %}` read from `_includes`. Front-matter `layout` works too. Jinja's `self` renders a block by name anywhere in the template, as the page's templates have it (the child's over the parent's): `<title>{% block title %}Camp{% endblock %}</title> ... <h1>{{ self.title() }}</h1>`; a block nothing defines is undefined, and a variable named `self` is that variable.
|
|
28
28
|
- **Nunjucks syntax:** `{% elseif %}`, `===`, `{ title: x }`, `{% for key, value in object %}` and Nunjucks' own filters work in `.jinja` files as in `.njk`. Not supported: extensions that parse a tag's arguments themselves.
|
|
29
|
-
- **Two flavors:** `.njk` prints values as Nunjucks does, as a site from Eleventy expects (`true`, a list as `a,b`, an object as `[object Object]`, `none` as nothing, and `dump` as compact JSON, escaped unless it's followed by `| safe`; `dump(2)` indents it). `.jinja` and `.j2` print as Jinja does (`True`, `['a', 'b']`, a spaced, unescaped `dump`). A date prints as ISO 8601 in both, whatever the machine's time zone.
|
|
29
|
+
- **Two flavors:** `.njk` prints values as Nunjucks does, as a site from Eleventy expects (`true`, a list as `a,b`, an object as `[object Object]`, `none` as nothing, and `dump` as compact JSON, escaped unless it's followed by `| safe`; `dump(2)` indents it). `.jinja` and `.j2` print as Jinja does (`True`, `['a', 'b']`, a spaced, unescaped `dump`, and `tojson` with a dict's keys sorted, as Jinja's `json.dumps(sort_keys=True)` writes them). A date prints as ISO 8601 in both, whatever the machine's time zone.
|
|
30
|
+
- **The final newline:** a `.jinja` or `.j2` template (a page, a layout, an include, an import) loses one newline at its end, as Jinja's do (`keep_trailing_newline=False`), so `{% include "nav.jinja" %}` adds no blank line after the nav, and a page ends where its last tag does. `.njk` keeps it, as Nunjucks does. Templates written for Jinja (a MkDocs theme) print the same whitespace as they did there.
|
|
31
|
+
- **Strings:** `"\u003ch1"`, `"\x3c"` and `"\U0001F332"` are the characters they name in both flavors, as in Python and JavaScript, and `\n`, `\t`, `\r`, `\\`, `\"` and `\'` work as usual. `in` searches a safe string's text (`{% if "<h1" not in page.content %}`), as Jinja searches its `Markup`.
|
|
30
32
|
- **Where Nunjucks isn't Jinja:** a variable set inside a loop or an `if` keeps its value after it (`{% set total = 0 %}{% for x in xs %}{% set total = total + x %}{% endfor %}` ends with the sum; `namespace()` still works), and a variable set in an include stays in the include, so set it in the page, or have the include print it. `{% break %}`, `{% continue %}`, `{% with %}`, `{% autoescape %}`, `{% for x in xs if x.ok %}` and `recursive` loops are errors that name their line and say what to write instead (an `{% if %}` inside the loop, `xs | selectattr("ok")`, a macro that calls itself). `loop.previtem`, `loop.nextitem` and `loop.depth` are undefined. Numbers have no separate float type (`{{ 4 / 2 }}` prints `2`), and `+` and `*` are JavaScript's: join lists with `xs | chain(ys)`.
|
|
31
|
-
- **Errors** name the template and line: `broken.njk:2: syntax error`.
|
|
33
|
+
- **Errors** name the template and line: `broken.njk:2: syntax error`. An error in a layout (a template that another `{% extends %}`) or after an `{% include %}` names that template's own line, not the page's `{% block %}` or the include's.
|
|
32
34
|
|
|
33
35
|
|
|
34
36
|
## Edge
|