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.
Files changed (153) hide show
  1. package/README.md +6 -4
  2. package/bin/ssqch.js +14 -48
  3. package/bundled/README.md +1247 -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 +532 -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-mkdocs.md +45 -0
  81. package/bundled/trailheads/from-zola.md +71 -0
  82. package/lib/assets.js +235 -3
  83. package/lib/chunk-37KSIVNY.js +29 -0
  84. package/lib/chunk-3GYLOC6Y.js +1017 -0
  85. package/lib/chunk-3NYSSA2C.js +22 -0
  86. package/lib/chunk-3PHCFZEU.js +209 -0
  87. package/lib/chunk-4Q6WMTER.js +32 -0
  88. package/lib/chunk-6XYSFG6V.js +4423 -0
  89. package/lib/chunk-6XYSFG6V.js.LEGAL.txt +41 -0
  90. package/lib/chunk-AD3HAW3W.js +10 -0
  91. package/lib/chunk-AMBFWPZ4.js +118 -0
  92. package/lib/chunk-BOBPVAX2.js +37088 -0
  93. package/lib/chunk-BOBPVAX2.js.LEGAL.txt +27 -0
  94. package/lib/chunk-BRK4MXXO.js +565 -0
  95. package/lib/chunk-C35KIPAR.js +247 -0
  96. package/lib/chunk-CDEPYU7W.js +25 -0
  97. package/lib/chunk-CMUWRPSQ.js +113 -0
  98. package/lib/chunk-DDV6JEC2.js +46 -0
  99. package/lib/chunk-DHHQKW4F.js +71 -0
  100. package/lib/chunk-EIT4ZDT4.js +1485 -0
  101. package/lib/chunk-EZZUUPI4.js +20 -0
  102. package/lib/chunk-F65YUXZ7.js +334 -0
  103. package/lib/chunk-FVZ5JBRI.js +115 -0
  104. package/lib/chunk-FYGE634X.js +44 -0
  105. package/lib/chunk-GOE4ZSAB.js +75 -0
  106. package/lib/chunk-GSKVRAHF.js +44 -0
  107. package/lib/chunk-HR2RU2LY.js +999 -0
  108. package/lib/chunk-HXCLCXRT.js +20 -0
  109. package/lib/chunk-I3PS26CI.js +48 -0
  110. package/lib/chunk-IAFM5ITE.js +11 -0
  111. package/lib/chunk-IRHRK7XB.js +54 -0
  112. package/lib/chunk-JRT7TQQP.js +57 -0
  113. package/lib/chunk-JSPSMIJ2.js +217 -0
  114. package/lib/chunk-KBGE5MCY.js +175 -0
  115. package/lib/chunk-N5QTGQ5N.js +207 -0
  116. package/lib/chunk-NKXEPHRZ.js +136 -0
  117. package/lib/chunk-NUKCUDC4.js +146 -0
  118. package/lib/chunk-RI2L3VGO.js +376 -0
  119. package/lib/chunk-TDGBQNGW.js +251 -0
  120. package/lib/chunk-TN6EEDX2.js +3935 -0
  121. package/lib/chunk-TWCVHOKO.js +1229 -0
  122. package/lib/chunk-UGEGUUBT.js +29 -0
  123. package/lib/chunk-UU43WIZG.js +29 -0
  124. package/lib/chunk-VJWQSYEG.js +119 -0
  125. package/lib/chunk-VVPZ5PDP.js +160 -0
  126. package/lib/chunk-WMOVCQO6.js +1287 -0
  127. package/lib/chunk-WP3RPVUM.js +211 -0
  128. package/lib/chunk-YSH2NMIE.js +502 -0
  129. package/lib/cli.js +540 -0
  130. package/lib/elements.js +180 -3
  131. package/lib/image.js +27 -3
  132. package/lib/links.js +464 -3
  133. package/lib/minify.js +69 -3
  134. package/lib/redirects.js +152 -3
  135. package/lib/rss.js +139 -3
  136. package/lib/sass.js +221 -3
  137. package/lib/sitemap.js +88 -3
  138. package/lib/ssqch.js +28 -0
  139. package/package.json +83 -80
  140. package/src/serve/live.js +174 -0
  141. package/src/serve/not-found.html +31 -0
  142. package/types/globals.d.ts +3 -2
  143. package/types/image.d.ts +7 -3
  144. package/types/index.d.ts +18 -5
  145. package/types/links.d.ts +1 -1
  146. package/types/minify.d.ts +1 -1
  147. package/types/rss.d.ts +1 -1
  148. package/types/sass.d.ts +1 -1
  149. package/wasm/markdown.wasm +0 -0
  150. package/wasm/minify.wasm +0 -0
  151. package/wasm/sass.wasm +0 -0
  152. package/lib/index.js +0 -3
  153. package/platforms.json +0 -6
@@ -0,0 +1,67 @@
1
+ // Optional extras. Every page reads fine without this file.
2
+
3
+ // Tabs: turn each group's labeled sections into buttons, and remember the
4
+ // choice, so picking "pnpm" once picks it in every group.
5
+ const groups = [...document.querySelectorAll(".tabs")].map((tabs) => {
6
+ const panels = /** @type {HTMLElement[]} */ ([...tabs.querySelectorAll(":scope > .tab")]);
7
+ const list = document.createElement("div");
8
+ list.setAttribute("role", "tablist");
9
+ for (const panel of panels) {
10
+ const button = document.createElement("button");
11
+ button.type = "button";
12
+ button.textContent = panel.dataset.label;
13
+ button.setAttribute("role", "tab");
14
+ button.addEventListener("click", () => choose(panel.dataset.label));
15
+ list.append(button);
16
+ panel.querySelector(".tab-label")?.remove();
17
+ panel.setAttribute("role", "tabpanel");
18
+ }
19
+ tabs.prepend(list);
20
+ return { panels, buttons: /** @type {HTMLElement[]} */ ([...list.children]) };
21
+ });
22
+
23
+ function choose(label) {
24
+ for (const { panels, buttons } of groups) {
25
+ // A group without that label keeps what it shows.
26
+ const index = panels.findIndex((p) => p.dataset.label === label);
27
+ if (index === -1 && panels.some((p) => !p.hidden) && buttons.some((b) => b.ariaSelected === "true")) continue;
28
+ const shown = index === -1 ? 0 : index;
29
+ panels.forEach((p, i) => (p.hidden = i !== shown));
30
+ buttons.forEach((b, i) => (b.ariaSelected = String(i === shown)));
31
+ }
32
+ try {
33
+ if (label) localStorage.setItem("tab", label);
34
+ } catch {}
35
+ }
36
+
37
+ let remembered = "";
38
+ try {
39
+ remembered = localStorage.getItem("tab") ?? "";
40
+ } catch {}
41
+ choose(remembered);
42
+
43
+ // The light and dark switch. It starts with the system's choice, and remembers the reader's.
44
+ /** @type {HTMLElement | null} */
45
+ const themeSwitch = document.querySelector(".theme-switch");
46
+ if (themeSwitch) {
47
+ const dark = matchMedia("(prefers-color-scheme: dark)");
48
+ const current = () => document.documentElement.dataset.theme ?? (dark.matches ? "dark" : "light");
49
+ const label = () => (themeSwitch.textContent = current() === "dark" ? "Switch to light" : "Switch to dark");
50
+ themeSwitch.addEventListener("click", () => {
51
+ const next = current() === "dark" ? "light" : "dark";
52
+ document.documentElement.dataset.theme = next;
53
+ try {
54
+ localStorage.setItem("theme", next);
55
+ } catch {}
56
+ label();
57
+ });
58
+ dark.addEventListener("change", label);
59
+ label();
60
+ themeSwitch.hidden = false;
61
+ }
62
+
63
+ // Search, when the site was built with SEARCH=1 (Pagefind's script defines PagefindUI).
64
+ const { PagefindUI } = /** @type {any} */ (window);
65
+ if (PagefindUI && document.getElementById("search")) {
66
+ new PagefindUI({ element: "#search", showSubResults: true });
67
+ }
@@ -0,0 +1 @@
1
+ { "layout": "doc.jinja", "tags": "docs" }
@@ -0,0 +1,77 @@
1
+ ---
2
+ title: Deploying
3
+ description: Publish the built site on any static host.
4
+ ---
5
+ `ssqch build` writes plain files to `dist/`. Any static host can serve them.
6
+
7
+ ## Netlify
8
+
9
+ ```toml
10
+ # netlify.toml
11
+ [build]
12
+ publish = "dist"
13
+ command = "npx ssqch build"
14
+
15
+ [build.environment]
16
+ NODE_VERSION = "24"
17
+ ```
18
+
19
+ With `ssqch` in the site's `devDependencies` (see [Installation](/docs/install/)), Netlify installs it at the version in the lockfile, so a build next year uses the ssqch you tested with. `NODE_VERSION` can be any Node from 22.18 on.
20
+
21
+ ## GitHub Pages
22
+
23
+ A project site is served under its repository's name, like `https://you.github.io/repo/`. Set that path in `ssqch.config.js`, and leave the links in your pages as they are:
24
+
25
+ ```js
26
+ export default defineConfig({
27
+ base: "/repo/",
28
+ });
29
+ ```
30
+
31
+ Then build it in a workflow with `actions/setup-node`, and deploy `dist/` with GitHub's own Pages actions (in the repository's settings, set Pages' source to "GitHub Actions"):
32
+
33
+ ```yaml
34
+ # .github/workflows/pages.yml
35
+ name: Deploy to GitHub Pages
36
+ on:
37
+ push:
38
+ branches: [main]
39
+ permissions:
40
+ contents: read
41
+ pages: write
42
+ id-token: write
43
+ jobs:
44
+ deploy:
45
+ runs-on: ubuntu-latest
46
+ environment: github-pages
47
+ steps:
48
+ - uses: actions/checkout@v4
49
+ - uses: actions/setup-node@v4
50
+ with:
51
+ node-version: 24
52
+ cache: npm
53
+ - run: npm ci
54
+ - run: npx ssqch build
55
+ - uses: actions/upload-pages-artifact@v3
56
+ with:
57
+ path: dist
58
+ - id: deployment
59
+ uses: actions/deploy-pages@v4
60
+ ```
61
+
62
+ ## Check before you publish
63
+
64
+ Build the site before and after a big change, and compare the two:
65
+
66
+ ```sh
67
+ npx ssqch build --output dist-before
68
+ # ...make the change...
69
+ npx ssqch build
70
+ npx ssqch diff dist-before dist
71
+ ```
72
+
73
+ It lists the pages that were added, removed and changed, and ignores what doesn't matter.
74
+
75
+ :::note[Beaver's build notes]
76
+ Beaver keeps `dist-before/` until the diff shows only what she meant to change. A dam is easier to fix before the water arrives.
77
+ :::
@@ -0,0 +1,65 @@
1
+ ---
2
+ title: Writing pages
3
+ description: Notes, tabs, code, footnotes and the rest of what a page can use.
4
+ ---
5
+ Pages are Markdown, with GitHub's extensions and a few of ssqch's own. This page uses each of them once, so its source is a cheat sheet.
6
+
7
+ ## Notes
8
+
9
+ :::note
10
+ A `:::note` block. There are `:::tip`, `:::warning` and `:::caution` too.
11
+ :::
12
+
13
+ :::warning[Check twice]
14
+ Give a block a title in brackets.
15
+ :::
16
+
17
+ > [!TIP]
18
+ > **Deer's shortcut:** GitHub's alert syntax works as well, which keeps a README readable in both places.
19
+
20
+ :::details How do these work?
21
+ Each `:::name` block renders through `src/_includes/containers/name.jinja` if there is one (like this one, `details.jinja`), or as a `<div class="name">`.
22
+ :::
23
+
24
+ ## Tabs
25
+
26
+ ::::tabs
27
+ :::tab npm
28
+ ```sh
29
+ npm install pinecone
30
+ ```
31
+ :::
32
+ :::tab pnpm
33
+ ```sh
34
+ pnpm add pinecone
35
+ ```
36
+ :::
37
+ ::::
38
+
39
+ Without JavaScript, tabs are labeled sections, one after another. With it, picking a tab picks it in every group on the site that has one with that name.
40
+
41
+ ## Code
42
+
43
+ Fences are highlighted while the site builds. Mark lines with braces:
44
+
45
+ ```js {2}
46
+ export function trail(name) {
47
+ return `/trails/${name}/`;
48
+ }
49
+ ```
50
+
51
+ ## Tables, tasks and footnotes
52
+
53
+ | Syntax | Result |
54
+ | --- | --- |
55
+ | `- [x] done` | A checked box |
56
+ | `[^1]` | A footnote[^1] |
57
+
58
+ - [x] Write the docs
59
+ - [ ] Spot a Squatch
60
+
61
+ ## Data in a page
62
+
63
+ Front matter and the files in `src/_data/` are available in every page: this site is called {{ site.name }}.
64
+
65
+ [^1]: Footnotes collect at the end of the page.
@@ -0,0 +1,29 @@
1
+ ---
2
+ title: Introduction
3
+ description: What's in this starter, and where things live.
4
+ ---
5
+ Welcome! This is a documentation site built with [SiteSquatch](https://github.com/reverentgeek/sitesquatch). It's yours to change: every file is in this folder, and there's no theme to fight.
6
+
7
+ ## Where things live
8
+
9
+ | Path | What it is |
10
+ | --- | --- |
11
+ | `src/docs/` | The pages, in Markdown. A folder is a section of the URL. |
12
+ | `src/_data/nav.yml` | The sidebar, which also gives each page its breadcrumbs and previous and next links. |
13
+ | `src/_data/site.json` | The site's name and description. |
14
+ | `src/_includes/` | The layouts (`base.jinja`, `doc.jinja`), and the templates behind headings, tabs and details. |
15
+ | `src/assets/` | The stylesheet (its colors are custom properties at the top), and a small script for tabs, search and the light and dark switch. |
16
+ | `ssqch.config.js` | The config: highlighting, the link checker, the schema for front matter. |
17
+
18
+ ## Add a page
19
+
20
+ 1. Create `src/docs/guides/my-page.md` with a `title` in its front matter.
21
+ 2. List it in `src/_data/nav.yml`.
22
+
23
+ That's it. Run `ssqch serve` and it's at `/docs/guides/my-page/`.
24
+
25
+ :::tip[Owl's field guide]
26
+ Owl reads the sidebar from the top: install first, then [Writing pages](/docs/guides/writing/), whose source uses every kind of block once, so it doubles as a cheat sheet.
27
+ :::
28
+
29
+ Next: [install ssqch](/docs/install/), or see [what a page can do](/docs/guides/writing/).
@@ -0,0 +1,42 @@
1
+ ---
2
+ title: Installation
3
+ description: Install ssqch and run this site.
4
+ ---
5
+ `ssqch` runs on [Node.js](https://nodejs.org) 22.18 or newer, and comes from npm. Install it in the site as a dev dependency, so the lockfile pins the version:
6
+
7
+ ::::tabs
8
+ :::tab npm
9
+ ```sh
10
+ npm init -y
11
+ npm install --save-dev ssqch
12
+ ```
13
+ :::
14
+ :::tab pnpm
15
+ ```sh
16
+ pnpm init
17
+ pnpm add -D ssqch
18
+ ```
19
+ :::
20
+ ::::
21
+
22
+ Then run it with `npx ssqch` (or `pnpm ssqch`), or by name in a `package.json` script: `"build": "ssqch build"`. To have `ssqch` on your `PATH` for every site, `npm install --global ssqch` or `brew install reverentgeek/tap/ssqch`.
23
+
24
+ ## Run the site
25
+
26
+ ```sh
27
+ npx ssqch serve
28
+ ```
29
+
30
+ Open <http://localhost:8080>. Pages rebuild and the browser reloads as you save, and that includes `ssqch.config.js`.
31
+
32
+ ## Build it
33
+
34
+ ```sh
35
+ npx ssqch build
36
+ ```
37
+
38
+ The site is in `dist/`, ready for any static host. A broken link or a page without a `title` stops the build and says where.
39
+
40
+ :::tip
41
+ `SEARCH=1 npx ssqch build` also builds a search index with [Pagefind](https://pagefind.app) and adds a search box to the header. Pagefind is a program of its own, which `npx` fetches for that one step.
42
+ :::
@@ -0,0 +1,13 @@
1
+ ---
2
+ title: ""
3
+ layout: base.jinja
4
+ ---
5
+ <div class="home">
6
+
7
+ # {{ site.name }}
8
+
9
+ {{ site.description }} This starter has a sidebar, a table of contents on each page, previous and next links, notes and tabs, highlighted code, a link checker and a schema for front matter.
10
+
11
+ [Read the docs](/docs/)
12
+
13
+ </div>
@@ -0,0 +1,40 @@
1
+ // A documentation site. `ssqch serve` serves it with live reload, and
2
+ // `ssqch build` builds it into dist/. ssqch.d.ts gives your editor the types.
3
+ import { defineConfig } from "ssqch";
4
+ import { linksPlugin } from "ssqch/links";
5
+ import { minifyPlugin } from "ssqch/minify";
6
+
7
+ // Search is Pagefind (https://pagefind.app), which indexes the built pages.
8
+ // It's a program of its own that npx fetches, so it's opt-in:
9
+ // SEARCH=1 ssqch build
10
+ const search = Boolean(process.env.SEARCH);
11
+
12
+ export default defineConfig(({ env }) => ({
13
+ dirs: { input: "src", output: "dist" },
14
+ templateFormats: ["jinja", "md"],
15
+ passthrough: ["src/assets"],
16
+
17
+ // For a site served under a path, like https://you.github.io/repo/:
18
+ // base: "/repo/",
19
+
20
+ // Highlight code while building; pages link /highlight.css.
21
+ markdown: { highlight: true },
22
+
23
+ // Every page in src/docs/ needs a title. A misspelled front matter key is a warning.
24
+ schemas: {
25
+ docs: {
26
+ files: "docs/**/*.md",
27
+ fields: { title: "string", description: "string?" },
28
+ unknown: "warn",
29
+ },
30
+ },
31
+
32
+ data: { search },
33
+ afterBuild: search ? [{ run: "npx -y pagefind --site dist" }] : [],
34
+
35
+ plugins: [
36
+ // Broken internal links (and anchors) fail a production build.
37
+ linksPlugin({ ignore: ["/pagefind/"] }),
38
+ env === "production" && minifyPlugin(),
39
+ ],
40
+ }));
@@ -0,0 +1,116 @@
1
+ # Trailhead: moving from Astro, VitePress, Next.js or Gatsby
2
+
3
+ These are component frameworks: a page is a tree of components, rendered on a server or at build time and, for some of them, run again in the browser. ssqch is a template-and-Markdown generator that ships HTML and only the JavaScript you write. So this move isn't a port of the framework. It's a sort of what you have into three piles:
4
+
5
+ 1. **Content** (Markdown, front matter, data files): moves as it is.
6
+ 2. **Presentational components** (cards, callouts, layouts, navigation): become templates, with no JavaScript in the browser.
7
+ 3. **Interactive components** (a search box, tabs with state, a live editor): stay JavaScript, as custom elements that load on the pages that use them, or as an app that lives beside the site.
8
+
9
+ On the sites studied for this guide, most components were in the second pile: about 80% of getbootstrap.com's (Astro) and 37% of vuejs.org's (VitePress). A site whose pages are mostly the third pile (react.dev, with a live editor in most pages) is an app, and should stay one.
10
+
11
+ The [`component-docs`](../../examples/sites/component-docs/) example is distilled from getbootstrap.com: components in place of MDX, live examples with their source, and values read from Sass files. [`islands`](../../examples/sites/islands/) shows interactive parts as custom elements.
12
+
13
+ ## Is ssqch a fit?
14
+
15
+ | The site is | Then |
16
+ | --- | --- |
17
+ | A blog, docs or marketing site with a few interactive widgets | Yes: content and templates in ssqch, widgets as custom elements |
18
+ | Docs where every page embeds a live playground | Partly: the prose pages, with the playground as its own bundle that pages load |
19
+ | Server-rendered per request (auth, personalization, API routes, ISR) | No: ssqch only builds static files. Keep those routes where they are and move the static section. |
20
+ | A framework's own docs (vuejs.org, react.dev) | No: they exist to show the framework |
21
+
22
+ Moving one section at a time works: build the docs or blog with ssqch into a folder, and let the host serve it under its path (`base: "/docs/"`).
23
+
24
+ ## Content
25
+
26
+ | Astro, VitePress, Next.js, Gatsby | SiteSquatch |
27
+ | --- | --- |
28
+ | Markdown with YAML front matter | The same. `title`, `description`, `date`, `tags` are read as they are. |
29
+ | Content collections with a Zod schema (`src/content/config.ts`) | `schemas` in the config: `{ posts: { fields: { title: "string", date: "date", tags: "string[]" } } }`, checked on every build, with types from `ssqch types` |
30
+ | `getCollection("blog")`, GraphQL page queries, `getStaticProps` | `collections.<tag>` in templates, custom `collections` in the config, and `_data/*.js` files that fetch or read whatever the query did |
31
+ | `getStaticPaths`, `[slug].astro`, `createPages` | Pagination over data with a `permalink` per item: one template, one page per entry |
32
+ | Remote data at build time | `fetch()` in a data file, with `{ cache: "1h" }` so rebuilds don't refetch |
33
+ | File-based routing (`src/pages/about.astro`) | The same idea: `src/about.md` is `/about/`. `permalink` overrides it. |
34
+ | `:::tip` containers (VitePress, Starlight) | The same syntax, built in |
35
+ | `{#custom-id}` on headings, `[[toc]]` | `{#custom-id}` works; the table of contents is `toc(page.headings)` in the layout |
36
+ | Code blocks with Shiki, line highlighting `{1,3}`, titles | `markdown: { highlight: true }`, `{1,3}` in the fence's info string; a `fence` render hook for titles and copy buttons |
37
+ | Extra Shiki languages (VitePress `markdown.languages` and `languageAlias`, Astro `shikiConfig.langs`) | `markdown: { highlight: { languages } }`: an alias (`mdx: "markdown"`), a function that returns tokens, or a `.sublime-syntax` file. Shiki's TextMate JSON grammars don't load as they are (`ssqch docs languages`) |
38
+ | Twoslash, or anything that needs a compiler at build time | A `beforeBuild` command that writes HTML or JSON for templates to include |
39
+ | `<Image>` / `gatsby-plugin-image` | `imagePlugin()`: every `<img>`, including Markdown images, becomes a responsive `<picture>` |
40
+ | i18n routing | Not yet |
41
+
42
+ ## MDX and components
43
+
44
+ MDX mixes Markdown with JSX. In ssqch, Markdown runs through a template language first (Jinja by default), so a component call sits in the Markdown the same way. With `markdownEngine: "edge"`, an Edge component reads most like MDX:
45
+
46
+ ```mdx
47
+ <Callout type="warning" title="Careful">
48
+ This **cannot** be undone.
49
+ </Callout>
50
+ ```
51
+
52
+ ```md
53
+ @component('components/callout', { type: 'warning', title: 'Careful' })
54
+ This **cannot** be undone.
55
+ @end
56
+ ```
57
+
58
+ or, for block content, a container, which keeps the page plain Markdown:
59
+
60
+ ```md
61
+ :::warning[Careful]
62
+ This **cannot** be undone.
63
+ :::
64
+ ```
65
+
66
+ | Component | Becomes |
67
+ | --- | --- |
68
+ | A layout (`<BaseLayout>`, `layout.tsx`, a VitePress theme `Layout.vue`) | A layout in `_includes/`, chosen by `layout` in front matter or directory data |
69
+ | A presentational component with props (`<Card title>`) | A Jinja macro (`{% macro card(title) %}`, with `caller()` for its body), an Edge component (`_includes/components/card.edge`, with `$props` and slots), or a Handlebars partial |
70
+ | A component that wraps Markdown (`<Aside>`, `<Tabs>`) | A container: `_includes/containers/aside.jinja` gets the rendered body as `container.content` |
71
+ | Something that changes how Markdown elements render (`components={{ a, h2, pre }}`) | Render hooks: `_includes/hooks/link.*`, `heading.*`, `fence.*` |
72
+ | A component that reads data (`Astro.glob`, a `useData()` composable) | The template reads the same data: `collections`, `_data`, front matter |
73
+ | `import` of a JSON or YAML file in a page | A file in `_data/`, available by name |
74
+ | Styles scoped to a component | A class and a stylesheet; `sassPlugin()` if you use Sass |
75
+ | A React, Vue or Svelte component with state or effects | A custom element (below) |
76
+
77
+ A codemod is worth writing when one component is used hundreds of times: the JSX call maps to one line of template.
78
+
79
+ ## Interactive parts
80
+
81
+ Write each one as a custom element, with what a visitor sees before (or without) JavaScript inside the tag:
82
+
83
+ ```html
84
+ <like-button count="3"><a href="/likes/">3 likes</a></like-button>
85
+ ```
86
+
87
+ `elementsPlugin()` from `ssqch/elements` loads `src/elements/like-button.js` on the pages that have the tag, and on no others, which is what `client:load` did. The other loading directives map too:
88
+
89
+ | Astro | SiteSquatch |
90
+ | --- | --- |
91
+ | `client:load` | The default: the script loads with the page |
92
+ | `client:idle` | `ssqch:load="idle"` on the tag |
93
+ | `client:visible` | `ssqch:load="visible"` |
94
+ | `client:only`, a component with no server-rendered HTML | An element with a fallback inside it (a link, a static version, or nothing) |
95
+ | `<ClientOnly>` (VitePress), `dynamic(() => ..., { ssr: false })` (Next.js) | The same |
96
+
97
+ An element's script can import your existing framework code: a Preact, Lit or Vue component mounted inside `connectedCallback` is still an island, bundled by your own esbuild or Vite step into the elements folder (`beforeBuild: { run: "esbuild ..." }`). What goes away is hydrating the whole page.
98
+
99
+ What doesn't have an equivalent: client-side routing between pages (links are ordinary page loads; the browser's View Transitions cover the animation), state shared across pages in memory (use `localStorage`, as the tabs in `ssqch init --starter docs` do), and server components.
100
+
101
+ ## Per framework
102
+
103
+ - **Astro:** `.astro` components are the closest to templates: the frontmatter script becomes data (front matter, `_data`, or a filter) and the template below it becomes Jinja or Edge. Starlight sites map onto `ssqch init --starter docs`.
104
+ - **VitePress:** `.vitepress/config.js` `themeConfig.sidebar` becomes `_data/nav.yml`; `:::` containers, `{#id}` and line highlighting already match. Vue components in Markdown are the work.
105
+ - **Next.js:** only statically exported pages (`output: "export"`) move. `next/link` and `next/image` become `<a>` and `<img>`; `getStaticProps` becomes a data file.
106
+ - **Gatsby:** source plugins become data files (`fetch`, or reading files with `node:fs`), page queries become collections, and `gatsby-node.js` `createPages` becomes pagination. remark plugins map to the `markdown` options, render hooks and containers.
107
+
108
+ ## Checking the move
109
+
110
+ Build both and compare the output:
111
+
112
+ ```sh
113
+ ssqch diff dist-old dist --ignore 'data-astro-[\w-]+(="[^"]*")?' --ignore '<!--\[?-->'
114
+ ```
115
+
116
+ `ssqch diff` compares tags and text, so framework noise shows up as markup-only differences: scoped-style attributes, hydration markers, inlined state. `--ignore` takes patterns for those. What's left is what a visitor would notice: the text of each page, its headings and ids, and its links.
@@ -0,0 +1,55 @@
1
+ # Trailhead: moving from Docusaurus
2
+
3
+ Docusaurus sites are React apps that happen to render documentation; ssqch builds the same documentation as static HTML that needs no JavaScript to read. The move is mostly mechanical for Markdown pages, and takes a decision for each React component: an Edge component, a container, or client-side JavaScript that stays.
4
+
5
+ Two examples are distilled from reactnative.dev: [`versioned-docs`](../../examples/sites/versioned-docs/) (versions, sidebars, tabs, a blog with authors) and [`component-docs`](../../examples/sites/component-docs/) (components in place of MDX, live examples).
6
+
7
+ ## The config
8
+
9
+ | Docusaurus | SiteSquatch |
10
+ | --- | --- |
11
+ | `docusaurus.config.js` | `ssqch.config.js` |
12
+ | `docs/`, `blog/`, `src/pages/` | Folders in the input (`src/docs/`, `src/blog/`), and templates for the other pages |
13
+ | `static/` | `passthrough: [{ "static": "." }]` |
14
+ | `@docusaurus/plugin-sitemap` | `sitemapPlugin({ url })` from `ssqch/sitemap` |
15
+ | `@docusaurus/plugin-client-redirects` | `redirectsPlugin({ redirects })` from `ssqch/redirects` (real pages or `_redirects` lines, not client-side redirects) |
16
+ | Algolia DocSearch, or a local search plugin | [Pagefind](https://pagefind.app) after the build: `afterBuild: { run: "npx -y pagefind --site dist" }` (see the `docs-sidebar` example) |
17
+ | `themeConfig.prism` | `markdown: { highlight: true }`; colors from `/highlight.css` and its `--hl-*` properties |
18
+ | `prism.additionalLanguages` | Nothing to list: about 200 languages are built in. One that isn't goes in `markdown: { highlight: { languages } }`, as a function that returns tokens, an alias or a `.sublime-syntax` file (`ssqch docs languages`) |
19
+ | `onBrokenLinks: "throw"` | `linksPlugin()`: broken links and anchors fail production builds |
20
+ | `i18n` | Not yet |
21
+
22
+ ## Docs, versions and sidebars
23
+
24
+ | Docusaurus | SiteSquatch |
25
+ | --- | --- |
26
+ | `versioned_docs/version-1.0/` and `docs/` (next) | `src/docs/1.0/` and `src/docs/next/`, each with directory data (`{ "version": "1.0", "layout": "doc.jinja" }`) |
27
+ | `versions.json` | `_data/versions.json`, for the version switcher |
28
+ | `sidebars.js` | `_data/sidebars/<version>.json`, or a `_data/sidebars.js` that exports the same object. `navTree(sidebar, page.url)` marks the current page, `navPager` gives previous and next, `navBreadcrumbs` the trail. |
29
+ | Autogenerated sidebars (`sidebar_position`) | `nav: { parent, order }` front matter and `pagesTree(collections.docs)` |
30
+ | `id`, `slug` | `permalink` |
31
+ | `sidebar_label`, `sidebar_position` | The sidebar data, or `nav: { title, order }` |
32
+ | `hide_table_of_contents` | A front-matter flag your layout checks before `toc(page.headings)` |
33
+ | `tags` | `tags` |
34
+ | `last_update` (git) | `lastModified: "git"` in the config, then `page.lastModified` |
35
+
36
+ ## Markdown and MDX
37
+
38
+ | Docusaurus | SiteSquatch |
39
+ | --- | --- |
40
+ | `:::note`, `:::tip Title`, `:::warning[Title]` | Containers, with the same `:::` syntax: `_includes/containers/note.*` renders them (the title is `container.args`) |
41
+ | `<Tabs>` and `<TabItem value="npm">` | `:::: tabs` holding `::: tab npm` containers (see `versioned-docs`) |
42
+ | A code block's `title="App.js"` and `{1,4-6}` | `{1,4-6}` marks lines with `highlight: true`; `title=` reaches a `fence` hook as part of `fence.info` |
43
+ | Live code blocks, `SnackPlayer` fences | A `fence-<lang>` hook (`_includes/hooks/fence-SnackPlayer.jinja`) that writes the embed |
44
+ | MDX `import` and JSX components | Edge components in the Markdown: `@component('components/callout', { type: 'warning' })...@end` (the page's Markdown runs through Edge first). Components that need React in the browser stay client-side JavaScript (web components work well). |
45
+ | `<!-- truncate -->` in blog posts | `<!-- more -->`, then `page.excerpt` |
46
+ | `authors.yml` | `_data/authors.json` (or `.yml`), looked up by the post's `authors` |
47
+ | `{#custom-id}` headings | The same |
48
+
49
+ ## React pages
50
+
51
+ Pages in `src/pages/*.js` become templates in any of ssqch's languages. Interactive parts (a playground, a live demo) stay JavaScript: ship them as custom elements with `elementsPlugin()` from `ssqch/elements`, which loads each one's script only on the pages that use it (the [`islands`](../../examples/sites/islands/) example).
52
+
53
+ ## Starting point
54
+
55
+ `ssqch init --starter docs` creates a docs site with a sidebar, a table of contents, tabs, notes and search, to move your pages into. To check the move, build both sites and run `ssqch diff build dist`.