ssqch 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (138) hide show
  1. package/bundled/completions/bash +67 -9
  2. package/bundled/completions/elvish +24 -4
  3. package/bundled/completions/fish +37 -25
  4. package/bundled/completions/powershell +26 -4
  5. package/bundled/completions/zsh +45 -10
  6. package/bundled/docs/agents.md +2 -2
  7. package/bundled/docs/build-summary.md +1 -1
  8. package/bundled/docs/comparing-builds.md +7 -4
  9. package/bundled/docs/configuring.md +7 -12
  10. package/bundled/docs/deploying.md +1 -1
  11. package/bundled/docs/field-guide.md +4 -4
  12. package/bundled/docs/github-pages.md +2 -1
  13. package/bundled/docs/index.md +1 -1
  14. package/bundled/docs/install.md +1 -1
  15. package/bundled/docs/known-gaps.md +1 -1
  16. package/bundled/docs/markdown.md +11 -13
  17. package/bundled/docs/nav.yml +6 -1
  18. package/bundled/docs/netlify.md +4 -2
  19. package/bundled/docs/patrol.md +48 -0
  20. package/bundled/docs/plugins.md +6 -4
  21. package/bundled/docs/robots.md +72 -0
  22. package/bundled/docs/seo.md +2 -38
  23. package/bundled/docs/serving-markdown.md +142 -0
  24. package/bundled/docs/template-languages.md +2 -1
  25. package/bundled/docs/templates.md +2 -1
  26. package/bundled/docs/trailheads/from-component-frameworks.md +9 -10
  27. package/bundled/docs/trailheads/from-hugo.md +5 -3
  28. package/bundled/docs/trailheads/from-jekyll.md +54 -13
  29. package/bundled/docs/trailheads/from-mkdocs.md +15 -12
  30. package/bundled/docs/trailheads/from-vitepress.md +142 -0
  31. package/bundled/docs/trailheads.md +5 -5
  32. package/bundled/docs/where-values-come-from.md +5 -5
  33. package/bundled/docs/writing-plugins.md +69 -0
  34. package/bundled/ssqch.d.ts +150 -34
  35. package/bundled/starter/engines/index.edge +1 -0
  36. package/bundled/starter/engines/index.ejs +1 -0
  37. package/bundled/starter/engines/index.hbs +1 -0
  38. package/bundled/starter/engines/index.liquid +1 -0
  39. package/bundled/starter/engines/layout.edge +7 -0
  40. package/bundled/starter/engines/layout.ejs +4 -0
  41. package/bundled/starter/engines/layout.hbs +4 -0
  42. package/bundled/starter/engines/layout.liquid +4 -0
  43. package/bundled/starter/src/_data/site.json +1 -0
  44. package/bundled/starter/src/_includes/layout.jinja +4 -0
  45. package/bundled/starter/src/index.jinja +1 -0
  46. package/bundled/starter/ssqch.config.js +14 -1
  47. package/bundled/starter-docs/engines/edge/base.edge +7 -0
  48. package/bundled/starter-docs/engines/edge/doc.edge +4 -0
  49. package/bundled/starter-docs/engines/ejs/base.ejs +4 -0
  50. package/bundled/starter-docs/engines/ejs/doc.ejs +4 -0
  51. package/bundled/starter-docs/engines/hbs/base.hbs +4 -0
  52. package/bundled/starter-docs/engines/hbs/doc.hbs +3 -0
  53. package/bundled/starter-docs/engines/liquid/base.liquid +4 -0
  54. package/bundled/starter-docs/engines/liquid/doc.liquid +4 -0
  55. package/bundled/starter-docs/src/_data/site.json +1 -0
  56. package/bundled/starter-docs/src/_includes/base.jinja +4 -0
  57. package/bundled/starter-docs/src/_includes/doc.jinja +4 -0
  58. package/bundled/starter-docs/src/assets/docs.css +4 -0
  59. package/bundled/starter-docs/src/assets/docs.js +17 -0
  60. package/bundled/starter-docs/ssqch.config.js +14 -1
  61. package/lib/assets.js +13 -11
  62. package/lib/chunk-25WERNDD.js +112 -0
  63. package/lib/{chunk-H5K2ZE7B.js → chunk-2BJFGKOE.js} +13 -5
  64. package/lib/chunk-2FKYWYAB.js +268 -0
  65. package/lib/{chunk-LJOURBYT.js → chunk-3ZTRIO6O.js} +21 -19
  66. package/lib/{chunk-IOBC665M.js → chunk-4AZFCSGJ.js} +5 -3
  67. package/lib/{chunk-HWW5NCVJ.js → chunk-4Q6WMTER.js} +1 -1
  68. package/lib/{chunk-V2FSMOFX.js → chunk-55WXDGO4.js} +3 -3
  69. package/lib/{chunk-ZR3JYLFB.js → chunk-6FY77I4M.js} +331 -58
  70. package/lib/{chunk-JC54PHIT.js → chunk-6OUCRDYI.js} +514 -141
  71. package/lib/{chunk-ERAIEV3O.js → chunk-6U5VIQVY.js} +9 -7
  72. package/lib/{chunk-Z5OP43HU.js → chunk-7U5GWTEH.js} +455 -94
  73. package/lib/{chunk-CMJ7X5WW.js → chunk-AIJNG6MJ.js} +3 -2
  74. package/lib/{chunk-3K237XAX.js → chunk-C2Q7JKFI.js} +12 -10
  75. package/lib/{chunk-GS5B3CBW.js → chunk-DDV6JEC2.js} +1 -1
  76. package/lib/{chunk-A75EVUJX.js → chunk-DFJFHULZ.js} +47 -20
  77. package/lib/{chunk-KZZS4W2V.js → chunk-ENWDM2RW.js} +45 -42
  78. package/lib/{chunk-I3HYKEEW.js → chunk-ER72RPD6.js} +3 -3
  79. package/lib/chunk-F3JPNFCZ.js +23 -0
  80. package/lib/{chunk-B5E27PLU.js → chunk-FENJHLNM.js} +6 -3
  81. package/lib/{chunk-UU43WIZG.js → chunk-FJML7INB.js} +4 -2
  82. package/lib/{chunk-KCF2Z6N7.js → chunk-FQZDUDFK.js} +5 -3
  83. package/lib/{chunk-GJNIQAIH.js → chunk-GSNRAGKQ.js} +13 -6
  84. package/lib/{chunk-443ZQLVX.js → chunk-GU7BBYWB.js} +5 -4
  85. package/lib/{chunk-X2GAVYV2.js → chunk-HDKU6LRI.js} +110 -748
  86. package/lib/chunk-J3C2LEW7.js +121 -0
  87. package/lib/{chunk-XS4EJSEK.js → chunk-K5WZ2VYK.js} +7 -5
  88. package/lib/{chunk-3HZZY3Y7.js → chunk-OOKBXQAY.js} +7 -6
  89. package/lib/chunk-P2WS4RM4.js +707 -0
  90. package/lib/{chunk-RBNPBTDP.js → chunk-SNQOHNXE.js} +1 -1
  91. package/lib/{chunk-HFSWUTXX.js → chunk-SPIFZBIW.js} +1 -1
  92. package/lib/{chunk-QLUTNR37.js → chunk-T5IUI7W7.js} +12 -11
  93. package/lib/{chunk-ZINLHOX4.js → chunk-TGSVSG2G.js} +3 -2
  94. package/lib/{chunk-2L3HR67O.js → chunk-U2KEMVXO.js} +24 -16
  95. package/lib/{chunk-RYIWYWRQ.js → chunk-UHRBPZ4A.js} +7 -5
  96. package/lib/{chunk-2QTJTEBV.js → chunk-ULCT3PAV.js} +1 -1
  97. package/lib/{chunk-FCM3NYFR.js → chunk-UZNUS7RP.js} +12 -9
  98. package/lib/{chunk-GLJQ4C76.js → chunk-V3G2QGL3.js} +13 -106
  99. package/lib/{chunk-Z44IAMNG.js → chunk-VILOEVK7.js} +60 -28
  100. package/lib/chunk-VJWQSYEG.js +119 -0
  101. package/lib/{chunk-5ELAUHRL.js → chunk-WGAIE3DD.js} +23 -19
  102. package/lib/{chunk-OQGXZYZS.js → chunk-WUCRAV36.js} +13 -7
  103. package/lib/{chunk-RZYAIX2R.js → chunk-XYAWJTHM.js} +11 -10
  104. package/lib/{chunk-OSBEH67S.js → chunk-YA23NDMW.js} +5 -3
  105. package/lib/{chunk-AIMEXBTK.js → chunk-YNJNMQWU.js} +37 -142
  106. package/lib/{chunk-QJ5ZFTML.js → chunk-ZMG25MXF.js} +20 -18
  107. package/lib/cli.js +72 -35
  108. package/lib/elements.js +13 -11
  109. package/lib/from-hugo.js +36 -0
  110. package/lib/from-jekyll.js +41 -0
  111. package/lib/from-mkdocs.js +49 -0
  112. package/lib/from-vitepress.js +49 -0
  113. package/lib/image.js +12 -11
  114. package/lib/links.js +13 -11
  115. package/lib/llms.js +613 -0
  116. package/lib/minify.js +14 -12
  117. package/lib/redirects.js +13 -11
  118. package/lib/robots.js +87 -0
  119. package/lib/rss.js +24 -13
  120. package/lib/sass.js +12 -11
  121. package/lib/sitemap.js +23 -18
  122. package/lib/ssqch.js +6 -5
  123. package/lib/vue.js +400 -0
  124. package/package.json +29 -1
  125. package/types/from-hugo.d.ts +5 -0
  126. package/types/from-jekyll.d.ts +11 -0
  127. package/types/from-mkdocs.d.ts +11 -0
  128. package/types/from-vitepress.d.ts +5 -0
  129. package/types/index.d.ts +51 -31
  130. package/types/llms.d.ts +27 -0
  131. package/types/robots.d.ts +13 -0
  132. package/types/sass.d.ts +1 -1
  133. package/types/sitemap.d.ts +2 -2
  134. package/types/vue.d.ts +17 -0
  135. package/wasm/markdown.wasm +0 -0
  136. package/lib/chunk-RVXGUMFI.js +0 -21
  137. /package/lib/{chunk-ZR3JYLFB.js.LEGAL.txt → chunk-6FY77I4M.js.LEGAL.txt} +0 -0
  138. /package/lib/{chunk-AIMEXBTK.js.LEGAL.txt → chunk-YNJNMQWU.js.LEGAL.txt} +0 -0
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Comparing two builds"
2
+ title: "Has the stump moved? Comparing two builds"
3
3
  description: "A build that succeeds isn't proof that an upgrade, a refactor or a migration left the site alone."
4
4
  ---
5
5
  <img align="right" src="../../../docs/assets/stickers/footprint.svg" alt="" width="96">
@@ -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, 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).
18
+ Ignoring asset fingerprints, image ids, integrity hashes, the generator's version, Vue's and Astro's scope ids and fragment markers, whitespace between tags, and how tags are written where browsers read them the same (attribute order, quotes, entities, percent-encoding in URLs, `<br/>`) (--exact compares bytes).
19
19
 
20
20
  Added (1)
21
21
  + /trails/cedar/
@@ -39,7 +39,7 @@ If a folder held an earlier build, its leftover files are among the added and re
39
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.
40
40
  ```
41
41
 
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.
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; or Vite's and Rollup's eight base64url characters, `style.Bfpn8qS8.css` and `index-D_xVD091.js`) is matched with its counterpart and compared by content, `integrity` hashes, the generator's version, Vue's scoped-style attributes (`data-v-ba3e0d0a`) and server-rendering markers (`<!--[-->`, `<!--]-->`, `<!---->`) and Astro's `data-astro-cid-*` 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.
43
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`.
44
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.
45
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.
@@ -51,8 +51,11 @@ Changes found: 3 pages and 1 other file (2 changed, 1 added, 1 removed); 148 pag
51
51
 
52
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.
53
53
 
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`).
54
+ **Expected in a move:** a group whose change every move from a component framework has is named under it: the old generator's client app (VitePress's, Astro's islands, Next.js's, Gatsby's scripts and page data), which ssqch doesn't write since its pages are HTML, and Shiki's inline colors where ssqch's highlighter writes classes. They're not mistakes in the port; `--format json` gives such a group `known`, what it is.
55
+
56
+ **Article text:** `ssqch diff ref dist --text` says how much of each page's article text is the same in the two builds, word by word: the text in `<main>` (or else `<article>`, or `<body>`), without its scripts, styles and comments, compared with the same edit script as the rest of `ssqch diff`. It's the number for a move that can't be byte for byte, from a framework whose client app is in every page or whose highlighter colors code its own way: `Identical: 99 of 109; at least 99%: 106; at least 95%: 109`, `All the words together: 99.9% of 125,249 match` (vuejs.org's move from VitePress), then the least alike pages first with their percentages (`--lines` says how many; `0` for all), the pages the second build doesn't have, and the ones with no text. `--only`, `--exclude` and `--ignore` work as above. It exits with 0 when the text matches on every page and 1 when it doesn't; `--format json` has `summary` (`pages`, `identical`, `atLeast99`, `atLeast95`, `words` and `match`, a share from 0 to 1) and `pages` (each one's `url`, the words `before` and `after`, `null` for a page the second build doesn't have, and its `match`).
55
57
 
58
+ **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`).
56
59
 
57
60
  ## Reference builds
58
61
 
@@ -52,34 +52,31 @@ The default export is the config: an object, or a function (sync or async) that
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
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
- | `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() }`. |
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() }`. It's the bottom of the cascade, so a key every page reads works there too: `data: { layout: "base.jinja" }` gives every page a layout, and `data: { permalink: "{{ page.filePathStem }}.html" }` every page a URL (a page's own front matter, or a folder's data, wins). |
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
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. |
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. It keeps data files out too: a file beside the templates is data by its name (`api/api.data.ts` is the data for `api/`, `intro.json` for `intro.md`), so another generator's file named that way (VitePress's data loaders) is read as data until it's listed: `ignore: ["**/*.data.ts"]`. A data file that fails to load says it was read by its name. |
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 `![](photo.jpg)` 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/`. 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. |
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. So `{ "src/public": "." }` copies the folder to `/public/`; for its contents at the root (VitePress's and Vite's `public/`), give the files: `{ "src/public/**": "." }`. 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 = [...]`. |
66
- | `beforeBuild`, `afterBuild` | Build hooks (a function or an array). They get `{ env, serving, quiet, verbose, dirs }`, plus `written` (the files written) after the build; `quiet` and `verbose` say whether the build was run with `--quiet` or `--verbose`, so a hook's own messages can follow them. Async works. A hook can also run a program: `afterBuild: { run: "npx -y pagefind --site dist" }` runs it in the project root (through `sh -c`, or `cmd /C` on Windows) with its output shown, and a failure fails the build. It gets `SSQCH_ENV`, `SSQCH_SERVING`, `SSQCH_QUIET` (`true` with `--quiet`), `SSQCH_INPUT` and `SSQCH_OUTPUT`, and each `node_modules/.bin` from the project's folder up goes in front of its `PATH`, as in an npm script, so a tool the site installed runs by name (`{ run: "postcss src/app.css -o $SSQCH_OUTPUT/app.css" }`) whether the build started from `npm run build` or a global `ssqch`. `serve.run` commands get the same (`SSQCH_QUIET` from `ssqch serve --quiet`). In `sitesquatch.toml`, `before_build` and `after_build` take lists of commands. |
66
+ | `beforeBuild`, `afterBuild` | Build hooks (a function or an array). They get `{ env, serving, quiet, verbose, dirs }`, plus `written` (the files written) after the build, and while serving, `changed`: the files whose change started the build (`["./src/guide/intro.md"]`, not there on the first build), so a hook can skip what an edit doesn't touch (`if (changed?.every((f) => f.endsWith(".md"))) return;`); `quiet` and `verbose` say whether the build was run with `--quiet` or `--verbose`, so a hook's own messages can follow them. Async works. A hook can also run a program: `afterBuild: { run: "npx -y pagefind --site dist" }` runs it in the project root (through `sh -c`, or `cmd /C` on Windows) with its output shown, and a failure fails the build. It gets `SSQCH_ENV`, `SSQCH_SERVING`, `SSQCH_QUIET` (`true` with `--quiet`), `SSQCH_INPUT` and `SSQCH_OUTPUT`, and each `node_modules/.bin` from the project's folder up goes in front of its `PATH`, as in an npm script, so a tool the site installed runs by name (`{ run: "postcss src/app.css -o $SSQCH_OUTPUT/app.css" }`) whether the build started from `npm run build` or a global `ssqch`. `serve.run` commands get the same (`SSQCH_QUIET` from `ssqch serve --quiet`). In `sitesquatch.toml`, `before_build` and `after_build` take lists of commands. |
67
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
+ | `jinja` | Jinja's settings, for `.jinja` and `.j2` templates (and `.html` read as Jinja): `{ autoescape: false }` prints values as they are, where they're HTML-escaped by default (`| e` still escapes; `.njk` always does). `fromMkdocs({ templates: true })` turns it off, since MkDocs' Jinja doesn't escape. |
74
71
  | `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`). |
75
72
  | `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. |
76
73
  | `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`. |
74
+ | `urls` | A page's URL when it has no `permalink`: `"folders"` (the default) builds `guide/intro.md` as `/guide/intro/` (`guide/intro/index.html`), and `"html"` as `/guide/intro.html`. An index page is its folder either way (`guide/index.md` is `/guide/`), and page 2 of a list is `/blog/1.html`. A `permalink` wins, and so does one set in data for a folder or the whole site. (`"html"` is VitePress without `cleanUrls`, Hugo's `uglyURLs` and Docusaurus's `trailingSlash: false`.) |
75
+ | `layoutAliases` | Other names for layouts: `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`. |
78
76
  | `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. |
79
77
 
80
78
  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)`.
81
79
 
82
-
83
80
  ## What a filter sees
84
81
 
85
82
  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:
@@ -130,7 +127,6 @@ export default async function () {
130
127
 
131
128
  CI starts without `.cache/`, so production builds fetch fresh data unless you restore that folder.
132
129
 
133
-
134
130
  ## npm packages
135
131
 
136
132
  Install packages with npm, pnpm or yarn as usual, and import them: `import { DateTime } from "luxon"`. Node finds them as it always does, in `node_modules` folders from the importing file's folder up (so monorepos and pnpm's symlinks work), using `package.json`'s `exports`, `imports` (`#internal`) and `main`. CommonJS works too: `.cjs` files, and `.js` files in packages without `"type": "module"`, run with `require`, `module.exports`, `__dirname` and `__filename`, and importing one gives `module.exports` as the default export and, where Node can read the names from its source, its properties as named exports (`import legacy from "legacy"; const { twice } = legacy;` is the safe way for a package whose exports are built at run time). Your own `.js` files follow Node's rules: `"type"` in your `package.json` decides, and without one Node 22 reads a file with `import` or `export` as an ES module and any other as CommonJS, so `module.exports = { ... }` in `_data/site.js` works. In an ES module, `createRequire(import.meta.url)` from `node:module` gives you a `require`.
@@ -139,7 +135,6 @@ Packages run on Node, as they are, so anything that works in a Node script works
139
135
 
140
136
  Every page is rendered on one thread, one call at a time (there are no worker threads), so module-level state in your config behaves as it would in any Node script: a counter in a filter counts every page in order. A filter or template gets your real objects, not copies, so a filter that sorts `collections.posts` in place reorders it for the pages rendered after it: copy first (`[...posts].sort()`).
141
137
 
142
-
143
138
  ## Configuring with TOML
144
139
 
145
140
  A site that needs no code at all can use a `sitesquatch.toml` instead (one or the other, not both). Every key is optional, they're the config's settings in snake case (`template_formats`, `leave_no_trace`, `before_build`), and an unknown key is an error that lists all of them.
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Deploying"
2
+ title: "Out of the woods: deploying"
3
3
  description: "Encoding images is by far the slowest part of a build, so it's worth never doing it twice."
4
4
  ---
5
5
  <img align="right" src="../../../docs/assets/stickers/canoe.svg" alt="" width="96">
@@ -101,13 +101,13 @@ You'll see a line for each page, then a summary:
101
101
  ```text
102
102
  [ssqch] Writing ./dist/index.html from ./src/index.jinja (jinja)
103
103
  [ssqch] Writing ./dist/posts/pine-cone-crunch/index.html from ./src/posts/pine-cone-crunch.md (jinja, md)
104
- First confirmed siting. Built in 2.75 ms (production)
104
+ First confirmed sighting. Built in 2.75 ms (production)
105
105
  Pages 2 written from 2 templates, 410 B
106
106
  Output dist: 2 files, 410 B
107
107
  Time setup 224 µs, data 435 µs, read 1.54 ms, paginate 45 µs, render 205 µs, write 282 µs, copy 0 µs, after 20 µs
108
108
  ```
109
109
 
110
- `dist/index.html` has a `SQUATCH SNACKS!` heading and a link to `/posts/pine-cone-crunch/`. You've got a website! (A site's first build is its first confirmed siting. After that it's plain `Built in`.)
110
+ `dist/index.html` has a `SQUATCH SNACKS!` heading and a link to `/posts/pine-cone-crunch/`. You've got a website! (A site's first build is its first confirmed sighting. After that it's plain `Built in`.)
111
111
 
112
112
  To work on it with live reload, run the dev server and open <http://localhost:8080>:
113
113
 
@@ -116,7 +116,7 @@ ssqch serve
116
116
  ```
117
117
 
118
118
  ```text
119
- First confirmed siting. Built in 2.75 ms (development)
119
+ First confirmed sighting. Built in 2.75 ms (development)
120
120
  ...
121
121
  Serving dist at http://localhost:8080/. Squatch Watch is on.
122
122
  Fresh tracks in src/posts/pine-cone-crunch.md
@@ -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 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).
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 trace`](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,7 @@ 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.11.0` (drop `cache: npm`, which looks for a lockfile) and runs `ssqch build` instead of `npx ssqch build`.
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.12.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)).
42
+ - **Markdown for agents:** GitHub Pages can't vary an answer by the request's `Accept`, so agents find a page's Markdown copy through its `<link rel="alternate">` and `llms.txt` ([Serving Markdown to agents](serving-markdown.md#github-pages)).
@@ -17,7 +17,7 @@ What's in the pack:
17
17
  - **A JavaScript config** with filters, global data, custom collections, transforms and build hooks, plus any npm package, `fetch` (with a cache) and every Node built-in, since the config runs on Node.
18
18
  - **Markdown that does the work of a plugin stack:** heading ids, footnotes, containers, render hooks in any template language, and syntax highlighting at build time.
19
19
  - **Responsive images:** every `<img>` becomes a `<picture>` with AVIF, WebP and fallback sources, cached by content so later builds skip the encoding.
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.
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 trace`](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
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.
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Install"
2
+ title: "Gear up: install"
3
3
  description: "You'll need Node.js 22.18 or newer."
4
4
  ---
5
5
  <img align="right" src="../../../docs/assets/stickers/backpack.svg" alt="" width="96">
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Known gaps"
2
+ title: "Uncharted territory: known gaps"
3
3
  description: "The uncharted parts of the map, as of this release."
4
4
  ---
5
5
  <img align="right" src="../../../docs/assets/stickers/direction-sign.svg" alt="" width="96">
@@ -15,26 +15,23 @@ 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). `"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. |
18
+ | `headingIds` | `"github"` | Automatic heading `id`s. `"github"` matches GitHub's anchors and github-slugger's (rehype-slug's, so Astro'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 `fromJekyll()`'s Markdown inside HTML, kramdown's own for headings inside it (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). `"vitepress"` matches VitePress's (@mdit-vue's `slugify`: punctuation and spaces become one `-`, accents go, and a leading digit gets `_`, so `What's Vue?` becomes `what-s-vue` and `1. Setup` becomes `_1-setup`). 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. Why the styles: a heading's id is part of a URL (`/guide/#install`), and other sites link to it, so a site moving to ssqch keeps the ids it had, whichever generator wrote them, and no one's link breaks. |
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. `"fuzzy"` links bare domains and email addresses too (`example.com`, `ranger@example.com`), as markdown-it's `linkify` does ([below](#markdown-its-habits)). |
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)). `"email"` links URLs and email addresses (`mailto:`) but not bare domains, as `linkify` with `fuzzyLink: false` does, which is VitePress's setting. |
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
- | `containers` | `true` | `::: name args` blocks (below). |
24
+ | `containers` | `true` | `::: name args` blocks (below). A closing `:::` indented less than four spaces closes the innermost open container wherever it is, so Prettier's `:::`, indented under the list it ends (`- two\n :::`), closes it, as markdown-it-container (and VitePress) read them. |
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. |
27
+ | `breaks` | `false` | A single newline inside a paragraph or a list item becomes a `<br>`. (markdown-it's `breaks: true`, [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>`. (markdown-it-implicit-figures, [below](#markdown-its-habits).) |
33
29
  | `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 `&amp;`), 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. |
36
30
  | `indentedCode` | `true` | Lines indented four spaces are code. `false` makes them ordinary Markdown, for HTML indented inside Markdown; fences are still code. |
37
31
  | `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)). |
32
+ | `preprocess` | none | A function of yours that changes a page's Markdown before ssqch reads it: `preprocess: (source, data) => source.replace(/<script setup>[\s\S]*?<\/script>\n?/g, "")` leaves out Vue's `<script setup>` blocks. It gets the page's Markdown (after front matter, and after the template language when `markdownEngine` runs one) and the page's data (`data.page.inputPath`), and returns the Markdown (or a promise of it). It runs for pages, not for the `markdown` filter; an error in it names the page. For a step that's a language of its own, an engine in `markdownEngine` works too. |
33
+
34
+ Another generator's Markdown, for a site moving from it, is a plugin of its own, each documented in its trailhead: `fromJekyll()` (kramdown's Markdown inside HTML, its heading ids), `fromMkdocs()` (Python-Markdown, admonitions and tabs), `fromHugo()` (shortcodes as containers) and `fromVitepress()` (VitePress's containers, headings, links and code blocks).
38
35
 
39
36
  **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">`.
40
37
 
@@ -54,7 +51,7 @@ export default { markdown: { highlight: { languages: { trailnotes, trail: "trail
54
51
 
55
52
  **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.
56
53
 
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:
54
+ **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), and `container.inline`, true for a Hugo shortcode inside a line of text (with `fromHugo()`, [Moving from Hugo](trailheads/from-hugo.md)), whose output goes in the line). One template covers admonitions, tabs, figures or anything else that wraps content:
58
55
 
59
56
  ```markdown
60
57
  ::: warning Hot pine cones
@@ -97,7 +94,8 @@ Pine Cone Crunch
97
94
  | Template | Gets | For example |
98
95
  | --- | --- | --- |
99
96
  | `heading.*` | `heading.level`, `id`, `text`, `content` (the inner HTML) and `attrs` | Anchor links next to headings |
100
- | `link.*` | `link.href`, `title`, `text` and `content` | `target="_blank"` and an icon on external links |
97
+ | `table.*` | `table.content` (the table's rows as ssqch writes them, `<thead>` to `</tbody>`, alignment included) and `columns` (how many); the template writes the `<table>` | VitePress's `<table tabindex="0">{{ table.content \| safe }}</table>`, or a wrapper that scrolls |
98
+ | `link.*` | `link.href` (the URL as the page wrote it, not percent-encoded as ssqch writes a link without a hook; browsers go to the same place either way), `title`, `text` and `content` | `target="_blank"` and an icon on external links |
101
99
  | `image.*` | `image.src`, `alt` and `title` | `<figure>` with a caption |
102
100
  | `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 |
103
101
  | `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 |
@@ -1,7 +1,7 @@
1
1
  # The docs' order: the site's sidebar, and the order `ssqch docs` reads the pages in (a page that
2
2
  # isn't listed is on the site but not in `ssqch docs`). Each is a page's file, or a page the site
3
3
  # makes itself.
4
- - title: Start here
4
+ - title: Base camp
5
5
  pages:
6
6
  - index.md
7
7
  - install.md
@@ -11,12 +11,14 @@
11
11
  - configuring.md
12
12
  - data-files.md
13
13
  - plugins.md
14
+ - writing-plugins.md
14
15
  - templates.md
15
16
  - markdown.md
16
17
  - template-languages.md
17
18
  - css-and-javascript.md
18
19
  - multilingual.md
19
20
  - seo.md
21
+ - robots.md
20
22
  - themes.md
21
23
  - new-pages.md
22
24
  - title: Check
@@ -26,11 +28,13 @@
26
28
  - build-summary.md
27
29
  - comparing-builds.md
28
30
  - footprint.md
31
+ - patrol.md
29
32
  - title: Ship
30
33
  pages:
31
34
  - deploying.md
32
35
  - netlify.md
33
36
  - github-pages.md
37
+ - serving-markdown.md
34
38
  - agents.md
35
39
  - rust-plugins.md
36
40
  - title: Trailheads
@@ -43,6 +47,7 @@
43
47
  - trailheads/from-docusaurus.md
44
48
  - trailheads/from-mkdocs.md
45
49
  - trailheads/from-hexo.md
50
+ - trailheads/from-vitepress.md
46
51
  - trailheads/from-component-frameworks.md
47
52
  - title: Reference
48
53
  pages:
@@ -18,13 +18,15 @@ 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.11.0`) and bump it when you're ready.
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.13.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.11.0"` under `[build.environment]` to pin it (and `NODE_VERSION` there as well):
25
+ A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.13.0"` under `[build.environment]` to pin it (and `NODE_VERSION` there as well):
26
26
 
27
27
  ```toml
28
28
  [build]
29
29
  command = "npx --yes ssqch@$SSQCH_VERSION build"
30
30
  ```
31
+
32
+ To answer a coding agent's `Accept: text/markdown` with a page's Markdown copy, add an edge function: [Serving Markdown to agents](serving-markdown.md#netlify) has it, ready to paste.
@@ -0,0 +1,48 @@
1
+ ---
2
+ title: "Patrol: what agents and crawlers find"
3
+ description: "ssqch patrol walks a built site the way a coding agent or a crawler reads it: the posted signs, each page's shape, and each page's Markdown copy."
4
+ ---
5
+ `ssqch patrol` walks a built site the way a coding agent or a crawler reads it, and warns about what would trip one up: a missing `robots.txt`, sitemap or `llms.txt`, a page with two `<h1>`s or no description, a Markdown copy that doesn't say what its page says.
6
+
7
+ ```text
8
+ $ ssqch build
9
+ $ ssqch patrol
10
+ Patrol of _site: 12 pages, 12 with a Markdown copy
11
+ robots.txt posted, sitemap posted, llms.txt posted, 404.html posted
12
+
13
+ warn[no-description]: pages with no <meta name="description">: what search results and agents show for a link (2)
14
+ posts/pine-cones/index.html
15
+ tags/index.html
16
+
17
+ 1 kind of warning in 2 files. `ssqch docs "what patrol checks"` says what each code means.
18
+ ```
19
+
20
+ It reads the site's output folder, or any build folder you name, another generator's included (`ssqch patrol _site` before a move shows what the move can fix). It needs no config and changes nothing. With `--format json`, standard output is one JSON document: `pages`, `copies` (the pages with a Markdown copy), `signs` (`robots`, `sitemap`, `llms` and `notFound`, each `true` or `false`) and `warnings`, each with its `code`, `message` and every one of its `files`. It exits with 0 when it found nothing, 1 when it warned, and 2 on an error (a folder that isn't there), so a CI step can run it after the build.
21
+
22
+ ## What patrol checks
23
+
24
+ Each warning has a code. The checks are the ones a build folder can answer from the two public lists of what agents need (the Agent-Friendly Documentation Spec and isitagentready.com); what needs the live site (a host's headers, `Accept: text/markdown`) isn't checked yet.
25
+
26
+ | Code | What it means, and the fix |
27
+ | --- | --- |
28
+ | `no-robots` | No `robots.txt`. `robotsPlugin()` writes one, with the sitemap's address and rules for AI crawlers ([Posted signs](robots.md)). |
29
+ | `no-sitemap` | No `sitemap.xml`, and `robots.txt` names none. `sitemapPlugin({ url })` writes one. |
30
+ | `no-404` | No `404.html`, or one that's the home page. A missing page should say so, with a 404 status: a page with `permalink: /404.html`. |
31
+ | `no-llms` | No `llms.txt`. `llmsPlugin()` writes it, with a Markdown copy of each page. |
32
+ | `llms-shape` | `llms.txt` doesn't start with a `# ` heading (the site's name), the one part llmstxt.org's format requires. |
33
+ | `llms-long` | `llms.txt` is over 50,000 characters: more than an agent reads before deciding where to go. Leave sections out with `exclude`, or link a section's own file. |
34
+ | `llms-broken` | A link in `llms.txt` to the site's own file that isn't in the build. |
35
+ | `llms-html` | `llms.txt` links pages, not their Markdown. An agent reads Markdown without the page's navigation and scripts. |
36
+ | `llms-coverage` | `llms.txt` lists under 95% of the sitemap's pages, so an agent misses some. |
37
+ | `no-h1`, `h1s` | A page with no `<h1>`, or more than one. An agent takes the first heading as what the page is about. |
38
+ | `no-description` | A page with no `<meta name="description">`, which search results and agents show for a link. |
39
+ | `no-main` | A page whose content is in neither `<main>` nor `<article>`, so a reader can't tell it from the navigation (`llmsPlugin()` copies a template page's `<article>` or `<main>` for the same reason). |
40
+ | `content-late` | A page whose `<main>` comes after most of its text: an agent with a short read sees the menus. Put the navigation after the content in the HTML (CSS can still show it first). |
41
+ | `copy-missing` | A page whose `<link rel="alternate" type="text/markdown">` points at a file that isn't in the build. |
42
+ | `copy-differs` | A Markdown copy that doesn't say what its page says: under 80% of its words are on the page, or under half the page's are in it (template code where the text should be, or a layout that adds most of the page). |
43
+ | `copy-long`, `copy-cut-off` | A Markdown copy over 50,000 characters, long for one fetch, or over 100,000, where Claude Code's fetch stops reading. Split the page. |
44
+ | `copy-broken` | A Markdown copy that links the site's own file that isn't in the build: often a picture's source path, which an image plugin published under another name. `llmsPlugin()` writes the published addresses. |
45
+ | `copy-fence` | A code fence in a copy that never closes, so the rest reads as code. |
46
+ | `relative-links` | A link in `llms.txt` or a copy that isn't a whole address or a path from the root: it breaks once the text is read away from its page. `llmsPlugin({ url })` writes whole addresses. |
47
+
48
+ A page that only sends a reader on (a redirect, with `http-equiv="refresh"`) isn't checked, and neither is `404.html`. A Markdown copy is the one the page links, or the one at the address llms.txt's proposal gives it (`/guide/intro/` has `/guide/intro/index.md`).
@@ -1,13 +1,15 @@
1
1
  ---
2
- title: "Built-in plugins"
2
+ title: "The gear shed: 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
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`.
6
+ - **`ssqch/rss`:** `rssPlugin()` adds the filters `getNewestCollectionItemDate`, `dateToRfc3339`, `dateToRfc822`, `rssDate` and `rssLastUpdatedDate` (the Eleventy RSS plugin's first names, as aliases: they work, and say once that they're `dateToRfc3339` and `getNewestCollectionItemDate | dateToRfc3339`), `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
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.
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, required: a sitemap lists whole addresses, and search engines read only those, so a build without one stops and asks for it; jekyll-sitemap wrote paths from the root instead), `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
+ - **`ssqch/llms`:** `llmsPlugin({ url: "https://example.com", description: "Hikes and the gear for them." })` writes the site for language models, as [llmstxt.org](https://llmstxt.org) describes it: `/llms.txt` lists the site's pages (each one's title, a link to its Markdown and its `description`), under a `##` heading for each of the site's top folders (`/guide/...` is "Guide"; the top's pages are "Pages"), and each of those pages gets a Markdown copy beside its URL as llms.txt's v2 proposal has it (`/guide/intro.html` is `/guide/intro.md`; a URL without a file name gets `index.md`, so `/guide/intro/` is `/guide/intro/index.md` and `/` is `/index.md`). A copy is what the page says: a Markdown page's copy is its Markdown after its template engine ran (`{{ site.title }}` is the title, a `{% for %}` is the list it wrote), without its front matter, its `<script>` and `<style>` blocks, or pictures with `alt=""` (decoration), and with its title on top when only the front matter had it, and its pictures (and links to them) at the addresses the page shows, so a picture `imagePlugin()` published under another name links the published file; any other page's copy (a home page in Jinja) is its `<article>`, or else its `<main>` or `<body>`, as Markdown (headings, paragraphs, lists, links, code, quotes, tables and described pictures; navigation, forms, scripts and anything `hidden` are left out). Links in a copy are whole addresses (with `url`), and a link to a page that has a copy goes to the copy, a relative `.md` link to another page's file included (`[Install](install.md)`). `/llms-full.txt` has the heading, then every copy in one file, each after a `url:` line. A page whose front matter says `llms: false` is left out. The plugin adds one template function, `markdownCopy(page.url)`: the URL of the page's copy, or `""` when it has none, for the layout to link it (a build adds no markup of its own): `{% if markdownCopy(page.url) %}<link rel="alternate" type="text/markdown" href="{{ markdownCopy(page.url) }}">{% endif %}`. Options: `title` (the `#` heading; default `site.title` in the site's data, or the home page's title), `description` (a `>` line under it), `details` (Markdown after that, in both files: what a model should know first), `url` (the site's address, for whole links; without it, links are from the site's root), `exclude` (URL globs, like `["/drafts/**"]`; 404 pages are always left out), `copies` (default `true`; `false` links `llms.txt` to the pages instead), `full` (default `true`), `section` (a function that gets each page and returns its section's name; sections come in the order of their first page) and `sort` (a function that compares two pages, as `Array.prototype.sort` takes it; default by URL). vitepress-plugin-llms does this for VitePress sites.
13
+ - **`ssqch/robots`:** `robotsPlugin({ ai: { training: false } })` writes `/robots.txt`: everyone's group (`disallow`, URL paths no crawler should read), a group with `Disallow: /` for each kind of AI crawler that's turned off (`ai`: `training`, `search` and `fetch`, each `true` by default), and the `Sitemap:` line with `sitemapPlugin()`'s address (`sitemap: false` leaves it out, a string is another address). [Posted signs](robots.md) lists the crawlers of each kind and the links a layout writes for agents.
14
+ - **`ssqch/vue`:** `vuePlugin(options)` renders the Vue components a site's pages use, at build time, with the site's own Vite, `@vitejs/plugin-vue` and Vue (`npm install -D vite @vitejs/plugin-vue vue`; ssqch doesn't bundle them, and says so if they're missing). With pnpm, which keeps a VitePress site's vite and @vitejs/plugin-vue beside `vitepress` rather than in the site's `node_modules`, they're found there. Vue renders with its production build in a production build and its development build while serving (`NODE_ENV` follows ssqch's env unless you set it). A page's `<script setup>` imports name them, as VitePress's pages do (`import ApiIndex from './ApiIndex.vue'`, then `<ApiIndex />` in the page), and `components` names the ones every page can use (`{ VueSchoolLink: ".vitepress/theme/components/VueSchoolLink.vue" }`, VitePress's `app.component()`). Each tag a page has (and no template in `_includes/components/`, which comes first) becomes the HTML Vue's server renderer writes for it: its attributes are its props, and a binding is read as Vue reads it in the page, with the page's front matter (`frontmatter`, `$frontmatter`), `params` (a dynamic route's, from its URL: `[partnerId].md` written as `/partners/vehikl.html`), `page` (VitePress's `useData().page`) and the `data` of each VitePress loader its `<script setup>` imports (`import { data } from './errors.data'`; the loader's `load()` runs once a build, through Vite, with `__dirname`), and what's between its tags is its default slot, with the components inside it rendered first (a layout component that holds the page works). With `fromVitepress()` from `ssqch/from-vitepress` (a site moving from VitePress), components that import from `"vitepress"` get a stand-in (with `current`, its page's state, for a wrapper that renders the site's theme: the VitePress trailhead's "Keeping your VitePress theme") for `useData()` (the page's front matter, title and route, and the config's `themeConfig`), `useRoute()`, `withBase()` and `inBrowser`, and `@theme/` is the theme's folder. `hydrate` runs each component in the browser too, as an island: `"load"`, `"idle"` or `"visible"` (when it scrolls into view) wraps its HTML in `<ssqch-vue>` and adds one script to the pages that have one, `/assets/vue/islands.js`, which loads only the components on the page; default `false`, HTML only. `css` is where the components' styles go (default `"/assets/vue.css"`, for your layout to link; `false` for none), and the fonts and images they point at go where Vite put them (`/assets/inter-x.woff2`, after `base`); the site's `public/` isn't copied (that's `passthrough`'s), `root` is Vite's root (default the input folder, so scope ids are VitePress's), and `vite` adds Vite options (`resolve.alias`, `plugins`). The components build in `.cache/ssqch/vue/` before each build; while serving, an edit that's only to pages keeps the last one. A VitePress loader named like ssqch's data (`api/api.data.ts`) goes in `ignore`, which `ssqch scout` drafts.
13
15
  - **`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`.
@@ -0,0 +1,72 @@
1
+ ---
2
+ title: "Posted signs: robots.txt and AI crawlers"
3
+ description: "robotsPlugin() writes robots.txt: the sitemap's address, the paths no crawler reads, and what AI crawlers may do, by what they're for. With llmsPlugin() and three links in the layout, a site is ready for agents."
4
+ ---
5
+ A crawler reads the signs at the trailhead before it walks in: `robots.txt` says what it may read and where the sitemap is, and `llms.txt` is the map an agent reads first. ssqch writes both with plugins, and three links in the layout's `<head>` point agents at them.
6
+
7
+ ```js
8
+ import { defineConfig } from "ssqch";
9
+ import { llmsPlugin } from "ssqch/llms";
10
+ import { robotsPlugin } from "ssqch/robots";
11
+ import { sitemapPlugin } from "ssqch/sitemap";
12
+
13
+ export default defineConfig({
14
+ plugins: [
15
+ sitemapPlugin({ url: "https://example.com" }),
16
+ robotsPlugin({ ai: { training: false } }),
17
+ llmsPlugin({ url: "https://example.com" }),
18
+ ],
19
+ });
20
+ ```
21
+
22
+ `ssqch patrol` checks the result ([Patrol](patrol.md)).
23
+
24
+ ## robots.txt
25
+
26
+ `robotsPlugin(options)` from `ssqch/robots` writes `/robots.txt`. With the options above:
27
+
28
+ ```text
29
+ User-agent: *
30
+ Allow: /
31
+
32
+ User-agent: GPTBot
33
+ User-agent: ClaudeBot
34
+ User-agent: Google-Extended
35
+ User-agent: Applebot-Extended
36
+ User-agent: CCBot
37
+ User-agent: meta-externalagent
38
+ User-agent: Bytespider
39
+ Disallow: /
40
+
41
+ Sitemap: https://example.com/sitemap.xml
42
+ ```
43
+
44
+ Options:
45
+
46
+ - `ai`: what AI crawlers may do, by what they're for, each `true` (the default) or `false`. `training` is collecting pages to train models on (GPTBot, ClaudeBot, Google-Extended, Applebot-Extended, CCBot, meta-externalagent, Bytespider); `search` is indexing them for an AI search's answers (OAI-SearchBot, Claude-SearchBot, PerplexityBot); `fetch` is reading a page because a person asked about it (ChatGPT-User, Claude-User, Perplexity-User, meta-externalfetcher). A purpose that's `false` gets a group with `Disallow: /`; one that's `true` gets none, so its crawlers read everyone's. Google-Extended and Applebot-Extended only say what may be trained on: Google Search, Siri and Spotlight still index the site. OpenAI and Perplexity say a fetch a person asked for may not read robots.txt at all.
47
+ - `disallow`: URL paths no crawler should read (`["/drafts/"]`), as `Disallow:` lines in everyone's group, with the site's `base` in front.
48
+ - `sitemap`: the `Sitemap:` line. By default it's `sitemapPlugin()`'s address when that's on, and there's none without it; `false` leaves it out, and a string is another sitemap's whole address.
49
+
50
+ The names come from each company's documentation, checked on 2026-11-21, and ssqch keeps the list as they change, so a site says what it wants once, by purpose. A site that copies its own `robots.txt` (in `passthrough`) and turns the plugin on is an error that says to keep one. A site served under a `base` (`/repo/`) has its `robots.txt` there too, where crawlers don't look: they read only the domain's own `/robots.txt`.
51
+
52
+ Not written yet, because nothing reads them yet: the IETF draft's shared group for training (`User-agent: __usage_ai-training`, a draft of October 2026) and Cloudflare's `Content-Signal` line.
53
+
54
+ ## llms.txt and the Markdown copies
55
+
56
+ `llmsPlugin()` writes `/llms.txt`, a Markdown copy of each page and `/llms-full.txt` ([Built-in plugins](plugins.md)). A copy is what the page says (a Markdown page's text after its template ran, a template page's `<article>` or `<main>` as Markdown), at the address llms.txt's proposal gives it: `/guide/intro/` has `/guide/intro/index.md`.
57
+
58
+ ## The links in the layout
59
+
60
+ llms.txt's proposal (v2) has agents find both from any page by two links, which a layout writes in its `<head>` (a build adds no markup of its own):
61
+
62
+ ```html
63
+ <link rel="canonical" href="{{ site.url }}{{ page.url }}">
64
+ {% if markdownCopy(page.url) %}<link rel="alternate" type="text/markdown" href="{{ markdownCopy(page.url) }}">{% endif %}
65
+ <link rel="describedby" href="/llms.txt">
66
+ ```
67
+
68
+ `markdownCopy(page.url)` comes with `llmsPlugin()`: the copy's URL, or `""` for a page without one. The starters' layouts have all three.
69
+
70
+ ## When an agent asks for Markdown
71
+
72
+ Claude Code, Cursor and OpenCode ask for a page with `Accept: text/markdown`. `ssqch serve` answers with the page's copy, and on a host it takes a few lines of the host's own code: [Serving Markdown to agents](serving-markdown.md) has them for Cloudflare, Netlify and Vercel, and what GitHub Pages does instead.