ssqch 0.11.0 → 0.13.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 (138) hide show
  1. package/bundled/completions/bash +67 -9
  2. package/bundled/completions/elvish +24 -4
  3. package/bundled/completions/fish +37 -25
  4. package/bundled/completions/powershell +26 -4
  5. package/bundled/completions/zsh +45 -10
  6. package/bundled/docs/agents.md +2 -2
  7. package/bundled/docs/build-summary.md +1 -1
  8. package/bundled/docs/comparing-builds.md +7 -4
  9. package/bundled/docs/configuring.md +7 -12
  10. package/bundled/docs/deploying.md +1 -1
  11. package/bundled/docs/field-guide.md +4 -4
  12. package/bundled/docs/github-pages.md +2 -1
  13. package/bundled/docs/index.md +1 -1
  14. package/bundled/docs/install.md +1 -1
  15. package/bundled/docs/known-gaps.md +1 -1
  16. package/bundled/docs/markdown.md +11 -13
  17. package/bundled/docs/nav.yml +6 -1
  18. package/bundled/docs/netlify.md +4 -2
  19. package/bundled/docs/patrol.md +48 -0
  20. package/bundled/docs/plugins.md +6 -4
  21. package/bundled/docs/robots.md +72 -0
  22. package/bundled/docs/seo.md +2 -38
  23. package/bundled/docs/serving-markdown.md +142 -0
  24. package/bundled/docs/template-languages.md +2 -1
  25. package/bundled/docs/templates.md +2 -1
  26. package/bundled/docs/trailheads/from-component-frameworks.md +9 -10
  27. package/bundled/docs/trailheads/from-hugo.md +5 -3
  28. package/bundled/docs/trailheads/from-jekyll.md +54 -13
  29. package/bundled/docs/trailheads/from-mkdocs.md +15 -12
  30. package/bundled/docs/trailheads/from-vitepress.md +142 -0
  31. package/bundled/docs/trailheads.md +5 -5
  32. package/bundled/docs/where-values-come-from.md +5 -5
  33. package/bundled/docs/writing-plugins.md +69 -0
  34. package/bundled/ssqch.d.ts +150 -34
  35. package/bundled/starter/engines/index.edge +1 -0
  36. package/bundled/starter/engines/index.ejs +1 -0
  37. package/bundled/starter/engines/index.hbs +1 -0
  38. package/bundled/starter/engines/index.liquid +1 -0
  39. package/bundled/starter/engines/layout.edge +7 -0
  40. package/bundled/starter/engines/layout.ejs +4 -0
  41. package/bundled/starter/engines/layout.hbs +4 -0
  42. package/bundled/starter/engines/layout.liquid +4 -0
  43. package/bundled/starter/src/_data/site.json +1 -0
  44. package/bundled/starter/src/_includes/layout.jinja +4 -0
  45. package/bundled/starter/src/index.jinja +1 -0
  46. package/bundled/starter/ssqch.config.js +14 -1
  47. package/bundled/starter-docs/engines/edge/base.edge +7 -0
  48. package/bundled/starter-docs/engines/edge/doc.edge +4 -0
  49. package/bundled/starter-docs/engines/ejs/base.ejs +4 -0
  50. package/bundled/starter-docs/engines/ejs/doc.ejs +4 -0
  51. package/bundled/starter-docs/engines/hbs/base.hbs +4 -0
  52. package/bundled/starter-docs/engines/hbs/doc.hbs +3 -0
  53. package/bundled/starter-docs/engines/liquid/base.liquid +4 -0
  54. package/bundled/starter-docs/engines/liquid/doc.liquid +4 -0
  55. package/bundled/starter-docs/src/_data/site.json +1 -0
  56. package/bundled/starter-docs/src/_includes/base.jinja +4 -0
  57. package/bundled/starter-docs/src/_includes/doc.jinja +4 -0
  58. package/bundled/starter-docs/src/assets/docs.css +4 -0
  59. package/bundled/starter-docs/src/assets/docs.js +17 -0
  60. package/bundled/starter-docs/ssqch.config.js +14 -1
  61. package/lib/assets.js +13 -11
  62. package/lib/chunk-25WERNDD.js +112 -0
  63. package/lib/{chunk-H5K2ZE7B.js → chunk-2BJFGKOE.js} +13 -5
  64. package/lib/chunk-2FKYWYAB.js +268 -0
  65. package/lib/{chunk-LJOURBYT.js → chunk-3ZTRIO6O.js} +21 -19
  66. package/lib/{chunk-IOBC665M.js → chunk-4AZFCSGJ.js} +5 -3
  67. package/lib/{chunk-HWW5NCVJ.js → chunk-4Q6WMTER.js} +1 -1
  68. package/lib/{chunk-V2FSMOFX.js → chunk-55WXDGO4.js} +3 -3
  69. package/lib/{chunk-ZR3JYLFB.js → chunk-6FY77I4M.js} +331 -58
  70. package/lib/{chunk-JC54PHIT.js → chunk-6OUCRDYI.js} +514 -141
  71. package/lib/{chunk-ERAIEV3O.js → chunk-6U5VIQVY.js} +9 -7
  72. package/lib/{chunk-Z5OP43HU.js → chunk-7U5GWTEH.js} +455 -94
  73. package/lib/{chunk-CMJ7X5WW.js → chunk-AIJNG6MJ.js} +3 -2
  74. package/lib/{chunk-3K237XAX.js → chunk-C2Q7JKFI.js} +12 -10
  75. package/lib/{chunk-GS5B3CBW.js → chunk-DDV6JEC2.js} +1 -1
  76. package/lib/{chunk-A75EVUJX.js → chunk-DFJFHULZ.js} +47 -20
  77. package/lib/{chunk-KZZS4W2V.js → chunk-ENWDM2RW.js} +45 -42
  78. package/lib/{chunk-I3HYKEEW.js → chunk-ER72RPD6.js} +3 -3
  79. package/lib/chunk-F3JPNFCZ.js +23 -0
  80. package/lib/{chunk-B5E27PLU.js → chunk-FENJHLNM.js} +6 -3
  81. package/lib/{chunk-UU43WIZG.js → chunk-FJML7INB.js} +4 -2
  82. package/lib/{chunk-KCF2Z6N7.js → chunk-FQZDUDFK.js} +5 -3
  83. package/lib/{chunk-GJNIQAIH.js → chunk-GSNRAGKQ.js} +13 -6
  84. package/lib/{chunk-443ZQLVX.js → chunk-GU7BBYWB.js} +5 -4
  85. package/lib/{chunk-X2GAVYV2.js → chunk-HDKU6LRI.js} +110 -748
  86. package/lib/chunk-J3C2LEW7.js +121 -0
  87. package/lib/{chunk-XS4EJSEK.js → chunk-K5WZ2VYK.js} +7 -5
  88. package/lib/{chunk-3HZZY3Y7.js → chunk-OOKBXQAY.js} +7 -6
  89. package/lib/chunk-P2WS4RM4.js +707 -0
  90. package/lib/{chunk-RBNPBTDP.js → chunk-SNQOHNXE.js} +1 -1
  91. package/lib/{chunk-HFSWUTXX.js → chunk-SPIFZBIW.js} +1 -1
  92. package/lib/{chunk-QLUTNR37.js → chunk-T5IUI7W7.js} +12 -11
  93. package/lib/{chunk-ZINLHOX4.js → chunk-TGSVSG2G.js} +3 -2
  94. package/lib/{chunk-2L3HR67O.js → chunk-U2KEMVXO.js} +24 -16
  95. package/lib/{chunk-RYIWYWRQ.js → chunk-UHRBPZ4A.js} +7 -5
  96. package/lib/{chunk-2QTJTEBV.js → chunk-ULCT3PAV.js} +1 -1
  97. package/lib/{chunk-FCM3NYFR.js → chunk-UZNUS7RP.js} +12 -9
  98. package/lib/{chunk-GLJQ4C76.js → chunk-V3G2QGL3.js} +13 -106
  99. package/lib/{chunk-Z44IAMNG.js → chunk-VILOEVK7.js} +60 -28
  100. package/lib/chunk-VJWQSYEG.js +119 -0
  101. package/lib/{chunk-5ELAUHRL.js → chunk-WGAIE3DD.js} +23 -19
  102. package/lib/{chunk-OQGXZYZS.js → chunk-WUCRAV36.js} +13 -7
  103. package/lib/{chunk-RZYAIX2R.js → chunk-XYAWJTHM.js} +11 -10
  104. package/lib/{chunk-OSBEH67S.js → chunk-YA23NDMW.js} +5 -3
  105. package/lib/{chunk-AIMEXBTK.js → chunk-YNJNMQWU.js} +37 -142
  106. package/lib/{chunk-QJ5ZFTML.js → chunk-ZMG25MXF.js} +20 -18
  107. package/lib/cli.js +72 -35
  108. package/lib/elements.js +13 -11
  109. package/lib/from-hugo.js +36 -0
  110. package/lib/from-jekyll.js +41 -0
  111. package/lib/from-mkdocs.js +49 -0
  112. package/lib/from-vitepress.js +49 -0
  113. package/lib/image.js +12 -11
  114. package/lib/links.js +13 -11
  115. package/lib/llms.js +613 -0
  116. package/lib/minify.js +14 -12
  117. package/lib/redirects.js +13 -11
  118. package/lib/robots.js +87 -0
  119. package/lib/rss.js +24 -13
  120. package/lib/sass.js +12 -11
  121. package/lib/sitemap.js +23 -18
  122. package/lib/ssqch.js +6 -5
  123. package/lib/vue.js +400 -0
  124. package/package.json +29 -1
  125. package/types/from-hugo.d.ts +5 -0
  126. package/types/from-jekyll.d.ts +11 -0
  127. package/types/from-mkdocs.d.ts +11 -0
  128. package/types/from-vitepress.d.ts +5 -0
  129. package/types/index.d.ts +51 -31
  130. package/types/llms.d.ts +27 -0
  131. package/types/robots.d.ts +13 -0
  132. package/types/sass.d.ts +1 -1
  133. package/types/sitemap.d.ts +2 -2
  134. package/types/vue.d.ts +17 -0
  135. package/wasm/markdown.wasm +0 -0
  136. package/lib/chunk-RVXGUMFI.js +0 -21
  137. /package/lib/{chunk-ZR3JYLFB.js.LEGAL.txt → chunk-6FY77I4M.js.LEGAL.txt} +0 -0
  138. /package/lib/{chunk-AIMEXBTK.js.LEGAL.txt → chunk-YNJNMQWU.js.LEGAL.txt} +0 -0
@@ -0,0 +1,142 @@
1
+ ---
2
+ title: "Trailhead: moving from VitePress"
3
+ navTitle: "From VitePress"
4
+ description: "VitePress builds each Markdown page into a Vue component; SiteSquatch reads the same Markdown and writes HTML."
5
+ ---
6
+ VitePress builds each Markdown page into a Vue component and ships a client app that hydrates it. SiteSquatch reads the same Markdown and writes HTML, so a move keeps your pages as they are and turns the theme into templates. What takes the work is Vue in your pages: the components they use, and the parts that run in the browser. The vuejs.org docs (111 pages, 33 component names) moved with no Markdown page edited, 99.9% of their article text the same as VitePress's, and the generator step at 0.54 s against VitePress's 5.7 s.
7
+
8
+ ## Scouting
9
+
10
+ `ssqch scout` (see [Scouting a site](../trailheads.md#scouting-a-site)) reads `.vitepress/config.ts` (`srcDir`, `srcExclude`, `cleanUrls`, the sitemap's `hostname`, `head`, the markdown-it plugins it `use`s) and lists what your pages use, each with its file and line: Vue's `<script setup>` blocks, containers and the closing `:::`s Prettier indents, `-vue` fences, `[[toc]]`, every component by name with the `.vue` file it comes from and whether it has state, the front matter the theme reads (`layout`, `hero`, `outline`, `aside`, `page: true`), data loaders named like ssqch's data, and dynamic routes. `--write-draft` writes a first `ssqch.config.js`, and `ssqch baseline "pnpm run build" --from .vitepress/dist` builds the reference to compare with. Run scout again as you go: what the config or a template does counts as done.
11
+
12
+ ```js
13
+ // ssqch.config.js, as scout drafts it for vuejs.org
14
+ import { sitemapPlugin } from "ssqch/sitemap";
15
+ import { vuePlugin } from "ssqch/vue";
16
+ import { fromVitepress } from "ssqch/from-vitepress";
17
+
18
+ export default {
19
+ dirs: { input: "src", output: "dist" },
20
+ templateFormats: ["md"],
21
+ markdownEngine: false,
22
+ urls: "html",
23
+ ignore: ["api/api.data.ts", "error-reference/errors.data.ts", "examples/examples.data.ts", "tutorial/tutorial.data.ts", "tutorial/**/description.md", ".vitepress/**", "public/**"],
24
+ passthrough: { "src/public/**": "." },
25
+ markdown: { highlight: true },
26
+ plugins: [
27
+ fromVitepress(),
28
+ vuePlugin({ components: { VueSchoolLink: ".vitepress/theme/components/VueSchoolLink.vue", ScrimbaLink: ".vitepress/theme/components/ScrimbaLink.vue" }, hydrate: "visible" }),
29
+ sitemapPlugin({ url: "https://vuejs.org" }),
30
+ ],
31
+ };
32
+ ```
33
+
34
+ - **`templateFormats: ["md"]` and `markdownEngine: false`:** VitePress's pages are its Markdown, and Vue's `{{ }}` in them isn't a template language's.
35
+ - **`urls: "html"`:** with `cleanUrls` off (VitePress's default) a page is `/guide/intro.html`. With `cleanUrls: true`, leave it out: ssqch's URLs are folders (`/guide/intro/`).
36
+ - **`ignore`:** VitePress's data loaders are `*.data.ts`, and `api/api.data.ts` is the name ssqch gives a folder's data. Listed by their paths, they aren't read as data, and the `.data.js` files the move adds (a dynamic route's pagination) still are; `vuePlugin()` runs the loaders for the components and pages that import their `data`.
37
+ - **`vuePlugin()`:** the Vue components the pages use, rendered with your Vite and Vue (`npm install -D vite @vitejs/plugin-vue vue`, which a VitePress site has already), with the ones the theme registers for every page in `components`, and `hydrate: "visible"` when one has state.
38
+ - **`passthrough: { "src/public/**": "." }`:** `public/`'s files at the site's root. `{ "src/public": "." }` would copy the folder by its name.
39
+ - **`fromVitepress()`** from `ssqch/from-vitepress`: VitePress's Markdown (below), as one plugin. It turns on VitePress's heading ids and email autolinks unless your `markdown` sets them, and a template of yours with a hook's or container's name replaces its markup.
40
+
41
+ ## What maps
42
+
43
+ | VitePress | SiteSquatch |
44
+ | --- | --- |
45
+ | Pages, front matter, `{#id}` on headings | The same |
46
+ | `::: tip`, `info`, `warning`, `danger`, `details`, `raw`, `code-group` | `fromVitepress()` writes VitePress's markup, default titles and all. A template in `_includes/containers/tip.*` replaces one. |
47
+ | A closing `:::` indented under a list (Prettier writes them) | The same: it closes its container |
48
+ | Heading anchors, `tabindex`, VitePress's ids | `fromVitepress()`'s heading, with `headingIds: "vitepress"` (`What's Vue?` is `what-s-vue`) |
49
+ | Links to `.md` files, external links in a new tab | `fromVitepress()`'s links: `.html` with `urls: "html"`, `./` in front of a relative one, `target="_blank" rel="noreferrer"` on an external one |
50
+ | Code blocks, `[title]`, `vue-html`, `-vue` fences | `fromVitepress()`'s wrapper, copy button and label; `highlight: true` for colors, with ssqch's classes rather than Shiki's |
51
+ | `[[toc]]` | The same, in any case |
52
+ | `<script setup>`, `<style>`, `<ClientOnly>` in a page | Left out by `fromVitepress()`, as VitePress writes none of it |
53
+ | A component in a page (`<VueSchoolLink href="..." />`) | A template in `_includes/components/VueSchoolLink.*`, with `component.props` and `component.content` ([components](../templates.md)) |
54
+ | A `.vue` component a page imports, or the theme registers | `vuePlugin()` from `ssqch/vue` renders it with your Vite and Vue at build time; with `fromVitepress()`, VitePress's loaders and `useData()` work in it too; `hydrate: "visible"` runs it in the browser as an island (the vuejs.org demos work this way). Scout drafts it, with the theme's `app.component()`s. |
55
+ | A component with state, without Vue | Its HTML from a template, and what it does from a custom element in `ssqch/elements` |
56
+ | `themeConfig.nav` and `sidebar` | Data: move them to `_data/themeConfig.js` and import that file in `.vitepress/config.ts`, so both read one list. `navTree` marks the page you're on; a sidebar keyed by path is the longest key the page's URL starts with. In Jinja, read `link.get("items")`: `link.items` is the dict's method where there's no key. |
57
+ | The default theme's `Layout`, a theme's slots | A layout in `_includes/`. The theme's markup is in your build's HTML; `toc()`, `navTree` and `navPager` make the outline, the sidebar and the pager. |
58
+ | `page: true`, `layout: home` | `page` is ssqch's own (it's warned about): give those pages a layout of their own (`layout: home.jinja`) |
59
+ | `[param].md` with `[param].paths.ts` | `pagination` over the same list, `size: 1`, a `permalink` with the item's value, and `addAllPagesToCollections: true`, in `[param].data.js` beside the page |
60
+ | `head` in the config | The layout's `<head>` |
61
+ | `sitemap: { hostname }` | `sitemapPlugin({ url })`, with the same URLs. The file is ssqch's own (a tag a line, pages by URL, with `<lastmod>`; `lastmod: false` leaves it out), so `ssqch diff` lists `sitemap.xml` as changed, and that's expected: no reader of a sitemap needs VitePress's bytes |
62
+ | `markdown.config(md)` plugins | A render hook, a container, or `markdown.preprocess` |
63
+ | `vitepress-plugin-llms` | `llmsPlugin()` from `ssqch/llms`: `llms.txt`, a Markdown copy of each page and `llms-full.txt` |
64
+
65
+ ## Keeping your VitePress theme
66
+
67
+ You don't have to rebuild your theme as templates: `vuePlugin()` can render it around each page, so its nav, sidebar, outline and footer are the HTML VitePress writes (the vuejs.org move's theme came out with no differences). It takes a wrapper component and a layout, about 30 lines, and nothing in your pages changes. ssqch has no option for this: a theme's way of placing the page (`<Content />`) and reading `useData()` is VitePress's own.
68
+
69
+ A wrapper that renders the theme, with the page as its slot. On the server, the theme's `<Content />` is the page ssqch rendered; in the browser (with `hydrate`), it's the HTML the server wrote:
70
+
71
+ ```vue
72
+ <!-- src/_includes/vue/SiteLayout.vue -->
73
+ <script setup>
74
+ import { getCurrentInstance, h, useSlots } from "vue";
75
+ import { current } from "vitepress";
76
+ import Theme from "../../../.vitepress/theme/index.ts";
77
+
78
+ // What useData() has for the page: the layout passes it in.
79
+ const props = defineProps({ page: { type: String, required: true } });
80
+ const given = JSON.parse(decodeURIComponent(props.page));
81
+ const headers = [];
82
+ for (const heading of given.headings) {
83
+ const header = { level: heading.level, title: heading.text, slug: heading.id, link: `#${heading.id}`, children: [] };
84
+ if (heading.level === 2) headers.push(header);
85
+ else if (heading.level === 3 && headers.length) headers.at(-1).children.push(header);
86
+ }
87
+ current.page.value = { ...current.page.value, relativePath: given.relativePath, title: given.title, headers, frontmatter: given.frontmatter };
88
+ current.frontmatter.value = given.frontmatter;
89
+
90
+ const slots = useSlots();
91
+ const html = typeof document === "undefined" ? undefined : document.querySelector("[data-page]")?.innerHTML;
92
+ const app = getCurrentInstance().appContext.app;
93
+ app.component("Content", { setup: () => () => (html === undefined ? h("div", { "data-page": "" }, slots.default?.()) : h("div", { "data-page": "", innerHTML: html })) });
94
+ Theme.enhanceApp?.({ app });
95
+ </script>
96
+
97
+ <template>
98
+ <component :is="Theme.Layout" />
99
+ </template>
100
+ ```
101
+
102
+ A layout every page gets (`layout: "vitepress.njk"` in `src/src.data.js`, the input folder's data), which passes the page's data to it as `useData()` reads it, and the page as its slot:
103
+
104
+ ```njk
105
+ {# src/_includes/vitepress.njk #}
106
+ {%- set vitepress = { relativePath: page.inputPath | replace(r/^.*?src\//, ""), title: title or "", headings: page.headings, frontmatter: { aside: aside, outline: outline, footer: footer, sidebar: sidebar, editLink: editLink } } -%}
107
+ <!DOCTYPE html>
108
+ <html lang="en-US">
109
+ <head>
110
+ <meta charset="utf-8">
111
+ <title>{{ title }}</title>
112
+ <link rel="stylesheet" href="/assets/vue.css">
113
+ {# What `head` in .vitepress/config.ts has. #}
114
+ </head>
115
+ <body>
116
+ <div id="app"><SiteLayout page="{{ vitepress | dump | urlencode }}">{{ content | safe }}</SiteLayout></div>
117
+ </body>
118
+ </html>
119
+ ```
120
+
121
+ And in `ssqch.config.js`, the wrapper as a component every page can use, with `hydrate` if the theme should run in the browser (dark mode, the sidebar on a phone, search): `vuePlugin({ components: { SiteLayout: "src/_includes/vue/SiteLayout.vue" }, hydrate: "visible" })`. A theme that imports something virtual (`virtual:group-icons.css`) needs the Vite plugin that makes it: `vite: { plugins: [groupIconVitePlugin()] }`.
122
+
123
+ What it costs, and the choices:
124
+
125
+ - **`hydrate` is for every component.** With it, the theme runs in the browser too (the vuejs.org move's dark mode, Options/Composition switch and sidebar work), and so does every demo; without it, the pages are HTML only, and the parts that need JavaScript are custom elements from `ssqch/elements`.
126
+ - **`page: true`:** ssqch's `page` is its own. Give those pages a layout of their own (`layout: "page.njk"`), or read the value from the file in a `computed` (`vitepressPage: (data) => /^page:\s*true$/m.test(readFileSync(data.page.inputPath, "utf8"))`, in the input folder's data) and pass it to `frontmatter` as `page`.
127
+ - **A dynamic route's `relativePath`** is its page's own: `vuePlugin()` gives `useRoute()` the page's URL, and the layout can pass `page.url` the same way.
128
+
129
+ ## Inline Vue in pages
130
+
131
+ VitePress compiles each page into a Vue component, so a page can have Vue in its HTML: `{{ count }}`, `v-model`, `v-if`. ssqch's pages are HTML, and with `markdownEngine: false` those print as written (scout lists each, with its line). For each, either write the text itself (a version number, a link), or move that part into a `.vue` component of its own, beside the page, and use it there (`<CountDemo />`, imported in the page's `<script setup>`): `vuePlugin()` renders it, and with `hydrate`, runs it. `dialect: "vitepress"` does what Vue's compiler does to the rest of the page's HTML: a self-closing `<sup />` gets its end tag, and `v-pre` and event listeners (`@click`) are left out.
132
+
133
+ ## Known gaps
134
+
135
+ - **Shiki's colors:** ssqch highlights with its own classes (`highlight: true`), so code is colored by its stylesheet, not inline. A site with one Shiki theme (VitePress's `markdown.theme: "github-dark"`) has no `vp-adaptive-theme` on its code blocks: a fence hook of your own (`_includes/hooks/fence.*`, starting from the dialect's markup) writes them without it.
136
+ - **`llms.txt`:** `llmsPlugin()` writes llmstxt.org's format, not vitepress-plugin-llms' word for word. For the same bytes, a page with `permalink: /llms.txt` that lists `collections.all` writes your own.
137
+ - **What only runs in VitePress's app:** a REPL, `<Teleport>`, and components that read the router at run time need their own JavaScript in the browser: a custom element, or Vue loaded for that part.
138
+ - **Speed in the dev server:** VitePress compiles the one module the browser asks for (a few milliseconds); ssqch builds the site again (about half a second for vuejs.org, the Vue components kept from the last build when only pages changed).
139
+
140
+ ## Checking the move
141
+
142
+ `ssqch diff .cache/ssqch/baseline/ref-1 dist` leaves out Vue's scoped-style attributes (`data-v-*`), its server renderer's `<!--[-->` markers and Vite's fingerprints (`style.Bfpn8qS8.css`). Expect two differences on every page: VitePress's client app in `<head>` (its scripts and preloads), and Shiki's inline colors where ssqch writes classes. The text should match. A Vite build's asset names and Vue's scope ids depend on the folder it ran in, so the reference builds' are their own; the comparison takes that into account.
@@ -3,19 +3,19 @@ title: "Trailheads: moving from another generator"
3
3
  navTitle: "Moving to ssqch"
4
4
  description: "Everything migrates eventually."
5
5
  ---
6
- Everything migrates eventually. The trailheads map another generator's config, front matter and templates onto ssqch's, and `ssqch docs --from <generator>` prints the one you need: [from Zola](trailheads/from-zola.md), [from Hugo](trailheads/from-hugo.md), [from Eleventy](trailheads/from-eleventy.md), [from Docusaurus](trailheads/from-docusaurus.md), [from MkDocs](trailheads/from-mkdocs.md), [from Hexo](trailheads/from-hexo.md), [from Jekyll](trailheads/from-jekyll.md) and [from component frameworks](trailheads/from-component-frameworks.md) (Astro, VitePress, Next.js, Gatsby). [`examples/sites/`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/) has small, complete sites to start from or copy parts of, each built in CI: `blog-tags`, `blog-categories`, `docs-sidebar`, `glossary-docs`, `versioned-docs`, `component-docs`, `reference-pages`, `islands` and `jekyll-guides`.
6
+ Everything migrates eventually. The trailheads map another generator's config, front matter and templates onto ssqch's, and `ssqch docs --from <generator>` prints the one you need: [from Zola](trailheads/from-zola.md), [from Hugo](trailheads/from-hugo.md), [from Eleventy](trailheads/from-eleventy.md), [from Docusaurus](trailheads/from-docusaurus.md), [from MkDocs](trailheads/from-mkdocs.md), [from Hexo](trailheads/from-hexo.md), [from Jekyll](trailheads/from-jekyll.md), [from VitePress](trailheads/from-vitepress.md) and [from component frameworks](trailheads/from-component-frameworks.md) (Astro, Next.js, Gatsby). [`examples/sites/`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/) has small, complete sites to start from or copy parts of, each built in CI: `blog-tags`, `blog-categories`, `docs-sidebar`, `glossary-docs`, `versioned-docs`, `component-docs`, `reference-pages`, `islands` and `jekyll-guides`.
7
7
 
8
8
  ## Scouting a site
9
9
 
10
10
  `ssqch scout` tells you what moving a site to ssqch takes, before you start and at any point during the move. Run it in the old site's folder (or name the folder: `ssqch scout ../old-site`). It finds the generator from its files (`_config.yml`, `hugo.toml`, `mkdocs.yml`, an Eleventy config; `--from <generator>` chooses when it can't tell or guesses wrong) and prints:
11
11
 
12
- - **Reference build:** the `ssqch baseline` command that builds the site with its own generator to compare with, from the site's own build command (`netlify.toml`, a `build` script), and what that build needs (`PAGES_REPO_NWO` for a GitHub Pages site, an `npm install` for Tailwind).
12
+ - **Reference build:** the `ssqch baseline` command that builds the site with its own generator to compare with, from the site's own build command (`netlify.toml`, a `build` script, or another script that runs the generator and isn't a watcher), and what that build needs (`PAGES_REPO_NWO` for a GitHub Pages site, an `npm install` for Tailwind, the old Node a site pins in `.nvmrc`). For Eleventy it's the config's output folder (`--from dist`), and a tool the script runs beside the generator comes along after it (`eleventy & gulp` becomes `"eleventy && gulp"`, so baseline doesn't copy the output while gulp is still writing it), as does a `gulpfile.js` no script runs. Mid-move, a script scout's patch changed to `ssqch build` stands for the generator's command again.
13
13
  - **A summary first:** how many things there are to do, across how many pages, and how many of them ssqch does as it is, an option does (the draft turns it on), are not in ssqch yet, or are the site's own code to port. It's the first answer to "how big is this move?".
14
14
  - **To do:** what the site uses that needs doing in ssqch, each with its file and line, ssqch's way to do it, or "not in ssqch yet", the most files first. A thing used many times is one line, with a count and the first place it's used. Each line is marked `[option]` (an option does it, in the draft), `[not yet]` or `[port]` (the site's own code: templates, plugins, hooks); a line without a mark is something ssqch does.
15
15
  - **Draft:** the new files a move starts with: a first `ssqch.config.js` from the old config, directory data for posts and collections, includes and render hooks for the old generator's plugins. `--write-draft` writes the ones that aren't there, and never overwrites a file.
16
- - **Edits:** the changes to the site's own files that are mechanical and clearly right (a data file's name, an image attribute, `{% seo %}` to an include, a `package.json` script). `--patch move.patch` writes them as a patch to read and apply with `git apply move.patch`; scout never applies it. It doesn't rewrite templates: where a template would need a rewrite, ssqch has the compatibility instead (`jekyllTemplates`, Eleventy's front matter keys as aliases), or the list says so.
16
+ - **Edits:** the changes to the site's own files that are mechanical and clearly right (a data file's name, an image attribute, `{% seo %}` to an include, a `package.json` script). `--patch move.patch` writes them as a patch to read and apply with `git apply move.patch`; scout never applies it. It doesn't rewrite templates: where a template would need a rewrite, ssqch has the compatibility instead (`fromJekyll()` and the other trailheads' modules, Eleventy's front matter keys as aliases), or the list says so.
17
17
 
18
- It changes nothing unless it's asked, so it's safe to run again during a move: the draft files you've written show as there already, applied edits are gone from the list, an `[option]` the site's `ssqch.config.js` sets already is done (scout loads the config and checks each value the option names: `3 done already: ssqch.config.js sets markdown: { admonitions: "mkdocs" }, ...`), and what's left is what still needs doing. An option that's a plugin call or a list stays on the list for you to check, and a config that doesn't load says why and counts nothing as done. `--compare` also builds the site with ssqch and compares the output with the reference build (`ssqch baseline`'s `ref-common`, or `ref-1`; `--reference <dir>` names another), and adds the result to the report: how many files differ, and the biggest groups of differences, the most files first, with the first file and the change. It builds with the clock `ssqch baseline` pins (`TZ=UTC`, and `SOURCE_DATE_EPOCH` at the HEAD commit's time, or 2026-01-01 outside git; one you set wins), so a sitemap's dates aren't a difference of their own. The comparison is the normalized one `ssqch diff` makes; `ssqch diff --exact` checks byte for byte. Fix the top group, and run `ssqch scout --compare` again: it's the move's loop in one command.
18
+ It changes nothing unless it's asked, so it's safe to run again during a move: the draft files you've written show as there already, applied edits are gone from the list, an `[option]` the site's `ssqch.config.js` sets already is done (scout loads the config and checks each value the option names: `3 done already: ssqch.config.js has fromMkdocs, ...`), and so is an Eleventy to-do the config does under the same name: a filter, shortcode or tag in `filters`, a collection in `collections`, a transform in `transforms`, a plugin's work by ssqch's plugin (`rssPlugin()` for the RSS plugin and its filters, `minifyPlugin()` for an `htmlmin` transform), a library by `engines: { md }` or the `markdown` options, or the old package itself, imported in `ssqch.config.js` for an identical first build. The config's own imports of Eleventy's packages aren't to-dos, and only data in the input folder is Eleventy's data (a JSON file elsewhere, such as a saved scout report, is left alone). What's left is what still needs doing. An option that's a plugin call or a list stays on the list for you to check, and a config that doesn't load says why and counts nothing as done. `--compare` also builds the site with ssqch and compares the output with the reference build (`ssqch baseline`'s `ref-common`, or `ref-1`; `--reference <dir>` names another), and adds the result to the report: how many files differ, and the biggest groups of differences, the most files first, with the first file and the change. It builds with the clock `ssqch baseline` pins (`TZ=UTC`, and `SOURCE_DATE_EPOCH` at the HEAD commit's time, or 2026-01-01 outside git; one you set wins), so a sitemap's dates aren't a difference of their own. The comparison is the normalized one `ssqch diff` makes; `ssqch diff --exact` checks byte for byte. Fix the top group, and run `ssqch scout --compare` again: it's the move's loop in one command.
19
19
 
20
20
  `--format json` prints the same report for agents and scripts: `generator`, `detectedBy`, `underWay` (an `ssqch.config.js` is there), `configError` (why it couldn't be read, or `null`), `summary` (`pages`, how many to-dos are `ssqch`, `option`, `notYet` and `site`, and how many are `done`), `build` (`command`, `output`, `baseline`, `needs`), `todo` (`at`, `what`, a stable `code` such as `hugo-shortcode` or `mkdocs-admonitions`, `status`: `ssqch`, `option`, `not-yet` or `site`, `count` and `files` when it's counted, `option` for the config that does it, and `docs` for an `ssqch docs` query), `done` (the to-dos the config does already: `at`, `what`, `code`, `option`), `draft` (`path`, `from`, `there`), `edits` (`path`, `to` for a rename, `changes`), `wroteDraft`, `patch`, `trailhead`, and with `--compare`, `compare` (`reference`, `output`, `built`, `errors`, `same`, `summary`, `groups` with `files`, `kind`, `first`, `removed` and `added`, `files` with the paths `changed`, `added` and `removed`, the first 20 of each, and `problem` when there was nothing to compare).
21
21
 
@@ -26,7 +26,7 @@ git apply move.patch # after reading it
26
26
  ssqch scout # later: what's left
27
27
  ```
28
28
 
29
- What it reads in depth: Eleventy (the config and the modules it loads, filters and shortcodes, plugins, data files, `package.json`), Jekyll (`_config.yml`, the Gemfile's plugins, collections, `_plugins/*.rb`, templates that read Jekyll's `page` and `site`), Zola (`config.toml`, sections, Tera templates and shortcodes), Hugo (shortcodes and their calls, sections and `cascade`, render hooks, Go templates and Hugo Pipes; the draft turns on `shortcodes: "hugo"` and has a container template to port for each of the site's shortcodes) and MkDocs (`mkdocs.yml`'s nav, theme, plugins and Markdown extensions, and the MkDocs syntax the pages use: admonitions, tabs, `.md` links, icons; the draft turns on the options that read them as they are, and writes the nav as `_data/nav.yml`). For Docusaurus (MDX and its imports, `<Tabs>`, admonitions, the sidebar, versions, plugins), Astro (`.astro` and framework components, content collections, integrations), VitePress (containers, Vue in pages, the config's sidebar, the theme) and Hexo (tag plugins, the theme, scaffolds, plugins) it lists what the pages use, without a draft yet. If it finds no generator's files, or two generators', it says so and asks for `--from`.
29
+ What it reads in depth: Eleventy (the config and the modules it loads, filters and shortcodes, plugins, data files, `package.json`), Jekyll (`_config.yml`, the Gemfile's plugins, collections, `_plugins/*.rb`, templates that read Jekyll's `page` and `site`), Zola (`config.toml`, sections, Tera templates and shortcodes), Hugo (shortcodes and their calls, sections and `cascade`, render hooks, Go templates and Hugo Pipes; the draft turns on `fromHugo()` and has a container template to port for each of the site's shortcodes) and MkDocs (`mkdocs.yml`'s nav, theme, plugins and Markdown extensions, and the MkDocs syntax the pages use: admonitions, tabs, `.md` links, icons; the draft turns on the options that read them as they are, and writes the nav as `_data/nav.yml`) and VitePress (`.vitepress/config.ts`'s `srcDir`, `srcExclude`, `cleanUrls`, sitemap, `head` and markdown-it plugins, and what the pages use: Vue's `<script setup>`, containers and Prettier's indented `:::`, every component by name with its `.vue` file and whether it has state, the front matter the theme reads, data loaders and dynamic routes; the draft turns on `fromVitepress()`, `urls`, `ignore` for the loaders and the sitemap, and a component counts as done once it has a template). For Docusaurus (MDX and its imports, `<Tabs>`, admonitions, the sidebar, versions, plugins), Astro (`.astro` and framework components, content collections, integrations) and Hexo (tag plugins, the theme, scaffolds, plugins) it lists what the pages use, without a draft yet. If it finds no generator's files, or two generators', it says so and asks for `--from`.
30
30
 
31
31
 
32
32
  ## Words you bring with you
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Where a value comes from"
2
+ title: "Following the tracks: where a value comes from"
3
3
  description: "A page's data is a cascade."
4
4
  ---
5
5
  A page's data is a cascade. From the lowest level to the highest:
@@ -13,10 +13,10 @@ A page's data is a cascade. From the lowest level to the highest:
13
13
 
14
14
  A higher level replaces what a lower one set. Objects merge key by key and lists are joined (a post's `tags` add to its folder's), unless `deepMerge` is off. `page` and `ssqch` are built in.
15
15
 
16
- When a value isn't what you expected, `ssqch inspect` follows its tracks back to the level that set it. Give it a page's URL or its template's path:
16
+ When a value isn't what you expected, `ssqch trace` follows its tracks back to the level that set it. Give it a page's URL or its template's path:
17
17
 
18
18
  ```sh
19
- ssqch inspect /guides/pine/
19
+ ssqch trace /guides/pine/
20
20
  ```
21
21
 
22
22
  ```text
@@ -39,7 +39,7 @@ ssqch inspect /guides/pine/
39
39
  `--field` shows one value in full, with every level that set it:
40
40
 
41
41
  ```sh
42
- ssqch inspect src/guides/2024-03-02-pine.md --field level
42
+ ssqch trace src/guides/2024-03-02-pine.md --field level
43
43
  ```
44
44
 
45
45
  ```text
@@ -52,6 +52,6 @@ Set by (the last one wins):
52
52
  ```
53
53
 
54
54
  - **Inside a value:** a dotted path reaches into objects (`--field site.author.name`, `--field hero.alt`).
55
- - **Pages made by pagination:** a template that makes many pages needs the URL of one of them. `ssqch inspect src/tags.jinja` lists them.
55
+ - **Pages made by pagination:** a template that makes many pages needs the URL of one of them. `ssqch trace src/tags.jinja` lists them.
56
56
  - **Scripts and agents:** `--format json` prints the report as JSON (`schemaVersion: 1`), with `value`, `from` and `setBy` for each field.
57
57
  - **No page is built:** it reads the site as a build does, up to the point of rendering. `beforeBuild` hooks run, since data can depend on them (a command that writes a data file, a plugin that sets itself up there), but no page is rendered or written, and `afterBuild` doesn't run. Standard output is only the report; anything a hook or `console.log` prints goes to standard error.
@@ -0,0 +1,69 @@
1
+ ---
2
+ title: "Writing a plugin"
3
+ description: "A plugin is an object with the config's parts, plus what only a plugin can give: steps in ssqch's Markdown, render hooks as functions, and defaults the site's own config replaces."
4
+ ---
5
+ A plugin is an object in the config's `plugins`, or a function that returns one. It can have any of the config's parts (`data`, `filters`, `collections`, `transforms`, `engines`, `passthrough`, `watch`, `beforeBuild`, `afterBuild`, `plugins`), which add to the site's own, and three things of its own: a `name` for its errors, `markdown` (steps in ssqch's Markdown and render hooks as functions) and `defaults` (settings the site's config replaces). Settings that change where files go (`dirs`, `base`) are the site's, and a plugin that sets one is an error.
6
+
7
+ Here's a plugin that turns `[[Page title]]` into a link to the page with that title, and writes `::: aside` blocks as `<aside>`:
8
+
9
+ ```js
10
+ // trail-links.js
11
+ export function trailLinks({ folder = "/guide/" } = {}) {
12
+ const slug = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
13
+ return {
14
+ name: "trailLinks",
15
+ markdown: {
16
+ // The page's Markdown, before ssqch's reads it.
17
+ before: (source) => source.replace(/\[\[([^\]]+)\]\]/g, (_, title) => `[${title}](${folder}${slug(title)}/)`),
18
+ hooks: {
19
+ "containers/aside": (container) => `<aside class="${container.args || "note"}">${container.content}</aside>`,
20
+ },
21
+ },
22
+ defaults: { markdown: { containers: true } },
23
+ };
24
+ }
25
+ ```
26
+
27
+ ```js
28
+ // ssqch.config.js
29
+ import { defineConfig } from "ssqch";
30
+ import { trailLinks } from "./trail-links.js";
31
+
32
+ export default defineConfig({
33
+ plugins: [trailLinks({ folder: "/trails/" })],
34
+ });
35
+ ```
36
+
37
+ ## Markdown steps
38
+
39
+ `markdown` has three keys, each optional:
40
+
41
+ - `before(source, context)`: the page's Markdown before ssqch's reads it, after its template engine ran. Return the Markdown to read.
42
+ - `after(html, context)`: the HTML ssqch's Markdown wrote for the page, before its layouts. Return the HTML.
43
+ - `hooks`: render hooks and containers as functions that return HTML, by the name the template would have: `heading`, `link`, `image`, `fence`, `code`, `table`, or `containers/<name>` for a `::: name` block. Each gets what the template of that name gets (`heading.level`, `heading.id`, `heading.content`; `container.args`, `container.content`), as [Render hooks](markdown.md) lists them. A site's own template of the same name (`_includes/hooks/heading.*`, `_includes/containers/aside.*`) replaces the plugin's, so a site can change one piece of a plugin's markup.
44
+
45
+ Steps run on a page's own Markdown (not on the `markdown()` function's text), in the order the plugins are listed, and `before` runs before the site's `markdown.preprocess`. A later plugin's hook of a name replaces an earlier one's. Each answers at once: a step or hook that returns a promise is an error that says so (work out what it needs in `beforeBuild` or a data file first), and one that returns something other than text names the plugin.
46
+
47
+ `context`, the second argument, has:
48
+
49
+ | Key | What it is |
50
+ | --- | --- |
51
+ | `data` | The page's data, as its templates see it |
52
+ | `page` | `data.page`: its `url`, `inputPath` and the rest |
53
+ | `urls` | The site's `urls`: `"folders"` or `"html"` |
54
+ | `markdown(text, { inline })` | Markdown rendered with the site's options and hooks, for a title or a block's inside; `inline: true` leaves out the `<p>` |
55
+ | `hasHook(name)` | Whether the site or a plugin has the hook or container `name` |
56
+ | `renderHook(name, key, value)` | Calls a hook as ssqch's Markdown does (`renderHook("containers/aside", "container", { args, content })`): the site's template if it has one, else a plugin's |
57
+
58
+ ## Defaults
59
+
60
+ `defaults: { markdown: { ... } }` gives values for the site's `markdown` options, for each key the site's own `markdown` doesn't set: a plugin for a kind of site can turn on what it needs (`containers`, `headingIds`) and the site can still say otherwise. A plugin's defaults are `markdown` options only, for now.
61
+
62
+ ## Plugins that come with ssqch
63
+
64
+ The built-in plugins (`ssqch docs "built-in plugins"`) are written this way where they can be. Four of them are another generator's ways, for a site moving from it, each documented in its trailhead:
65
+
66
+ - `fromVitepress()` from `ssqch/from-vitepress`: VitePress's Markdown, built with what this page describes (a `before` and an `after` step, eleven hooks and two defaults), and VitePress's `useData()`, `@theme/` and data loaders for `vuePlugin()`'s components ([Moving from VitePress](trailheads/from-vitepress.md)).
67
+ - `fromMkdocs()` from `ssqch/from-mkdocs`: MkDocs' Markdown as defaults (Python-Markdown's reading, admonitions, tabs, toc's ids, `.md` links), and its theme context with `templates: true` ([Moving from MkDocs](trailheads/from-mkdocs.md)).
68
+ - `fromJekyll()` from `ssqch/from-jekyll`: Jekyll's `page` and `site` in templates, and kramdown's Markdown ([Moving from Jekyll](trailheads/from-jekyll.md)).
69
+ - `fromHugo()` from `ssqch/from-hugo`: Hugo's shortcodes as containers ([Moving from Hugo](trailheads/from-hugo.md)).
@@ -75,23 +75,23 @@ declare module "ssqch" {
75
75
 
76
76
  /** How Markdown renders. */
77
77
  export interface MarkdownOptions {
78
- /** Automatic heading `id`s: `"github"` (the default: GitHub's and github-slugger's anchors, character for character), `"blackfriday"` (Hugo's older style: `a-b` for `A -- B`), `"kramdown"` (Jekyll's: GitHub's ids for the page's headings, and kramdown's ASCII ones, `section` for none, for headings inside `markdown="1"` HTML), `"markdown-it-anchor"` (that plugin's default: the lowercase text with spaces as `-`, percent-encoded, `what%E2%80%99s-new%3F`), `"python-markdown"` (MkDocs': Python-Markdown's `toc` ids, ASCII, `cafe-notes` for `Café notes`), or `false` for none. A `{#id}` on the heading always wins. */
79
- headingIds?: "github" | "blackfriday" | "ascii" | "kramdown" | "markdown-it-anchor" | "python-markdown" | false | ((text: string) => string);
78
+ /** Automatic heading `id`s: `"github"` (the default: GitHub's and github-slugger's anchors, character for character), `"blackfriday"` (Hugo's older style: `a-b` for `A -- B`), `"kramdown"` (Jekyll's: GitHub's ids for the page's headings, and kramdown's ASCII ones, `section` for none, for headings inside `markdown="1"` HTML), `"markdown-it-anchor"` (that plugin's default: the lowercase text with spaces as `-`, percent-encoded, `what%E2%80%99s-new%3F`), `"python-markdown"` (MkDocs': Python-Markdown's `toc` ids, ASCII, `cafe-notes` for `Café notes`), or `false` for none. A `{#id}` on the heading always wins. `"vitepress"`: VitePress's (@mdit-vue's `slugify`: `What's Vue?` is `what-s-vue`, `1. Setup` is `_1-setup`). */
79
+ headingIds?: "github" | "blackfriday" | "ascii" | "kramdown" | "markdown-it-anchor" | "python-markdown" | "vitepress" | false | ((text: string) => string);
80
80
  /** `## Heading {#id .class key=value}`. Default `true`. */
81
81
  headingAttributes?: boolean;
82
82
  /** `[^1]` references, with the notes at the end of the page. Default `true`. */
83
83
  footnotes?: boolean;
84
84
  /** `- [ ]` and `- [x]` items. Default `true`. */
85
85
  taskLists?: boolean;
86
- /** Bare `https://` and `www.` URLs become links. `"fuzzy"` links bare domains (`example.com`, with a common or two-letter country TLD) and email addresses too, as markdown-it's `linkify` does. Default `true`. */
87
- autolinks?: boolean | "fuzzy";
88
- /** A single newline inside a paragraph (or a list item) becomes a `<br>`, as markdown-it's `breaks: true` makes it. Default `false`. */
86
+ /** Bare `https://` and `www.` URLs become links. `"fuzzy"` links bare domains (`example.com`, with a common or two-letter country TLD) and email addresses too, as markdown-it's `linkify` does. `"email"` links email addresses (with `mailto:`) and URLs, not bare domains, as markdown-it's `linkify` with `fuzzyLink: false` does (VitePress's setting). Default `true`. */
87
+ autolinks?: boolean | "fuzzy" | "email";
88
+ /** A single newline inside a paragraph (or a list item) becomes a `<br>`. Default `false`. (markdown-it's `breaks: true` writes the same.) */
89
89
  breaks?: boolean;
90
- /** An image (or a linked image) alone in a paragraph becomes `<figure><img alt=""><figcaption>its alt text</figcaption></figure>`, as markdown-it-implicit-figures with `figcaption: true` writes it. Default `false`. */
90
+ /** An image (or a linked image) alone in a paragraph becomes `<figure><img alt=""><figcaption>its alt text</figcaption></figure>`. Default `false`. (markdown-it-implicit-figures with `figcaption: true` writes the same.) */
91
91
  figures?: boolean;
92
92
  /** GitHub's `> [!NOTE]` alerts: note, tip, important, warning and caution. Default `true`. */
93
93
  alerts?: boolean;
94
- /** `::: name args` blocks, rendered by `_includes/containers/name.*`. Default `true`. */
94
+ /** `::: name args` blocks, rendered by `_includes/containers/name.*`. A closing `:::` indented less than four spaces closes the innermost open container, so Prettier's `:::`, indented under the list it ends, works (as markdown-it-container and VitePress read them). Default `true`. */
95
95
  containers?: boolean;
96
96
  /** A term, then `: definition` lines. Default `false`. */
97
97
  definitionLists?: boolean;
@@ -99,21 +99,9 @@ declare module "ssqch" {
99
99
  smartPunctuation?: boolean;
100
100
  /** Lines indented four spaces are code blocks. `false` renders them as ordinary Markdown (HTML indented inside Markdown, say); fences are still code. Default `true`. */
101
101
  indentedCode?: boolean;
102
- /** Link and image URLs are percent-encoded, as CommonMark's reference renderer writes them (`#كتابة` as `#%D9%83...`, `café.png` as `caf%C3%A9.png`). `false` writes them as the page has them, HTML-escaped only (`&` as `&amp;`), as kramdown (Jekyll) does; browsers go to the same place either way. A link or image hook gets the URL as written in both. Default `true`. */
103
- encodeUrls?: boolean;
104
102
  /** Highlight fenced code at build time, with `hl-*` classes. The build writes their stylesheet to `/highlight.css`, or to `css` (a URL path), or not at all with `css: false`. `languages` adds languages or replaces built-in ones. `classes` names the tokens as another highlighter does, so a site keeps its theme's CSS: `"prism"` (`token keyword`, `<pre class="language-js">`, marked lines as `<mark class="highlight-line highlight-line-active">`), `"pygments"` or `"chroma"` (Pygments' short names, `k`, `s`, `nf`, which MkDocs' and Hugo's themes style), or `{ keyword: "tok-keyword" }` for some kinds; the stylesheet uses the same names. Default `false`. */
105
- /** Markdown inside HTML, as Jekyll's kramdown reads it: `"kramdown"` renders the content of an element with `markdown="1"` (span-level for `p`, headings and inline elements, block-level for the others; `"block"` and `"span"` choose) and drops the attribute, and keeps kramdown's HTML rules: a block-level element is raw HTML to its end tag, blank lines and all. Default `false`: HTML is CommonMark's, and Markdown inside it stays text. */
106
- htmlMarkdown?: "kramdown" | false;
107
- /** MkDocs' admonitions: `"mkdocs"` writes `!!! note "Title"` (body indented four spaces) as Python-Markdown's `<div class="admonition note"><p class="admonition-title">Title</p>...</div>`, and `??? note` and `???+ note` (pymdownx.details) as `<details class="note">`, open with `+`. The title is the type's name when there's none, and left out for `""`. Default `false`. */
108
- admonitions?: "mkdocs" | false;
109
- /** MkDocs' content tabs: `"mkdocs"` writes `=== "Tab"` blocks (body indented four spaces; tabs one after another are one set, `===+` selected, `===!` a new set) as pymdownx.tabbed's `alternate_style` writes them (`<div class="tabbed-set tabbed-alternate">`), which Material's CSS styles. Default `false`. */
110
- tabs?: "mkdocs" | false;
111
- /** Hugo's shortcodes: `"hugo"` reads a shortcode on a line of its own as a container: `{{< note type="tip" >}}` to `{{< /note >}}` (or `{{% %}}`) renders `_includes/containers/note.*` with `container.args`, `container.props` and the content as Markdown; one with no closing tag has no content. A shortcode inside a line of text is left as written. Default `false`. */
112
- shortcodes?: "hugo" | false;
113
103
  /** Links to `.md` files (`[Setup](setup/install.md#first)`) go to the page built from that file, with the `#` part: `true` writes its URL from the site's root (`/setup/install/#first`), `"relative"` from the page, as MkDocs does (`setup/install/#first`). A link to a file that isn't a page stays as written, for the link checker. Default `false`. */
114
104
  sourceLinks?: boolean | "relative";
115
- /** Another Markdown's ways, where they're CommonMark's otherwise. `"python-markdown"` (MkDocs'): a raw HTML block runs to its closing tag, blank lines and all; a list nests at four spaces (an item indented less is the next item); and the HTML is Python-Markdown's: `"` as it is in text, `<hr />`, `<br />`, `<img alt="" src="" />`, a tight item's nested list right after its text, nothing at the end. Default `false`. */
116
- dialect?: "python-markdown" | false;
117
105
  highlight?: boolean | { css?: string | false; languages?: Record<string, Highlighter>; classes?: "prism" | "pygments" | "chroma" | Partial<Record<TokenKind, string>> };
118
106
  }
119
107
 
@@ -149,6 +137,8 @@ declare module "ssqch" {
149
137
  dirs: { input: string; output: string; includes: string; data: string };
150
138
  /** The files the build wrote (`afterBuild` only). */
151
139
  written?: string[];
140
+ /** While serving, the files whose change started this build, relative to the project root (`./src/guide/intro.md`), so a hook can skip work the change doesn't touch: `if (changed && !changed.some((f) => f.endsWith(".vue"))) return;`. Not there on the first build or a build of everything (`ssqch build`). */
141
+ changed?: string[];
152
142
  }
153
143
 
154
144
  type MaybePromise<T> = T | Promise<T>;
@@ -229,11 +219,47 @@ declare module "ssqch" {
229
219
  plugins?: Plugin[];
230
220
  }
231
221
 
222
+ /** What a plugin's Markdown steps and hooks get besides their text. */
223
+ export interface MarkdownStepContext {
224
+ /** The page's data, as its templates see it. */
225
+ data: Record<string, any>;
226
+ /** The page (`data.page`): `url`, `inputPath` and the rest. */
227
+ page: Record<string, any> | undefined;
228
+ /** The site's `urls`: `"html"` when pages are `/guide/intro.html`. */
229
+ urls: "folders" | "html";
230
+ /** Markdown rendered with the site's options and hooks; `{ inline: true }` leaves out the `<p>`. */
231
+ markdown(text: string, options?: { inline?: boolean }): string;
232
+ /** Whether the site or a plugin has the render hook or container `name` (`"heading"`, `"containers/tip"`). */
233
+ hasHook(name: string): boolean;
234
+ /** Calls the render hook `name` with `value` under `key` (`renderHook("containers/tip", "container", { args, content })`): the site's template if it has one, else a plugin's. */
235
+ renderHook(name: string, key: string, value: Record<string, any>): string;
236
+ }
237
+
238
+ /** A plugin's own steps in ssqch's Markdown. Each answers at once with text. */
239
+ export interface PluginMarkdown {
240
+ /** The page's Markdown, before ssqch's Markdown reads it (after its template engine). Runs in the order the plugins are listed, before the site's `markdown.preprocess`. */
241
+ before?: (source: string, context: MarkdownStepContext) => string;
242
+ /** The HTML ssqch's Markdown wrote for the page, before its layouts. */
243
+ after?: (html: string, context: MarkdownStepContext) => string;
244
+ /** Render hooks and containers, as functions that return HTML: `heading`, `link`, `image`, `fence`, `code`, `table`, `containers/<name>`. Each gets what the template of the same name would (`heading.level`, `container.content`). A site's own template of the same name (`_includes/hooks/heading.*`) replaces it; a later plugin's replaces an earlier one's. */
245
+ hooks?: Record<string, (value: Record<string, any>, context: MarkdownStepContext) => string>;
246
+ }
247
+
248
+ /** A plugin: the config's parts, and what only a plugin can give. */
249
+ export interface PluginParts extends ConfigParts {
250
+ /** The plugin's name, for its errors. */
251
+ name?: string;
252
+ /** Steps in ssqch's Markdown, and render hooks as functions. */
253
+ markdown?: PluginMarkdown;
254
+ /** Values for the site's settings that its own config replaces: `markdown` options (`{ markdown: { headingIds: "ascii" } }`) for any key the site's `markdown` doesn't set. */
255
+ defaults?: { markdown?: MarkdownOptions };
256
+ }
257
+
232
258
  export type Plugin =
233
- | ConfigParts
259
+ | PluginParts
234
260
  | BuiltinPlugin
235
261
  | RustPlugin
236
- | ((context: ConfigContext) => MaybePromise<ConfigParts | BuiltinPlugin | RustPlugin | false | null | undefined>)
262
+ | ((context: ConfigContext) => MaybePromise<PluginParts | BuiltinPlugin | RustPlugin | false | null | undefined>)
237
263
  | false
238
264
  | null
239
265
  | undefined;
@@ -262,21 +288,13 @@ declare module "ssqch" {
262
288
  deepMerge?: boolean;
263
289
  /** Delete output files an earlier build wrote or copied that this one didn't (a deleted post's page). Files other tools write are never touched. Default `false`. */
264
290
  leaveNoTrace?: boolean;
265
- /** Another name for `leaveNoTrace`. Set one of them. */
266
- clean?: boolean;
267
291
  /** Globs (relative to the input folder) of files that aren't pages, like `["drafts/**", "notes/*.wip.md"]`. */
268
292
  ignore?: string | string[];
269
293
  /** Page bundles: copy the other files in a folder whose page is `index.*` (images, downloads) next to the page. Default `false`. */
270
294
  bundles?: boolean;
271
295
  /** Printing an undefined value (`{{ titel }}`) is an error, in every template language. Conditionals and defaults still work. Default `false`. */
272
296
  strict?: boolean;
273
- /** Start a template's body at its first line with text, dropping the blank lines after the closing `---`, as Jekyll does (its layouts and includes print no blank line there). Off by default: the body starts on the line after `---`, as Eleventy and gray-matter have it. */
274
- trimAfterFrontMatter?: boolean;
275
- /** Templates see Jekyll's `page` and `site`, so a Jekyll site's layouts and includes run as written: `page` has the page's front matter too (`page.title`; ssqch's own keys, like `url` and `date`, win) and `page.path` and `page.categories`; `site` has the site's own keys, `posts` (newest first), each collection by its tag (`site.articles`), `pages`, `html_pages`, `categories`, `tags`, `data` (the global data) and `time`; and their items read in Jekyll's shape (`post.title`, `post.content`, `post.excerpt`). Off by default: front matter is at the top level (`title`) and items keep it under `data`. */
276
- jekyllTemplates?: boolean;
277
- /** Templates see what MkDocs gives a theme's, so an MkDocs theme's Jinja templates (Material for MkDocs') run as written: `config` (mkdocs.yml, with the theme's `mkdocs_theme.yml` under its `theme`), `nav` (Sections, Pages and Links, with `active` on the page being rendered), `page` in a layout (MkDocs' page: `title`, `url` without its first `/`, `abs_url`, `canonical_url`, `edit_url`, `content`, `toc`, `meta`, `previous_page`, `next_page`, `ancestors`, `is_homepage`), `base_url`, `mkdocs_version` and `build_date_utc`, and the `url` and `script_tag` filters, relative to the page. A Markdown page's layout is `main.html` (or its front matter's `template`), the theme's `404.html` makes `/404.html`, and Jinja doesn't escape (`jinja: { autoescape }` says otherwise). `true` reads `mkdocs.yml`; a string names another file. Off by default. */
278
- mkdocsTemplates?: boolean | string;
279
- /** Jinja's settings for `.jinja` and `.j2` templates. `autoescape: false` prints values as they are, as MkDocs' Jinja does (`| e` still escapes); default `true`, or `false` with `mkdocsTemplates`. `.njk` always escapes. */
297
+ /** Jinja's settings for `.jinja` and `.j2` templates. `autoescape: false` prints values as they are (`| e` still escapes); default `true`, or `false` with `fromMkdocs({ templates: true })`, since MkDocs' Jinja doesn't escape. `.njk` always escapes. */
280
298
  jinja?: { autoescape?: boolean };
281
299
  /** `page.lastModified`: `"git"` for the last commit that changed the page's file (its modification time when it has uncommitted changes), or `"file"` for the modification time. Off by default. Needs the full history in CI (`fetch-depth: 0`). */
282
300
  lastModified?: "git" | "file" | false;
@@ -284,7 +302,9 @@ declare module "ssqch" {
284
302
  dateFallback?: "git" | "file";
285
303
  /** The time zone the site's own JavaScript runs in, as an IANA name (`"UTC"`, `"America/New_York"`): `Date`'s local methods and libraries like luxon and date-fns, in data files, filters, hooks and Edge templates, so a laptop and CI build the same pages. ssqch's own date filters are UTC whatever this says. Default: the machine's. The config's own top-level code runs before it applies. */
286
304
  timeZone?: string;
287
- /** Other names for layouts: `{ post: "layouts/post.njk" }` makes `layout: post` that file (where it would be `_includes/post.*`), as Eleventy's `addLayoutAlias` did. A page's `layout` is still the name it gave. */
305
+ /** A page's URL when it has no `permalink`: `"folders"` (the default) writes `guide/intro.md` as `/guide/intro/` (`guide/intro/index.html`), `"html"` as `/guide/intro.html`. An index page is its folder either way (`guide/index.md` is `/guide/`). (`"html"` is VitePress without `cleanUrls`, Hugo's `uglyURLs` and Docusaurus's `trailingSlash: false`.) */
306
+ urls?: "folders" | "html";
307
+ /** Other names for layouts: `{ post: "layouts/post.njk" }` makes `layout: post` that file (where it would be `_includes/post.*`). A page's `layout` is still the name it gave. (Eleventy's `addLayoutAlias` does the same.) */
288
308
  layoutAliases?: Record<string, string>;
289
309
  /** The path the site is served under, when that isn't the root of its domain: `"/repo/"` for `https://you.github.io/repo/`. Templates and `page.url` stay as they are; ssqch adds the base to URLs from the site's root in the HTML it writes. Use the `withBase()` filter outside HTML attributes. */
290
310
  base?: string;
@@ -533,8 +553,8 @@ declare module "ssqch/sitemap" {
533
553
  import type { BuiltinPlugin } from "ssqch";
534
554
 
535
555
  export interface SitemapPluginOptions {
536
- /** The site's address, like `"https://example.com"`. Without one (or with `""`, as a Jekyll site's `url` often is), each `<loc>` is a path from the site's root, as jekyll-sitemap writes it, and every build warns: search engines read only whole addresses. */
537
- url?: string;
556
+ /** The site's address, like `"https://example.com"`: required, since a sitemap lists whole addresses and search engines read only those. With a `base`, it can be the domain or include the base. */
557
+ url: string;
538
558
  /** URL globs to leave out, like `["/tags/**"]`. Pages with `sitemap: false` and 404 pages are always left out. */
539
559
  exclude?: string[];
540
560
  /** Add `<lastmod>` from each page's date. Default `true`. */
@@ -551,6 +571,102 @@ declare module "ssqch/sitemap" {
551
571
  export function sitemapPlugin(options: SitemapPluginOptions): BuiltinPlugin;
552
572
  }
553
573
 
574
+ declare module "ssqch/from-vitepress" {
575
+ import type { BuiltinPlugin } from "ssqch";
576
+ /** VitePress's Markdown, for a site moving from VitePress, and VitePress's ways for `vuePlugin()`'s components (`useData()` and the rest from "vitepress", `@theme/`, and `./x.data` imports running its data loaders): Vue's `<script>` and `<style>` blocks and `<ClientOnly>` left out, VitePress's markup for headings (`header-anchor`), links (`.html` with `urls: "html"`, external ones in a new tab), code blocks and tables, its `tip`, `info`, `warning`, `danger`, `details`, `raw` and `code-group` containers, `[[toc]]`, and, under the site's own `markdown` options, its heading ids and email autolinks. A site's own hook or container template of the same name replaces VitePress's. Takes no options. */
577
+ export function fromVitepress(): BuiltinPlugin;
578
+ }
579
+
580
+ declare module "ssqch/from-mkdocs" {
581
+ import type { BuiltinPlugin } from "ssqch";
582
+ export interface FromMkdocsOptions {
583
+ /** The mkdocs.yml, from the project root, that `templates` reads. Default `"mkdocs.yml"`. */
584
+ config?: string;
585
+ /** What MkDocs gives a theme's templates, so an MkDocs theme's Jinja (Material for MkDocs') runs as written: `config`, `nav`, `page` (with `content` and `toc` in layouts), `base_url`, the `url` filter, `main.html` (or a page's `template`) as a Markdown page's layout, the theme's `404.html` as the 404 page, and `.jinja` not escaping what it prints, as MkDocs' Jinja doesn't. Default `false`: turn it on once the theme's templates are in the site (`theme: "theme"`). */
586
+ templates?: boolean;
587
+ }
588
+ /** MkDocs' Markdown for a site moving from MkDocs, each a default under the site's own `markdown` options: Python-Markdown's reading (`dialect: "python-markdown"`: raw HTML blocks to their closing tag, lists at four spaces), its toc's heading ids, `!!! note` admonitions and `=== "Tab"` tabs as Material writes them, and `.md` links from the page; and with `templates`, MkDocs' context for a theme's templates. */
589
+ export function fromMkdocs(options?: FromMkdocsOptions): BuiltinPlugin;
590
+ }
591
+
592
+ declare module "ssqch/from-jekyll" {
593
+ import type { BuiltinPlugin } from "ssqch";
594
+ export interface FromJekyllOptions {
595
+ /** Templates see Jekyll's `page` and `site`, so a Jekyll site's layouts and includes run as written: `page` has the page's front matter too (`page.title`; ssqch's own keys, like `url` and `date`, win), `page.path` and `page.categories`; `site` has the site's own keys, `posts` (newest first), each collection by its tag (`site.articles`), `pages`, `html_pages`, `categories`, `tags`, `data` (the global data) and `time`; and items read in Jekyll's shape (`post.title`, `post.content`, `post.excerpt`). Default `true`. */
596
+ templates?: boolean;
597
+ /** kramdown's Markdown, each a default under the site's own `markdown` options: Markdown inside HTML with `markdown="1"` (`htmlMarkdown: "kramdown"`), kramdown's heading ids (`headingIds: "kramdown"`), smart quotes (`smartPunctuation: true`) and no links from bare URLs (`autolinks: false`). Default `true`. */
598
+ kramdown?: boolean;
599
+ }
600
+ /** What a Jekyll site's templates and Markdown expect, for a site moving from Jekyll: Jekyll's `page` and `site` in templates, and kramdown's Markdown. */
601
+ export function fromJekyll(options?: FromJekyllOptions): BuiltinPlugin;
602
+ }
603
+
604
+ declare module "ssqch/from-hugo" {
605
+ import type { BuiltinPlugin } from "ssqch";
606
+ /** Hugo's shortcodes for a site moving from Hugo, as a default under the site's own `markdown` options (`shortcodes: "hugo"`): a shortcode on a line of its own (`{{< note type="tip" >}}` to `{{< /note >}}`, or `{{% %}}`) is a container rendered by `_includes/containers/<name>.*`, with its arguments as `container.props`, and one inside a line of text renders the same template in its place, with `container.inline` true. Takes no options. */
607
+ export function fromHugo(): BuiltinPlugin;
608
+ }
609
+
610
+ declare module "ssqch/vue" {
611
+ import type { BuiltinPlugin } from "ssqch";
612
+ export interface VuePluginOptions {
613
+ /** Components every page can use without importing them, by name: `{ VueSchoolLink: ".vitepress/theme/components/VueSchoolLink.vue" }` (VitePress's `app.component()`), paths from the project's root. A page's own come from its `<script setup>` imports. */
614
+ components?: Record<string, string>;
615
+ /** Vite's root for the build, from the project's root. Default: the input folder (VitePress's `srcDir`), so the components' scope ids are the ones VitePress gave them. */
616
+ root?: string;
617
+ /** Run each component in the browser too, as an island: `"load"` (at once), `"idle"` (when the browser is idle) or `"visible"` (when it scrolls into view). Its server HTML is wrapped in `<ssqch-vue>` and the page gets one script, `/assets/vue/islands.js`. Default `false`: HTML only. */
618
+ hydrate?: false | "load" | "idle" | "visible";
619
+ /** Where the components' styles go: a path like `"/assets/vue.css"` (the default), for the layout to link, or `false`. */
620
+ css?: string | false;
621
+ /** Vite's options to add (`resolve.alias`, more `plugins`), as a Vite config has them. */
622
+ vite?: Record<string, unknown>;
623
+ }
624
+ /** Renders the Vue components a page uses (`<ApiIndex />`, imported in its `<script setup>`) with the site's own Vite, @vitejs/plugin-vue and Vue, at build time; with `hydrate`, as islands in the browser too. */
625
+ export function vuePlugin(options?: VuePluginOptions): BuiltinPlugin;
626
+ }
627
+
628
+ declare module "ssqch/llms" {
629
+ import type { BuiltinPlugin } from "ssqch";
630
+ /** A page as `section` and `sort` get it. */
631
+ export interface LlmsPage { url: string; inputPath: string; outputPath: string; date: Date; data: Record<string, any> }
632
+ export interface LlmsPluginOptions {
633
+ /** The `# heading` of `llms.txt`. Default: `site.title` in the site's data, or the home page's title. */
634
+ title?: string;
635
+ /** A line under it, as `> description`. */
636
+ description?: string;
637
+ /** Markdown after the description, in `llms.txt` and `llms-full.txt`: what a model should know before it reads on, like a list of where else the docs are. */
638
+ details?: string;
639
+ /** The site's address, like `"https://example.com"`, for whole links in `llms.txt` and in every copy. Default: links from the site's root. */
640
+ url?: string;
641
+ /** URL globs of pages to leave out, like `["/blog/**"]`. 404 pages are always left out, and so is a page whose front matter says `llms: false`. */
642
+ exclude?: string[];
643
+ /** A Markdown copy of each listed page beside its URL (`/guide/intro.html` is `/guide/intro.md`, and `/guide/intro/` is `/guide/intro/index.md`, as llms.txt's v2 proposal has them), which `llms.txt` links to. A Markdown page's copy is its Markdown after its template engine ran; another page's is its `<article>`, `<main>` or `<body>` as Markdown. Links in a copy are whole addresses, and a link to a page with a copy goes to the copy. Default `true`; with `false`, `llms.txt` links to the pages. */
644
+ copies?: boolean;
645
+ /** `/llms-full.txt`, every listed page's Markdown in one file, each after a `url:` line. Default `true`. */
646
+ full?: boolean;
647
+ /** A page's section in `llms.txt`: a function that gets each page and returns a name. Default: its first folder (`/guide/...` is "Guide"; the top's pages are "Pages"). Sections are in the order their first page comes. */
648
+ section?: (page: LlmsPage) => string | undefined;
649
+ /** The pages' order, as `Array.prototype.sort` takes it: `(a, b) => a.data.order - b.data.order`. Default: by URL. */
650
+ sort?: (a: LlmsPage, b: LlmsPage) => number;
651
+ }
652
+ /** Writes `/llms.txt` (the site's pages, with links to their Markdown), a Markdown copy of each, and `/llms-full.txt`, for language models, as llmstxt.org describes; and adds the template function `markdownCopy(page.url)`, the URL of a page's copy (or `""` when it has none), for a layout's `<link rel="alternate" type="text/markdown">`. */
653
+ export function llmsPlugin(options?: LlmsPluginOptions): BuiltinPlugin;
654
+ }
655
+
656
+ declare module "ssqch/robots" {
657
+ import type { BuiltinPlugin } from "ssqch";
658
+ export interface RobotsPluginOptions {
659
+ /** What AI crawlers may do, by what they're for: `training` (collecting pages to train models: GPTBot, ClaudeBot, Google-Extended, Applebot-Extended, CCBot, meta-externalagent, Bytespider), `search` (indexing them for an AI search: OAI-SearchBot, Claude-SearchBot, PerplexityBot) and `fetch` (reading a page a person asked about: ChatGPT-User, Claude-User, Perplexity-User, meta-externalfetcher). `false` gives that purpose's crawlers a group with `Disallow: /`. Each defaults to `true`: no group, so they read everyone's. */
660
+ ai?: { training?: boolean; search?: boolean; fetch?: boolean };
661
+ /** URL paths no crawler should read, like `["/drafts/"]`, as `Disallow:` lines in everyone's group. */
662
+ disallow?: string[];
663
+ /** The `Sitemap:` line: by default `sitemapPlugin()`'s address when it's on (none without it); `false` leaves it out; a string is another sitemap's whole address. */
664
+ sitemap?: boolean | string;
665
+ }
666
+ /** Writes `/robots.txt`: the paths no crawler reads, a group for each kind of AI crawler that's turned off, and the sitemap's address. */
667
+ export function robotsPlugin(options?: RobotsPluginOptions): BuiltinPlugin;
668
+ }
669
+
554
670
  declare module "ssqch/elements" {
555
671
  import type { BuiltinPlugin } from "ssqch";
556
672
 
@@ -593,7 +709,7 @@ declare module "ssqch/sass" {
593
709
  style?: "compressed" | "expanded";
594
710
  /** More folders `@use` and `@import` look in, relative to the project root. */
595
711
  loadPaths?: string[];
596
- /** `false` leaves out what CSS with a character outside ASCII starts with: a byte order mark (compressed) or `@charset "UTF-8";` (expanded), as Dart Sass's `--no-charset` does and jekyll-sass-converter's output has it. Default `true`. */
712
+ /** `false` leaves out what CSS with a character outside ASCII starts with: a byte order mark (compressed) or `@charset "UTF-8";` (expanded). Default `true`. (Dart Sass's `--no-charset`; jekyll-sass-converter's CSS has neither.) */
597
713
  charset?: boolean;
598
714
  }
599
715
 
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  layout: layout.edge
3
3
  ---
4
+ <h1>{{ site.title }}</h1>
4
5
  <p>{{ site.description }}</p>
5
6
 
6
7
  <h2>Posts</h2>