ssqch 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/README.md +8 -4
  2. package/bin/ssqch.js +14 -48
  3. package/bundled/README.md +1314 -0
  4. package/bundled/completions/bash +840 -0
  5. package/bundled/completions/elvish +286 -0
  6. package/bundled/completions/fish +182 -0
  7. package/bundled/completions/powershell +318 -0
  8. package/bundled/completions/zsh +510 -0
  9. package/bundled/ssqch.d.ts +540 -0
  10. package/bundled/starter/engines/index.edge +11 -0
  11. package/bundled/starter/engines/index.ejs +11 -0
  12. package/bundled/starter/engines/index.hbs +11 -0
  13. package/bundled/starter/engines/index.liquid +11 -0
  14. package/bundled/starter/engines/layout.edge +35 -0
  15. package/bundled/starter/engines/layout.ejs +35 -0
  16. package/bundled/starter/engines/layout.hbs +35 -0
  17. package/bundled/starter/engines/layout.liquid +35 -0
  18. package/bundled/starter/gitignore +3 -0
  19. package/bundled/starter/jsconfig.json +11 -0
  20. package/bundled/starter/src/404.md +8 -0
  21. package/bundled/starter/src/_blueprints/posts.md +5 -0
  22. package/bundled/starter/src/_data/site.json +4 -0
  23. package/bundled/starter/src/_includes/layout.jinja +35 -0
  24. package/bundled/starter/src/index.jinja +11 -0
  25. package/bundled/starter/src/posts/i-know-what-i-saw.md +11 -0
  26. package/bundled/starter/src/posts/posts.json +4 -0
  27. package/bundled/starter/src/posts/raiders-of-the-lost-path.md +27 -0
  28. package/bundled/starter/src/posts/the-cache-of-the-wild.md +26 -0
  29. package/bundled/starter/src/posts/the-stump-has-moved.md +15 -0
  30. package/bundled/starter/src/posts/upon-further-review-a-stump.md +18 -0
  31. package/bundled/starter/ssqch.config.js +29 -0
  32. package/bundled/starter-docs/engines/edge/base.edge +41 -0
  33. package/bundled/starter-docs/engines/edge/containers/details.edge +5 -0
  34. package/bundled/starter-docs/engines/edge/containers/tab.edge +4 -0
  35. package/bundled/starter-docs/engines/edge/containers/tabs.edge +5 -0
  36. package/bundled/starter-docs/engines/edge/doc.edge +59 -0
  37. package/bundled/starter-docs/engines/edge/hooks/heading.edge +2 -0
  38. package/bundled/starter-docs/engines/ejs/base.ejs +41 -0
  39. package/bundled/starter-docs/engines/ejs/containers/details.ejs +5 -0
  40. package/bundled/starter-docs/engines/ejs/containers/tab.ejs +4 -0
  41. package/bundled/starter-docs/engines/ejs/containers/tabs.ejs +5 -0
  42. package/bundled/starter-docs/engines/ejs/doc.ejs +59 -0
  43. package/bundled/starter-docs/engines/ejs/hooks/heading.ejs +2 -0
  44. package/bundled/starter-docs/engines/hbs/base.hbs +41 -0
  45. package/bundled/starter-docs/engines/hbs/containers/details.hbs +5 -0
  46. package/bundled/starter-docs/engines/hbs/containers/tab.hbs +4 -0
  47. package/bundled/starter-docs/engines/hbs/containers/tabs.hbs +5 -0
  48. package/bundled/starter-docs/engines/hbs/doc.hbs +58 -0
  49. package/bundled/starter-docs/engines/hbs/hooks/heading.hbs +2 -0
  50. package/bundled/starter-docs/engines/liquid/base.liquid +41 -0
  51. package/bundled/starter-docs/engines/liquid/containers/details.liquid +5 -0
  52. package/bundled/starter-docs/engines/liquid/containers/tab.liquid +4 -0
  53. package/bundled/starter-docs/engines/liquid/containers/tabs.liquid +5 -0
  54. package/bundled/starter-docs/engines/liquid/doc.liquid +60 -0
  55. package/bundled/starter-docs/engines/liquid/hooks/heading.liquid +2 -0
  56. package/bundled/starter-docs/gitignore +4 -0
  57. package/bundled/starter-docs/src/404.md +12 -0
  58. package/bundled/starter-docs/src/_blueprints/docs.md +5 -0
  59. package/bundled/starter-docs/src/_data/nav.yml +10 -0
  60. package/bundled/starter-docs/src/_data/site.json +5 -0
  61. package/bundled/starter-docs/src/_includes/base.jinja +41 -0
  62. package/bundled/starter-docs/src/_includes/containers/details.jinja +5 -0
  63. package/bundled/starter-docs/src/_includes/containers/tab.jinja +4 -0
  64. package/bundled/starter-docs/src/_includes/containers/tabs.jinja +5 -0
  65. package/bundled/starter-docs/src/_includes/doc.jinja +59 -0
  66. package/bundled/starter-docs/src/_includes/hooks/heading.jinja +2 -0
  67. package/bundled/starter-docs/src/assets/docs.css +257 -0
  68. package/bundled/starter-docs/src/assets/docs.js +67 -0
  69. package/bundled/starter-docs/src/docs/docs.json +1 -0
  70. package/bundled/starter-docs/src/docs/guides/deploying.md +77 -0
  71. package/bundled/starter-docs/src/docs/guides/writing.md +65 -0
  72. package/bundled/starter-docs/src/docs/index.md +29 -0
  73. package/bundled/starter-docs/src/docs/install.md +42 -0
  74. package/bundled/starter-docs/src/index.md +13 -0
  75. package/bundled/starter-docs/ssqch.config.js +40 -0
  76. package/bundled/trailheads/from-component-frameworks.md +116 -0
  77. package/bundled/trailheads/from-docusaurus.md +55 -0
  78. package/bundled/trailheads/from-eleventy.md +140 -0
  79. package/bundled/trailheads/from-hexo.md +92 -0
  80. package/bundled/trailheads/from-jekyll.md +79 -0
  81. package/bundled/trailheads/from-mkdocs.md +45 -0
  82. package/bundled/trailheads/from-zola.md +71 -0
  83. package/lib/assets.js +235 -3
  84. package/lib/chunk-3A647I3N.js +384 -0
  85. package/lib/chunk-3GYLOC6Y.js +1017 -0
  86. package/lib/chunk-3K3ANWZ2.js +118 -0
  87. package/lib/chunk-3NYSSA2C.js +22 -0
  88. package/lib/chunk-47P4YREZ.js +1287 -0
  89. package/lib/chunk-4Q6WMTER.js +32 -0
  90. package/lib/chunk-76NTVE34.js +338 -0
  91. package/lib/chunk-7PWCYHTJ.js +1350 -0
  92. package/lib/chunk-7RDRZHJD.js +217 -0
  93. package/lib/chunk-7SD7K567.js +57 -0
  94. package/lib/chunk-7XLK2GEG.js +54 -0
  95. package/lib/chunk-AD3HAW3W.js +10 -0
  96. package/lib/chunk-BEGC7YP6.js +502 -0
  97. package/lib/chunk-CMUWRPSQ.js +113 -0
  98. package/lib/chunk-CZ4XQC56.js +999 -0
  99. package/lib/chunk-D2XE2GTY.js +71 -0
  100. package/lib/chunk-DDV6JEC2.js +46 -0
  101. package/lib/chunk-DELWRJAO.js +37409 -0
  102. package/lib/chunk-DELWRJAO.js.LEGAL.txt +27 -0
  103. package/lib/chunk-F65YUXZ7.js +334 -0
  104. package/lib/chunk-FVZ5JBRI.js +115 -0
  105. package/lib/chunk-GRWMGC7D.js +4435 -0
  106. package/lib/chunk-GRWMGC7D.js.LEGAL.txt +41 -0
  107. package/lib/chunk-GUKSZ2XM.js +207 -0
  108. package/lib/chunk-HPXAZ2HU.js +251 -0
  109. package/lib/chunk-HXCLCXRT.js +20 -0
  110. package/lib/chunk-I3PS26CI.js +48 -0
  111. package/lib/chunk-IAFM5ITE.js +11 -0
  112. package/lib/chunk-II5DEH3Q.js +209 -0
  113. package/lib/chunk-IJWHOFRP.js +44 -0
  114. package/lib/chunk-LPHNACE4.js +29 -0
  115. package/lib/chunk-MI6EJWA2.js +175 -0
  116. package/lib/chunk-NCWFYT74.js +1541 -0
  117. package/lib/chunk-NKXEPHRZ.js +136 -0
  118. package/lib/chunk-NNUKIGOO.js +160 -0
  119. package/lib/chunk-R7K3D5W5.js +3957 -0
  120. package/lib/chunk-RNJFPFXE.js +29 -0
  121. package/lib/chunk-SF4I6Z7S.js +25 -0
  122. package/lib/chunk-SURPOAW7.js +44 -0
  123. package/lib/chunk-SXMJ52IK.js +572 -0
  124. package/lib/chunk-TICWN55Z.js +20 -0
  125. package/lib/chunk-TVU3OPPK.js +146 -0
  126. package/lib/chunk-UU43WIZG.js +29 -0
  127. package/lib/chunk-VJWQSYEG.js +119 -0
  128. package/lib/chunk-XMXBHXZR.js +75 -0
  129. package/lib/chunk-YTHQBMDJ.js +211 -0
  130. package/lib/cli.js +547 -0
  131. package/lib/elements.js +180 -3
  132. package/lib/image.js +27 -3
  133. package/lib/links.js +464 -3
  134. package/lib/minify.js +69 -3
  135. package/lib/redirects.js +152 -3
  136. package/lib/rss.js +139 -3
  137. package/lib/sass.js +256 -3
  138. package/lib/sitemap.js +113 -3
  139. package/lib/ssqch.js +28 -0
  140. package/package.json +83 -80
  141. package/src/serve/live.js +174 -0
  142. package/src/serve/not-found.html +31 -0
  143. package/types/globals.d.ts +3 -2
  144. package/types/image.d.ts +7 -3
  145. package/types/index.d.ts +28 -9
  146. package/types/links.d.ts +1 -1
  147. package/types/minify.d.ts +1 -1
  148. package/types/rss.d.ts +1 -1
  149. package/types/sass.d.ts +1 -1
  150. package/types/sitemap.d.ts +2 -0
  151. package/wasm/markdown.wasm +0 -0
  152. package/wasm/minify.wasm +0 -0
  153. package/wasm/sass.wasm +0 -0
  154. package/lib/index.js +0 -3
  155. 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,79 @@
1
+ # Trailhead: moving from Jekyll
2
+
3
+ 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
+
5
+ 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).
6
+
7
+ ## Build it both ways first
8
+
9
+ Build the Jekyll site from a fresh checkout twice and compare the two: a page that prints the build's time (an undated article gets `site.time`) differs on every build. Pin it with a second config file holding `time: 2026-01-01 00:00:00 +0000` (`jekyll build --config _config.yml,pin.yml`), and build ssqch with the same time: `SOURCE_DATE_EPOCH=1767225600`. GitHub Pages' gem needs `PAGES_REPO_NWO=owner/repo` in a checkout without a git remote. Then build with ssqch into an empty folder and compare the two with `ssqch diff jekyll-site ssqch-site`.
10
+
11
+ ## The config
12
+
13
+ Start with `templateFormats: ["liquid", "md", "html"]`, `markdownEngine: "liquid"` and `htmlEngine: "liquid"`, so Markdown and HTML pages run through Liquid first, as in Jekyll, and `dirs: { layouts: "_layouts" }`.
14
+
15
+ ```js
16
+ import { defineConfig, readData } from "ssqch";
17
+ import { sitemapPlugin } from "ssqch/sitemap";
18
+ import { redirectsPlugin } from "ssqch/redirects";
19
+
20
+ const site = readData("_config.yml");
21
+
22
+ export default defineConfig({
23
+ templateFormats: ["liquid", "md", "html"],
24
+ markdownEngine: "liquid",
25
+ htmlEngine: "liquid",
26
+ dirs: { layouts: "_layouts" },
27
+ ignore: ["Gemfile", "Gemfile.lock", "README.md", "script/**"],
28
+ data: { site },
29
+ plugins: [sitemapPlugin({ url: site.url }), redirectsPlugin()],
30
+ });
31
+ ```
32
+
33
+ | Jekyll (`_config.yml`) | ssqch (`ssqch.config.js`) |
34
+ | --- | --- |
35
+ | `title`, `description`, `url`, any key | `readData("_config.yml")` as `data: { site }`, so `site.title` still works |
36
+ | `exclude: [docs, Gemfile]` | `ignore: ["docs/**", "Gemfile"]`. A Bundler install (`vendor/bundle`) is skipped by itself. |
37
+ | `_data/locales/fr.yml` as `site.data.locales.fr` | `locales.fr`: `_data` is global data, and a folder in it is an object. Add `data: { site: { ...site, data: ... } }` only if templates must keep `site.data`. |
38
+ | `collections: { guides: { output: true, permalink: "/:path/" } }` | `collections: { guides: (c) => c.byGlob("_guides/**") }`, and `_guides/_guides.json` with the permalink: `{ "permalink": "{{ page.filePathStem \| remove_first: '/_guides' }}/" }` |
39
+ | `defaults` for a `path` | Directory data in that folder: `_guides/_guides.json` with `{ "layout": "guide" }` |
40
+ | `layouts_dir` | `dirs: { layouts: "_layouts" }` |
41
+ | `sass: { load_paths }` | `sassPlugin({ files, loadPaths })` from `ssqch/sass`. Front matter on a `.scss` file is fine. |
42
+ | `time:` | `SOURCE_DATE_EPOCH=1767225600 ssqch build` (seconds since 1970): `now()` and every undated page get that time, as with `time:` |
43
+
44
+ ## Templates
45
+
46
+ - **`page` and front matter:** in ssqch, front matter is at the top level (`{{ title }}`), and `page` has the file's facts (`page.url`, `page.inputPath`, `page.date`, `page.headings`). Rename `page.title` to `title` in layouts and includes (the build warns once for each `page.<key>` that's front matter, naming a page that reads it), and look for a template whose own variable has a front matter key's name (`{% assign lang = ... %}` next to `page.lang`).
47
+ - **`site.posts` and collections:** `collections.posts` (the pages tagged `posts`) and your own collections. Items have `url` and `data`: `post.data.title`, `| where: "data.lang", "fr"`.
48
+ - **Includes:** `{% include nav.html section="home" %}` works, with `include.section`, and so does `{% include_relative parts/intro.md %}`. A file read by `include_relative` is a page of its own too, if it's Markdown: give its folder `permalink: false` in directory data.
49
+ - **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
+ - **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
+ - **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 (the README's "Text files with front matter").
53
+
54
+ ## Plugins
55
+
56
+ | Jekyll | ssqch |
57
+ | --- | --- |
58
+ | jekyll-redirect-from | `redirect_from` works (ssqch calls it `aliases`), with `redirectsPlugin()`; `_includes/hooks/redirect.*` for its page's markup |
59
+ | jekyll-sitemap | `sitemapPlugin({ url })` |
60
+ | jekyll-feed | `rssPlugin()` and a feed template |
61
+ | jekyll-seo-tag | A `seo` function (a tag), or an include with the tags you use |
62
+ | jekyll-toc | `toc(page.headings, ...)`, above |
63
+ | jekyll-github-metadata | Data in the config (`site.github.repository_nwo`) |
64
+ | github-pages' default theme (jekyll-theme-primer) | Nothing: it writes `/assets/css/style.css`. Check whether a page links to it. |
65
+
66
+ ## Markdown
67
+
68
+ ssqch's Markdown is CommonMark; Jekyll's is kramdown. `markdown: { smartPunctuation: true, autolinks: false }` comes closest. What differs:
69
+
70
+ - **`markdown="1"`** on an HTML element (kramdown reads its content as Markdown): ssqch writes the element as it is, so Markdown inside stays text. It's on the way; count them first, with `grep -rc 'markdown="1"' .`. A container (`::: name`) is ssqch's way to wrap Markdown in HTML.
71
+ - **HTML blocks** end at a blank line in CommonMark, and at their end tag in kramdown: keep blank lines out of HTML elements, or a line indented by four spaces inside one becomes code.
72
+ - **Heading ids:** kramdown's GFM ids keep accents and other letters, as ssqch's do; headings inside HTML get kramdown's ASCII ids (`section`, `section-1`).
73
+ - **Bold next to punctuation** (`**完成。**下一步`) closes in kramdown but not in CommonMark.
74
+ - **Code:** GitHub Pages adds Rouge's `class="language-plaintext highlighter-rouge"` to code; ssqch doesn't (`markdown: { highlight: true }` highlights, with its own classes).
75
+ - Smart quotes next to non-Latin letters, and non-ASCII characters in link URLs (which ssqch percent-encodes), come out differently; readers see the same page.
76
+
77
+ ## Checking the move
78
+
79
+ `ssqch diff` lists the files that differ and how. Most of what's left after the steps above is Markdown: `markdown="1"`, then kramdown's spacing and quotes. `linksPlugin()` from `ssqch/links` checks every internal link and anchor on each build.
@@ -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.