ssqch 0.12.0 → 0.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bundled/completions/bash +66 -8
- package/bundled/completions/elvish +23 -4
- package/bundled/completions/fish +36 -25
- package/bundled/completions/powershell +25 -4
- package/bundled/completions/zsh +44 -10
- package/bundled/docs/agents.md +2 -2
- package/bundled/docs/build-summary.md +1 -1
- package/bundled/docs/comparing-builds.md +2 -2
- package/bundled/docs/configuring.md +3 -6
- package/bundled/docs/deploying.md +1 -1
- package/bundled/docs/field-guide.md +4 -4
- package/bundled/docs/github-pages.md +1 -0
- package/bundled/docs/index.md +1 -1
- package/bundled/docs/install.md +1 -1
- package/bundled/docs/known-gaps.md +1 -1
- package/bundled/docs/markdown.md +8 -12
- package/bundled/docs/nav.yml +5 -1
- package/bundled/docs/netlify.md +4 -2
- package/bundled/docs/patrol.md +48 -0
- package/bundled/docs/plugins.md +6 -6
- package/bundled/docs/robots.md +85 -0
- package/bundled/docs/seo.md +2 -38
- package/bundled/docs/serving-markdown.md +142 -0
- package/bundled/docs/template-languages.md +1 -1
- package/bundled/docs/templates.md +1 -1
- package/bundled/docs/trailheads/from-hugo.md +5 -3
- package/bundled/docs/trailheads/from-jekyll.md +54 -13
- package/bundled/docs/trailheads/from-mkdocs.md +15 -12
- package/bundled/docs/trailheads/from-vitepress.md +13 -11
- package/bundled/docs/trailheads.md +3 -3
- package/bundled/docs/where-values-come-from.md +5 -5
- package/bundled/docs/writing-plugins.md +69 -0
- package/bundled/ssqch.d.ts +118 -44
- package/bundled/starter/engines/index.edge +1 -0
- package/bundled/starter/engines/index.ejs +1 -0
- package/bundled/starter/engines/index.hbs +1 -0
- package/bundled/starter/engines/index.liquid +1 -0
- package/bundled/starter/engines/layout.edge +7 -0
- package/bundled/starter/engines/layout.ejs +4 -0
- package/bundled/starter/engines/layout.hbs +4 -0
- package/bundled/starter/engines/layout.liquid +4 -0
- package/bundled/starter/src/_data/site.json +1 -0
- package/bundled/starter/src/_includes/layout.jinja +4 -0
- package/bundled/starter/src/index.jinja +1 -0
- package/bundled/starter/ssqch.config.js +14 -1
- package/bundled/starter-docs/engines/edge/base.edge +7 -0
- package/bundled/starter-docs/engines/edge/doc.edge +4 -0
- package/bundled/starter-docs/engines/ejs/base.ejs +4 -0
- package/bundled/starter-docs/engines/ejs/doc.ejs +4 -0
- package/bundled/starter-docs/engines/hbs/base.hbs +4 -0
- package/bundled/starter-docs/engines/hbs/doc.hbs +3 -0
- package/bundled/starter-docs/engines/liquid/base.liquid +4 -0
- package/bundled/starter-docs/engines/liquid/doc.liquid +4 -0
- package/bundled/starter-docs/src/_data/site.json +1 -0
- package/bundled/starter-docs/src/_includes/base.jinja +4 -0
- package/bundled/starter-docs/src/_includes/doc.jinja +4 -0
- package/bundled/starter-docs/src/assets/docs.css +4 -0
- package/bundled/starter-docs/src/assets/docs.js +17 -0
- package/bundled/starter-docs/ssqch.config.js +14 -1
- package/lib/assets.js +9 -9
- package/lib/chunk-25WERNDD.js +112 -0
- package/lib/{chunk-4ZMNLWE4.js → chunk-2BJFGKOE.js} +2 -2
- package/lib/{chunk-M2BBE2C3.js → chunk-3ZTRIO6O.js} +18 -17
- package/lib/{chunk-57HLSKZS.js → chunk-4AZFCSGJ.js} +2 -2
- package/lib/{chunk-ULQHJ4TS.js → chunk-55WXDGO4.js} +3 -3
- package/lib/{chunk-JX43SJHU.js → chunk-6FY77I4M.js} +24 -22
- package/lib/{chunk-RY3KLUQ3.js → chunk-6OUCRDYI.js} +267 -202
- package/lib/{chunk-EVFNYUTR.js → chunk-6U5VIQVY.js} +5 -5
- package/lib/{chunk-N3IZ44XY.js → chunk-7U5GWTEH.js} +88 -54
- package/lib/{chunk-VTYQ3JKL.js → chunk-AIJNG6MJ.js} +2 -2
- package/lib/{chunk-IIBZPHAW.js → chunk-C2Q7JKFI.js} +8 -8
- package/lib/{chunk-6CSH757V.js → chunk-DFJFHULZ.js} +33 -8
- package/lib/{chunk-XVV7JJK7.js → chunk-ENWDM2RW.js} +40 -39
- package/lib/{chunk-JUALMFW3.js → chunk-ER72RPD6.js} +1 -1
- package/lib/{chunk-RFREB3SI.js → chunk-F3JPNFCZ.js} +7 -7
- package/lib/{chunk-LLOA3QXV.js → chunk-FENJHLNM.js} +3 -2
- package/lib/{chunk-UU43WIZG.js → chunk-FJML7INB.js} +4 -2
- package/lib/{chunk-IZCF4UH3.js → chunk-FQZDUDFK.js} +1 -1
- package/lib/chunk-GM5SHCTU.js +272 -0
- package/lib/{chunk-GVHQ37JE.js → chunk-GSNRAGKQ.js} +10 -5
- package/lib/{chunk-L2IY4P6O.js → chunk-GU7BBYWB.js} +3 -3
- package/lib/{chunk-RGYJQYW3.js → chunk-HDKU6LRI.js} +32 -5
- package/lib/{chunk-IQUGLVZY.js → chunk-K5WZ2VYK.js} +4 -4
- package/lib/{chunk-JVT5ZRRH.js → chunk-OOKBXQAY.js} +5 -5
- package/lib/{chunk-MOLTDO5A.js → chunk-SNQOHNXE.js} +1 -1
- package/lib/{chunk-Z3XH4KWX.js → chunk-SPIFZBIW.js} +1 -1
- package/lib/{chunk-FNNXRVSU.js → chunk-T5IUI7W7.js} +10 -10
- package/lib/{chunk-5HEZ3WUQ.js → chunk-TGSVSG2G.js} +2 -2
- package/lib/{chunk-3GROJ3TY.js → chunk-U2KEMVXO.js} +24 -17
- package/lib/{chunk-4B3N44SN.js → chunk-UHRBPZ4A.js} +3 -3
- package/lib/{chunk-GWWA5Y3X.js → chunk-ULCT3PAV.js} +1 -1
- package/lib/{chunk-7RGEWDLF.js → chunk-UZNUS7RP.js} +10 -8
- package/lib/{chunk-DZ5F5XSI.js → chunk-V3G2QGL3.js} +10 -105
- package/lib/{chunk-DOHOKUGB.js → chunk-VILOEVK7.js} +50 -26
- package/lib/{chunk-DXMDXHV7.js → chunk-WGAIE3DD.js} +15 -14
- package/lib/{chunk-G3RFQDKO.js → chunk-WUCRAV36.js} +8 -6
- package/lib/{chunk-52ROOMBZ.js → chunk-XYAWJTHM.js} +9 -9
- package/lib/{chunk-L3K7MMFC.js → chunk-YA23NDMW.js} +2 -2
- package/lib/{chunk-R7PBREXL.js → chunk-YNJNMQWU.js} +8 -5
- package/lib/{chunk-AK7ZKSZP.js → chunk-ZMG25MXF.js} +17 -16
- package/lib/cli.js +56 -34
- package/lib/elements.js +9 -9
- package/lib/from-hugo.js +36 -0
- package/lib/from-jekyll.js +41 -0
- package/lib/from-mkdocs.js +49 -0
- package/lib/from-vitepress.js +49 -0
- package/lib/image.js +10 -10
- package/lib/links.js +9 -9
- package/lib/llms.js +619 -54
- package/lib/minify.js +10 -10
- package/lib/redirects.js +9 -9
- package/lib/robots.js +87 -0
- package/lib/rss.js +22 -12
- package/lib/sass.js +10 -10
- package/lib/sitemap.js +22 -33
- package/lib/ssqch.js +5 -5
- package/lib/vue.js +14 -13
- package/package.json +21 -1
- package/types/from-hugo.d.ts +5 -0
- package/types/from-jekyll.d.ts +11 -0
- package/types/from-mkdocs.d.ts +11 -0
- package/types/from-vitepress.d.ts +5 -0
- package/types/index.d.ts +45 -29
- package/types/llms.d.ts +18 -8
- package/types/robots.d.ts +13 -0
- package/types/sass.d.ts +1 -1
- package/types/sitemap.d.ts +3 -5
- package/wasm/markdown.wasm +0 -0
- /package/lib/{chunk-JX43SJHU.js.LEGAL.txt → chunk-6FY77I4M.js.LEGAL.txt} +0 -0
- /package/lib/{chunk-R7PBREXL.js.LEGAL.txt → chunk-YNJNMQWU.js.LEGAL.txt} +0 -0
|
@@ -67,15 +67,12 @@ The default export is the config: an object, or a function (sync or async) that
|
|
|
67
67
|
| `theme` | A theme under the site: a folder (`"themes/docs"`), or a git repository pinned to a commit or tag (`"https://github.com/you/theme#v1.2.0"`). The site's own files win over the theme's, one by one. See [Themes](themes.md). |
|
|
68
68
|
| `schemas` | What each kind of page's data has to look like, checked on every build: `{ posts: { fields: { title: "string", date: "date" } } }`. See [Content schemas](content-schemas.md). |
|
|
69
69
|
| `base` | The path the site is served under, when that isn't the root of its domain: `base: "/repo/"` for a GitHub Pages project site at `https://you.github.io/repo/`. Templates, Markdown links and `page.url` stay as they are (`/about/`); ssqch adds the base to every URL from the site's root in the HTML it writes. See [Serving a site under a path](deploying.md#serving-a-site-under-a-path). |
|
|
70
|
-
| `
|
|
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
|
-
| `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
|
|
78
|
-
| `layoutAliases` | Other names for layouts
|
|
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`. |
|
|
79
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. |
|
|
80
77
|
|
|
81
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)`.
|
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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).
|
|
@@ -39,3 +39,4 @@ jobs:
|
|
|
39
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)).
|
package/bundled/docs/index.md
CHANGED
|
@@ -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
|
|
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.
|
package/bundled/docs/install.md
CHANGED
package/bundled/docs/markdown.md
CHANGED
|
@@ -15,28 +15,24 @@ 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 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 `
|
|
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
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). A
|
|
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
|
|
28
|
-
| `figures` | `false` | An image, or a linked image, alone in a paragraph becomes a `<figure>` with its alt text as the `<figcaption
|
|
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 inline Markdown, as Python-Markdown reads it (`!!! tip "Run `ssqch build`"` has `<code>`, and a `[link]` can use a reference defined anywhere on the page). |
|
|
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`). A tab's label, like an admonition's title, is inline Markdown, as Python-Markdown reads it: `=== "`base.html`"` labels it with `<code>`, and a `[link]` can use a reference defined anywhere on the page. |
|
|
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 (`Added in {{< new-in 0.148 />}}`, `[About]({{< ref "about" >}})`, `{{% kbd %}}Ctrl{{% /kbd %}}`) renders through the same container template in its place, with `container.inline` true and what's between a pair's tags (on the same line) as `container.content`; what the template writes goes in as it is, and in a heading it leaves the id alone. One with no container template 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. `"vitepress"` reads and writes Markdown as VitePress does, for a site moving from it: Vue's `<script>` and `<style>` blocks and `<ClientOnly>` are left out (outside fences), a `-vue` fence (```` ```sh-vue ````) prints its `{{ 'literal' }}`s, and it has VitePress's markup as built-in render hooks and containers, each replaced by a template of yours of the same name: headings with `tabindex="-1"` and the `header-anchor` link; links with `.html` when `urls` is `"html"` (VitePress without `cleanUrls`), `./` in front of a relative one, and `target="_blank" rel="noreferrer"` on an external one; code blocks in `<div class="language-js vp-adaptive-theme">` with the copy button, the language label (`vue-html` as `template`), each line in a `<span class="line">`, and a `[title]` as the block's title; tables with `tabindex="0"`; and the `tip`, `info`, `warning`, `danger`, `details`, `raw` and `code-group` containers, with VitePress's default titles. `[[toc]]` (in any case) is the page's `h2`s and `h3`s as markdown-it-table-of-contents writes them, and HTML comments are left out, as Vue's server renderer leaves them out. Unless you set them, it also sets `headingIds: "vitepress"`, `autolinks: "email"` and `containers: "markdown-it"`. Highlighted code has ssqch's classes, not Shiki's colors. Use it with `markdownEngine: false`: Vue's `{{ }}` in the pages isn't a template language's. |
|
|
35
|
-
| `encodeUrls` | `true` | Link and image URLs are percent-encoded, as CommonMark's reference renderer writes them (`#كتابة` as `#%D9%83...`, `café.png` as `caf%C3%A9.png`). `false` writes them as the page has them, HTML-escaped only (`&` as `&`), as kramdown (Jekyll) does, so a move compares clean; browsers go to the same place either way. A link or image hook gets the URL as written in both. |
|
|
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)). |
|
|
38
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. |
|
|
39
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).
|
|
35
|
+
|
|
40
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">`.
|
|
41
37
|
|
|
42
38
|
**Your own languages:** `languages`, in `highlight: { languages: { ... } }`, gives a highlighter for a language ssqch doesn't have (a custom syntax highlighter), or replaces a built-in one. Each name is a fence's language, matched in any case, and it comes before the built-in grammars. A highlighter can be a function, `(code, lang) => tokens`, that returns the code cut into tokens, as `[text, kind]` pairs or `{ text, kind }` objects, where `kind` is one of the `hl-*` names without the prefix (`comment`, `keyword`, `operator`, `string`, `regexp`, `escape`, `number`, `constant`, `builtin`, `property`, `attribute`, `function`, `type`, `parameter`, `tag`, `heading`, `strong`, `emphasis`, `link`, `inserted` or `deleted`) and a token without one (or a plain string) is plain text. ssqch escapes the text and writes the spans, so marked lines and `/highlight.css` work as they do for the built-in languages. The tokens' text has to add up to the code; when it doesn't, or the function throws or returns another kind, the build warns (naming the page) and that fence is plain text. A highlighter can also be another language's name, an alias (`cho: "chordpro"`, `jsx: "js"`), or the path of a Sublime Text `.sublime-syntax` grammar from the project root, for a language that has one. A replacement only takes the name it's given: `js: fn` leaves `javascript` fences to the built-in grammar, unless you add `javascript: "js"`. The languages apply everywhere highlighting does: fences, `highlight(code, lang)` and a fence hook's `highlighted`.
|
|
@@ -55,7 +51,7 @@ export default { markdown: { highlight: { languages: { trailnotes, trail: "trail
|
|
|
55
51
|
|
|
56
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.
|
|
57
53
|
|
|
58
|
-
**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 (`
|
|
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:
|
|
59
55
|
|
|
60
56
|
```markdown
|
|
61
57
|
::: warning Hot pine cones
|
|
@@ -99,7 +95,7 @@ Pine Cone Crunch
|
|
|
99
95
|
| --- | --- | --- |
|
|
100
96
|
| `heading.*` | `heading.level`, `id`, `text`, `content` (the inner HTML) and `attrs` | Anchor links next to headings |
|
|
101
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 |
|
|
102
|
-
| `link.*` | `link.href` (the URL as the page wrote it
|
|
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 |
|
|
103
99
|
| `image.*` | `image.src`, `alt` and `title` | `<figure>` with a caption |
|
|
104
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 |
|
|
105
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 |
|
package/bundled/docs/nav.yml
CHANGED
|
@@ -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:
|
|
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
|
package/bundled/docs/netlify.md
CHANGED
|
@@ -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.
|
|
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.1`) and bump it when you're ready.
|
|
22
22
|
- **`NODE_VERSION`** is the Node that runs the build: anything from 22.18 on. ssqch builds the same bytes on every supported Node, so pick the one your other build tools like.
|
|
23
23
|
- **[`netlify-plugin-cache`](https://github.com/jakejarvis/netlify-plugin-cache)** carries `.cache/ssqch` (the encoded images and their hashes, highlighted code, and any `fetch` copies) over to the next build. Add it to your `devDependencies`.
|
|
24
24
|
|
|
25
|
-
A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.
|
|
25
|
+
A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.13.1"` 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`).
|
package/bundled/docs/plugins.md
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
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
|
|
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
|
|
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
|
-
|
|
13
|
-
- **`ssqch/
|
|
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).
|
|
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, with "Optional" last) and `sort` (a function that compares two pages, as `Array.prototype.sort` takes it; default by URL). `paths` (parts of the site with an `llms.txt` of their own, like `["/docs/"]`), `budget` (the most characters an `llms.txt` has before pages move into "Optional"; default 50,000) and the template function `llmsTxt(page.url)`, in [A big site's llms.txt](robots.md#a-big-sites-llmstxt). 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.
|
|
15
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,85 @@
|
|
|
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
|
+
### A big site's llms.txt
|
|
59
|
+
|
|
60
|
+
`llms.txt` is the map an agent reads before it decides where to go, so it has to stay short enough to read whole (llms.txt's proposal: "small enough to fit in context"). Three options keep it that way:
|
|
61
|
+
|
|
62
|
+
- `paths`: parts of the site that get an `llms.txt` of their own, which covers the pages under it (llms.txt's v2 has agents use the most specific one). `paths: ["/docs/"]` writes `/docs/llms.txt` with the pages under `/docs/`, and `/llms.txt` lists that file once, where its first page would be, in place of them. An item is a URL path that starts and ends with `/`, or `{ path: "/docs/api/", title: "Trail API", description: "Every endpoint.", details: "..." }` for the file's `#` heading (default: the site's title and the folder's name, `Trail Guide: Docs`), its `>` line and its Markdown after that; the title and description are also its line in the file above it. Inside a file, a page's section is its folder under the path (`/docs/guide/start/` is "Guide" in `/docs/llms.txt`), unless `section` names one. A path can be under another (`/docs/` and `/docs/api/`), and a path with no listed pages writes no file and warns. `llms-full.txt` stays one file with every page.
|
|
63
|
+
- A section named "Optional" always comes last: llms.txt's convention for links an agent can skip when its context is short. `section: (page) => (page.date < new Date("2020-01-01") ? "Optional" : undefined)` puts old posts there and leaves the rest in their folder's section.
|
|
64
|
+
- `budget`: the most characters an `llms.txt` may have, 50,000 by default (where `ssqch patrol` warns, `llms-long`). Past it, pages from the end of the file move into "Optional" without their descriptions until it fits. A file that wouldn't fit even with every page moved stays as it is, and the build warns with what to do: give a part of the site its own file with `paths`, or raise `budget`. `budget: false` turns it off.
|
|
65
|
+
|
|
66
|
+
`ssqch patrol` reads `/llms.txt` and every `llms.txt` it links, with the same checks, and counts the pages they all list.
|
|
67
|
+
|
|
68
|
+
## The links in the layout
|
|
69
|
+
|
|
70
|
+
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):
|
|
71
|
+
|
|
72
|
+
```html
|
|
73
|
+
<link rel="canonical" href="{{ site.url }}{{ page.url }}">
|
|
74
|
+
{% if markdownCopy(page.url) %}<link rel="alternate" type="text/markdown" href="{{ markdownCopy(page.url) }}">{% endif %}
|
|
75
|
+
<link rel="describedby" href="{{ llmsTxt(page.url) }}">
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`markdownCopy(page.url)` comes with `llmsPlugin()`: the copy's URL, or `""` for a page without one. The starters' layouts have all three, with `/llms.txt` written out.
|
|
79
|
+
`llmsTxt(page.url)` comes with it too: the `llms.txt` that covers the page, `/docs/llms.txt` for a page under `/docs/` when `paths` has it and `/llms.txt` for the rest.
|
|
80
|
+
|
|
81
|
+
A copy is a Markdown file, with no `<head>` to point from: llms.txt's v2 points from it with an HTTP `Link` header, which a host's `_headers` file (Netlify, Cloudflare) sends for a folder, like `/docs/*` with `Link: </docs/llms.txt>; rel="describedby"`. ssqch adds no line to the copy itself, so a copy says what its page says and nothing more.
|
|
82
|
+
|
|
83
|
+
## When an agent asks for Markdown
|
|
84
|
+
|
|
85
|
+
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.
|
package/bundled/docs/seo.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "SEO tags"
|
|
2
|
+
title: "Getting spotted: SEO tags"
|
|
3
3
|
description: "ssqch writes no <head> tags of its own, so a site's title, description, canonical link, Open Graph and Twitter tags are a partial in its layout."
|
|
4
4
|
---
|
|
5
5
|
ssqch writes no `<head>` tags of its own, so a site's title, description, canonical link, Open Graph and Twitter tags are a partial in its layout. A starting point (Nunjucks):
|
|
@@ -18,40 +18,4 @@ ssqch writes no `<head>` tags of its own, so a site's title, description, canoni
|
|
|
18
18
|
|
|
19
19
|
JSON-LD, if the site wants it, is a `json` (Liquid), `tojson` (Jinja) or `dump` (Nunjucks) of an object built in the template or by a filter.
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
```liquid
|
|
24
|
-
{%- comment -%} _includes/seo.liquid {%- endcomment -%}
|
|
25
|
-
{%- assign site_title = site.title | default: site.name | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
26
|
-
{%- assign page_title = title | markdownify | strip_html | normalize_whitespace | escape_once | default: site_title -%}
|
|
27
|
-
{%- assign about = description | default: site.description | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
28
|
-
{%- if page_title != site_title -%}{%- assign full_title = page_title | append: " | " | append: site_title -%}{%- elsif site.description -%}{%- assign full_title = site_title | append: " | " | append: about -%}{%- else -%}{%- assign full_title = site_title -%}{%- endif -%}
|
|
29
|
-
{%- assign canonical = site.url | append: page.url -%}
|
|
30
|
-
{%- if image -%}{%- assign image_url = site.url | append: image -%}{%- endif -%}
|
|
31
|
-
{%- if date or tags -%}{%- assign published = page.date | date_to_xmlschema -%}{%- endif -%}
|
|
32
|
-
{%- if page.url == "/" or page.url == "/about/" -%}{%- assign ld_type = "WebSite" -%}{%- elsif published -%}{%- assign ld_type = "BlogPosting" -%}{%- else -%}{%- assign ld_type = "WebPage" -%}{%- endif -%}
|
|
33
|
-
<!-- Begin Jekyll SEO tag v2.8.0 -->
|
|
34
|
-
<title>{{ full_title }}</title>
|
|
35
|
-
<meta name="generator" content="{{ ssqch.generator }}" />
|
|
36
|
-
<meta property="og:title" content="{{ page_title }}" />
|
|
37
|
-
<meta property="og:locale" content="{{ lang | default: site.lang | default: "en_US" | replace: "-", "_" }}" />
|
|
38
|
-
{% if about %}<meta name="description" content="{{ about }}" />
|
|
39
|
-
<meta property="og:description" content="{{ about }}" />
|
|
40
|
-
{% endif %}{% if site.url %}<link rel="canonical" href="{{ canonical }}" />
|
|
41
|
-
<meta property="og:url" content="{{ canonical }}" />
|
|
42
|
-
{% endif %}<meta property="og:site_name" content="{{ site_title }}" />
|
|
43
|
-
{% if image_url %}<meta property="og:image" content="{{ image_url }}" />
|
|
44
|
-
{% endif %}{% if published %}<meta property="og:type" content="article" />
|
|
45
|
-
<meta property="article:published_time" content="{{ published }}" />
|
|
46
|
-
{% else %}<meta property="og:type" content="website" />
|
|
47
|
-
{% endif %}<meta name="twitter:card" content="{% if image_url %}summary_large_image{% else %}summary{% endif %}" />
|
|
48
|
-
{% if image_url %}<meta property="twitter:image" content="{{ image_url }}" />
|
|
49
|
-
{% endif %}<meta property="twitter:title" content="{{ page_title }}" />
|
|
50
|
-
{% if site.twitter.username %}<meta name="twitter:site" content="@{{ site.twitter.username | remove: "@" }}" />
|
|
51
|
-
{% endif %}{% if site.facebook.publisher %}<meta property="article:publisher" content="{{ site.facebook.publisher }}" />
|
|
52
|
-
{% endif %}<script type="application/ld+json">
|
|
53
|
-
{"@context":"https://schema.org","@type":{{ ld_type | jsonify }}{% if published %},"dateModified":{{ published | jsonify }},"datePublished":{{ published | jsonify }}{% endif %}{% if about %},"description":{{ about | jsonify }}{% endif %},"headline":{{ page_title | jsonify }}{% if image_url %},"image":{{ image_url | jsonify }}{% endif %}{% if ld_type == "BlogPosting" %},"mainEntityOfPage":{"@type":"WebPage","@id":{{ canonical | jsonify }}}{% endif %}{% if ld_type == "WebSite" %},"name":{{ site_title | jsonify }}{% endif %}{% if site.logo %},"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":{{ site.url | append: site.logo | jsonify }}}}{% endif %},"url":{{ canonical | jsonify }}}</script>
|
|
54
|
-
<!-- End Jekyll SEO tag -->
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
A function can write all of it instead, when the template passes it what it needs: functions are Liquid tags too, so `{% seo page, title, description %}` calls `seo(page, title, description)` (a function doesn't see the page unless it's given). opensource.guide's port did that, writing jekyll-seo-tag's bytes, JSON-LD included, in 100 lines.
|
|
21
|
+
A Jekyll site's `{% seo %}` (jekyll-seo-tag) becomes an include that writes the same tags: it's in [the Jekyll trailhead](trailheads/from-jekyll.md#from-jekyll-seo-tag), and `ssqch scout` drafts it.
|