ssqch 0.7.0 → 0.8.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 +6 -4
- package/bin/ssqch.js +14 -48
- package/bundled/README.md +1247 -0
- package/bundled/completions/bash +840 -0
- package/bundled/completions/elvish +286 -0
- package/bundled/completions/fish +182 -0
- package/bundled/completions/powershell +318 -0
- package/bundled/completions/zsh +510 -0
- package/bundled/ssqch.d.ts +532 -0
- package/bundled/starter/engines/index.edge +11 -0
- package/bundled/starter/engines/index.ejs +11 -0
- package/bundled/starter/engines/index.hbs +11 -0
- package/bundled/starter/engines/index.liquid +11 -0
- package/bundled/starter/engines/layout.edge +35 -0
- package/bundled/starter/engines/layout.ejs +35 -0
- package/bundled/starter/engines/layout.hbs +35 -0
- package/bundled/starter/engines/layout.liquid +35 -0
- package/bundled/starter/gitignore +3 -0
- package/bundled/starter/jsconfig.json +11 -0
- package/bundled/starter/src/404.md +8 -0
- package/bundled/starter/src/_blueprints/posts.md +5 -0
- package/bundled/starter/src/_data/site.json +4 -0
- package/bundled/starter/src/_includes/layout.jinja +35 -0
- package/bundled/starter/src/index.jinja +11 -0
- package/bundled/starter/src/posts/i-know-what-i-saw.md +11 -0
- package/bundled/starter/src/posts/posts.json +4 -0
- package/bundled/starter/src/posts/raiders-of-the-lost-path.md +27 -0
- package/bundled/starter/src/posts/the-cache-of-the-wild.md +26 -0
- package/bundled/starter/src/posts/the-stump-has-moved.md +15 -0
- package/bundled/starter/src/posts/upon-further-review-a-stump.md +18 -0
- package/bundled/starter/ssqch.config.js +29 -0
- package/bundled/starter-docs/engines/edge/base.edge +41 -0
- package/bundled/starter-docs/engines/edge/containers/details.edge +5 -0
- package/bundled/starter-docs/engines/edge/containers/tab.edge +4 -0
- package/bundled/starter-docs/engines/edge/containers/tabs.edge +5 -0
- package/bundled/starter-docs/engines/edge/doc.edge +59 -0
- package/bundled/starter-docs/engines/edge/hooks/heading.edge +2 -0
- package/bundled/starter-docs/engines/ejs/base.ejs +41 -0
- package/bundled/starter-docs/engines/ejs/containers/details.ejs +5 -0
- package/bundled/starter-docs/engines/ejs/containers/tab.ejs +4 -0
- package/bundled/starter-docs/engines/ejs/containers/tabs.ejs +5 -0
- package/bundled/starter-docs/engines/ejs/doc.ejs +59 -0
- package/bundled/starter-docs/engines/ejs/hooks/heading.ejs +2 -0
- package/bundled/starter-docs/engines/hbs/base.hbs +41 -0
- package/bundled/starter-docs/engines/hbs/containers/details.hbs +5 -0
- package/bundled/starter-docs/engines/hbs/containers/tab.hbs +4 -0
- package/bundled/starter-docs/engines/hbs/containers/tabs.hbs +5 -0
- package/bundled/starter-docs/engines/hbs/doc.hbs +58 -0
- package/bundled/starter-docs/engines/hbs/hooks/heading.hbs +2 -0
- package/bundled/starter-docs/engines/liquid/base.liquid +41 -0
- package/bundled/starter-docs/engines/liquid/containers/details.liquid +5 -0
- package/bundled/starter-docs/engines/liquid/containers/tab.liquid +4 -0
- package/bundled/starter-docs/engines/liquid/containers/tabs.liquid +5 -0
- package/bundled/starter-docs/engines/liquid/doc.liquid +60 -0
- package/bundled/starter-docs/engines/liquid/hooks/heading.liquid +2 -0
- package/bundled/starter-docs/gitignore +4 -0
- package/bundled/starter-docs/src/404.md +12 -0
- package/bundled/starter-docs/src/_blueprints/docs.md +5 -0
- package/bundled/starter-docs/src/_data/nav.yml +10 -0
- package/bundled/starter-docs/src/_data/site.json +5 -0
- package/bundled/starter-docs/src/_includes/base.jinja +41 -0
- package/bundled/starter-docs/src/_includes/containers/details.jinja +5 -0
- package/bundled/starter-docs/src/_includes/containers/tab.jinja +4 -0
- package/bundled/starter-docs/src/_includes/containers/tabs.jinja +5 -0
- package/bundled/starter-docs/src/_includes/doc.jinja +59 -0
- package/bundled/starter-docs/src/_includes/hooks/heading.jinja +2 -0
- package/bundled/starter-docs/src/assets/docs.css +257 -0
- package/bundled/starter-docs/src/assets/docs.js +67 -0
- package/bundled/starter-docs/src/docs/docs.json +1 -0
- package/bundled/starter-docs/src/docs/guides/deploying.md +77 -0
- package/bundled/starter-docs/src/docs/guides/writing.md +65 -0
- package/bundled/starter-docs/src/docs/index.md +29 -0
- package/bundled/starter-docs/src/docs/install.md +42 -0
- package/bundled/starter-docs/src/index.md +13 -0
- package/bundled/starter-docs/ssqch.config.js +40 -0
- package/bundled/trailheads/from-component-frameworks.md +116 -0
- package/bundled/trailheads/from-docusaurus.md +55 -0
- package/bundled/trailheads/from-eleventy.md +140 -0
- package/bundled/trailheads/from-hexo.md +92 -0
- package/bundled/trailheads/from-mkdocs.md +45 -0
- package/bundled/trailheads/from-zola.md +71 -0
- package/lib/assets.js +235 -3
- package/lib/chunk-37KSIVNY.js +29 -0
- package/lib/chunk-3GYLOC6Y.js +1017 -0
- package/lib/chunk-3NYSSA2C.js +22 -0
- package/lib/chunk-3PHCFZEU.js +209 -0
- package/lib/chunk-4Q6WMTER.js +32 -0
- package/lib/chunk-6XYSFG6V.js +4423 -0
- package/lib/chunk-6XYSFG6V.js.LEGAL.txt +41 -0
- package/lib/chunk-AD3HAW3W.js +10 -0
- package/lib/chunk-AMBFWPZ4.js +118 -0
- package/lib/chunk-BOBPVAX2.js +37088 -0
- package/lib/chunk-BOBPVAX2.js.LEGAL.txt +27 -0
- package/lib/chunk-BRK4MXXO.js +565 -0
- package/lib/chunk-C35KIPAR.js +247 -0
- package/lib/chunk-CDEPYU7W.js +25 -0
- package/lib/chunk-CMUWRPSQ.js +113 -0
- package/lib/chunk-DDV6JEC2.js +46 -0
- package/lib/chunk-DHHQKW4F.js +71 -0
- package/lib/chunk-EIT4ZDT4.js +1485 -0
- package/lib/chunk-EZZUUPI4.js +20 -0
- package/lib/chunk-F65YUXZ7.js +334 -0
- package/lib/chunk-FVZ5JBRI.js +115 -0
- package/lib/chunk-FYGE634X.js +44 -0
- package/lib/chunk-GOE4ZSAB.js +75 -0
- package/lib/chunk-GSKVRAHF.js +44 -0
- package/lib/chunk-HR2RU2LY.js +999 -0
- package/lib/chunk-HXCLCXRT.js +20 -0
- package/lib/chunk-I3PS26CI.js +48 -0
- package/lib/chunk-IAFM5ITE.js +11 -0
- package/lib/chunk-IRHRK7XB.js +54 -0
- package/lib/chunk-JRT7TQQP.js +57 -0
- package/lib/chunk-JSPSMIJ2.js +217 -0
- package/lib/chunk-KBGE5MCY.js +175 -0
- package/lib/chunk-N5QTGQ5N.js +207 -0
- package/lib/chunk-NKXEPHRZ.js +136 -0
- package/lib/chunk-NUKCUDC4.js +146 -0
- package/lib/chunk-RI2L3VGO.js +376 -0
- package/lib/chunk-TDGBQNGW.js +251 -0
- package/lib/chunk-TN6EEDX2.js +3935 -0
- package/lib/chunk-TWCVHOKO.js +1229 -0
- package/lib/chunk-UGEGUUBT.js +29 -0
- package/lib/chunk-UU43WIZG.js +29 -0
- package/lib/chunk-VJWQSYEG.js +119 -0
- package/lib/chunk-VVPZ5PDP.js +160 -0
- package/lib/chunk-WMOVCQO6.js +1287 -0
- package/lib/chunk-WP3RPVUM.js +211 -0
- package/lib/chunk-YSH2NMIE.js +502 -0
- package/lib/cli.js +540 -0
- package/lib/elements.js +180 -3
- package/lib/image.js +27 -3
- package/lib/links.js +464 -3
- package/lib/minify.js +69 -3
- package/lib/redirects.js +152 -3
- package/lib/rss.js +139 -3
- package/lib/sass.js +221 -3
- package/lib/sitemap.js +88 -3
- package/lib/ssqch.js +28 -0
- package/package.json +83 -80
- package/src/serve/live.js +174 -0
- package/src/serve/not-found.html +31 -0
- package/types/globals.d.ts +3 -2
- package/types/image.d.ts +7 -3
- package/types/index.d.ts +18 -5
- package/types/links.d.ts +1 -1
- package/types/minify.d.ts +1 -1
- package/types/rss.d.ts +1 -1
- package/types/sass.d.ts +1 -1
- package/wasm/markdown.wasm +0 -0
- package/wasm/minify.wasm +0 -0
- package/wasm/sass.wasm +0 -0
- package/lib/index.js +0 -3
- package/platforms.json +0 -6
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Trailhead: moving from Eleventy
|
|
2
|
+
|
|
3
|
+
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
|
+
|
|
5
|
+
The [ReverentGeek blog](https://github.com/reverentgeek/blog) made this move (from Eleventy with Edge templates), and the [`blog-categories`](../../examples/sites/blog-categories/) example is distilled from eslint.org, an Eleventy site.
|
|
6
|
+
|
|
7
|
+
## Importing
|
|
8
|
+
|
|
9
|
+
`ssqch import eleventy` does the mechanical part of what this guide describes: it renames `*.11tydata.*` data files, rewrites the front matter keys and `eleventy:` image attributes below, writes a first `ssqch.config.js` from the Eleventy config (folders, passthrough copies, watch targets, template engines, `pathPrefix`, and filters and shortcodes that use only their own arguments, copied as written, in the config's own indentation), swaps `@11ty/eleventy` for `ssqch` in `package.json` and its scripts (`eleventy` is `ssqch build`, `eleventy --serve` is `ssqch serve`), and lists what's left, including a lockfile to update or a stale one from another package manager, each with its file and line: every filter, shortcode, collection, transform and plugin, and what it becomes. Run it once to read the list (it changes nothing), then with `--write` in a clean git checkout.
|
|
10
|
+
|
|
11
|
+
## The config
|
|
12
|
+
|
|
13
|
+
`.eleventy.js` becomes `ssqch.config.js`, an ES module whose default export is the config: an object, or a function of `{ env, serving }` that returns one.
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
import { defineConfig } from "ssqch";
|
|
17
|
+
import { rssPlugin } from "ssqch/rss";
|
|
18
|
+
|
|
19
|
+
export default defineConfig(({ env }) => ({
|
|
20
|
+
dirs: { input: "src", output: "_site" },
|
|
21
|
+
templateFormats: ["njk", "md"],
|
|
22
|
+
markdownEngine: "njk",
|
|
23
|
+
filters: { year: (d) => d.getUTCFullYear() },
|
|
24
|
+
collections: { posts: (pages) => pages.byGlob("src/posts/*.md") },
|
|
25
|
+
plugins: [rssPlugin()],
|
|
26
|
+
}));
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
| Eleventy | SiteSquatch |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| `addFilter`, `addNunjucksFilter` | `filters: { name: fn }`, callable from every template language (`{{ name(x) }}` in Edge, `{{ x \| name }}` in Nunjucks and Liquid). Async functions are awaited. |
|
|
32
|
+
| `addShortcode` | A filter too. In Nunjucks, a config filter is also a tag, so `{% image "a.png", "Alt" %}` keeps working as it is. |
|
|
33
|
+
| `addPairedShortcode` | In Nunjucks, the same filter with a closing tag: `{% callout "tip" %}...{% endcallout %}` calls `callout(content, "tip")`. In Markdown, a `::: name` container (`_includes/containers/name.*`). In Edge, a component. |
|
|
34
|
+
| `addCollection(name, api => ...)` | `collections: { name: (pages) => ... }`. `getAll()` is `pages.all()`, `getFilteredByTag(t)` is `pages.byTag(t)`, `getFilteredByGlob(g)` is `pages.byGlob(g)`. |
|
|
35
|
+
| `addGlobalData` | `data: { name: value or function }` |
|
|
36
|
+
| `addTransform` | `transforms: { name: (content, page) => content }` |
|
|
37
|
+
| `addPassthroughCopy` | `passthrough`: a path, a glob, or `{ from: to }` |
|
|
38
|
+
| `addWatchTarget` | `watch` |
|
|
39
|
+
| `addPlugin` | `plugins`: objects with any of these keys, or functions that return one |
|
|
40
|
+
| `on("eleventy.before")`, `on("eleventy.after")` | `beforeBuild`, `afterBuild` |
|
|
41
|
+
| `dir` | `dirs` (`dir` works too) |
|
|
42
|
+
| `markdownTemplateEngine`, `htmlTemplateEngine` | `markdownEngine`, `htmlEngine` (Eleventy's names work too) |
|
|
43
|
+
| `setLibrary("md", markdownIt(...).use(...))` | `markdown: { ... }` options, render hooks and containers (below) |
|
|
44
|
+
| `pathPrefix` | `base: "/repo/"` (`pathPrefix` works too). Links in templates need no `url` filter (it works, and gives the URL back as it is): ssqch adds the base to every URL from the site's root in the HTML it writes, and `withBase()` covers scripts and JSON. |
|
|
45
|
+
|
|
46
|
+
The config is ESM, though your own CommonJS files (`require`, `module.exports`) load too. ssqch runs on Node, like Eleventy, so a site's packages run as they are: luxon, date-fns, lodash, markdown-it, slugify-style helpers and the libraries Eleventy brought along all work, and so do servers, child processes and native addons.
|
|
47
|
+
|
|
48
|
+
Where Eleventy's word means the same thing in ssqch, it works as it is: `ssqch dev` and `ssqch build --serve` serve, `--pathprefix` is `--base`, and the config options and front matter keys marked "works too" in these tables do what ssqch's names do, so a site can move first and rename later. Each one says ssqch's name once (`note: pathPrefix works; ssqch calls it base`), and setting both names is an error. Filters too: `url`, and a `slugify` that's the same in every template language.
|
|
49
|
+
|
|
50
|
+
`ssqch serve` reads the config again when it changes, so there's no restart while you port it.
|
|
51
|
+
|
|
52
|
+
## Front matter and data
|
|
53
|
+
|
|
54
|
+
| Eleventy | SiteSquatch |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `eleventyComputed` | `computed` (`eleventyComputed` works too) |
|
|
57
|
+
| `eleventyExcludeFromCollections` | `excludeFromCollections` (Eleventy's name works too) |
|
|
58
|
+
| `templateEngineOverride: md` | `render: md` (or a list, or `false`). `templateEngineOverride` works too, `"njk,md"` included. |
|
|
59
|
+
| `permalink`, `layout`, `tags`, `pagination`, `date` | The same |
|
|
60
|
+
| `*.11tydata.js`, `*.11tydata.json` | `*.data.js`, `*.data.json` |
|
|
61
|
+
| `_data/*.js` and directory data (`posts/posts.json`) | The same |
|
|
62
|
+
| `page.url`, `page.fileSlug`, `page.inputPath`, `page.outputPath`, `page.date` | The same, plus `page.headings` and `page.excerpt` in layouts. Dates in file names (`2024-06-01-post.md`) work the same way. |
|
|
63
|
+
| `layouts: "_includes/layouts"` and `layout: post` | `dirs: { layouts: "_includes/layouts" }` |
|
|
64
|
+
| `addDataExtension("yml", ...)` with js-yaml | Built in: YAML, TOML and JSON data files load as they are, and `readData(path)` from `ssqch` reads one in code |
|
|
65
|
+
| `eleventyNavigation` | `nav` front matter with the same `key`, `parent`, `order` and `title` (for now, `parent` has to be another page's `key` or title, and `title` doesn't fall back to `key`), turned into a tree with `pagesTree(collections.all)`; or a data file such as `_data/nav.yml`. `navTree`, `navPager` and `navBreadcrumbs` mark the current page, and give previous/next and the trail. To keep eleventy-navigation's filter instead, leave the front matter as it is and define the filter with the package's function: `import navigation from "@11ty/eleventy-navigation/eleventy-navigation.js"`, then `filters: { eleventyNavigation: (pages, key) => navigation.findNavigationEntries(pages, key) }` (`ssqch import eleventy` leaves the front matter alone when templates call that filter). |
|
|
66
|
+
| `eleventy.env`, `process.env.ELEVENTY_ENV` | The `ssqch` template global (`ssqch.env`, `ssqch.serving`), and `SSQCH_ENV` |
|
|
67
|
+
|
|
68
|
+
## Plugins
|
|
69
|
+
|
|
70
|
+
| Eleventy plugin | SiteSquatch |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `@11ty/eleventy-img` | `imagePlugin()` from `ssqch/image`: every `<img>` becomes a `<picture>` |
|
|
73
|
+
| `@11ty/eleventy-plugin-rss` | `rssPlugin()` from `ssqch/rss` |
|
|
74
|
+
| `@11ty/eleventy-plugin-syntaxhighlight` | `markdown: { highlight: true }` |
|
|
75
|
+
| A Prism language added in the plugin's `init({ Prism })`, or its `alias` option | `markdown: { highlight: { languages } }`: a function that returns `[text, kind]` tokens, another language's name (`cho: "chordpro"`), or a `.sublime-syntax` file (`ssqch docs languages`) |
|
|
76
|
+
| markdown-it-anchor | Heading IDs are built in; add anchor links with a heading render hook |
|
|
77
|
+
| markdown-it-footnote | Built in |
|
|
78
|
+
| markdown-it-container | Built in: `::: name` |
|
|
79
|
+
| markdown-it-attrs | `{#id .class}` on headings |
|
|
80
|
+
| An HTML minifier transform | `minifyPlugin()` from `ssqch/minify` |
|
|
81
|
+
| A link checker | `linksPlugin()` from `ssqch/links` |
|
|
82
|
+
| A sitemap template | `sitemapPlugin({ url })` from `ssqch/sitemap` |
|
|
83
|
+
| Redirect pages made with pagination | `redirectsPlugin()` from `ssqch/redirects`, with `aliases` front matter |
|
|
84
|
+
|
|
85
|
+
## Templates
|
|
86
|
+
|
|
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; the README 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
|
+
|
|
89
|
+
## Things that work differently
|
|
90
|
+
|
|
91
|
+
- **Templates in a passthrough folder aren't pages.** Eleventy renders a `feed.njk` inside a copied `static/` folder and also copies it. ssqch only copies it. Move templates out, or use a glob for the files to copy (`{ "src/static/*.{png,ico,svg}": "." }`).
|
|
92
|
+
- **In Nunjucks, a filter called as a function loses to page data of the same name.** With `image:` in a post's front matter, `image(src)` is that string, not the filter. `src | image` and the tag form (`{% image src %}`) always reach the filter, and Edge's `image(src)` does too.
|
|
93
|
+
- **A page without a date has its file's modification time,** not its creation time as in Eleventy. A footer with `{{ page.date.getFullYear() }}` can print a different year on every page, and `ssqch diff` says `differ only in dates or years`. For a copyright year, use the build's time: `{{ now() | dateformat("%Y") }}`. In data files, `dateformat` also saves formatting dates by hand (`toLocaleDateString`).
|
|
94
|
+
- **`slugify` drops apostrophes** (`drews-brownies`), where a slug filter of your own might have split the words there (`drew_s_brownies`). `slugify(title, { separator: "_", apostrophes: "separate" })` matches that, and `ssqch diff` shows any URL that changed before you swap one for the other.
|
|
95
|
+
- **`.length` works in Nunjucks,** on lists and strings, as in Eleventy (`{{ collections.post.length }}`); `| length` is the Jinja way and does the same.
|
|
96
|
+
- **A data file can start with a byte-order mark** (SQL Server's and Excel's exports do): ssqch skips it in JSON, YAML, TOML, JavaScript and templates, as Node does.
|
|
97
|
+
- **A folder of full-size photos** is what `imagePlugin()` from `ssqch/image` is for: every `<img>` gets sized, modern-format copies in a `<picture>`, and `image()` in a data file gives the URLs and dimensions without markup.
|
|
98
|
+
- **A printed date is ISO 8601** (`2024-06-01T00:00:00.000Z`), not JavaScript's `Date.toString()`, which depends on the machine's time zone. Format dates with a filter.
|
|
99
|
+
- **Markdown differs from markdown-it in a few places:** bare domains like `example.com` aren't links (only `https://` and `www.` URLs are, as on GitHub), and with `indentedCode: false`, indented HTML renders as HTML (markdown-it wraps it in `<p>`).
|
|
100
|
+
- **The layout is chosen before `computed` runs.** A computed `layout` that's plain text (`eleventyComputed: { layout: "article" }`) is used; one that depends on the page is an error. Set it in the front matter or a data file.
|
|
101
|
+
- **`computed` doesn't see `collections`.** Build lists that need collections in a filter or a collection instead.
|
|
102
|
+
- **Includes come from `_includes`** (and themes), not from the project root as in Eleventy's Nunjucks. To show a source file in a page, read it in a filter: `filters: { readFile: (p) => fs.readFileSync(p, "utf8") }`.
|
|
103
|
+
- **Filters get your real objects,** as in Eleventy, not copies: a filter that sorts or changes what it's given changes it for the pages rendered after it. Copy first (`[...posts].sort()`). Data that refers to itself (nav items whose `prev` and `next` point at each other) is fine.
|
|
104
|
+
- **`{#id}` at the end of a Markdown line is a heading attribute,** not a Nunjucks comment, even though Markdown runs through Nunjucks or Jinja first.
|
|
105
|
+
- **markdown-it-anchor's ids** need a slugger: `markdown: { headingIds: (text) => encodeURIComponent(text.trim().toLowerCase().replace(/\s+/g, "-")) }`, and a heading hook if you want its `tabindex="-1"`.
|
|
106
|
+
|
|
107
|
+
## Moving with identical output first
|
|
108
|
+
|
|
109
|
+
A big site moves most safely in two steps: first the same pages, byte for byte, then ssqch's own features one at a time. For the first step, keep Eleventy's template libraries and let ssqch do the rest (finding pages, the data cascade, pagination, collections, layouts, transforms, writing):
|
|
110
|
+
|
|
111
|
+
- **Markdown and HTML:** an engine of your own (`engines` in the config) that runs liquidjs and then your markdown-it for `.md`, and your Nunjucks for `.njk` and `.html`, set for every page with one line, `data: { render: "eleventy" }` (global data reaches every page), and for layouts with `htmlEngine: "eleventy"`. Branch on `data.page.inputPath`. Eleventy's defaults: Markdown runs through Liquid first, and markdown-it has `code` (indented code blocks) turned off.
|
|
112
|
+
- **Front matter strings:** the same engine renders `computed` strings and permalinks before the page has a URL (`data.page.url` is undefined): render those with the template language only, not Markdown.
|
|
113
|
+
- **Install what Eleventy brought along:** liquidjs, nunjucks, gray-matter and luxon came with `@11ty/eleventy`, and a site's data files often import them without listing them. Pin the versions Eleventy had (`npm ls liquidjs nunjucks`), since the output depends on them.
|
|
114
|
+
- **Compare bytes:** `ssqch diff --exact`. Without `--exact`, whitespace between tags is ignored.
|
|
115
|
+
|
|
116
|
+
Then move one feature at a time to ssqch's (Markdown, highlighting, minifying, the table of contents), with `ssqch diff` after each.
|
|
117
|
+
|
|
118
|
+
## Packages
|
|
119
|
+
|
|
120
|
+
ssqch runs a site's JavaScript on Node, so every package that worked with Eleventy works here, at Node's speed, with nothing to port. A few notes:
|
|
121
|
+
|
|
122
|
+
| Package | On ssqch | Instead |
|
|
123
|
+
| --- | --- | --- |
|
|
124
|
+
| html-minifier, html-minifier-terser | Works, as a transform of your own (`transforms: { minify: async (content, page) => page.outputPath.endsWith(".html") ? await minify(content, options) : content }`). It gives Eleventy's bytes, which is what you want while the move is checked with `ssqch diff --exact` | `minifyPlugin()` from `ssqch/minify`, several times faster, with bytes of its own; switch when the bytes stop mattering |
|
|
125
|
+
| cheerio, @lit-labs/ssr | Work | `page.headings`, `toc()` and transforms on strings are cheaper for a little work |
|
|
126
|
+
| Anything that drives a browser (Playwright, Puppeteer) | Works, but a build that opens a browser is slow | A `beforeBuild` `run:` step that renders once, or a small local server your config `fetch`es |
|
|
127
|
+
|
|
128
|
+
Pages render one at a time on one thread (there are no worker threads), so if a build is much slower than with Eleventy, time the filters and transforms with `console.time`: one slow package is usually most of it.
|
|
129
|
+
|
|
130
|
+
## Checking the move
|
|
131
|
+
|
|
132
|
+
Build the old site with Eleventy and the new one with ssqch, and compare the two output folders:
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
ssqch diff _site-eleventy dist
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
It lists the URLs that were added and removed and what changed on each page, ignoring whitespace between tags and fingerprinted file names; `--ignore <regex>` drops differences you expect (a generator meta tag, say). The link checker (`linksPlugin()`) catches pages and anchors that moved, and a `schemas` entry catches front matter that didn't survive the trip.
|
|
139
|
+
|
|
140
|
+
`ssqch import eleventy` does the mechanical renames above for you; see [Importing](#importing).
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Trailhead: moving from Hexo
|
|
2
|
+
|
|
3
|
+
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
|
+
|
|
5
|
+
The [`docs-sidebar`](../../examples/sites/docs-sidebar/) example is distilled from hexo.io (and the FastAPI docs), and [`blog-tags`](../../examples/sites/blog-tags/) shows a blog with tag pages and feeds.
|
|
6
|
+
|
|
7
|
+
## The config
|
|
8
|
+
|
|
9
|
+
`_config.yml` becomes `ssqch.config.js`. Keep the site's own values (`title`, `url`, `author`) where templates expect them by moving them to `src/_data/config.yml`, so `{{ config.title }}` still works.
|
|
10
|
+
|
|
11
|
+
| Hexo | SiteSquatch |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| `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](../../README.md#themes): `theme: "themes/<name>"`, with its templates under `_includes/` |
|
|
15
|
+
| `themes/<name>/source/` (CSS, JS, images) | The theme folder's other files are copied as they are, or `passthrough` |
|
|
16
|
+
| `_config.yml` values in templates (`config.title`) | `src/_data/config.yml`: every file in `_data` is a template variable |
|
|
17
|
+
| `theme_config`, `themes/<name>/_config.yml` (`theme.menu`) | `src/_data/theme.yml` |
|
|
18
|
+
| `permalink: :year/:month/:day/:title/` | A `permalink` in the posts' directory data: `"/{{ page.date \| dateformat('%Y/%m/%d') }}/{{ page.fileSlug }}/"` |
|
|
19
|
+
| `new_post_name: :year-:month-:day-:title.md` | The same file names: a date at the start of a file name is the page's date |
|
|
20
|
+
| `root: /blog/` | `base: "/blog/"`. Links stay as written; `url_for()` isn't needed. |
|
|
21
|
+
| `per_page`, `pagination_dir` | `pagination: { data: collections.posts, size: 10 }` on the index template |
|
|
22
|
+
| `skip_render` | `passthrough`, or `ignore` |
|
|
23
|
+
| `highlight` / `prismjs` | `markdown: { highlight: true }`, at build time |
|
|
24
|
+
| `hexo-generator-feed` | A feed template with `rssPlugin()`'s filters (see `blog-tags`) |
|
|
25
|
+
| `hexo-generator-sitemap` | `sitemapPlugin({ url })` |
|
|
26
|
+
| `hexo-generator-alias` (`alias:` front matter) | `redirectsPlugin()` and `aliases` front matter |
|
|
27
|
+
| `hexo-generator-search`, a build-time lunr index | Pagefind after the build: `afterBuild: { run: "npx -y pagefind --site public" }` |
|
|
28
|
+
| `hexo-renderer-sass` / `stylus` | `sassPlugin()` from `ssqch/sass`. Stylus needs converting, or running as a `beforeBuild` command. |
|
|
29
|
+
| `hexo server`, `hexo generate` | `ssqch serve`, `ssqch build` (`ssqch server` and `ssqch generate` work too) |
|
|
30
|
+
|
|
31
|
+
## Posts and pages
|
|
32
|
+
|
|
33
|
+
| Hexo | SiteSquatch |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `source/_posts/*.md` | The same folder, with a directory data file `source/_posts/_posts.json`: `{ "layout": "post.njk", "tags": "posts" }` plus the `permalink` above |
|
|
36
|
+
| `title`, `date`, `updated`, `tags`, `permalink` | The same. `tags` build `collections.<tag>`. |
|
|
37
|
+
| `categories` | A front matter list like any other; group pages by it in a custom collection (the `blog-categories` example) |
|
|
38
|
+
| `layout: false` | `layout: false`; `permalink: false` for a page that isn't written |
|
|
39
|
+
| `<!-- more -->` | The same: `page.excerpt` is the HTML before it |
|
|
40
|
+
| `source/_drafts/`, `published: false` | `draft: true` (built in development only) |
|
|
41
|
+
| `source/_data/*.yml` (`site.data.menu`) | `_data/menu.yml` is `{{ menu }}` |
|
|
42
|
+
| Post asset folders (`post_asset_folder`) | `bundles: true`: a post that's `my-post/index.md` gets the folder's other files next to it |
|
|
43
|
+
| `lang` and `i18n_dir` | Not yet: folders per language work with directory data, but there's no translation lookup |
|
|
44
|
+
|
|
45
|
+
## Themes and helpers
|
|
46
|
+
|
|
47
|
+
Nunjucks templates render with Nunjucks (ssqch's fork of it), the library Hexo's Nunjucks renderer uses, so most theme code works; these are the differences that come up:
|
|
48
|
+
|
|
49
|
+
| Hexo | SiteSquatch |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `layout/layout.njk` wraps every layout through `body` | A layout chain: `post.njk` has `layout: layout.njk` in its front matter and prints `{{ content \| safe }}` |
|
|
52
|
+
| `partial('_partial/header', { ... })` | `{% include "_partial/header.njk" %}`, or a macro for a partial that takes arguments |
|
|
53
|
+
| `page.title`, `page.content`, `page.date` | `title`, `content` and `page.date`: front matter is at the top level, and `page` has the URL, the date and the file's details |
|
|
54
|
+
| `site.posts`, `site.pages`, `site.tags` | `collections.posts`, `collections.all`, and one collection per tag. Collections are oldest first: `collections.posts \| reverse`. |
|
|
55
|
+
| `url_for(path)`, `relative_url` | The path itself; with `base` set, ssqch adds it to links in the HTML (`relative_url` works, and gives the path back as it is) |
|
|
56
|
+
| `full_url_for(path)` | `absoluteUrl(path, config.url)` from `rssPlugin()` |
|
|
57
|
+
| `date(post.date, "YYYY-MM-DD")` (Moment formats) | `post.date \| dateformat("%Y-%m-%d")`, or a config filter that uses luxon or date-fns from `node_modules` |
|
|
58
|
+
| `css('css/style')`, `js('js/app')` | Plain `<link>` and `<script>` tags |
|
|
59
|
+
| `is_home()`, `is_post()`, `is_current(path)` | Compare `page.url`, or set a flag in each layout's front matter |
|
|
60
|
+
| `toc(page.content)` | `toc(page.headings)` in a layout |
|
|
61
|
+
| `paginator(...)` | `pagination.href.previous`, `pagination.href.next` and `pagination.hrefs` |
|
|
62
|
+
| `list_categories()`, `tagcloud()`, `list_archives()` | A loop over a collection built in the config |
|
|
63
|
+
| `strip_html`, `truncate`, `titlecase`, `markdown(text)` | `striptags`, `truncate`, `title` and `markdown(text)` |
|
|
64
|
+
| `__('key')`, `_p('key', n)` | A config filter over `_data/languages/<lang>.yml`: `t: (key) => strings[key] ?? key` |
|
|
65
|
+
| Helpers in `scripts/*.js` (`hexo.extend.helper.register`) | `filters` in the config. The function bodies usually move over unchanged; `this.page` becomes an argument. |
|
|
66
|
+
| Generators (`hexo.extend.generator.register`) | Pagination over data or a collection, with a `permalink` per page |
|
|
67
|
+
| EJS, Pug or Swig themes | EJS renders as it is: add `"ejs"` to `templateFormats`. For Pug or Swig, rewrite the theme in Nunjucks (Swig is close already), or give ssqch an engine of your own, `engines: { pug: (source, data) => pug.render(source, data) }`: ssqch runs on Node, so the package runs as it does in Hexo. |
|
|
68
|
+
|
|
69
|
+
## Tag plugins
|
|
70
|
+
|
|
71
|
+
A config filter is also a tag in Nunjucks, so most tag plugins port by moving their function into `filters` and setting `markdownEngine: "njk"` so tags in posts run:
|
|
72
|
+
|
|
73
|
+
| Hexo | SiteSquatch |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `{% youtube id %}`, `{% vimeo id %}` | `filters: { youtube: (id) => '<iframe ...>' }`, called the same way. Arguments are comma-separated and strings are quoted: `{% youtube "dQw4w9WgXcQ" %}`. |
|
|
76
|
+
| `{% note info %}...{% endnote %}` | `filters: { note: (content, kind) => ... }` with `{% note "info" %}...{% endnote %}`, or a `::: note` container in Markdown |
|
|
77
|
+
| `{% codeblock lang:js %}...{% endcodeblock %}` | A fenced code block |
|
|
78
|
+
| `{% blockquote Author %}...{% endblockquote %}`, `{% pullquote %}` | A filter with a closing tag, or a container |
|
|
79
|
+
| `{% post_link slug %}`, `{% asset_path %}`, `{% asset_img %}` | A link to the post's URL; with `bundles: true`, assets are relative paths |
|
|
80
|
+
| `{% raw %}...{% endraw %}` | The same |
|
|
81
|
+
|
|
82
|
+
Posts that show `{{ }}` or `{% %}` in code samples need `{% raw %}` around them once Markdown runs through Nunjucks, or `render: md` in their front matter to skip it.
|
|
83
|
+
|
|
84
|
+
## Checking the move
|
|
85
|
+
|
|
86
|
+
Build with Hexo and with ssqch, then compare:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
ssqch diff public-hexo public
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
It lists the URLs that were added and removed, and what changed on each page. Hexo and ssqch escape and wrap a few things differently, so expect markup-only differences at first; `--ignore <regex>` hides the ones you've accepted. `linksPlugin()` catches posts whose URLs moved.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Trailhead: moving from MkDocs
|
|
2
|
+
|
|
3
|
+
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 (the README's "Jinja and Nunjucks" section 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.
|
|
4
|
+
|
|
5
|
+
The [`docs-sidebar`](../../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
|
+
|
|
7
|
+
## The config
|
|
8
|
+
|
|
9
|
+
| `mkdocs.yml` | `ssqch.config.js` |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `docs_dir`, `site_dir` | `dirs: { input, output }` |
|
|
12
|
+
| `nav:` | `_data/nav.yml`, in the shape the nav helpers read: `- { title: Install, url: /install/ }`, with sections holding `children` (or `items`, `pages`). `navTree(nav, page.url)` marks the current page and its sections, `navPager` gives previous and next, `navBreadcrumbs` the trail. |
|
|
13
|
+
| `theme: material` and its options | Templates of your own (start from `docs-sidebar`) |
|
|
14
|
+
| `theme.custom_dir` / `overrides/` (Jinja) | `.jinja` templates in `_includes`; `{% extends %}`, blocks and macros work |
|
|
15
|
+
| `extra:` | `_data/site.yml` |
|
|
16
|
+
| `use_directory_urls: true` | The default: `install.md` is `/install/` |
|
|
17
|
+
| `plugins: [search]` | [Pagefind](https://pagefind.app) after the build: `afterBuild: { run: "npx -y pagefind --site dist" }` |
|
|
18
|
+
| `mkdocs-redirects` | `redirectsPlugin({ redirects })` from `ssqch/redirects`, or `aliases` on each page |
|
|
19
|
+
| `git-revision-date-localized` | `lastModified: "git"`, then `page.lastModified` |
|
|
20
|
+
| `mkdocs-macros` (Jinja in Markdown) | Built in: Markdown runs through Jinja first (`markdownEngine: "jinja"`, the default) |
|
|
21
|
+
| `extra_css` with Sass | `sassPlugin()` from `ssqch/sass` |
|
|
22
|
+
| `strict: true` | `linksPlugin()` for broken links, and `strict: true` for undefined template values |
|
|
23
|
+
|
|
24
|
+
## Markdown extensions
|
|
25
|
+
|
|
26
|
+
| Python-Markdown / PyMdown | SiteSquatch |
|
|
27
|
+
| --- | --- |
|
|
28
|
+
| `admonition`: `!!! note "Title"` and an indented body | A container: `::: note Title` ... `:::` (`_includes/containers/note.*`). GitHub's `> [!NOTE]` works too. |
|
|
29
|
+
| `pymdownx.details`: `??? note` | A container whose template writes `<details>` (see `docs-sidebar`'s `details` container) |
|
|
30
|
+
| `pymdownx.tabbed`: `=== "Tab"` | `:::: tabs` holding `::: tab Name` containers (see `versioned-docs`) |
|
|
31
|
+
| `pymdownx.superfences` custom fences (`mermaid`) | A `fence-mermaid` hook |
|
|
32
|
+
| `pymdownx.highlight`, `hl_lines="2 3"` | `markdown: { highlight: true }`, with `{2,3}` in the fence's info string |
|
|
33
|
+
| `pymdownx.snippets`: `--8<-- "file.py"` | `{% include "samples/file.py" %}` inside the fence |
|
|
34
|
+
| `toc` with `permalink: true` | Heading ids are built in; a heading hook adds the permalink. `toc(page.headings)` builds the table of contents. |
|
|
35
|
+
| `attr_list`: `## Title { #id }` | `## Title {#id}` |
|
|
36
|
+
| `footnotes`, `tables` | Built in |
|
|
37
|
+
| `def_list` | `markdown: { definitionLists: true }` |
|
|
38
|
+
| `md_in_html` (`markdown="1"`) | The `markdown` filter, or a container |
|
|
39
|
+
| `pymdownx.emoji` (`:smile:`) | Not built in; write the emoji |
|
|
40
|
+
|
|
41
|
+
## Pages
|
|
42
|
+
|
|
43
|
+
Front matter (`title`, `description`, and anything else) is the same YAML. MkDocs reads a page's title from its first heading when there's no `title`; in ssqch, give each page a `title` or use `page.headings[0].text` in the layout. A schema makes the first a rule: `schemas: { docs: { files: "docs/**/*.md", fields: { title: "string" } } }` fails the build for a page without one.
|
|
44
|
+
|
|
45
|
+
`ssqch init --starter docs` creates a docs site with a sidebar from `nav.yml`, a table of contents, notes, tabs and search, to move your pages into. To check the move, build both sites and run `ssqch diff site dist`.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Trailhead: moving from Zola
|
|
2
|
+
|
|
3
|
+
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
|
+
|
|
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`](../../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
|
+
|
|
7
|
+
## Importing
|
|
8
|
+
|
|
9
|
+
`ssqch import zola` does the mechanical part of this guide. In each page's `+++` front matter it moves `tags` out of `[taxonomies]` to the top level and turns `path` into a `permalink`. It writes a first `ssqch.config.js` from `config.toml`: `content/` as the input and `templates/` for layouts, `config.title` and `config.extra` as data so templates keep reading them, the Markdown options, Sass, a sitemap, redirects for `aliases`, and `static/` copied as it is. Then it lists what's left with where it is: each section (`_index.md`), each shortcode used in the content, and counts of the Tera constructs in your templates that read differently in Jinja. Run it once to read the list (it changes nothing), then with `--write` in a clean git checkout.
|
|
10
|
+
|
|
11
|
+
## The config
|
|
12
|
+
|
|
13
|
+
| Zola (`config.toml`) | SiteSquatch (`ssqch.config.js`) |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| `base_url` | Data: `data: { site: { url: "https://example.com" } }`, then `{{ site.url }}`. For a site under a path, `base: "/repo/"`. |
|
|
16
|
+
| `title`, `description`, `[extra]` | The same `site` data, or `_data/site.toml` (TOML data files work) |
|
|
17
|
+
| `highlight_code = true`, `highlight_theme` | `markdown: { highlight: true }`. Colors come from `/highlight.css` and its `--hl-*` properties instead of a theme name. |
|
|
18
|
+
| `generate_feeds = true` | `rssPlugin()` from `ssqch/rss`, plus a feed template (see `blog-tags/src/feed.njk`) |
|
|
19
|
+
| `taxonomies = [{ name = "tags", feed = true }]` | Tags are built in: `tags: [...]` in front matter, `collections.<tag>` in templates. Tag pages and per-tag feeds are a template paginated over the tag list. |
|
|
20
|
+
| Automatic `sitemap.xml` | `sitemapPlugin({ url })` from `ssqch/sitemap` |
|
|
21
|
+
| `insert_anchor_links` | A heading render hook: `_includes/hooks/heading.njk` |
|
|
22
|
+
| `slugify` settings (Zola's default anchors) | `markdown: { headingIds: "ascii" }`, which transliterates the same way (`🦀` is `crab`) |
|
|
23
|
+
| `compile_sass` | `sassPlugin({ files: { "sass": "/" } })` from `ssqch/sass` |
|
|
24
|
+
| `build_search_index` | Not built in; Pagefind after the build |
|
|
25
|
+
| `zola check` | `linksPlugin()` checks internal links and anchors on every build. External links aren't checked. |
|
|
26
|
+
|
|
27
|
+
## Content
|
|
28
|
+
|
|
29
|
+
| Zola | SiteSquatch |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| `content/blog/_index.md` (a section) | A folder with directory data, `blog/blog.json` (layout, tags, permalink), and an `index` page that lists its posts |
|
|
32
|
+
| `content/blog/post/index.md` with images (a page bundle) | The same, with `bundles: true` in the config |
|
|
33
|
+
| `+++` TOML front matter | Works as is |
|
|
34
|
+
| `title`, `date`, `description` | The same names |
|
|
35
|
+
| `draft = true` | The same: built by `ssqch serve`, left out of `ssqch build` |
|
|
36
|
+
| `aliases = ["2019/05/15/post.html"]` | The same, with `redirectsPlugin()` from `ssqch/redirects`. Without a leading `/`, an alias is still from the site's root, and old URLs keep their `#fragment`. |
|
|
37
|
+
| `slug`, `path` | `permalink`, which can use data: `permalink: "/blog/{{ page.date \| datePath }}/{{ page.fileSlug }}/"` |
|
|
38
|
+
| `weight` | Any field; sort by it in a custom collection |
|
|
39
|
+
| `[taxonomies]` `tags = [...]` | `tags = [...]` at the top level of the front matter |
|
|
40
|
+
| `[extra]` fields | Stay where they are: `{{ extra.subtitle }}` |
|
|
41
|
+
| No `date`, with the date in `path` | `computed: { date: (data) => ... }` in a directory data file (`content/content.data.js`); a computed date is the page's date |
|
|
42
|
+
| `_index.md` section front matter | A data file (`_data/sections.json`), and `ignore: ["**/_index.md"]` |
|
|
43
|
+
| `<!-- more -->` summaries | The same: `page.excerpt` is the HTML before it |
|
|
44
|
+
| Internal links (`@/blog/post.md`) | URL paths (`/blog/2024/01/15/post/`); the link checker catches mistakes |
|
|
45
|
+
| Footnotes | Built in |
|
|
46
|
+
|
|
47
|
+
## Templates
|
|
48
|
+
|
|
49
|
+
Use `.jinja` files, ssqch's default, so Markdown already runs through Jinja and shortcode calls in it keep working as macros. (`.njk` works too, with `markdownEngine: "njk"`.)
|
|
50
|
+
|
|
51
|
+
| Tera | Nunjucks in SiteSquatch |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `{% extends "base.html" %}`, `{% block %}` | The same. Layouts can also use `layout:` front matter with `{{ content \| safe }}`. |
|
|
54
|
+
| `{{ page.title }}`, `{{ page.content \| safe }}` | `{{ title }}`, `{{ content \| safe }}`: a page's data is at the top level |
|
|
55
|
+
| `{{ section.pages }}` | `collections.<name>`: a tag, or a custom collection from `collections` in the config |
|
|
56
|
+
| `{{ get_url(path="...") }}` | The plain path |
|
|
57
|
+
| `get_page(path="...")` | Look the page up in a collection |
|
|
58
|
+
| `{{ page.date \| date(format="%Y") }}` | A config filter: `filters: { year: d => d.getUTCFullYear() }` |
|
|
59
|
+
| `{{ page.toc }}` | `{{ toc(page.headings) \| safe }}`, in the layout |
|
|
60
|
+
| `{{ page.reading_time }}` | `{{ readingTime(content) }}` |
|
|
61
|
+
| Macros (`{% import "macros.html" as m %}`) | The same; add `with context` if the macro reads page data or collections |
|
|
62
|
+
| Shortcodes (`{{ youtube(id="x") }}`) | Macros in an include, imported where they're used, or a config filter |
|
|
63
|
+
| Body shortcodes (`{% note() %}...{% end %}`) | Containers: `::: note` renders `_includes/containers/note.njk` with the body as `container.content` |
|
|
64
|
+
|
|
65
|
+
Config filters are JavaScript functions with positional arguments: Tera's `date(format="%Y")` becomes `date("%Y")`.
|
|
66
|
+
|
|
67
|
+
## What's missing
|
|
68
|
+
|
|
69
|
+
A search index, translations and external link checking aren't built in; search works with Pagefind after the build (`afterBuild: { run: "npx -y pagefind --site dist" }`). Sass is `sassPlugin()` from `ssqch/sass`, and Zola's footnote markup can be kept with the `footnote-ref` and `footnotes` render hooks.
|
|
70
|
+
|
|
71
|
+
To check the move, build with Zola and with ssqch and run `ssqch diff public dist`: it lists the pages that differ and how.
|
package/lib/assets.js
CHANGED
|
@@ -1,3 +1,235 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
import { createRequire as __ssqchCreateRequire } from "node:module";
|
|
2
|
+
const require = __ssqchCreateRequire(import.meta.url);
|
|
3
|
+
import {
|
|
4
|
+
Options
|
|
5
|
+
} from "./chunk-JRT7TQQP.js";
|
|
6
|
+
import {
|
|
7
|
+
BUILTINS,
|
|
8
|
+
blake3Hex,
|
|
9
|
+
rewriteHtml
|
|
10
|
+
} from "./chunk-TN6EEDX2.js";
|
|
11
|
+
import "./chunk-IRHRK7XB.js";
|
|
12
|
+
import "./chunk-NKXEPHRZ.js";
|
|
13
|
+
import "./chunk-AD3HAW3W.js";
|
|
14
|
+
import "./chunk-DDV6JEC2.js";
|
|
15
|
+
import "./chunk-EIT4ZDT4.js";
|
|
16
|
+
import "./chunk-FVZ5JBRI.js";
|
|
17
|
+
import "./chunk-TDGBQNGW.js";
|
|
18
|
+
import "./chunk-UU43WIZG.js";
|
|
19
|
+
import "./chunk-C35KIPAR.js";
|
|
20
|
+
import "./chunk-CMUWRPSQ.js";
|
|
21
|
+
import {
|
|
22
|
+
bail,
|
|
23
|
+
warn,
|
|
24
|
+
warning
|
|
25
|
+
} from "./chunk-6XYSFG6V.js";
|
|
26
|
+
import {
|
|
27
|
+
displayPath
|
|
28
|
+
} from "./chunk-VJWQSYEG.js";
|
|
29
|
+
import "./chunk-I3PS26CI.js";
|
|
30
|
+
|
|
31
|
+
// src/modules/assets.ts
|
|
32
|
+
import crypto from "node:crypto";
|
|
33
|
+
import fs from "node:fs";
|
|
34
|
+
import path from "node:path";
|
|
35
|
+
function assetsPlugin(options = {}) {
|
|
36
|
+
return { name: "ssqch/assets", builtin: "ssqch/assets", options };
|
|
37
|
+
}
|
|
38
|
+
function splitName(name) {
|
|
39
|
+
const dot = name.lastIndexOf(".");
|
|
40
|
+
return dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
|
|
41
|
+
}
|
|
42
|
+
function fingerprintedCopies(dir, stem, ext) {
|
|
43
|
+
let names;
|
|
44
|
+
try {
|
|
45
|
+
names = fs.readdirSync(dir);
|
|
46
|
+
} catch {
|
|
47
|
+
return [];
|
|
48
|
+
}
|
|
49
|
+
const out = [];
|
|
50
|
+
for (const name of names) {
|
|
51
|
+
if (!name.startsWith(`${stem}.`) || !name.endsWith(ext)) continue;
|
|
52
|
+
const hash = name.slice(stem.length + 1, name.length - ext.length);
|
|
53
|
+
if (hash.length === 8 && /^[0-9a-f]{8}$/.test(hash) && name.length === stem.length + 1 + 8 + ext.length && fs.statSync(path.join(dir, name), { throwIfNoEntry: false })?.isFile()) out.push(path.join(dir, name));
|
|
54
|
+
}
|
|
55
|
+
return out.sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
|
|
56
|
+
}
|
|
57
|
+
function fingerprint(output, file) {
|
|
58
|
+
const plain = path.join(output, file.replace(/^\/+/, ""));
|
|
59
|
+
const dir = path.dirname(plain);
|
|
60
|
+
const name = path.basename(plain);
|
|
61
|
+
const [stem, ext] = splitName(name);
|
|
62
|
+
const copies = fingerprintedCopies(dir, stem, ext);
|
|
63
|
+
let hashed;
|
|
64
|
+
if (fs.statSync(plain, { throwIfNoEntry: false })?.isFile()) {
|
|
65
|
+
let bytes;
|
|
66
|
+
try {
|
|
67
|
+
bytes = fs.readFileSync(plain);
|
|
68
|
+
} catch (e) {
|
|
69
|
+
bail(`reading ${plain}: ${e.message}`);
|
|
70
|
+
}
|
|
71
|
+
hashed = `${stem}.${blake3Hex(bytes).slice(0, 8)}${ext}`;
|
|
72
|
+
try {
|
|
73
|
+
fs.renameSync(plain, path.join(dir, hashed));
|
|
74
|
+
} catch (e) {
|
|
75
|
+
bail(`renaming ${plain} to ${hashed}: ${e.message}`);
|
|
76
|
+
}
|
|
77
|
+
for (const old of copies.filter((c) => path.basename(c) !== hashed)) {
|
|
78
|
+
try {
|
|
79
|
+
fs.rmSync(old);
|
|
80
|
+
} catch (e) {
|
|
81
|
+
bail(`removing ${old}: ${e.message}`);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
} else if (copies.length === 1) {
|
|
85
|
+
hashed = path.basename(copies[0]);
|
|
86
|
+
} else if (copies.length === 0) {
|
|
87
|
+
bail(`${plain} doesn't exist; build the CSS and JS before ssqch`);
|
|
88
|
+
} else {
|
|
89
|
+
bail(`${plain} doesn't exist, and there are ${copies.length} fingerprinted copies of it; rebuild it`);
|
|
90
|
+
}
|
|
91
|
+
return file.slice(0, file.length - name.length) + hashed;
|
|
92
|
+
}
|
|
93
|
+
function builtCopy(output, file) {
|
|
94
|
+
const plain = path.join(output, file.replace(/^\/+/, ""));
|
|
95
|
+
const name = path.basename(plain);
|
|
96
|
+
const [stem, ext] = splitName(name);
|
|
97
|
+
const copies = fingerprintedCopies(path.dirname(plain), stem, ext);
|
|
98
|
+
return copies.length === 1 ? file.slice(0, file.length - name.length) + path.basename(copies[0]) : void 0;
|
|
99
|
+
}
|
|
100
|
+
function integrity(bytes) {
|
|
101
|
+
return `sha384-${crypto.createHash("sha384").update(bytes).digest("base64")}`;
|
|
102
|
+
}
|
|
103
|
+
function passthroughSource(config, url) {
|
|
104
|
+
const root = config.root;
|
|
105
|
+
const input = path.resolve(root, config.input);
|
|
106
|
+
const output = path.resolve(root, config.output);
|
|
107
|
+
const want = path.join(output, url.replace(/^\/+/, ""));
|
|
108
|
+
const inside = (dir, p) => p.startsWith(dir + path.sep);
|
|
109
|
+
for (const { from, to } of config.passthrough) {
|
|
110
|
+
if (/[*?[{]/.test(from)) continue;
|
|
111
|
+
const src = path.resolve(root, from);
|
|
112
|
+
const dest = to !== void 0 ? path.join(output, to) : path.join(output, inside(input, src) ? path.relative(input, src) : inside(root, src) ? path.relative(root, src) : src);
|
|
113
|
+
const found = want === dest ? src : inside(dest, want) ? path.join(src, path.relative(dest, want)) : void 0;
|
|
114
|
+
if (found !== void 0 && (fs.statSync(found, { throwIfNoEntry: false })?.isFile() ?? false)) return found;
|
|
115
|
+
}
|
|
116
|
+
return void 0;
|
|
117
|
+
}
|
|
118
|
+
var plainPath = (value) => value.split(/[?#]/)[0];
|
|
119
|
+
function rewriteAssets(html, urls, sri) {
|
|
120
|
+
const rewrite = (value) => {
|
|
121
|
+
const at = value.search(/[?#]/);
|
|
122
|
+
const [p, rest] = at === -1 ? [value, ""] : [value.slice(0, at), value.slice(at)];
|
|
123
|
+
const url = urls.get(p);
|
|
124
|
+
return url !== void 0 && url !== p ? url + rest : void 0;
|
|
125
|
+
};
|
|
126
|
+
return rewriteHtml(html, {
|
|
127
|
+
tag: (el) => {
|
|
128
|
+
for (const attr of ["href", "src"]) {
|
|
129
|
+
const value = el.get(attr);
|
|
130
|
+
if (value === void 0) continue;
|
|
131
|
+
const loads = el.name === "link" && attr === "href" || el.name === "script" && attr === "src";
|
|
132
|
+
if (loads && el.get("integrity") === void 0) {
|
|
133
|
+
const hash = sri.get(plainPath(value));
|
|
134
|
+
if (hash !== void 0) el.set("integrity", hash);
|
|
135
|
+
}
|
|
136
|
+
const changed = rewrite(value);
|
|
137
|
+
if (changed !== void 0) el.set(attr, changed);
|
|
138
|
+
}
|
|
139
|
+
},
|
|
140
|
+
script: (el, js) => {
|
|
141
|
+
const module = el.get("src") === void 0 && el.get("type")?.trim().toLowerCase() === "module";
|
|
142
|
+
return module ? rewriteImports(js, urls) : js;
|
|
143
|
+
}
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
var IMPORT = /(\bfrom\s*|\bimport\s*(?:\(\s*)?)(?:"([^"\n]*)"|'([^'\n]*)')/g;
|
|
147
|
+
function rewriteImports(js, urls) {
|
|
148
|
+
if (!js.includes("import") && !js.includes("export")) return js;
|
|
149
|
+
return js.replace(IMPORT, (whole, lead, double, single) => {
|
|
150
|
+
const [quote, spec] = double !== void 0 ? ['"', double] : ["'", single];
|
|
151
|
+
const at = spec.search(/[?#]/);
|
|
152
|
+
const [p, rest] = at === -1 ? [spec, ""] : [spec.slice(0, at), spec.slice(at)];
|
|
153
|
+
const url = urls.get(p);
|
|
154
|
+
return url !== void 0 && url !== p ? `${lead}${quote}${url}${rest}${quote}` : whole;
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
BUILTINS.set("ssqch/assets", (config, given) => {
|
|
158
|
+
const o = new Options(given, ["files", "fingerprint", "integrity"]);
|
|
159
|
+
const files = o.list("files") ?? [];
|
|
160
|
+
if (!files.length) bail('files is required: the URL paths of the files to fingerprint, like ["/assets/index.css"]');
|
|
161
|
+
const fingerprinting = o.bool("fingerprint");
|
|
162
|
+
const withIntegrity = o.bool("integrity") ?? false;
|
|
163
|
+
for (const file of files) {
|
|
164
|
+
if (!file.startsWith("/") || file.endsWith("/") || file.includes("..")) bail(`files: "${file}" must be a URL path to a file, starting with / (like "/assets/index.css")`);
|
|
165
|
+
}
|
|
166
|
+
let urls = /* @__PURE__ */ new Map();
|
|
167
|
+
let sri = /* @__PURE__ */ new Map();
|
|
168
|
+
let names = [];
|
|
169
|
+
let changing = [];
|
|
170
|
+
config.beforeBuild.push({ label: "", fn: () => {
|
|
171
|
+
const output = path.resolve(config.root, config.output);
|
|
172
|
+
const shownOutput = displayPath(config.root, output);
|
|
173
|
+
const enabled = fingerprinting ?? (config.env === "production" && !config.serving);
|
|
174
|
+
const map = /* @__PURE__ */ new Map();
|
|
175
|
+
const hashes = /* @__PURE__ */ new Map();
|
|
176
|
+
const done = [];
|
|
177
|
+
for (const file of files) {
|
|
178
|
+
if (enabled) {
|
|
179
|
+
const src = passthroughSource(config, file);
|
|
180
|
+
if (src !== void 0) {
|
|
181
|
+
const plain = path.join(output, file.replace(/^\/+/, ""));
|
|
182
|
+
fs.mkdirSync(path.dirname(plain), { recursive: true });
|
|
183
|
+
try {
|
|
184
|
+
fs.copyFileSync(src, plain);
|
|
185
|
+
} catch (e) {
|
|
186
|
+
bail(`copying ${src} to ${plain}: ${e.message}`);
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
const hashed = fingerprint(output, file);
|
|
190
|
+
if (withIntegrity) {
|
|
191
|
+
const at = path.join(output, hashed.replace(/^\/+/, ""));
|
|
192
|
+
let bytes;
|
|
193
|
+
try {
|
|
194
|
+
bytes = fs.readFileSync(at);
|
|
195
|
+
} catch (e) {
|
|
196
|
+
bail(`reading ${at}: ${e.message}`);
|
|
197
|
+
}
|
|
198
|
+
hashes.set(file, integrity(bytes));
|
|
199
|
+
}
|
|
200
|
+
done.push(hashed.slice(hashed.lastIndexOf("/") + 1));
|
|
201
|
+
map.set(file, hashed);
|
|
202
|
+
} else if ((fs.statSync(path.join(output, file.replace(/^\/+/, "")), { throwIfNoEntry: false })?.isFile() ?? false) || passthroughSource(config, file) !== void 0) {
|
|
203
|
+
map.set(file, file);
|
|
204
|
+
} else {
|
|
205
|
+
const copy = builtCopy(output, file);
|
|
206
|
+
if (copy !== void 0) {
|
|
207
|
+
warn(warning("assets", `${file} isn't in the output (${shownOutput}), so pages link to ${copy} from the last production build; run the tool that writes ${file} to see changes`));
|
|
208
|
+
map.set(file, copy);
|
|
209
|
+
} else {
|
|
210
|
+
warn(warning("assets", `${file} isn't in the output yet (${shownOutput}); its tool may still be building it`));
|
|
211
|
+
map.set(file, file);
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
urls = map;
|
|
216
|
+
sri = hashes;
|
|
217
|
+
names = done;
|
|
218
|
+
changing = [.../* @__PURE__ */ new Set([...[...map].filter(([plain, url]) => plain !== url).map(([plain]) => plain), ...hashes.keys()])];
|
|
219
|
+
} });
|
|
220
|
+
config.htmlTransforms.push(["assets", (content, info) => {
|
|
221
|
+
if (path.extname(info.outputPath) !== ".html") return content;
|
|
222
|
+
if (!changing.some((plain) => content.includes(plain))) return content;
|
|
223
|
+
return rewriteAssets(content, urls, sri);
|
|
224
|
+
}]);
|
|
225
|
+
config.filters.set("assetUrl", (...given2) => {
|
|
226
|
+
const p = given2.length === 0 ? "" : String(given2[0]);
|
|
227
|
+
const url = urls.get(p);
|
|
228
|
+
if (url === void 0) bail(`assetUrl("${p}"): not one of the assets plugin's files (${[...urls.keys()].sort((a, b) => a < b ? -1 : a > b ? 1 : 0).join(", ")})`);
|
|
229
|
+
return url;
|
|
230
|
+
});
|
|
231
|
+
config.summaries.push(["Assets", () => names.length ? `${names.length} fingerprinted (${names.join(", ")})` : void 0]);
|
|
232
|
+
});
|
|
233
|
+
export {
|
|
234
|
+
assetsPlugin
|
|
235
|
+
};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { createRequire as __ssqchCreateRequire } from "node:module";
|
|
2
|
+
const require = __ssqchCreateRequire(import.meta.url);
|
|
3
|
+
import {
|
|
4
|
+
buildFiles,
|
|
5
|
+
footprintJson,
|
|
6
|
+
footprintText,
|
|
7
|
+
kindOf,
|
|
8
|
+
measure,
|
|
9
|
+
overBudget,
|
|
10
|
+
urlOf
|
|
11
|
+
} from "./chunk-3PHCFZEU.js";
|
|
12
|
+
import "./chunk-IRHRK7XB.js";
|
|
13
|
+
import "./chunk-NKXEPHRZ.js";
|
|
14
|
+
import "./chunk-DDV6JEC2.js";
|
|
15
|
+
import "./chunk-FVZ5JBRI.js";
|
|
16
|
+
import "./chunk-UU43WIZG.js";
|
|
17
|
+
import "./chunk-CMUWRPSQ.js";
|
|
18
|
+
import "./chunk-6XYSFG6V.js";
|
|
19
|
+
import "./chunk-VJWQSYEG.js";
|
|
20
|
+
import "./chunk-I3PS26CI.js";
|
|
21
|
+
export {
|
|
22
|
+
buildFiles,
|
|
23
|
+
footprintJson,
|
|
24
|
+
footprintText,
|
|
25
|
+
kindOf,
|
|
26
|
+
measure,
|
|
27
|
+
overBudget,
|
|
28
|
+
urlOf
|
|
29
|
+
};
|