ssqch 0.9.0 → 0.10.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/README.md +1 -1
- package/bundled/completions/bash +1 -1
- package/bundled/completions/elvish +1 -0
- package/bundled/completions/fish +1 -0
- package/bundled/completions/powershell +1 -0
- package/bundled/completions/zsh +1 -0
- package/bundled/docs/agents.md +70 -0
- package/bundled/docs/benchmarks.md +29 -0
- package/bundled/docs/build-summary.md +57 -0
- package/bundled/docs/comparing-builds.md +51 -0
- package/bundled/docs/configuring.md +138 -0
- package/bundled/docs/content-schemas.md +54 -0
- package/bundled/docs/css-and-javascript.md +33 -0
- package/bundled/docs/data-files.md +55 -0
- package/bundled/docs/deploying.md +47 -0
- package/bundled/docs/field-guide.md +144 -0
- package/bundled/docs/footprint.md +27 -0
- package/bundled/docs/github-pages.md +41 -0
- package/bundled/docs/index.md +26 -0
- package/bundled/docs/install.md +27 -0
- package/bundled/docs/known-gaps.md +18 -0
- package/bundled/docs/markdown.md +114 -0
- package/bundled/docs/multilingual.md +14 -0
- package/bundled/docs/nav.yml +50 -0
- package/bundled/docs/netlify.md +30 -0
- package/bundled/docs/new-pages.md +42 -0
- package/bundled/docs/plugins.md +13 -0
- package/bundled/docs/rust-plugins.md +32 -0
- package/bundled/docs/seo.md +19 -0
- package/bundled/docs/template-languages.md +106 -0
- package/bundled/docs/templates.md +37 -0
- package/bundled/docs/themes.md +31 -0
- package/bundled/{trailheads → docs/trailheads}/from-component-frameworks.md +7 -3
- package/bundled/{trailheads → docs/trailheads}/from-docusaurus.md +7 -4
- package/bundled/{trailheads → docs/trailheads}/from-eleventy.md +7 -4
- package/bundled/{trailheads → docs/trailheads}/from-hexo.md +7 -4
- package/bundled/{trailheads → docs/trailheads}/from-jekyll.md +6 -3
- package/bundled/{trailheads → docs/trailheads}/from-mkdocs.md +8 -5
- package/bundled/{trailheads → docs/trailheads}/from-zola.md +6 -3
- package/bundled/docs/trailheads.md +38 -0
- package/bundled/docs/where-values-come-from.md +57 -0
- package/bundled/ssqch.d.ts +10 -3
- package/lib/assets.js +18 -12
- package/lib/{chunk-7PWCYHTJ.js → chunk-26SHWRC6.js} +6 -8
- package/lib/{chunk-GUKSZ2XM.js → chunk-3BQJY6GF.js} +4 -6
- package/lib/{chunk-TICWN55Z.js → chunk-3LODFCCH.js} +2 -3
- package/lib/{chunk-TVU3OPPK.js → chunk-3NDFUMV2.js} +3 -3
- package/lib/{chunk-YTHQBMDJ.js → chunk-6OUT5VFK.js} +3 -6
- package/lib/{chunk-HXCLCXRT.js → chunk-6RSZV5O2.js} +5 -3
- package/lib/{chunk-4Q6WMTER.js → chunk-7JGYYAKI.js} +1 -1
- package/lib/{chunk-MI6EJWA2.js → chunk-BT3NVQOD.js} +1 -1
- package/lib/{chunk-DDV6JEC2.js → chunk-BXARVN5Z.js} +1 -1
- package/lib/{chunk-RNJFPFXE.js → chunk-CXRHH5P5.js} +5 -6
- package/lib/{chunk-HPXAZ2HU.js → chunk-DNWA7WNO.js} +1 -1
- package/lib/{chunk-SURPOAW7.js → chunk-DTSTCVRX.js} +8 -9
- package/lib/{chunk-7SD7K567.js → chunk-DUGGZ4EE.js} +1 -1
- package/lib/{chunk-7XLK2GEG.js → chunk-ERNVEZOK.js} +1 -1
- package/lib/{chunk-3A647I3N.js → chunk-FYRC2HBU.js} +4 -6
- package/lib/{chunk-IJWHOFRP.js → chunk-FYU22VDK.js} +12 -13
- package/lib/{chunk-II5DEH3Q.js → chunk-FZGJUJAL.js} +5 -7
- package/lib/{chunk-BEGC7YP6.js → chunk-G67W2FTJ.js} +9 -11
- package/lib/{chunk-7RDRZHJD.js → chunk-HMVYNV6M.js} +13 -15
- package/lib/{chunk-DELWRJAO.js → chunk-HNG372DW.js} +143 -74
- package/lib/{chunk-47P4YREZ.js → chunk-II7ZRIAC.js} +11 -13
- package/lib/{chunk-NCWFYT74.js → chunk-IOXCGMSF.js} +5 -7
- package/lib/{chunk-GRWMGC7D.js → chunk-JFPLNHEQ.js} +2410 -2298
- package/lib/{chunk-LPHNACE4.js → chunk-LU73FTIR.js} +10 -11
- package/lib/{chunk-D2XE2GTY.js → chunk-LYPKL524.js} +9 -10
- package/lib/{chunk-NKXEPHRZ.js → chunk-MDB3D3LP.js} +106 -4
- package/lib/{chunk-CZ4XQC56.js → chunk-MDG5A4NI.js} +15 -13
- package/lib/{chunk-SXMJ52IK.js → chunk-MUYWL4ZX.js} +58 -19
- package/lib/{chunk-R7K3D5W5.js → chunk-P2TRR6XK.js} +83 -24
- package/lib/{chunk-SF4I6Z7S.js → chunk-R2YGC3VE.js} +2 -3
- package/lib/{chunk-76NTVE34.js → chunk-RFNLZM7W.js} +2 -4
- package/lib/{chunk-3K3ANWZ2.js → chunk-X7C6GFUM.js} +4 -4
- package/lib/{chunk-XMXBHXZR.js → chunk-XR7GFL4B.js} +12 -13
- package/lib/{chunk-NNUKIGOO.js → chunk-ZZBHBLDB.js} +16 -18
- package/lib/cli.js +25 -25
- package/lib/elements.js +10 -12
- package/lib/image.js +10 -11
- package/lib/links.js +13 -15
- package/lib/minify.js +9 -10
- package/lib/redirects.js +11 -13
- package/lib/rss.js +22 -22
- package/lib/sass.js +10 -12
- package/lib/sitemap.js +10 -12
- package/lib/ssqch.js +4 -5
- package/package.json +2 -2
- package/types/index.d.ts +9 -2
- package/types/rss.d.ts +1 -1
- package/bundled/README.md +0 -1314
- package/lib/chunk-VJWQSYEG.js +0 -119
- package/lib/{chunk-DELWRJAO.js.LEGAL.txt → chunk-HNG372DW.js.LEGAL.txt} +0 -0
- package/lib/{chunk-GRWMGC7D.js.LEGAL.txt → chunk-JFPLNHEQ.js.LEGAL.txt} +3 -3
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Deploying"
|
|
3
|
+
description: "Encoding images is by far the slowest part of a build, so it's worth never doing it twice."
|
|
4
|
+
---
|
|
5
|
+
<img align="right" src="../../../docs/assets/stickers/canoe.svg" alt="" width="96">
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
## Keep the image cache between builds
|
|
9
|
+
|
|
10
|
+
Encoding images is by far the slowest part of a build, so it's worth never doing it twice. Each image file is named by a hash of the source image's contents and the encoder settings, not its path or modification time, and it's encoded into `.cache/ssqch/img/`, outside the output. Each build links the files it uses into the output's `img/` folder (a hard link, so no extra space, or a copy where links don't work), so you can delete the output folder whenever you like and the next build encodes nothing. Restore `.cache/ssqch` from the last build in CI, and a build with no new images encodes nothing there either, even on a fresh clone. (An output folder from before the cache, or one a deploy cache restored, is taken in as it is: its files move into the cache instead of being encoded again.) `cacheDir` on `imagePlugin()` puts the cache somewhere else, and `cacheDir: false` encodes straight into the output, which then has to be kept to keep the images.
|
|
11
|
+
|
|
12
|
+
ssqch also remembers each source image's hash, size and modification time in `.cache/ssqch/image-hashes.json`, so unchanged images aren't read again. (A fresh clone gives every file a new modification time, so its first build re-hashes everything, which takes about 20 ms on the blog's 420 MB of images.) Add `.cache/` to your `.gitignore`, or turn the hash cache off with `hashCache: false`. It's kept outside the output folder because it names your source paths, and the output gets published.
|
|
13
|
+
|
|
14
|
+
Set `prune: true` on `imagePlugin()` to delete image files the build didn't use, in the output and in the cache, so the cache doesn't keep growing as images change. Only turn it on for full builds, where every image goes through the image plugin.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
## Serving a site under a path
|
|
18
|
+
|
|
19
|
+
A GitHub Pages project site lives at `https://you.github.io/repo/`, not at the root of a domain, so a link to `/about/` would miss. Set `base` and leave the templates alone:
|
|
20
|
+
|
|
21
|
+
```js
|
|
22
|
+
export default defineConfig({
|
|
23
|
+
base: "/repo/",
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- **HTML:** in every page ssqch writes, a URL that starts with `/` gets the base in front: `href`, `src`, `srcset`, `action`, `poster` and the other URL attributes, a meta refresh, and `url()` in `style` attributes and `<style>` elements. That covers Markdown links, images from `imagePlugin()`, fingerprinted assets, redirect pages and Sass output. Relative URLs, `#fragments` and URLs with a domain aren't changed, so a link to something else on the same domain needs the whole address (`https://you.github.io/other-project/`).
|
|
28
|
+
- **Everywhere else:** in an inline script, a JSON file or a feed, call `withBase("/search.json")`, or print `ssqch.base` (`/repo`, or an empty string without a base). The feed filters add it for you: `absoluteUrl(post.url, site.url)` is `https://example.com/repo/posts/pine/`, with or without the path in `site.url`, and a URL that already has the base keeps one. Don't use `withBase()` inside an HTML attribute, or the URL gets the base twice (the link checker reports it).
|
|
29
|
+
- **`page.url` and collections:** unchanged, so `page.url == item.url` and the navigation helpers work the same with or without a base.
|
|
30
|
+
- **The output folder:** unchanged too. `dist/about/index.html` is what the host serves at `/repo/about/`.
|
|
31
|
+
- **Plugins:** `linksPlugin()` checks links under the base (other paths on the domain count as external), and `sitemapPlugin({ url })` takes the address with or without the base in it.
|
|
32
|
+
- **`ssqch serve`:** serves the site at `http://localhost:8080/repo/`, so what you click through locally is what the host will serve.
|
|
33
|
+
|
|
34
|
+
`ssqch build --base /repo/` sets it from the command line (for a preview deployed under another path, say) and wins over the config. In `sitesquatch.toml` it's `base = "/repo/"`.
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
## Search
|
|
38
|
+
|
|
39
|
+
ssqch doesn't build a search index itself; [Pagefind](https://pagefind.app) does it well and runs after the build. Add it as a command (`npx` comes with Node, or install Pagefind's own binary):
|
|
40
|
+
|
|
41
|
+
```js
|
|
42
|
+
export default defineConfig(({ env }) => ({
|
|
43
|
+
afterBuild: env === "production" ? [{ run: "npx -y pagefind --site dist" }] : [],
|
|
44
|
+
}));
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Then load `/pagefind/pagefind-ui.js` and `pagefind-ui.css` in your layout and add a `<div id="search">` for its search box. The `docs-sidebar` example does this.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Field guide: build your first site"
|
|
3
|
+
navTitle: "Field guide"
|
|
4
|
+
description: "The quickest way in is ssqch init, which sets up camp (a config, a layout, a home page, five posts, a 404 page, a data file, a blueprint for the next post, editor types, and an AGENTS.md for coding agents) and then leaves you to it."
|
|
5
|
+
---
|
|
6
|
+
<img align="right" src="../../../docs/assets/stickers/compass.svg" alt="" width="96">
|
|
7
|
+
|
|
8
|
+
The quickest way in is `ssqch init`, which sets up camp (a config, a layout, a home page, five posts, a 404 page, a data file, a blueprint for the next post, editor types, and an `AGENTS.md` for coding agents) and then leaves you to it:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
ssqch init my-site
|
|
12
|
+
cd my-site && ssqch serve
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Haven't installed it yet? `npx ssqch init my-site`, then `npx ssqch serve` in the new folder, works too. Open <http://localhost:8080>, edit `src/posts/i-know-what-i-saw.md`, and watch the page reload. (The starter is an amateur investigator's field notes: a sighting, a correction, a stump, an old map and a raccoon's cache. The posts are short, and each one shows you something.) `ssqch init` never overwrites a file that's already there, so it's safe to run in a folder you've started.
|
|
16
|
+
|
|
17
|
+
The layout and home page are [Jinja](template-languages.md#jinja-and-nunjucks) templates, ssqch's default language. To start in another one, pass `--engine edge`, `--engine liquid`, `--engine njk` (Nunjucks) or `--engine hbs` (Handlebars); the config then lists that engine in `templateFormats` and runs Markdown through it. `--engine` works with `--starter docs` too.
|
|
18
|
+
|
|
19
|
+
Writing documentation? `ssqch init my-docs --starter docs` creates a docs site instead: a light and dark switch, a sidebar, breadcrumbs and previous/next links from one `nav.yml`, a table of contents on each page, notes and tabs, highlighted code, a schema that checks each page's front matter, the link checker, and Pagefind search with `SEARCH=1`. The pages are plain HTML that reads fine without JavaScript (a small script turns tab sections into tabs), and every file is yours to edit: there's no theme package underneath.
|
|
20
|
+
|
|
21
|
+
To see how the pieces fit, here's a small site built by hand: a home page that lists posts. This is all of it:
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
ssqch.config.js
|
|
25
|
+
src/
|
|
26
|
+
_includes/layout.jinja
|
|
27
|
+
index.jinja
|
|
28
|
+
posts/pine-cone-crunch.md
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## Step 1: The config
|
|
33
|
+
|
|
34
|
+
`ssqch.config.js` sits in your project root. This one reads templates from `src`, writes to `dist`, and adds a `shout` filter:
|
|
35
|
+
|
|
36
|
+
```js
|
|
37
|
+
// ssqch.config.js
|
|
38
|
+
import { defineConfig } from "ssqch";
|
|
39
|
+
|
|
40
|
+
export default defineConfig({
|
|
41
|
+
dirs: { input: "src", output: "dist" },
|
|
42
|
+
filters: {
|
|
43
|
+
shout: (text) => `${text.toUpperCase()}!`,
|
|
44
|
+
},
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
## Step 2: A layout
|
|
50
|
+
|
|
51
|
+
Layouts live in `src/_includes`. In `src/_includes/layout.jinja`, `{{ content }}` is where each page's body goes (Jinja escapes what it prints, but `content` is already HTML, so it's marked safe):
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<!doctype html>
|
|
55
|
+
<html lang="en">
|
|
56
|
+
<head><title>{{ title }}</title></head>
|
|
57
|
+
<body>
|
|
58
|
+
<main>{{ content }}</main>
|
|
59
|
+
</body>
|
|
60
|
+
</html>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
## Step 3: A post and a home page
|
|
65
|
+
|
|
66
|
+
Front matter sets each page's data, and it has to come first in the file. Tagging the post `posts` puts it in `collections.posts`. Save this as `src/posts/pine-cone-crunch.md`:
|
|
67
|
+
|
|
68
|
+
```markdown
|
|
69
|
+
---
|
|
70
|
+
layout: layout.jinja
|
|
71
|
+
title: Pine Cone Crunch
|
|
72
|
+
tags: posts
|
|
73
|
+
---
|
|
74
|
+
Crunchy, foresty, and only slightly sticky.
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The home page, `src/index.jinja`, uses the filter and loops over the posts:
|
|
78
|
+
|
|
79
|
+
```html
|
|
80
|
+
---
|
|
81
|
+
layout: layout.jinja
|
|
82
|
+
title: Squatch Snacks
|
|
83
|
+
---
|
|
84
|
+
<h1>{{ title | shout }}</h1>
|
|
85
|
+
<ul>
|
|
86
|
+
{% for post in collections.posts %}
|
|
87
|
+
<li><a href="{{ post.url }}">{{ post.data.title }}</a></li>
|
|
88
|
+
{% endfor %}
|
|
89
|
+
</ul>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
## Step 4: Build it
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
ssqch build
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
You'll see a line for each page, then a summary:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
[ssqch] Writing ./dist/index.html from ./src/index.jinja (jinja)
|
|
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)
|
|
105
|
+
Pages 2 written from 2 templates, 410 B
|
|
106
|
+
Output dist: 2 files, 410 B
|
|
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
|
+
```
|
|
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`.)
|
|
111
|
+
|
|
112
|
+
To work on it with live reload, run the dev server and open <http://localhost:8080>:
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
ssqch serve
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
First confirmed siting. Built in 2.75 ms (development)
|
|
120
|
+
...
|
|
121
|
+
Serving dist at http://localhost:8080/. Squatch Watch is on.
|
|
122
|
+
Fresh tracks in src/posts/pine-cone-crunch.md
|
|
123
|
+
Built in 1.92 ms (development)
|
|
124
|
+
...
|
|
125
|
+
Serving dist at http://localhost:8080/. Squatch Watch is on.
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The address comes after each build's report, so it's on the last line however long the build was. With `--quiet`, the server prints the address once, without its name, and then only warnings and errors.
|
|
129
|
+
|
|
130
|
+
`ssqch serve` (it answers to Squatch Watch) rebuilds when your sources change, and it's careful about what it disturbs:
|
|
131
|
+
|
|
132
|
+
- **Only the page you're on reloads,** and only if it came out different. Edit another post, and the tab you're looking at stays where it is. The summary says how many pages changed: `Pages 168 written from 140 templates, 6.83 MB (1 changed)`.
|
|
133
|
+
- **A stylesheet is swapped in place,** without a reload, so the page keeps its scroll position and a half-filled form. That goes for CSS another tool writes into the output folder too (a PostCSS watcher, say): the browser hears about it without a rebuild, once the tool has finished writing it, so a page never reloads before its new CSS is there. The old stylesheet stays until the new one has loaded, so the page is never unstyled in between, and a new one that doesn't load (or comes back empty) leaves the old one in place. A changed script or image reloads the page.
|
|
134
|
+
- **A build that fails shows up in the browser,** over the page, with the error and the lines it's about. The tab's title and icon say so too, which is how you find out from another window. "Copy diagnostic" copies the error to paste into an issue or a chat, and Escape (or "Hide") puts it away until the error changes. The page underneath is from the last build that worked, and the next good build clears the error and says so in the terminal: `Build recovered. Back on the trail.`
|
|
135
|
+
- **A URL that isn't there** gets the site's `404.html`, or, when the site has none, a page of the server's own that says where the trail went cold and suggests the closest URL.
|
|
136
|
+
- **A site without a `favicon.ico`** gets a map-paper footprint on a pine circle in the tab. While the build is broken, the circle turns burnt orange.
|
|
137
|
+
|
|
138
|
+
None of that is written to the output folder: the server adds it to pages as it sends them.
|
|
139
|
+
|
|
140
|
+
**What it watches:** the input folder, a theme's folder, the config and the modules it imports, the config's `watch` paths, and the files plugins read (a Sass partial in a folder the config never named). A change to the config, or to code it imports, reloads all of it, so a filter you edited is the new one on the next build. Builds run in a process of their own, so the server keeps answering while a build runs, and a site's code that crashes or calls `process.exit()` fails that one build rather than the server. It listens on `127.0.0.1` only.
|
|
141
|
+
|
|
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
|
+
|
|
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 import`](trailheads.md), [`ssqch capabilities`](agents.md) and [`ssqch docs`](agents.md), and `ssqch build --format json` reports to a [script or a coding agent](agents.md).
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "A build's footprint"
|
|
3
|
+
description: "ssqch footprint says how much the last build weighs, by kind of file, and which pages and files leave the largest footprints."
|
|
4
|
+
---
|
|
5
|
+
`ssqch footprint` says how much the last build weighs, by kind of file, and which pages and files leave the largest footprints:
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
$ ssqch footprint
|
|
9
|
+
Footprint of dist: 4,965 files, 302 MB
|
|
10
|
+
Pages 163 files 6.91 MB 2%
|
|
11
|
+
Images 4,782 files 291 MB 96%
|
|
12
|
+
CSS 1 file 58.2 KB <1%
|
|
13
|
+
JavaScript 2 files 7.61 KB <1%
|
|
14
|
+
Fonts 9 files 708 KB <1%
|
|
15
|
+
|
|
16
|
+
Largest footprints: pages
|
|
17
|
+
108 KB /build-a-secure-node-js-application-with-javascript-async-await-using-hapi/
|
|
18
|
+
104 KB /avatars/
|
|
19
|
+
|
|
20
|
+
Largest footprints: other files
|
|
21
|
+
3.15 MB /static/job-hunt-ai-cheat-sheet.pdf
|
|
22
|
+
2.10 MB /img/ElD54Br0Nm-1200.png
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
It reads the site's output folder, or any build folder you name (`ssqch footprint dist-before`), so build first. `--top 20` lists more of the heaviest (0 for none), and `--format json` gives the same as data: `files`, `bytes`, `kinds` and `largest.pages` and `largest.files`, each with its `path` and `bytes`.
|
|
26
|
+
|
|
27
|
+
To keep a site light, give the config `budgets`. Every build then checks the output against them, after plugins like `assetsPlugin()` have run, and warns about whatever is over: `warn: 2 pages are over the pages budget of 100 KB: /build-a-secure-node-js-application-with-javascript-async-await-using-hapi/ (108 KB), /avatars/ (104 KB)`.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "GitHub Pages"
|
|
3
|
+
description: "A project site is served at https://you.github.io/<repository>/, so the build needs that path as its base."
|
|
4
|
+
---
|
|
5
|
+
A project site is served at `https://you.github.io/<repository>/`, so the build needs that path as its [`base`](deploying.md#serving-a-site-under-a-path). This workflow builds on every push to `main` and deploys with GitHub's own Pages actions (in the repository's settings, set Pages' source to "GitHub Actions"):
|
|
6
|
+
|
|
7
|
+
```yaml
|
|
8
|
+
# .github/workflows/pages.yml
|
|
9
|
+
name: Deploy to GitHub Pages
|
|
10
|
+
on:
|
|
11
|
+
push:
|
|
12
|
+
branches: [main]
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
pages: write
|
|
16
|
+
id-token: write
|
|
17
|
+
jobs:
|
|
18
|
+
deploy:
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
environment:
|
|
21
|
+
name: github-pages
|
|
22
|
+
url: ${{ steps.deployment.outputs.page_url }}
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@v4
|
|
25
|
+
- uses: actions/setup-node@v4
|
|
26
|
+
with:
|
|
27
|
+
node-version: 24
|
|
28
|
+
cache: npm
|
|
29
|
+
- run: npm ci
|
|
30
|
+
- run: npx ssqch build --output dist --base "/${{ github.event.repository.name }}/"
|
|
31
|
+
- uses: actions/upload-pages-artifact@v3
|
|
32
|
+
with:
|
|
33
|
+
path: dist
|
|
34
|
+
- id: deployment
|
|
35
|
+
uses: actions/deploy-pages@v4
|
|
36
|
+
```
|
|
37
|
+
|
|
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.8.0` (drop `cache: npm`, which looks for a lockfile) and runs `ssqch build` instead of `npx ssqch build`.
|
|
40
|
+
- **A 404 page:** GitHub Pages serves `404.html` from the site's root, so give your 404 page `permalink: /404.html`.
|
|
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)).
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "SiteSquatch"
|
|
3
|
+
navTitle: "Introduction"
|
|
4
|
+
description: "SiteSquatch (ssqch) is a static site generator for Node.js."
|
|
5
|
+
---
|
|
6
|
+
<img align="right" src="../../../docs/assets/stickers/sitesquatch.svg" alt="SiteSquatch, a Sasquatch with a deadpan stare" width="180">
|
|
7
|
+
|
|
8
|
+
SiteSquatch (`ssqch`) is a static site generator for Node.js: large, quick, and rarely photographed. Write your pages in Markdown and [Jinja](https://jinja.palletsprojects.com/) (the default), [Edge.js](https://edgejs.dev), [Liquid](https://shopify.github.io/liquid/), [Nunjucks](https://mozilla.github.io/nunjucks/), [Handlebars](https://handlebarsjs.com/), [Mustache](https://mustache.github.io/) or [EJS](https://ejs.co/), configure the site in JavaScript, and `ssqch build` turns it all into plain HTML. Your config runs on Node, so any npm package you already know works in it.
|
|
9
|
+
|
|
10
|
+
It moves fast for its size. [reverentgeek.com](https://reverentgeek.com) (168 pages, a feed, a sitemap and about 4,700 responsive image files) rebuilds in **under a second** once its images are cached, which is gone before you've found your camera. [Benchmarks](benchmarks.md) has the measurements.
|
|
11
|
+
|
|
12
|
+
It reports like a park ranger who has seen some things. What happened comes first, with the file and the line, and now and then something large walks through the log. The jokes never stand in for the facts, the JSON output has none, and nothing of ssqch's own is ever added to the pages it builds.
|
|
13
|
+
|
|
14
|
+
What's in the pack:
|
|
15
|
+
|
|
16
|
+
- **A data cascade, layouts, collections, pagination and permalinks**, so a blog or docs site needs no custom code.
|
|
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
|
+
- **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
|
+
- **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.
|
|
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
|
+
- **Themes without a package manager, custom elements that load only where they're used**, Sass (yes, Sassquatch), a sitemap, redirects, RSS helpers, HTML minification and asset fingerprinting.
|
|
23
|
+
- **A quick start and a way in:** `ssqch init` (a blog, or a docs site with a sidebar and search), `ssqch import` for Eleventy and Zola sites, [`ssqch new`](new-pages.md) for the next post, and a dev server (it answers to Squatch Watch) that reloads only the page you changed, swaps stylesheets in place, and shows a broken build in the browser.
|
|
24
|
+
- **Plugins in Rust** for the heavy lifting: transforms, filters and template languages built to one `.wasm` file that runs on every platform.
|
|
25
|
+
|
|
26
|
+
SiteSquatch is a young one (0.x), so expect some breaking changes between minor versions. Each is listed in the [changelog](https://github.com/reverentgeek/sitesquatch/blob/main/CHANGELOG.md) with what you'd need to change.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Install"
|
|
3
|
+
description: "You'll need Node.js 22.18 or newer."
|
|
4
|
+
---
|
|
5
|
+
<img align="right" src="../../../docs/assets/stickers/backpack.svg" alt="" width="96">
|
|
6
|
+
|
|
7
|
+
You'll need [Node.js](https://nodejs.org) 22.18 or newer. In a site with a `package.json`, add ssqch as a dev dependency, so the lockfile pins the version you built with:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --save-dev ssqch
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
(Or `pnpm add -D ssqch`, or `yarn add -D ssqch`.) Then run `npx ssqch build`, or `ssqch build` from a `package.json` script.
|
|
14
|
+
|
|
15
|
+
A site whose `.npmrc` holds new releases back (`min-release-age=2`, a supply-chain cooldown) gets a new ssqch that many days after it's published, and until then npm says `ETARGET No matching version found for ssqch@<version> with a date before ...`: install the version before it, or wait. `ignore-scripts=true` is fine: ssqch runs no install script, and sharp, its one dependency, comes with its binaries prebuilt.
|
|
16
|
+
|
|
17
|
+
To have `ssqch` everywhere instead, install it globally with `npm install --global ssqch`, or with [Homebrew](https://brew.sh) on macOS or Linux: `brew install reverentgeek/tap/ssqch` (it brings Node along if you don't have it).
|
|
18
|
+
|
|
19
|
+
Confirm the sighting:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
ssqch --version
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**pnpm's release age:** pnpm 11 and newer hold a version back for a day after it's published (`minimumReleaseAge`). If `pnpm add -D ssqch` fails on a release day, or installs the version before, list `ssqch` under `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`.
|
|
26
|
+
|
|
27
|
+
For Tab completion of commands and options, `ssqch completions zsh` (or `bash`, `fish`, `powershell`, `elvish`) prints a script for your shell, and `ssqch completions --help` says where each shell wants it.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Known gaps"
|
|
3
|
+
description: "The uncharted parts of the map, as of this release."
|
|
4
|
+
---
|
|
5
|
+
<img align="right" src="../../../docs/assets/stickers/direction-sign.svg" alt="" width="96">
|
|
6
|
+
|
|
7
|
+
The uncharted parts of the map, as of this release:
|
|
8
|
+
|
|
9
|
+
- **JavaScript:** there are no worker threads: pages render one at a time on one thread (image encoding uses every core), so a site with heavy per-page JavaScript doesn't spread it across cores, and module-level state in your config (a counter in a filter) is one counter. `Intl`, `toLocaleDateString()` and `localeCompare` are Node's, and their results can differ between Node releases (Node 22.18 ships an older ICU than 24 and 26). ssqch's own date filters and sorting never use `Intl`, so only a site's own `Intl` calls can make a build's output depend on the Node version; pin `NODE_VERSION` where that matters.
|
|
10
|
+
- **Async functions and Markdown:** a page's own Markdown waits for an async `headingIds` function or highlighter, but Markdown made while a template renders can't: `markdown()` and `highlight()` in a template, `markdown()` from `"ssqch"`, a render hook or a container whose template calls an async function are errors that name the function when it answers with a promise. Make those functions synchronous. A page whose own templates are async can't be rendered on demand either: reading its `templateContent` before it has rendered is an error that names it.
|
|
11
|
+
- **Edge:** the async functions inside a callback of `filter`, `find` and the other array methods aren't awaited (an error says to call them first with `@let`).
|
|
12
|
+
- **Markdown:** containers have to close inside the block they opened in (the same list item, say). Highlighting parses more slowly than tree-sitter would: the blog's 350 fences add about 60 ms to a build, and a process's first highlight compiles each grammar it uses (about 0.3 s for the blog's first build), unless [the highlighting cache](markdown.md) has the fence, and not again for the rebuilds of `ssqch serve`. A site with `.sublime-syntax` grammars of its own (or an alias to a built-in grammar, `jsx: "js"`) still loads the set of built-in grammars when its config is read, a few dozen milliseconds, though the cache spares it each grammar's patterns.
|
|
13
|
+
- **Images:** no SVG rasterizing, and HDR photos (the PQ, gain-map profiles of newer iPhones) can't be converted to sRGB, so they look washed out; the build warns about them, and converting the source to sRGB once fixes it. SVGs are served as they are, and GIFs are copied for `auto` output, so animations keep working.
|
|
14
|
+
- **The dev server:** it listens on `127.0.0.1` only (no `--host`), doesn't watch `node_modules`, and rebuilds the whole site on a change, on one thread: after one edit, a 10,000-page site takes about 0.9 s.
|
|
15
|
+
- **Collections:** custom collections don't see pages that are paginated over collections. Those pages are added to `all` and their tags afterwards.
|
|
16
|
+
- **Platforms:** ssqch needs Node 22.18 or newer, and runs wherever that Node and sharp do: macOS, Windows and Linux, Alpine and ARM included. See [TODO.md](https://github.com/reverentgeek/sitesquatch/blob/main/TODO.md) for what's next.
|
|
17
|
+
|
|
18
|
+
Found a bug, or have an idea? [Open an issue](https://github.com/reverentgeek/sitesquatch/issues). Happy building, and may your pages load faster than a Squatch sighting disappears.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Markdown"
|
|
3
|
+
description: "Markdown is CommonMark with GitHub's extensions."
|
|
4
|
+
---
|
|
5
|
+
Markdown is [CommonMark](https://commonmark.org) with GitHub's extensions: tables, strikethrough, footnotes, task lists, bare URLs as links, and alerts. Headings get `id`s, so every section can be linked to. The `markdown` config key turns the extensions on and off:
|
|
6
|
+
|
|
7
|
+
```js
|
|
8
|
+
export default defineConfig({
|
|
9
|
+
markdown: {
|
|
10
|
+
headingIds: "blackfriday", // or "github" (the default), or false
|
|
11
|
+
smartPunctuation: true,
|
|
12
|
+
},
|
|
13
|
+
});
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
| Option | Default | What it does |
|
|
17
|
+
| --- | --- | --- |
|
|
18
|
+
| `headingIds` | `"github"` | Automatic heading `id`s. `"github"` matches GitHub's anchors and github-slugger's (rehype-slug's, so Astro's, VitePress's and Docusaurus's) character for character (`Hello, World!` becomes `hello-world`; letters in any script, combining accents and emoji joiners stay); `"blackfriday"` matches Hugo's older ones (`A -- B` becomes `a-b`, not `a----b`); `"ascii"` transliterates first (`Straße 🦀` becomes `strasse-crab`, like Zola's). A function of the heading's text makes your own: `headingIds: (text) => ...`. A repeated heading gets `-1`, `-2` and so on. `false` turns them off. |
|
|
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
|
+
| `footnotes` | `true` | `[^1]` references, with the notes in a `<section class="footnotes">` at the end and links back to each reference. |
|
|
21
|
+
| `taskLists` | `true` | `- [ ]` and `- [x]` items, as disabled checkboxes. |
|
|
22
|
+
| `autolinks` | `true` | Bare `https://` and `www.` URLs become links. |
|
|
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). |
|
|
25
|
+
| `definitionLists` | `false` | A term, then `: definition` lines, as `<dl>`. |
|
|
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
|
+
| `indentedCode` | `true` | Lines indented four spaces are code. `false` makes them ordinary Markdown, for HTML indented inside Markdown; fences are still code. |
|
|
28
|
+
| `highlight` | `false` | Syntax highlighting at build time (below). `true`, or `{ css: "/assets/code.css" }` to put the stylesheet somewhere else, or `{ css: false }` to leave it out. `languages` adds languages or replaces built-in ones: `{ languages: { chordpro: code => tokens, cho: "chordpro", snack: "grammars/snack.sublime-syntax" } }` (below). |
|
|
29
|
+
|
|
30
|
+
**Syntax highlighting:** with `highlight: true`, fenced code is highlighted while the site builds, so pages need no highlighting script. The grammars are Sublime Text's and TextMate's (about 200 languages, from [syntect](https://github.com/trishume/syntect) and [bat](https://github.com/sharkdp/bat)), plus ssqch's own for the template languages those don't cover (`edge`, `liquid`, `hbs`, `mustache` and `ejs`: the tags, over highlighted HTML) and for ChordPro songs (`chordpro` and `cho`: directives, `[G7]` chords and comments), and each token gets one class for what it is: `hl-keyword`, `hl-string`, `hl-comment`, `hl-function`, `hl-type`, `hl-number` and so on. The build writes a stylesheet for them to `/highlight.css` (link it from your layout) with GitHub's colors, light and dark. Each color is a CSS custom property, like `--hl-keyword`, so a theme switch or your own palette only has to set those. Mark lines with braces in the fence's info string, ```` ```js {1,4-6} ````, and those lines get `class="line highlighted"`. A language without a grammar renders as plain `<pre><code class="language-x">`.
|
|
31
|
+
|
|
32
|
+
**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`.
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
// Trail notes: a line that starts with `!` is a warning, and `@Cedar` names a trail.
|
|
36
|
+
const trailnotes = code => code.split( /(^!.*$|@\w+)/m ).filter( Boolean ).map( text => text.startsWith( "!" ) ? [ text, "deleted" ] : text.startsWith( "@" ) ? [ text, "type" ] : [ text ] );
|
|
37
|
+
export default { markdown: { highlight: { languages: { trailnotes, trail: "trailnotes" } } } };
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**A table of contents:** after a page's content renders, `page.headings` lists its headings (`level`, `id` and `text`), so its layouts can build a table of contents. The built-in `toc` filter does it for you: `{{{ toc(page.headings) }}}` writes nested `<ul>` links to the `h2` and `h3` headings, and `toc(page.headings, { from: 2, to: 4, ordered: true })` changes the levels or uses `<ol>`. `id` and `class` go on the outer list, `sublistClass` on the lists inside it, `itemClass` on each `<li>` (with `{level}` replaced by the heading's level) and `linkClass` on each link, so jekyll-toc's markup is `toc(page.headings, { class: "section-nav", itemClass: "toc-entry toc-h{level}" })`, and an unknown option is an error that lists them. In Liquid that's `{{ page.headings | toc: 2, 4 }}`, or `{{ page.headings | toc: class: "section-nav" }}` with options, and in Nunjucks, `{{ toc(page.headings) | safe }}`. The headings come from the HTML, so they work for pages in any template language. Collections have them too (`post.page.headings`). They're there once the page has rendered: in its layouts, and in a collection item after that item's `templateContent` has been read. Read in `computed`, which runs before any page renders, they're an empty list.
|
|
41
|
+
|
|
42
|
+
**Highlighting anywhere:** `highlight(code, lang)` returns the highlighted HTML for the inside of a `<code>` (escaped text for a language without a grammar), for code that isn't a Markdown fence: an example container's source, a snippet from a data file.
|
|
43
|
+
|
|
44
|
+
**The highlighting cache:** each build keeps the code it highlighted in `.cache/ssqch/highlight/fences.json`, beside `fetch`'s copies and the images, and the next build takes the HTML from there instead of loading the grammars, which is most of what highlighting costs a new process: the ReverentGeek blog's `ssqch build` takes 0.64 s with it and 1.0 s without (rendering, 48 ms against 390 ms). `ssqch serve` keeps the same fences in memory between rebuilds, so the file is for its first build and for `ssqch build`. A fence is kept by its language, code and marked lines, the site's `languages` (a `.sublime-syntax` file by its contents), and the highlighter's own version: a hash of what ssqch's highlighter is built from, so a release that changes highlighting starts afresh by itself. Fences a site's own function highlights aren't kept, because a function can answer differently each time, and `highlight(code, lang)` in a template uses the cache too. The file holds the fences the last build used and no others, it's written only when they change (beside its place, then moved in), and a build that fails doesn't write it. A file that's damaged or from another version of ssqch is ignored and written again, never an error, and the cache never changes a page: a build with it writes the same bytes as a build without. `leaveNoTrace` cleans the output, not `.cache`; delete the file (or `.cache/`) to highlight everything again, and restore `.cache/ssqch` in CI to keep it, as for images.
|
|
45
|
+
|
|
46
|
+
**Markdown anywhere:** the `markdown` filter renders a string, such as a description from front matter: `{{{ markdown(summary) }}}`, or `markdown(title, "inline")` (in Liquid, `{{ title | markdown: "inline" }}`) to leave out the `<p>`. Config and data files can `import { markdown } from "ssqch"`.
|
|
47
|
+
|
|
48
|
+
**Containers:** a block between `::: name` and `:::` renders through `_includes/containers/name.*`, a template in any engine. It gets the page's data plus `container.name`, `container.args` (the rest of the opening line, without `[` `]` around it: `:::tip[Watch out]` works), `container.props` (the arguments read as a component's attributes: `::: card type="tip" open items='["a","b"]'` is `{ type: "tip", open: true, items: ["a", "b"] }`, where a single-quoted value that starts with `{` or `[` is JSON, an unquoted one like `size=3` is the text `3`, and a word on its own is `true`), `container.slots` (below), `container.content` (the block's Markdown, rendered) and `container.source` (the block's lines as written, for an example that shows its own code). One template covers admonitions, tabs, figures or anything else that wraps content:
|
|
49
|
+
|
|
50
|
+
```markdown
|
|
51
|
+
::: warning Hot pine cones
|
|
52
|
+
They're **very** crunchy.
|
|
53
|
+
:::
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```njk
|
|
57
|
+
{# src/_includes/containers/warning.njk #}
|
|
58
|
+
<aside class="callout warning">
|
|
59
|
+
<p class="callout-title">{{ container.args or "Warning" }}</p>
|
|
60
|
+
{{ container.content | safe }}
|
|
61
|
+
</aside>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Containers nest: an outer one opens with more colons (`::::`) and closes with as many. Without a template, a container renders as `<div class="name">` (with the arguments as a `<p class="container-title">`). An alert renders through a container template with its name, if there is one, so `containers/warning.njk` styles `> [!WARNING]` too.
|
|
65
|
+
|
|
66
|
+
**Named slots:** a `::: slot <name>` block (or `::: slot name="<name>"`) inside another container is that container's `container.slots.<name>`, its Markdown rendered, and is left out of `container.content`, as MDX's `<Fragment slot="title">` and a component's named slots are. Two slots with the same name are joined. A slot with no container template around it to take it (the container renders as a `<div>`, or the slot is on its own) stays where it is, as its content. `slot` is ssqch's: `_includes/containers/slot.*` is an error.
|
|
67
|
+
|
|
68
|
+
```markdown
|
|
69
|
+
:::: card type="tip"
|
|
70
|
+
Squatch Snacks, **crunchy**.
|
|
71
|
+
|
|
72
|
+
::: slot title
|
|
73
|
+
Pine Cone Crunch
|
|
74
|
+
:::
|
|
75
|
+
::::
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```njk
|
|
79
|
+
{# src/_includes/containers/card.njk #}
|
|
80
|
+
<div class="card {{ container.props.type }}">
|
|
81
|
+
<h3>{{ container.slots.title | safe }}</h3>
|
|
82
|
+
{{ container.content | safe }}
|
|
83
|
+
</div>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**Render hooks:** templates in `_includes/hooks/` take over how parts of Markdown render, in any engine. Each gets the page's data plus one value:
|
|
87
|
+
|
|
88
|
+
| Template | Gets | For example |
|
|
89
|
+
| --- | --- | --- |
|
|
90
|
+
| `heading.*` | `heading.level`, `id`, `text`, `content` (the inner HTML) and `attrs` | Anchor links next to headings |
|
|
91
|
+
| `link.*` | `link.href`, `title`, `text` and `content` | `target="_blank"` and an icon on external links |
|
|
92
|
+
| `image.*` | `image.src`, `alt` and `title` | `<figure>` with a caption |
|
|
93
|
+
| `footnote-ref.*` | `footnote.number`, `label`, `id` (the note's), `refId` (this reference's) and `index` (1 for a note's first reference) | Footnote links in another generator's markup |
|
|
94
|
+
| `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 |
|
|
95
|
+
| `fence.*`, or `fence-<lang>.*` for one language | `fence.lang`, `info` (the whole line after the backticks, like `js {1,3} title="app.js"`), `code`, and `highlighted` (the highlighted HTML, with `highlight` on) | Diagrams from `mermaid` fences, titled code blocks |
|
|
96
|
+
|
|
97
|
+
```jinja
|
|
98
|
+
{# src/_includes/hooks/heading.jinja #}
|
|
99
|
+
<h{{ heading.level }} id="{{ heading.id }}">{{ heading.content | safe }} <a href="#{{ heading.id }}" class="anchor" aria-hidden="true">#</a></h{{ heading.level }}>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Put `aria-hidden="true"` on decoration like that `#`, and `page.headings` leaves it out of the heading's text.
|
|
103
|
+
|
|
104
|
+
A fence hook writes the whole block, so it has to write `<pre><code>` itself: `fence.highlighted` is only what goes inside it (spans, already escaped), and `fence.code` is the raw text, which the template escapes (Nunjucks and Jinja do it by themselves; in Liquid write `{{ fence.code | escape }}`). With `highlight` off, `highlighted` is empty:
|
|
105
|
+
|
|
106
|
+
```njk
|
|
107
|
+
{# src/_includes/hooks/fence.njk #}
|
|
108
|
+
<div class="code-block">
|
|
109
|
+
<button class="copy" data-code="{{ fence.code }}">Copy</button>
|
|
110
|
+
<pre><code class="language-{{ fence.lang }}">
|
|
111
|
+
{%- if fence.highlighted %}{{ fence.highlighted | safe }}{% else %}{{ fence.code }}{% endif -%}
|
|
112
|
+
</code></pre>
|
|
113
|
+
</div>
|
|
114
|
+
```
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Multilingual sites: translations, i18n and hreflang"
|
|
3
|
+
navTitle: "Multilingual sites"
|
|
4
|
+
description: "ssqch has no built-in i18n yet (TODO.md, \"Internationalization\")."
|
|
5
|
+
---
|
|
6
|
+
ssqch has no built-in i18n yet ([TODO.md](https://github.com/reverentgeek/sitesquatch/blob/main/TODO.md), "Internationalization"). What two real sites (one from Jekyll, one from Astro) did instead, with what ssqch has:
|
|
7
|
+
|
|
8
|
+
- **A folder per language** (`content/fr/guide.md`), and the language from directory data (`content/fr/fr.json`: `{ "lang": "fr" }`) or front matter. A key that groups a page's translations (the file's path below the language folder, or a front matter key like `translationKey`).
|
|
9
|
+
- **A page's translations** are a lookup in a collection: `collections.docs | where: "data.key", key` in Liquid, or a filter of your own that groups pages by key once.
|
|
10
|
+
- **Fallback pages** (the default language's page at another language's URL): a collection function that returns one object per URL (`{ lang, slug, page }`), choosing the translation when there is one, and one template with `pagination: { data: "collections.routes", size: 1, alias: "route" }` and `permalink: "/{{ route.lang }}/{{ route.slug }}/"` that writes `route.page.templateContent`. The content pages get `permalink: false`, so they're written only where the routes put them.
|
|
11
|
+
- **Strings:** `_data/i18n/<lang>.json`, read in templates as `i18n[lang].nav.about`, or a `t(lang, key)` filter that falls back to the default language.
|
|
12
|
+
- **hreflang:** a loop over the page's translations in the layout's `<head>`, with `x-default` for the default language; `sitemapPlugin({ url, alternates })` lists the same translations in the sitemap.
|
|
13
|
+
- **Direction:** `dir` on `<html>` from a language list in data (`{ "ar": { "dir": "rtl" } }`).
|
|
14
|
+
- **Old language codes:** `aliases` on each page, or `redirectsPlugin({ redirects })`.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# The docs' order: the site's sidebar, and the order `ssqch docs` reads the pages in (a page that
|
|
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
|
+
# makes itself.
|
|
4
|
+
- title: Start here
|
|
5
|
+
pages:
|
|
6
|
+
- index.md
|
|
7
|
+
- install.md
|
|
8
|
+
- field-guide.md
|
|
9
|
+
- title: Build
|
|
10
|
+
pages:
|
|
11
|
+
- configuring.md
|
|
12
|
+
- data-files.md
|
|
13
|
+
- plugins.md
|
|
14
|
+
- templates.md
|
|
15
|
+
- markdown.md
|
|
16
|
+
- template-languages.md
|
|
17
|
+
- css-and-javascript.md
|
|
18
|
+
- multilingual.md
|
|
19
|
+
- seo.md
|
|
20
|
+
- themes.md
|
|
21
|
+
- new-pages.md
|
|
22
|
+
- title: Check
|
|
23
|
+
pages:
|
|
24
|
+
- content-schemas.md
|
|
25
|
+
- where-values-come-from.md
|
|
26
|
+
- build-summary.md
|
|
27
|
+
- comparing-builds.md
|
|
28
|
+
- footprint.md
|
|
29
|
+
- title: Ship
|
|
30
|
+
pages:
|
|
31
|
+
- deploying.md
|
|
32
|
+
- netlify.md
|
|
33
|
+
- github-pages.md
|
|
34
|
+
- agents.md
|
|
35
|
+
- rust-plugins.md
|
|
36
|
+
- title: Trailheads
|
|
37
|
+
pages:
|
|
38
|
+
- trailheads.md
|
|
39
|
+
- trailheads/from-eleventy.md
|
|
40
|
+
- trailheads/from-jekyll.md
|
|
41
|
+
- trailheads/from-zola.md
|
|
42
|
+
- trailheads/from-docusaurus.md
|
|
43
|
+
- trailheads/from-mkdocs.md
|
|
44
|
+
- trailheads/from-hexo.md
|
|
45
|
+
- trailheads/from-component-frameworks.md
|
|
46
|
+
- title: Reference
|
|
47
|
+
pages:
|
|
48
|
+
- { title: "Every name", url: /docs/reference/ }
|
|
49
|
+
- benchmarks.md
|
|
50
|
+
- known-gaps.md
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Netlify"
|
|
3
|
+
description: "Netlify can build the site itself, with no deploy token to manage."
|
|
4
|
+
---
|
|
5
|
+
Netlify can build the site itself, with no deploy token to manage. With `ssqch` in the site's `devDependencies` (see [Install](install.md)), Netlify installs it with the site's other packages, at the version in the lockfile, and runs it on the Node it has: set `NODE_VERSION` to 22.18 or newer, as below. This is the ReverentGeek blog's `netlify.toml` (it builds its CSS and JavaScript with npm scripts first, so it runs `pnpm run build`; a site without that step can run `npx ssqch build` instead):
|
|
6
|
+
|
|
7
|
+
```toml
|
|
8
|
+
[build]
|
|
9
|
+
command = "pnpm run build && node --test test/smoke.test.js"
|
|
10
|
+
publish = "dist/"
|
|
11
|
+
|
|
12
|
+
[build.environment]
|
|
13
|
+
NODE_VERSION = "24"
|
|
14
|
+
|
|
15
|
+
[[plugins]]
|
|
16
|
+
package = "netlify-plugin-cache"
|
|
17
|
+
[plugins.inputs]
|
|
18
|
+
paths = [".cache/ssqch"]
|
|
19
|
+
```
|
|
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.10.1`) and bump it when you're ready.
|
|
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
|
+
- **[`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
|
+
|
|
25
|
+
A site without a `package.json` can run a pinned release straight from npm in the build command, with `SSQCH_VERSION = "0.10.1"` under `[build.environment]` to pin it (and `NODE_VERSION` there as well):
|
|
26
|
+
|
|
27
|
+
```toml
|
|
28
|
+
[build]
|
|
29
|
+
command = "npx --yes ssqch@$SSQCH_VERSION build"
|
|
30
|
+
```
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Starting a new page"
|
|
3
|
+
description: "ssqch new creates a page from a blueprint."
|
|
4
|
+
---
|
|
5
|
+
`ssqch new` creates a page from a blueprint: a page to start from, kept in `_blueprints/` in the input folder and named after the folder its pages go in. Here's `src/_blueprints/posts.md`:
|
|
6
|
+
|
|
7
|
+
```md
|
|
8
|
+
---
|
|
9
|
+
# Fill in the description before publishing.
|
|
10
|
+
title:
|
|
11
|
+
date:
|
|
12
|
+
description:
|
|
13
|
+
draft: true
|
|
14
|
+
---
|
|
15
|
+
Write here. The title is {{ title }}.
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
ssqch new posts --title "Pine cones: a field guide"
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
Created src/posts/pine-cones-a-field-guide.md from src/_blueprints/posts.md. Field notes started.
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The new post:
|
|
27
|
+
|
|
28
|
+
```md
|
|
29
|
+
---
|
|
30
|
+
# Fill in the description before publishing.
|
|
31
|
+
title: "Pine cones: a field guide"
|
|
32
|
+
date: 2026-11-10
|
|
33
|
+
description:
|
|
34
|
+
draft: true
|
|
35
|
+
---
|
|
36
|
+
Write here. The title is {{ title }}.
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
- **Only front matter is filled in.** `title` is set, `date` is set to today when the blueprint has that key (or you pass `--date`), and `--set key=value` sets anything else (`--set draft=false`, `--set "tags=[news, trails]"`). Comments and the order of the keys stay. The body is copied as it is, so a blueprint isn't a template with a syntax of its own: `{{ title }}` in it is for the page.
|
|
40
|
+
- **Which blueprint:** the one named after the page's folder, the most specific first. `docs/guides/install.md` uses `_blueprints/docs/guides.md`, then `_blueprints/docs.md`, then `_blueprints/default.md`, and with none of them the page gets a `title` and a `date`. `--blueprint notes` picks one by name. A blueprint can be in any template language (`posts.jinja`), and a [theme](themes.md) can bring its own in its `_blueprints/`.
|
|
41
|
+
- **A file, or a folder and a title:** `ssqch new posts/pine-cones.md` names the file itself (the title is then "Pine cones", unless you pass `--title`). Given a folder, the file is named after the title, the way the folder's other pages are: with the date in front (`2026-11-10-pine-cones.md`) when most of them have one, and as `pine-cones/index.md` when most are folders with an index file.
|
|
42
|
+
- **Nothing is overwritten,** and `--format json` prints the new file's `path`, its `blueprint`, `title` and `date`.
|