ssqch 0.9.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/bundled/docs/agents.md +70 -0
- package/bundled/docs/benchmarks.md +29 -0
- package/bundled/docs/build-summary.md +27 -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 +3 -1
- package/lib/assets.js +15 -7
- package/lib/{chunk-GUKSZ2XM.js → chunk-2LEOPLTZ.js} +2 -2
- package/lib/{chunk-3K3ANWZ2.js → chunk-3EPHKJEG.js} +3 -3
- package/lib/{chunk-SXMJ52IK.js → chunk-3HHRKG33.js} +56 -16
- package/lib/{chunk-NCWFYT74.js → chunk-5DNDSNTP.js} +3 -3
- package/lib/{chunk-TVU3OPPK.js → chunk-7HXCQEGA.js} +3 -3
- package/lib/{chunk-GRWMGC7D.js → chunk-BGCBSQ4A.js} +3054 -3053
- package/lib/{chunk-3A647I3N.js → chunk-CB6YFUXU.js} +3 -3
- package/lib/{chunk-7RDRZHJD.js → chunk-DMVJ53SM.js} +9 -9
- package/lib/{chunk-IJWHOFRP.js → chunk-DW7VMJEZ.js} +9 -9
- package/lib/{chunk-SURPOAW7.js → chunk-E5UB2YY7.js} +6 -6
- package/lib/{chunk-D2XE2GTY.js → chunk-EEJDLCD3.js} +7 -7
- package/lib/{chunk-7PWCYHTJ.js → chunk-HDQ4SRWM.js} +3 -3
- package/lib/{chunk-7SD7K567.js → chunk-HGJ5VWUR.js} +1 -1
- package/lib/{chunk-76NTVE34.js → chunk-JWCCVTTR.js} +1 -1
- package/lib/{chunk-TICWN55Z.js → chunk-JXZT5L7W.js} +2 -2
- package/lib/{chunk-MI6EJWA2.js → chunk-LAV3DEY4.js} +1 -1
- package/lib/{chunk-7XLK2GEG.js → chunk-LCPSKHAV.js} +1 -1
- package/lib/{chunk-II5DEH3Q.js → chunk-N4O5MDIB.js} +2 -2
- package/lib/{chunk-HPXAZ2HU.js → chunk-NFJJKDRI.js} +1 -1
- package/lib/{chunk-LPHNACE4.js → chunk-NUUEOGLZ.js} +8 -8
- package/lib/{chunk-NNUKIGOO.js → chunk-Q4LFTYK2.js} +11 -11
- package/lib/{chunk-R7K3D5W5.js → chunk-QMA7CK7B.js} +29 -6
- package/lib/{chunk-SF4I6Z7S.js → chunk-RJFWTW2Y.js} +2 -2
- package/lib/{chunk-BEGC7YP6.js → chunk-RKFZSVNF.js} +6 -6
- package/lib/{chunk-XMXBHXZR.js → chunk-RM5Q3KFB.js} +9 -9
- package/lib/{chunk-RNJFPFXE.js → chunk-RVBNVGZV.js} +3 -3
- package/lib/{chunk-CZ4XQC56.js → chunk-SA5KSJ4Y.js} +8 -4
- package/lib/{chunk-DELWRJAO.js → chunk-SRNLKWXL.js} +60 -35
- package/lib/{chunk-YTHQBMDJ.js → chunk-Y2ESFAAD.js} +2 -3
- package/lib/{chunk-47P4YREZ.js → chunk-ZM6TU2JB.js} +6 -6
- package/lib/cli.js +20 -20
- package/lib/elements.js +7 -7
- package/lib/image.js +8 -8
- package/lib/links.js +10 -10
- package/lib/minify.js +7 -7
- package/lib/redirects.js +8 -8
- package/lib/rss.js +20 -19
- package/lib/sass.js +7 -7
- package/lib/sitemap.js +7 -7
- package/lib/ssqch.js +4 -4
- package/package.json +2 -2
- package/types/index.d.ts +2 -0
- package/types/rss.d.ts +1 -1
- package/bundled/README.md +0 -1314
- package/lib/{chunk-GRWMGC7D.js.LEGAL.txt → chunk-BGCBSQ4A.js.LEGAL.txt} +3 -3
- /package/lib/{chunk-DELWRJAO.js.LEGAL.txt → chunk-SRNLKWXL.js.LEGAL.txt} +0 -0
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Plugins in Rust"
|
|
3
|
+
description: "Most plugins should be JavaScript."
|
|
4
|
+
---
|
|
5
|
+
Most plugins should be JavaScript: a piece of config, in the config or an npm package (see [Configuring a site](configuring.md)). When a plugin does heavy work, it can be written in Rust instead, with the [`ssqch-plugin`](https://crates.io/crates/ssqch-plugin) crate, the plugin SDK. It builds one `.wasm` file (for `wasm32-wasip1`) that ssqch runs in Node's own WebAssembly: the same file on macOS, Linux and Windows, with nothing to compile when a site installs it, no native code, and no files, network or environment for the plugin to reach. ssqch's own minifier (`ssqch/minify`) is built this way, and its Markdown and Sass are Rust compiled to WebAssembly too.
|
|
6
|
+
|
|
7
|
+
A Rust plugin can give a site a **transform** (every HTML page the build writes, after the image transform), **filters** (functions every template language can call) and **engines** (template languages of its own, by file extension). A site adds it as it adds any plugin; its npm package's function returns `{ name, rust: { wasm, options } }`, with `wasm` the absolute path to its file and `options` JSON for the plugin (`ssqch.d.ts` has the type, `RustPlugin`):
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
// ssqch.config.js
|
|
11
|
+
import trailGuide from "ssqch-plugin-trail-guide";
|
|
12
|
+
|
|
13
|
+
export default {
|
|
14
|
+
templateFormats: ["jinja", "md", "trail"], // the plugin's engine renders .trail files
|
|
15
|
+
plugins: [trailGuide({ greeting: "Howdy" })],
|
|
16
|
+
};
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The plugin's hooks come from its manifest, inside the `.wasm` file: its filters' names and its engines' extensions, so the package doesn't list them. A name the config already uses is an error, as for any plugin. Options are JSON, checked by the plugin when the config loads: ``plugin "trail-guide": options: unknown field `greting`, expected one of `greeting`, `wordsPerMinute`, `externalRel` ``. A filter's error names the plugin (`index.edge:2: readingTime(): trail-guide: readingTime expects text, got a number`), an engine's error on a line of the file shows that line, and a panic is an error with its place in the Rust. A file that isn't a plugin, or that was built for another version of the plugin ABI, is refused with what to do: `built for plugin ABI 2, and this ssqch loads ABI 1: update ssqch, or use a version of the plugin built for ABI 1`.
|
|
20
|
+
|
|
21
|
+
What a plugin gets: a filter gets the template's values as JSON (a date as ISO 8601 text, `undefined` as `null`, no functions) and its answer is printed as any filter's is; an engine gets the file's text after the front matter and the page's data without `collections`; a transform gets each HTML page and its `url`, `inputPath` and `outputPath`, and no data, as a JavaScript transform does.
|
|
22
|
+
|
|
23
|
+
**The plugin SDK:** a plugin is a Rust crate with `crate-type = ["cdylib", "rlib"]`, a type that implements `ssqch_plugin::Plugin` (its `Options`, its `NAME` and `HOOKS`, `new`, and the hooks it has) and the line `export!(MyPlugin);`. `cargo build --release --target wasm32-wasip1` builds the file (`rustup target add wasm32-wasip1` first), and `cargo test` tests the plugin as plain Rust. [`examples/rust-plugin`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/rust-plugin/) is a whole plugin with all three hooks and its npm package, and [the crate's README](https://github.com/reverentgeek/sitesquatch/blob/main/crates/ssqch-plugin/README.md) has the rules and a complete example: the manifest, the options, what each hook sees, how errors and panics are reported, and the ABI.
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
## When a Rust plugin pays
|
|
27
|
+
|
|
28
|
+
Each call copies its text into the plugin's memory and the answer back out, and WebAssembly runs at most at native speed, so Rust pays for work that's heavy for each byte, not for a few edits.
|
|
29
|
+
|
|
30
|
+
- **Heavy work pays:** minifying, parsing a real grammar (a template language, a highlighter), work on images or fonts, hashing, compression, a search index. Measured on 10,000 pages, minify-html as a plugin minified them in 0.28 of html-minifier-terser's time (0.82 s against 2.97 s), and ssqch's own minifier minifies the ReverentGeek blog's 169 pages (7.9 MB) in about 0.1 s.
|
|
31
|
+
- **A regex doesn't.** Adding `loading="lazy"` to images, swapping a word, counting words: JavaScript's regular expressions compile to machine code. Adding attributes to 200,000 images on 10,000 pages took a JavaScript regex 53 ms, the same scan in Rust 81 ms as a plugin, and a real HTML tokenizer (lol_html) 311 ms. Write those as a transform in the config.
|
|
32
|
+
- **Many small calls cost.** A filter call costs about 0.25 µs besides its work (its arguments and answer cross as JSON): fifty a page on 10,000 pages is a tenth of a second. A filter that's called for every item of every list is better in JavaScript.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "SEO tags"
|
|
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
|
+
---
|
|
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):
|
|
6
|
+
|
|
7
|
+
```njk
|
|
8
|
+
{# _includes/seo.njk #}
|
|
9
|
+
<title>{{ title ~ " · " ~ site.title if title else site.title }}</title>
|
|
10
|
+
<meta name="description" content="{{ description or site.description }}">
|
|
11
|
+
<link rel="canonical" href="{{ site.url ~ page.url }}">
|
|
12
|
+
<meta property="og:title" content="{{ title or site.title }}">
|
|
13
|
+
<meta property="og:description" content="{{ description or site.description }}">
|
|
14
|
+
<meta property="og:url" content="{{ site.url ~ page.url }}">
|
|
15
|
+
<meta property="og:image" content="{{ site.url ~ (image or "/og.png") }}">
|
|
16
|
+
<meta name="twitter:card" content="summary_large_image">
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Jekyll's `{% seo %}` (jekyll-seo-tag) becomes this include. 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.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Each template language"
|
|
3
|
+
navTitle: "Template languages"
|
|
4
|
+
description: "Jinja is ssqch's default template language."
|
|
5
|
+
---
|
|
6
|
+
## Jinja and Nunjucks
|
|
7
|
+
|
|
8
|
+
Jinja is ssqch's default template language: `.jinja` (and `.j2`) pages and layouts render with ssqch's own fork of [Nunjucks](https://mozilla.github.io/nunjucks/), the library Eleventy's Nunjucks templates run on, with Jinja's filters, tests, functions and string, list and dict methods on top, so templates written for Jinja (MkDocs themes, say) run too. Markdown and HTML files run through it first. `ssqch init` starts a site in it. `.njk` files render with the same library, printing values as Nunjucks does. Add `"njk"` (Nunjucks) or `"j2"` to `templateFormats` for those extensions, `markdownEngine: "njk"` to run Markdown through the Nunjucks flavor, and `render: [njk, md]` to do that for one post. A home page, `src/index.jinja`, that lists the posts:
|
|
9
|
+
|
|
10
|
+
```jinja
|
|
11
|
+
---
|
|
12
|
+
layout: base.jinja
|
|
13
|
+
title: Squatch Snacks
|
|
14
|
+
---
|
|
15
|
+
{% for post in collections.posts %}
|
|
16
|
+
<h2><a href="{{ post.url }}">{{ post.data.title }}</a></h2>
|
|
17
|
+
<p>{{ post.date | dateformat("%B %-d, %Y") }}</p>
|
|
18
|
+
{% endfor %}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- **Data:** front matter, the cascade, `page`, `collections` and `content` in layouts, the same as in the other engines. Undefined values, and properties of undefined values, print nothing (`strict: true` makes printing one an error).
|
|
22
|
+
- **Escaping:** output is HTML-escaped, as in Nunjucks and Jinja; use `| safe` to opt out. A layout's `content` is already marked safe, so `{{ content }}` works.
|
|
23
|
+
- **Filters and functions:** Jinja's built-in filters, plus Nunjucks' own (`dump`, `truncate`, `forceescape`, `nl2br`, `urlize`, `wordcount`, `center`, `random`), and `pluralize`, `filesizeformat`, `striptags`, `cycler()` and `joiner()`. Your config `filters` work both ways: `{{ title | shout }}` and `{{ shout(title) }}`. On a page whose data has a field with a function's name, the call finds the field first, so use the filter form there. An async function is awaited.
|
|
24
|
+
- **JavaScript properties and methods:** Nunjucks templates use JavaScript's, and they work in `.njk` and `.jinja` files alike. `.length` counts a list's items or a string's characters (`{{ collections.posts.length }}`, the same as `| length`); `loop.length` and an object's own `length` key keep their meaning, and on any other object `.length` is undefined, as in JavaScript. Strings and lists also have `startsWith()`, `endsWith()`, `includes()`, `indexOf()`, `toLowerCase()`, `toUpperCase()` and `trim()`, beside Python's (`startswith()`, `lower()`).
|
|
25
|
+
- **Dates:** `{{ page.date | dateformat }}` prints `Mar 14 2026`. `dateformat`, `timeformat` and `datetimeformat` take `"short"`, `"medium"`, `"long"`, `"full"`, `"iso"`, `"unix"`, or a `strftime` pattern (`dateformat("%B %-d, %Y")`), in UTC. Dates also have Python's `strftime()` and `isoformat()` and JavaScript's `toISOString()` and friends, and `now()` is the build's time.
|
|
26
|
+
- **Your own tags:** a config filter is a tag too, in `.njk` and `.jinja` files alike. `{% image "/a.png", "A pine" %}` prints what `image("/a.png", "A pine")` returns, without escaping it. With a closing tag, the function gets what's between them first: `{% callout "tip" %}...{% endcallout %}` calls `callout(content, "tip")`. That covers the built-in filters as well, so `{% markdown %}...{% endmarkdown %}` renders Markdown inside a template.
|
|
27
|
+
- **Includes and inheritance:** `{% include %}`, `{% extends %}` with `{% block %}`, `{% import %}` and `{% from ... import %}` read from `_includes`. Front-matter `layout` works too.
|
|
28
|
+
- **Nunjucks syntax:** `{% elseif %}`, `===`, `{ title: x }`, `{% for key, value in object %}` and Nunjucks' own filters work in `.jinja` files as in `.njk`. Not supported: extensions that parse a tag's arguments themselves.
|
|
29
|
+
- **Two flavors:** `.njk` prints values as Nunjucks does, as a site from Eleventy expects (`true`, a list as `a,b`, an object as `[object Object]`, `none` as nothing, and `dump` as compact JSON, escaped unless it's followed by `| safe`; `dump(2)` indents it). `.jinja` and `.j2` print as Jinja does (`True`, `['a', 'b']`, a spaced, unescaped `dump`). A date prints as ISO 8601 in both, whatever the machine's time zone.
|
|
30
|
+
- **Where Nunjucks isn't Jinja:** a variable set inside a loop or an `if` keeps its value after it (`{% set total = 0 %}{% for x in xs %}{% set total = total + x %}{% endfor %}` ends with the sum; `namespace()` still works), and a variable set in an include stays in the include, so set it in the page, or have the include print it. `{% break %}`, `{% continue %}`, `{% with %}`, `{% autoescape %}`, `{% for x in xs if x.ok %}` and `recursive` loops are errors that name their line and say what to write instead (an `{% if %}` inside the loop, `xs | selectattr("ok")`, a macro that calls itself). `loop.previtem`, `loop.nextitem` and `loop.depth` are undefined. Numbers have no separate float type (`{{ 4 / 2 }}` prints `2`), and `+` and `*` are JavaScript's: join lists with `xs | chain(ys)`.
|
|
31
|
+
- **Errors** name the template and line: `broken.njk:2: syntax error`.
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
## Edge
|
|
35
|
+
|
|
36
|
+
[Edge.js](https://edgejs.dev) templates (`.edge`) render with edge.js itself (6.5), so what its documentation describes works. Add `"edge"` to `templateFormats`, and `markdownEngine: "edge"` to run Markdown through it (`ssqch init --engine edge` does both). Its components with slots are handy in Markdown: [`component-docs`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/component-docs/) uses them in place of MDX.
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
export default defineConfig({
|
|
40
|
+
templateFormats: ["edge", "md"],
|
|
41
|
+
markdownEngine: "edge",
|
|
42
|
+
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
All of edge.js is there: `{{ }}`, `{{{ }}}`, `{{-- --}}`, `@{{ }}`, `@if/@elseif/@else/@unless`, `@each` (with index, objects, `@else` and `$loop`), `@let` (destructuring included) and `@assign`, `@include` and `@includeIf`, `@component` and `@!component` with named slots and isolated scope, `@eval`, `@inject`, `@stack` and `@pushTo`, `~` whitespace control, and edge.js's helpers (`excerpt`, `html.attrs`, `nl2br` and the rest; `nl2br` gives HTML to print as it is, so escape what it's given: `{{{ nl2br(html.escape(text)) }}}`). Expressions are JavaScript: object and array literals, template literals, optional chaining, arrow functions with block bodies, regular expressions, the `in` operator, `await`, and Node's globals (`process`, `URL`; a page's value or a config function of the same name wins). `await` waits for a promise, and an async function (an async config filter) is awaited when it's called in a mustache or `@let`. Inside a callback it's awaited in `map` (`posts.map(p => cover(p))`), and in `filter`, `find` and the others it's an error that says to call it first with `@let`.
|
|
46
|
+
|
|
47
|
+
ssqch smooths a few of edge.js's corners: an undefined value prints nothing (edge.js prints `undefined`), a call reaches the config filter when the page has a field of the same name (`{{ image(...) }}` beside `image:` in front matter), a mustache can start with an object literal (`{{ { tip: 'T' }[kind] }}`), `@let(n = n - 1)` reads the value it replaces, `reverse()` and `sort()` give copies (so a page can't reorder a collection under the next one), dates are in UTC and print as ISO 8601, strings index by character, and numbers never print in exponent notation. `{{ safe(html) }}` prints `html` as it is, as edge.js's `html.safe` does. A variable an include declares with `@let` stays in the include unless the including template declares it first. Errors report `template:line` through the include and component chain, a parse error is in edge.js's words (`parse error in page.edge: line 2: Unexpected token`), and a function that isn't there says which one you probably meant (``index.edge:2: `uper` is not a function (did you mean `upper`?)``), or ssqch's name for another generator's (`slug`).
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
## Liquid
|
|
51
|
+
|
|
52
|
+
Coming from Jekyll or a Shopify theme? Add `"liquid"` to `templateFormats` and `.liquid` pages and layouts render with [liquidjs](https://liquidjs.com) (10.30), the Liquid library Eleventy uses. Use `markdownEngine: "liquid"` to run Markdown through Liquid instead of Jinja, or `render: [liquid, md]` for one post.
|
|
53
|
+
|
|
54
|
+
```js
|
|
55
|
+
import { defineConfig } from "ssqch";
|
|
56
|
+
|
|
57
|
+
export default defineConfig({
|
|
58
|
+
templateFormats: ["liquid", "md"],
|
|
59
|
+
markdownEngine: "liquid",
|
|
60
|
+
filters: { shout: (s) => s.toUpperCase() },
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
- **Data:** Liquid templates get the same data as the other engines: front matter, the cascade, `page`, `collections` and `content` in layouts. Unknown variables and properties print nothing, as in Jekyll. Front matter is at the top level (`{{ title }}`), not under `page` as in Jekyll: a template that reads `page.title` gets nothing, and the build warns once for each such name, naming the page.
|
|
65
|
+
- **Filters:** liquidjs' standard filters and tags (`where_exp`, `sum`, `{% liquid %}`, `{% echo %}`), Jekyll's `push`, `pop`, `shift`, `unshift`, `array_to_sentence_string`, `date_to_xmlschema`, `date_to_rfc822`, `date_to_string` and `date_to_long_string`, and Shopify's `pluralize`. `slugify` is ssqch's, the same as in the other languages. Your config `filters` work too: `{{ title | shout }}` calls `shout(title)`, and `{{ x | wrap: "[", "]" }}` calls `wrap(x, "[", "]")`. A config filter replaces a built-in one with the same name.
|
|
66
|
+
- **Dates** print as `2026-01-02 00:00:00 +0000`, in UTC, whatever the machine's time zone, in every filter, and `date` reads ISO 8601 text (`2024-03-04`).
|
|
67
|
+
- **Objects:** `{{ some_object }}` prints `[object Object]`, so write `{{ some_object | json }}`; `{{ some_object.size }}` is its number of keys, and a string's `size` counts as JavaScript does (`café` is 4). A variable named `empty` or `blank` is Liquid's keyword (`{% if empty %}`), so rename it.
|
|
68
|
+
- **Includes:** `{% include "nav.html" %}` and Jekyll's `{% include nav.html section="home" %}` (read as `include.section`) see the page's variables. `{% render "footer", year: 2026 %}` sees only what it's given, and prints nothing for a variable it wasn't given (with `strict`, that is an error). Both read from `_includes`, adding `.liquid` when the name has none.
|
|
69
|
+
- **`include_relative`:** Jekyll's `{% include_relative parts/intro.md who="rangers" %}` reads a file beside the template that has the tag (or in a folder below it), not in `_includes`, and renders it with the page's variables and `include.who`. The name can have `{{ }}` in it (`parts/{{ lang }}.md`); `..` is refused, as in Jekyll. The file is read as it is, front matter and all, and a Markdown file there is a page of its own too, so give it `permalink: false` in directory data (not in its front matter) or keep it out with `ignore`.
|
|
70
|
+
- **Your own tags:** a config filter is a tag too, as in Nunjucks, so a Jekyll plugin's tag can be a function: `{% seo %}` prints what `seo()` returns, without escaping it. Arguments are values, by commas or spaces (`{% image "/a.png", "A pine" %}`), and `name: value` or Jekyll's `name=value` arrive as one object at the end (`{% seo title=false %}` calls `seo({ title: false })`). With a closing tag, the function gets what's between them first: `{% callout "tip" %}...{% endcallout %}` calls `callout(content, "tip")`. A function can be async. Liquid's own tags keep their names: a filter called `include` is a filter only. Arguments are plain values: a filter inside a tag's arguments (`{% image page.cover | url %}`) is an error, so `assign` it first.
|
|
71
|
+
- **Ruby's Liquid:** math, `split` and blank blocks follow Ruby's Liquid (4.0.4, Jekyll's and GitHub Pages'): `plus`, `minus`, `times`, `divided_by`, `modulo` and the rest read text as Ruby does (`"3.5"` is a float, `"3.5x"` is 3, `"r>"` and nothing are 0); `split` drops empty strings at the end and splits `" "` at every run of whitespace; and an `if`, `unless`, `for` or `case` whose bodies are only whitespace, `assign`, `capture` and comments writes nothing, so a layout that computes in blocks doesn't fill with blank lines. Dividing by zero is still an error.
|
|
72
|
+
- **Mixing engines:** a Liquid page can use a Jinja layout and the other way around.
|
|
73
|
+
- **Errors** name the file and line, and an unknown filter gets the closest name (`did you mean`).
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
## Handlebars and Mustache
|
|
77
|
+
|
|
78
|
+
Add `"hbs"` (or `"handlebars"`) or `"mustache"` to `templateFormats`, and those files render with [handlebars.js](https://handlebarsjs.com) (4.7). Mustache templates render as Handlebars.
|
|
79
|
+
|
|
80
|
+
- **Data:** the same as the other engines, so a template reads the page's real data and collections, and a missing value prints nothing. A date passed to a helper itself (`{{year date}}`) arrives as ISO 8601 text, and one inside an object the helper is given (`{{byline post}}`) is a `Date`.
|
|
81
|
+
- **Escaping:** `{{ }}` escapes HTML and `{{{ }}}` doesn't, so a layout writes `{{{content}}}`.
|
|
82
|
+
- **Helpers:** Handlebars' built-ins (`if`, `unless`, `each`, `with`, `lookup`, `len`, `eq` and the other comparisons). Your config `filters` are helpers: `{{shout title}}`, `{{wrap title "[" "]"}}`, and hash arguments (`size=2`) arrive as a trailing object. An unknown helper gets the closest name (`did you mean`). Use `{{len list}}`, not `list.length`.
|
|
83
|
+
- **Partials:** every file in `_includes`, by its path with or without the extension: `{{> nav}}` or `{{> nav.hbs}}`. A name without an extension is the Handlebars file when there is one.
|
|
84
|
+
- **Mustache:** variables, `{{{ }}}`, partials, sections over lists and truthy values (`{{#items}}{{.}}{{/items}}`) and inverted sections (`{{^items}}none{{/items}}`), also in `.hbs` files. Inside a section, reach outer values with `../name`, as in Handlebars. Not supported: lambdas and changing delimiters.
|
|
85
|
+
- **Errors** name the file and line, and an error in a partial names the partial's file.
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
## EJS
|
|
89
|
+
|
|
90
|
+
[EJS](https://ejs.co/) templates (`.ejs`) are plain JavaScript between tags, rendered with ejs 3.1, which is bundled in ssqch (no npm install). Add `"ejs"` to `templateFormats`, and `markdownEngine: "ejs"` to run Markdown through it. The output matches EJS 3's, whitespace included.
|
|
91
|
+
|
|
92
|
+
```ejs
|
|
93
|
+
<ul>
|
|
94
|
+
<%_ for (const post of collections.posts) { _%>
|
|
95
|
+
<li><a href="<%= post.url %>"><%= post.data.title %></a></li>
|
|
96
|
+
<%_ } _%>
|
|
97
|
+
</ul>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
- **Tags:** `<% code %>`, `<%= escaped %>`, `<%- raw %>` (a layout writes `<%- content %>`), `<%# comment %>` and `<%%` for a literal `<%`. `-%>` drops the newline after a tag, and `<%_`/`_%>` the spaces and tabs around it too.
|
|
101
|
+
- **Data:** the page's data, as variables (`title`, `page`, `collections`, and `locals` for all of it). Your config `filters` and ssqch's functions (`markdown`, `highlight`, `navTree`, ...) are functions by the same names: `<%= shout(title) %>`. A config filter is called directly, without converting anything.
|
|
102
|
+
- **Async:** a function's promise that's printed (`<%= later(x) %>`) is awaited, and a template can `await`.
|
|
103
|
+
- **Dates** print at UTC (`Sun Apr 05 2026 06:07:08 GMT+0000`), in `<%= %>`, `<%- %>` and lists, whatever the machine's time zone. Format a date in the template to show it otherwise (`date.toLocaleString("en-US", { timeZone: "America/New_York" })`).
|
|
104
|
+
- **Includes:** `<%- include("partials/nav") %>` reads `_includes/partials/nav.ejs` (and the themes'), `include("./card")` reads from the template's own folder, and a second argument adds variables: `include("card", { post })`. One that isn't there says which file you probably meant.
|
|
105
|
+
- **Errors** name the template and line, and the lines under them are the file's own. A variable nothing defines is a `ReferenceError`, as in EJS (`typeof x` is still safe).
|
|
106
|
+
- **Starters:** `ssqch init --engine ejs` (and `--starter docs --engine ejs`) writes the starters' layouts, render hook and containers in EJS.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Templates and data"
|
|
3
|
+
description: "The lay of the land."
|
|
4
|
+
---
|
|
5
|
+
The lay of the land:
|
|
6
|
+
|
|
7
|
+
- **The data cascade:** a page's data comes from several places, and each one replaces what the ones before it set: global data, the front matter of its layouts, directory data, the page's data file, its front matter, then `computed`. [Where a value comes from](where-values-come-from.md) has the exact order, and `ssqch inspect` shows it for any page.
|
|
8
|
+
- **Collections:** tags become collections, sorted by date, plus your custom ones. `excludeFromCollections: true` keeps a page out.
|
|
9
|
+
- **Pagination:** one template makes a page for each item, or each group of items, in a list. In its front matter, `pagination: { data: "collections.posts", size: 10, alias: "posts" }` and a `permalink` with the page number (`/blog/{% if pagination.pageNumber > 0 %}{{ pagination.pageNumber + 1 }}/{% endif %}`). `data` names the list: global data (`snacks`), a collection (`collections.posts`, a custom collection included, even one that returns plain objects, so one template can write a page per route of a route table), or `collections` itself, the collections' names, for a page per tag (`filter: [all]` leaves `all` out). `size: 1` gives a page per item, and `alias` names the item (`alias: post`, then `{{ post.data.title }}`). Each page gets `pagination.items` (its items), `pageNumber` (from 0), `pages` (every page's items), `hrefs` (every page's URL), `href.previous`, `href.next`, `href.first` and `href.last`. More options: `reverse`, `filter` (values to leave out) and `addAllPagesToCollections` (every page in the template's collections, not just the first). A `computed` value in a data file beside the template sees the alias, so each page's data can come from its item.
|
|
10
|
+
- **Permalinks:** dynamic permalinks, `permalink: false` and `dynamicPermalink`. A permalink (or `computed` value) with `{{ }}` renders in the page's own template language, so a Liquid page can write `permalink: "/{{ title | slugify }}/"`; Markdown and HTML pages use their `markdownEngine` or `htmlEngine` (Edge when that's `false`).
|
|
11
|
+
- **Front matter:** YAML between `---` lines, TOML between `+++` lines, or JSON after `---json` (`---yaml` and `---toml` work too). `.markdown` files are Markdown, like `.md`.
|
|
12
|
+
- **Navigation:** `navTree(nav, page.url)` takes a tree from data (`_data/nav.yml`: entries with `title`, `url`, and children under `children`, `items` or `pages`) and marks each entry `current`, `ancestor` or `open`, for a sidebar that highlights where you are. `navPager(nav, page.url)` returns `{ previous, next }` in reading order, and `navBreadcrumbs(nav, page.url)` the entries from the top down to the page. To build the tree from front matter instead, give pages `nav: { title, parent, order }` (or `nav: true`; `parent` names another entry's title, or its `key` when it has one) and use `pagesTree(collections.docs)`. URLs match with or without `index.html` and the last `/`.
|
|
13
|
+
- **Dates:** a page's `date` comes from its data, then from the start of its file name (`2024-06-01-post.md`), then from when the file last changed. `computed.date` works too. Collections are oldest first; undated pages come after the dated ones, in path order, so a fresh checkout or an edit (which changes file times) doesn't reorder them.
|
|
14
|
+
- **`SOURCE_DATE_EPOCH`:** set it (whole seconds since 1970, the reproducible-builds convention: `SOURCE_DATE_EPOCH=1767225600 ssqch build`) to pin the build's time, as Jekyll's `time:` does. `now()` in every engine, Liquid's `"now"`, Edge's `new Date()` and the date of every page without one become that time, so two builds of the same files write the same pages. A value that isn't a number is an error before the build starts. A site's own JavaScript (`Date.now()` in a filter) isn't changed.
|
|
15
|
+
- **Drafts:** `draft: true` builds the page in development (`ssqch serve`, or `--env development`) and leaves it out of production builds, collections included.
|
|
16
|
+
- **Excerpts and reading time:** `page.excerpt` is the HTML before a `<!-- more -->` comment, or else the first paragraph, for layouts and collections (`post.page.excerpt` in a list of posts). `readingTime(content)` is the minutes it takes to read some HTML at 200 words a minute (`readingTime(content, 250)` for another pace), at least 1.
|
|
17
|
+
- **Slugs:** `slugify("Pine Cone Crunch!")` is `pine-cone-crunch`: lowercase letters and digits, with a dash for each run of anything else (apostrophes are dropped, and letters outside ASCII are kept). It's the same function in every template language (`{{ title | slugify }}` in Jinja, Nunjucks and Liquid), and a config filter named `slugify` replaces it. `slugify(title, { separator: "_" })` (or `slugify(title, "_")`, `{{ title | slugify: "_" }}` in Liquid) puts another separator between the words, for URLs like `/recipes/taco_bake/`. Apostrophes are dropped (`Drew's Brownies` is `drews-brownies`); `apostrophes: "separate"` splits words there instead (`drew-s-brownies`), for a site whose URLs were made that way. Another option is an error. Before replacing a site's own slug filter with `slugify`, build with both and compare with `ssqch diff`: one changed URL is a broken link. Data files can import it, and `slugger()`, from `ssqch`.
|
|
18
|
+
- **Choosing engines:** pages are Jinja (`.jinja`) unless you list other languages in `templateFormats`, and `.md` files run through Jinja first, then Markdown (change that with `markdownEngine` and `htmlEngine`). Layouts follow the same rules, so a `.html` layout is a Jinja template by default. A template's `render` front matter overrides it: `render: md` for Markdown only (handy for a post full of `{{ }}` code samples), `render: [edge, md]` for a chain, or `render: false` to write the body as it is. A layout chain can mix languages (a Markdown post in a Liquid layout that sits in an Edge one). Around here that's called trail mix.
|
|
19
|
+
- **Text files with front matter** (Jekyll renders any file that starts with `---`, like a `.js` or `.txt` file): give the extension an engine that hands the text back, `engines: { js: (s) => s }`, add it to `templateFormats`, and in that folder's directory data (`assets/js/js.json`) set `"render": "liquid,js"` (Liquid first, or the engine you use) and `"permalink": "/{{ page.filePathStem }}.js"`, so the file keeps its name instead of becoming `app/index.html`. The config and the modules it imports are never pages, so `lib/filters.js` stays code. A `.scss` file with front matter needs nothing: `sassPlugin()` blanks it.
|
|
20
|
+
- **Everything else:** layout chaining, `page.*`, `templateContent` in collections, and an error when two pages would write the same file. Every template can read `ssqch.version`, `ssqch.env`, `ssqch.serving` and `ssqch.generator`.
|
|
21
|
+
|
|
22
|
+
Templates are [Jinja](template-languages.md#jinja-and-nunjucks) by default; [Edge](template-languages.md#edge), [Liquid](template-languages.md#liquid), [Nunjucks](template-languages.md#jinja-and-nunjucks), [Handlebars and Mustache](template-languages.md#handlebars-and-mustache) and [EJS](template-languages.md#ejs) are a `templateFormats` entry away, and one site can use several.
|
|
23
|
+
|
|
24
|
+
When a template fails, the error names the file and line (counted as the file is, front matter included) and is followed by the lines it's about, with carets under the part the message names when it quotes one:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
error: 1 error(s):
|
|
28
|
+
- rendering posts/pine.md with `jinja`: posts/pine.md:8: unknown filter `rnd` (did you mean `round`?)
|
|
29
|
+
|
|
30
|
+
--> src/posts/pine.md:8
|
|
31
|
+
6 | Crunchy, foresty, and only slightly sticky.
|
|
32
|
+
7 |
|
|
33
|
+
8 | The count is {{ sightings.total | rnd(1) }} so far.
|
|
34
|
+
| ^^^
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
A Jinja filter, test or function that doesn't exist says which one you probably meant, and so does a layout, a Jinja or Nunjucks template (`include`, `extends`, `import`) or an Edge include that isn't there (``layout `bse` not found: no sightings in src/_includes (did you mean `base`?)``). One that leads back to itself names the loop instead of running out of patience: `we've passed this tree before. Layout loop: base.edge -> wrap.edge -> base.edge`.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Themes"
|
|
3
|
+
description: "A theme is a folder shaped like a site's input folder."
|
|
4
|
+
---
|
|
5
|
+
<img align="right" src="../../../docs/assets/stickers/tent.svg" alt="" width="96">
|
|
6
|
+
|
|
7
|
+
A theme is a folder shaped like a site's input folder: `_includes/` (layouts, partials, render hooks, containers), `_data/`, pages, and files to copy, like stylesheets and fonts. Your site sits on top of it:
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
export default defineConfig({
|
|
11
|
+
theme: "themes/trail",
|
|
12
|
+
});
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
themes/trail/ src/ what the build uses
|
|
17
|
+
_includes/base.jinja the theme's layout
|
|
18
|
+
_includes/footer.jinja _includes/footer.jinja your footer
|
|
19
|
+
_data/site.json _data/site.json both, merged; your values win
|
|
20
|
+
404.md the theme's 404 page
|
|
21
|
+
about.md about.md your about page
|
|
22
|
+
assets/theme.css copied to /assets/theme.css
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- **File by file:** an include, layout, hook or container you have wins over the theme's at the same path, so changing a theme's footer means adding one file, not forking the theme. Data is merged, with your values winning. A page or file in the theme is built or copied unless your input folder has a file at that path.
|
|
26
|
+
- **Any engine:** the fallback works for Jinja, Nunjucks, Edge, Liquid and Handlebars includes alike, and a theme can mix them.
|
|
27
|
+
- **No package manager:** a theme can be a git repository pinned to a tag or a commit (its full 40-character hash): `theme: "https://github.com/you/trail-theme#v1.2.0"`, or `#v1.2.0:theme` when the theme is in a folder of its repository (`{ git, ref, dir }` says the same as an object). ssqch fetches it once with `git` and keeps it in `.cache/ssqch/themes/`, so later builds don't touch the network; changing the commit or tag fetches the new one. An unpinned URL is an error, so a build next year gets the theme you tested with.
|
|
28
|
+
- **Layers:** `theme` takes a list, and earlier themes sit on top of later ones.
|
|
29
|
+
- **Not part of a theme:** the files about it at the top of its folder (`README`, `LICENSE`, `CHANGELOG`, `package.json`).
|
|
30
|
+
|
|
31
|
+
To change something in a git theme, copy that one file from `.cache/ssqch/themes/` to the same path in your input folder and edit it there. In `sitesquatch.toml`, it's `theme = ["themes/trail"]`.
|
|
@@ -1,5 +1,9 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from Astro, VitePress, Next.js or Gatsby"
|
|
3
|
+
navTitle: "From Astro, VitePress, Next.js, Gatsby"
|
|
4
|
+
description: "These are component frameworks."
|
|
5
|
+
command: "ssqch docs --from astro"
|
|
6
|
+
---
|
|
3
7
|
These are component frameworks: a page is a tree of components, rendered on a server or at build time and, for some of them, run again in the browser. ssqch is a template-and-Markdown generator that ships HTML and only the JavaScript you write. So this move isn't a port of the framework. It's a sort of what you have into three piles:
|
|
4
8
|
|
|
5
9
|
1. **Content** (Markdown, front matter, data files): moves as it is.
|
|
@@ -8,7 +12,7 @@ These are component frameworks: a page is a tree of components, rendered on a se
|
|
|
8
12
|
|
|
9
13
|
On the sites studied for this guide, most components were in the second pile: about 80% of getbootstrap.com's (Astro) and 37% of vuejs.org's (VitePress). A site whose pages are mostly the third pile (react.dev, with a live editor in most pages) is an app, and should stay one.
|
|
10
14
|
|
|
11
|
-
The [`component-docs`](
|
|
15
|
+
The [`component-docs`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/component-docs/) example is distilled from getbootstrap.com: components in place of MDX, live examples with their source, and values read from Sass files. [`islands`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/islands/) shows interactive parts as custom elements.
|
|
12
16
|
|
|
13
17
|
## Is ssqch a fit?
|
|
14
18
|
|
|
@@ -1,8 +1,11 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from Docusaurus"
|
|
3
|
+
navTitle: "From Docusaurus"
|
|
4
|
+
description: "Docusaurus sites are React apps that happen to render documentation; ssqch builds the same documentation as static HTML that needs no JavaScript to read."
|
|
5
|
+
---
|
|
3
6
|
Docusaurus sites are React apps that happen to render documentation; ssqch builds the same documentation as static HTML that needs no JavaScript to read. The move is mostly mechanical for Markdown pages, and takes a decision for each React component: an Edge component, a container, or client-side JavaScript that stays.
|
|
4
7
|
|
|
5
|
-
Two examples are distilled from reactnative.dev: [`versioned-docs`](
|
|
8
|
+
Two examples are distilled from reactnative.dev: [`versioned-docs`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/versioned-docs/) (versions, sidebars, tabs, a blog with authors) and [`component-docs`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/component-docs/) (components in place of MDX, live examples).
|
|
6
9
|
|
|
7
10
|
## The config
|
|
8
11
|
|
|
@@ -48,7 +51,7 @@ Two examples are distilled from reactnative.dev: [`versioned-docs`](../../exampl
|
|
|
48
51
|
|
|
49
52
|
## React pages
|
|
50
53
|
|
|
51
|
-
Pages in `src/pages/*.js` become templates in any of ssqch's languages. Interactive parts (a playground, a live demo) stay JavaScript: ship them as custom elements with `elementsPlugin()` from `ssqch/elements`, which loads each one's script only on the pages that use it (the [`islands`](
|
|
54
|
+
Pages in `src/pages/*.js` become templates in any of ssqch's languages. Interactive parts (a playground, a live demo) stay JavaScript: ship them as custom elements with `elementsPlugin()` from `ssqch/elements`, which loads each one's script only on the pages that use it (the [`islands`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/islands/) example).
|
|
52
55
|
|
|
53
56
|
## Starting point
|
|
54
57
|
|
|
@@ -1,8 +1,11 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from Eleventy"
|
|
3
|
+
navTitle: "From Eleventy"
|
|
4
|
+
description: "SiteSquatch keeps many of the same ideas as Eleventy (a data cascade, collections, pagination, layouts) but isn't a drop-in replacement."
|
|
5
|
+
---
|
|
3
6
|
SiteSquatch keeps many of the same ideas as Eleventy (a data cascade, collections, pagination, layouts) but isn't a drop-in replacement: the config is one object instead of method calls, and names are SiteSquatch's own. Nunjucks and Liquid templates render as they are, so the first build usually comes early, and what's left is the config and a few front-matter keys.
|
|
4
7
|
|
|
5
|
-
The [ReverentGeek blog](https://github.com/reverentgeek/blog) made this move (from Eleventy with Edge templates), and the [`blog-categories`](
|
|
8
|
+
The [ReverentGeek blog](https://github.com/reverentgeek/blog) made this move (from Eleventy with Edge templates), and the [`blog-categories`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/blog-categories/) example is distilled from eslint.org, an Eleventy site.
|
|
6
9
|
|
|
7
10
|
## Importing
|
|
8
11
|
|
|
@@ -84,7 +87,7 @@ Where Eleventy's word means the same thing in ssqch, it works as it is: `ssqch d
|
|
|
84
87
|
|
|
85
88
|
## Templates
|
|
86
89
|
|
|
87
|
-
Nunjucks (`.njk`) renders with Nunjucks, the library Eleventy uses (ssqch's fork of it, which prints values as Nunjucks does: `true`, `a,b`), Liquid with liquidjs, Eleventy's Liquid library, and EJS (`.ejs`) with ejs (`include()` reads from `_includes`, as in Eleventy). Most templates work unchanged, shortcodes included;
|
|
90
|
+
Nunjucks (`.njk`) renders with Nunjucks, the library Eleventy uses (ssqch's fork of it, which prints values as Nunjucks does: `true`, `a,b`), Liquid with liquidjs, Eleventy's Liquid library, and EJS (`.ejs`) with ejs (`include()` reads from `_includes`, as in Eleventy). Most templates work unchanged, shortcodes included; [Each template language](../template-languages.md) lists what differs (Liquid shortcodes become filters, for one). JavaScript templates (`.11ty.js`) need rewriting in a template language, or an engine of your own for a new extension: `engines: { page: (source, data) => html }` renders `.page` files. WebC isn't supported.
|
|
88
91
|
|
|
89
92
|
## Things that work differently
|
|
90
93
|
|
|
@@ -1,8 +1,11 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from Hexo"
|
|
3
|
+
navTitle: "From Hexo"
|
|
4
|
+
description: "Hexo sites are Markdown posts, a theme of templates (often Nunjucks, sometimes EJS or Pug) and tag plugins inside the posts."
|
|
5
|
+
---
|
|
3
6
|
Hexo sites are Markdown posts, a theme of templates (often Nunjucks, sometimes EJS or Pug) and tag plugins inside the posts. Nunjucks themes render in ssqch as they are, posts keep their front matter, and tag plugins become filters that keep the same `{% tag %}` syntax. What takes work is the theme's helpers and anything that leans on Hexo's `site` object.
|
|
4
7
|
|
|
5
|
-
The [`docs-sidebar`](
|
|
8
|
+
The [`docs-sidebar`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/docs-sidebar/) example is distilled from hexo.io (and the FastAPI docs), and [`blog-tags`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/blog-tags/) shows a blog with tag pages and feeds.
|
|
6
9
|
|
|
7
10
|
## The config
|
|
8
11
|
|
|
@@ -11,7 +14,7 @@ The [`docs-sidebar`](../../examples/sites/docs-sidebar/) example is distilled fr
|
|
|
11
14
|
| Hexo | SiteSquatch |
|
|
12
15
|
| --- | --- |
|
|
13
16
|
| `source_dir: source`, `public_dir: public` | `dirs: { input: "source", output: "public" }` |
|
|
14
|
-
| `themes/<name>/layout/` | `dirs: { includes: "_includes" }`, or keep the theme where it is as a [theme](
|
|
17
|
+
| `themes/<name>/layout/` | `dirs: { includes: "_includes" }`, or keep the theme where it is as a [theme](../themes.md): `theme: "themes/<name>"`, with its templates under `_includes/` |
|
|
15
18
|
| `themes/<name>/source/` (CSS, JS, images) | The theme folder's other files are copied as they are, or `passthrough` |
|
|
16
19
|
| `_config.yml` values in templates (`config.title`) | `src/_data/config.yml`: every file in `_data` is a template variable |
|
|
17
20
|
| `theme_config`, `themes/<name>/_config.yml` (`theme.menu`) | `src/_data/theme.yml` |
|
|
@@ -1,5 +1,8 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from Jekyll"
|
|
3
|
+
navTitle: "From Jekyll"
|
|
4
|
+
description: "Jekyll sites move well."
|
|
5
|
+
---
|
|
3
6
|
Jekyll sites move well: Liquid runs as it is, `_layouts/`, `_includes/` and `_data/` keep their names, and `redirect_from`, `relative_url`, `markdownify` and `jsonify` work. What takes the time is the Ruby around the templates (Jekyll's `page` and `site`, its plugins) and kramdown, Jekyll's Markdown.
|
|
4
7
|
|
|
5
8
|
opensource.guide (382 pages in 29 languages, on GitHub Pages' gem) was moved this way as a study: the same 478 files, 95% of pages with the same text, and builds 5.9 times faster. Two thirds of the work was kramdown's `markdown="1"`, which ssqch doesn't read yet (below).
|
|
@@ -49,7 +52,7 @@ export default defineConfig({
|
|
|
49
52
|
- **Plugin tags** (`{% seo %}`, `{% feed_meta %}`): the config's functions are Liquid tags, so each is a function in `filters` that returns the HTML (`{% seo title=false %}` calls `seo({ title: false })`), or an include. `ssqch docs seo` has a starting point.
|
|
50
53
|
- **Filters:** `relative_url`, `markdownify` and `jsonify` work, and `where` is fast. Math, `split` and blocks that only `assign` behave as in Ruby's Liquid (`"r>" | times: 1` is 0, which jekyll-toc depends on). Jekyll's own `sort` differs from Liquid's: it sorts a hash into `[key, value]` pairs and puts pages missing the property first, where ssqch's `sort` (Liquid's) does neither, so pass a list from the config, or `sort` then handle the missing ones. A whole float prints as `5` (Ruby writes `5.0`).
|
|
51
54
|
- **A table of contents:** `toc(page.headings, { class: "section-nav", itemClass: "toc-entry toc-h{level}" })` writes jekyll-toc's markup, so its CSS keeps working (`{{ page.headings | toc: class: "section-nav" }}` in Liquid). It reads the page's headings after it renders, so it goes in the layout.
|
|
52
|
-
- **Files with front matter:** Jekyll renders any file that starts with `---`. In ssqch a `.js` (or `.txt`) file needs an engine: `engines: { js: (s) => s }`, `"js"` in `templateFormats`, and `"render": "liquid,js"` with a `.js` permalink in that folder's directory data (
|
|
55
|
+
- **Files with front matter:** Jekyll renders any file that starts with `---`. In ssqch a `.js` (or `.txt`) file needs an engine: `engines: { js: (s) => s }`, `"js"` in `templateFormats`, and `"render": "liquid,js"` with a `.js` permalink in that folder's directory data ("Text files with front matter" in [Templates and data](../templates.md)).
|
|
53
56
|
|
|
54
57
|
## Plugins
|
|
55
58
|
|
|
@@ -1,8 +1,11 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from MkDocs"
|
|
3
|
+
navTitle: "From MkDocs"
|
|
4
|
+
description: "MkDocs and SiteSquatch both build a site from a folder of Markdown and one config file."
|
|
5
|
+
---
|
|
6
|
+
MkDocs and SiteSquatch both build a site from a folder of Markdown and one config file. MkDocs' theme templates are Jinja, which ssqch renders with Jinja's filters, tests and methods on a fork of Nunjucks (`.jinja` files), so a custom theme or `overrides/` folder ports with few changes ([Jinja and Nunjucks](../template-languages.md#jinja-and-nunjucks) lists where Nunjucks isn't Jinja: a `{% set %}` inside a loop keeps its value, and there is no `{% break %}`); Material for MkDocs' features map onto containers, hooks and the navigation helpers.
|
|
7
|
+
|
|
8
|
+
The [`docs-sidebar`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/docs-sidebar/) example is distilled from the FastAPI docs (and hexo.io): a sidebar from a YAML nav, a table of contents, admonitions, code from files and Pagefind search.
|
|
6
9
|
|
|
7
10
|
## The config
|
|
8
11
|
|
|
@@ -1,8 +1,11 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from Zola"
|
|
3
|
+
navTitle: "From Zola"
|
|
4
|
+
description: "Zola is a single Rust binary, and SiteSquatch runs on Node (from npm), so the move is mostly about templates."
|
|
5
|
+
---
|
|
3
6
|
Zola is a single Rust binary, and SiteSquatch runs on Node (from npm), so the move is mostly about templates: Tera becomes Nunjucks or Jinja (which read almost the same), and `config.toml` becomes `ssqch.config.js`. Your content can stay as it is: SiteSquatch reads TOML front matter between `+++` lines.
|
|
4
7
|
|
|
5
|
-
blog.rust-lang.org was ported this way as a trial: all of its URLs and most pages came out the same. The [`blog-tags`](
|
|
8
|
+
blog.rust-lang.org was ported this way as a trial: all of its URLs and most pages came out the same. The [`blog-tags`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/blog-tags/) example is a small blog laid out like a Zola site (sections, tags with feeds, aliases, highlighting), distilled from blog.rust-lang.org.
|
|
6
9
|
|
|
7
10
|
## Importing
|
|
8
11
|
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Trailheads: moving from another generator"
|
|
3
|
+
navTitle: "Moving to ssqch"
|
|
4
|
+
description: "Everything migrates eventually."
|
|
5
|
+
---
|
|
6
|
+
Everything migrates eventually. The trailheads map another generator's config, front matter and templates onto ssqch's, and `ssqch docs --from <generator>` prints the one you need: [from Zola](trailheads/from-zola.md), [from Eleventy](trailheads/from-eleventy.md), [from Docusaurus](trailheads/from-docusaurus.md), [from MkDocs](trailheads/from-mkdocs.md), [from Hexo](trailheads/from-hexo.md), [from Jekyll](trailheads/from-jekyll.md) and [from component frameworks](trailheads/from-component-frameworks.md) (Astro, VitePress, Next.js, Gatsby). [`examples/sites/`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/) has small, complete sites to start from or copy parts of, each built in CI: `blog-tags`, `blog-categories`, `docs-sidebar`, `glossary-docs`, `versioned-docs`, `component-docs`, `reference-pages` and `islands`.
|
|
7
|
+
|
|
8
|
+
For a Zola site, `ssqch import zola` moves `tags` out of `[taxonomies]` and turns `path` into `permalink` in each page's front matter, writes a first `ssqch.config.js` from `config.toml` (the site's data, Markdown options, Sass, redirects, a sitemap), and lists what the Tera templates, shortcodes and sections need.
|
|
9
|
+
|
|
10
|
+
For an Eleventy site, `ssqch import eleventy` does the mechanical part. It renames `*.11tydata.*` files, rewrites front matter keys and image attributes to ssqch's names, writes a first `ssqch.config.js` from what it can read in the Eleventy config (folders, passthrough copies, template engines, `pathPrefix`), and lists what's left to port by hand, each with its file and line and what it becomes: filters, shortcodes, collections, plugins and their ssqch equivalents. Without `--write` it only prints the list, so run it in a clean git checkout, read it, then run it again with `--write`:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
ssqch import eleventy # what would change, and what's left (or: ssqch import zola)
|
|
14
|
+
ssqch import eleventy --write # make the changes
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Habits come along too. Where another generator's word means the same thing in ssqch, it works, and says ssqch's name once (`--quiet` hides it):
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
$ ssqch dev
|
|
21
|
+
note: dev works; ssqch calls it serve (ssqch docs serve)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The words that work: the commands `dev`, `start`, `server` and `watch` (for `ssqch serve`), `preview` (`ssqch serve --built`) and `generate` (`ssqch build`); the flags `--watch` and `--serve` (`ssqch serve`), `-d` and `--destination` (`--output`) and `--pathprefix` (`--base`); the config options `pathPrefix` (`base`), `dir` (`dirs`), `publishDir` and `outDir` (`dirs.output`), and `markdownTemplateEngine` and `htmlTemplateEngine` (`markdownEngine` and `htmlEngine`); the front-matter keys `eleventyComputed` (`computed`), `eleventyExcludeFromCollections` (`excludeFromCollections`), `redirect_from` (`aliases`) and `templateEngineOverride` (`render`, its `"njk,md"` string included); and, in Jinja, Nunjucks and Liquid, the filters `url` and `relative_url` (they give the URL back as it is, since the build adds `base` itself) and `markdownify` (`markdown`). An alias and ssqch's name for the same thing together are an error (`pathPrefix and base are two names for one option`). The docs, starters and messages use ssqch's names, and `ssqch build --format json` lists the aliases a site used in `aliases` rather than in `warnings`.
|
|
25
|
+
|
|
26
|
+
A word that would mean something else in ssqch is refused, with ssqch's name for it and where to read more:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
$ ssqch check
|
|
30
|
+
error: unrecognized subcommand 'check'
|
|
31
|
+
|
|
32
|
+
`ssqch build` checks as it builds: content schemas on every build, and internal links with `linksPlugin()`.
|
|
33
|
+
More: ssqch docs "Content schemas"
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Hugo's `baseURL` (a full URL, where `base` is a path), `--drafts` and `-D` (ssqch builds drafts in development, not with a flag), `addPassthroughCopy` and the other `add*` calls (an ssqch config is an object), `{{ eleventy.generator }}`, Jekyll's `site.posts` and `published: false`, and `eleventyNavigation` (ssqch's own navigation reads `nav`; templates that call eleventy-navigation's filter still read it) get the same treatment (every unknown config option is listed in one go), and `ssqch build --format json` carries the answer as data, in a `hint` with `use` (ssqch's name) and `more`. A folder that has another generator's config and no ssqch config gets a warning naming the importer and `ssqch docs --from`, instead of a build with ssqch's defaults that nobody asked for. `ssqch docs --from eleventy` (or `hugo`, `jekyll`, `zola`, ...) lists that generator's words with ssqch's for each, marking the ones that work, then prints its trailhead, and `ssqch docs pathPrefix` answers for one word.
|
|
37
|
+
|
|
38
|
+
Whichever generator you're leaving, build the site with it and with ssqch and run [`ssqch diff`](comparing-builds.md) on the two output folders: it shows which pages differ and how, so you know when the move is done.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Where a value comes from"
|
|
3
|
+
description: "A page's data is a cascade."
|
|
4
|
+
---
|
|
5
|
+
A page's data is a cascade. From the lowest level to the highest:
|
|
6
|
+
|
|
7
|
+
1. **Global data:** files in a theme's `_data/`, then the site's `_data/` (`site.json` is `site`), then the config's `data`.
|
|
8
|
+
2. **Layouts:** the front matter of the page's layouts, the outermost layout first.
|
|
9
|
+
3. **Directory data:** `posts/posts.json` (or `.yaml`, `.toml`, `posts.data.js`) applies to everything in `posts/` and below it. The outermost folder goes first.
|
|
10
|
+
4. **The page's data file:** `pine.json` or `pine.data.js` next to `pine.md`.
|
|
11
|
+
5. **Front matter.**
|
|
12
|
+
6. **`computed`:** worked out last, from everything above. A computed value that reads `collections` sees them as they are without the pages that wait for them, the way a page paginated over a collection does. A computed `layout` can depend on the page (`layout: (data) => data.wide ? "wide.html" : "post.html"`): each page then gets the layouts its value names, with their front matter below the page's data, and `""` or `false` for none. It can't set `page` (ssqch's own: a computed `page` is an error, which names the file).
|
|
13
|
+
|
|
14
|
+
A higher level replaces what a lower one set. Objects merge key by key and lists are joined (a post's `tags` add to its folder's), unless `deepMerge` is off. `page` and `ssqch` are built in.
|
|
15
|
+
|
|
16
|
+
When a value isn't what you expected, `ssqch inspect` follows its tracks back to the level that set it. Give it a page's URL or its template's path:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
ssqch inspect /guides/pine/
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
/guides/pine/
|
|
24
|
+
From src/guides/2024-03-02-pine.md (jinja, md)
|
|
25
|
+
Writes dist/guides/pine/index.html
|
|
26
|
+
Layouts _includes/guide.jinja > _includes/base.jinja
|
|
27
|
+
Date 2024-03-02T00:00:00Z (from the file's name)
|
|
28
|
+
Collections all, guides
|
|
29
|
+
|
|
30
|
+
Data (name, value, and the level of the cascade that set it)
|
|
31
|
+
site {name, author} src/_data/site.json
|
|
32
|
+
section "guides" layout _includes/guide.jinja (over layout _includes/base.jinja)
|
|
33
|
+
layout "guide.jinja" src/guides/guides.json
|
|
34
|
+
level "hard" front matter (over src/guides/guides.json, src/guides/2024-03-02-pine.json)
|
|
35
|
+
title "Pine" front matter
|
|
36
|
+
label "Pine (hard)" computed
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`--field` shows one value in full, with every level that set it:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
ssqch inspect src/guides/2024-03-02-pine.md --field level
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
level = "hard"
|
|
47
|
+
|
|
48
|
+
Set by (the last one wins):
|
|
49
|
+
src/guides/guides.json "easy"
|
|
50
|
+
src/guides/2024-03-02-pine.json "medium"
|
|
51
|
+
> front matter "hard"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
- **Inside a value:** a dotted path reaches into objects (`--field site.author.name`, `--field hero.alt`).
|
|
55
|
+
- **Pages made by pagination:** a template that makes many pages needs the URL of one of them. `ssqch inspect src/tags.jinja` lists them.
|
|
56
|
+
- **Scripts and agents:** `--format json` prints the report as JSON (`schemaVersion: 1`), with `value`, `from` and `setBy` for each field.
|
|
57
|
+
- **No page is built:** it reads the site as a build does, up to the point of rendering. `beforeBuild` hooks run, since data can depend on them (a command that writes a data file, a plugin that sets itself up there), but no page is rendered or written, and `afterBuild` doesn't run. Standard output is only the report; anything a hook or `console.log` prints goes to standard error.
|
package/bundled/ssqch.d.ts
CHANGED
|
@@ -249,6 +249,8 @@ declare module "ssqch" {
|
|
|
249
249
|
strict?: boolean;
|
|
250
250
|
/** `page.lastModified`: `"git"` for the last commit that changed the page's file (its modification time when it has uncommitted changes), or `"file"` for the modification time. Off by default. Needs the full history in CI (`fetch-depth: 0`). */
|
|
251
251
|
lastModified?: "git" | "file" | false;
|
|
252
|
+
/** 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, the same in every checkout, or `"file"` (the default) for the file's modification time, which is when the checkout wrote it. Either way it sorts after the dated pages, by path. Needs the full history in CI (`fetch-depth: 0`). */
|
|
253
|
+
dateFallback?: "git" | "file";
|
|
252
254
|
/** The time zone the site's own JavaScript runs in, as an IANA name (`"UTC"`, `"America/New_York"`): `Date`'s local methods and libraries like luxon and date-fns, in data files, filters, hooks and Edge templates, so a laptop and CI build the same pages. ssqch's own date filters are UTC whatever this says. Default: the machine's. The config's own top-level code runs before it applies. */
|
|
253
255
|
timeZone?: string;
|
|
254
256
|
/** The path the site is served under, when that isn't the root of its domain: `"/repo/"` for `https://you.github.io/repo/`. Templates and `page.url` stay as they are; ssqch adds the base to URLs from the site's root in the HTML it writes. Use the `withBase()` filter outside HTML attributes. */
|
|
@@ -407,7 +409,7 @@ declare module "ssqch/rss" {
|
|
|
407
409
|
export function dateToRfc3339(date: Date | string): string;
|
|
408
410
|
/** A date as RFC 822 (`Sat, 01 Jun 2024 00:00:00 +0000`), for RSS feeds. */
|
|
409
411
|
export function dateToRfc822(date: Date | string): string;
|
|
410
|
-
/** A URL made absolute against the site's address: `absoluteUrl(post.url, "https://example.com")`. */
|
|
412
|
+
/** A URL made absolute against the site's address: `absoluteUrl(post.url, "https://example.com")`. As a template filter, it puts the site's `base` in front of a URL from the root that doesn't have it yet; called from code, it resolves as `new URL(url, base)` does. */
|
|
411
413
|
export function absoluteUrl(url: string, base: string): string;
|
|
412
414
|
/** Every link and image in some HTML made absolute, for a feed's content. */
|
|
413
415
|
export function htmlToAbsoluteUrls(html: string, base: string): string;
|
package/lib/assets.js
CHANGED
|
@@ -2,27 +2,27 @@ import { createRequire as __ssqchCreateRequire } from "node:module";
|
|
|
2
2
|
const require = __ssqchCreateRequire(import.meta.url);
|
|
3
3
|
import {
|
|
4
4
|
Options
|
|
5
|
-
} from "./chunk-
|
|
5
|
+
} from "./chunk-HGJ5VWUR.js";
|
|
6
6
|
import {
|
|
7
7
|
BUILTINS,
|
|
8
8
|
blake3Hex,
|
|
9
9
|
rewriteHtml
|
|
10
|
-
} from "./chunk-
|
|
11
|
-
import "./chunk-
|
|
10
|
+
} from "./chunk-QMA7CK7B.js";
|
|
11
|
+
import "./chunk-LCPSKHAV.js";
|
|
12
12
|
import "./chunk-NKXEPHRZ.js";
|
|
13
13
|
import "./chunk-AD3HAW3W.js";
|
|
14
14
|
import "./chunk-DDV6JEC2.js";
|
|
15
|
-
import "./chunk-
|
|
15
|
+
import "./chunk-5DNDSNTP.js";
|
|
16
16
|
import "./chunk-FVZ5JBRI.js";
|
|
17
|
-
import "./chunk-
|
|
17
|
+
import "./chunk-NFJJKDRI.js";
|
|
18
18
|
import "./chunk-UU43WIZG.js";
|
|
19
|
-
import "./chunk-
|
|
19
|
+
import "./chunk-JWCCVTTR.js";
|
|
20
20
|
import "./chunk-CMUWRPSQ.js";
|
|
21
21
|
import {
|
|
22
22
|
bail,
|
|
23
23
|
warn,
|
|
24
24
|
warning
|
|
25
|
-
} from "./chunk-
|
|
25
|
+
} from "./chunk-BGCBSQ4A.js";
|
|
26
26
|
import {
|
|
27
27
|
displayPath
|
|
28
28
|
} from "./chunk-VJWQSYEG.js";
|
|
@@ -167,6 +167,7 @@ BUILTINS.set("ssqch/assets", (config, given) => {
|
|
|
167
167
|
let sri = /* @__PURE__ */ new Map();
|
|
168
168
|
let names = [];
|
|
169
169
|
let changing = [];
|
|
170
|
+
let renamed = [];
|
|
170
171
|
config.beforeBuild.push({ label: "", fn: () => {
|
|
171
172
|
const output = path.resolve(config.root, config.output);
|
|
172
173
|
const shownOutput = displayPath(config.root, output);
|
|
@@ -174,6 +175,8 @@ BUILTINS.set("ssqch/assets", (config, given) => {
|
|
|
174
175
|
const map = /* @__PURE__ */ new Map();
|
|
175
176
|
const hashes = /* @__PURE__ */ new Map();
|
|
176
177
|
const done = [];
|
|
178
|
+
for (const plain of renamed) config.renamedCopies.delete(plain);
|
|
179
|
+
renamed = [];
|
|
177
180
|
for (const file of files) {
|
|
178
181
|
if (enabled) {
|
|
179
182
|
const src = passthroughSource(config, file);
|
|
@@ -187,6 +190,11 @@ BUILTINS.set("ssqch/assets", (config, given) => {
|
|
|
187
190
|
}
|
|
188
191
|
}
|
|
189
192
|
const hashed = fingerprint(output, file);
|
|
193
|
+
if (src !== void 0) {
|
|
194
|
+
const plain = path.join(output, file.replace(/^\/+/, ""));
|
|
195
|
+
config.renamedCopies.set(plain, path.join(output, hashed.replace(/^\/+/, "")));
|
|
196
|
+
renamed.push(plain);
|
|
197
|
+
}
|
|
190
198
|
if (withIntegrity) {
|
|
191
199
|
const at = path.join(output, hashed.replace(/^\/+/, ""));
|
|
192
200
|
let bytes;
|