ssqch 0.12.0 → 0.13.1

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 (130) hide show
  1. package/bundled/completions/bash +66 -8
  2. package/bundled/completions/elvish +23 -4
  3. package/bundled/completions/fish +36 -25
  4. package/bundled/completions/powershell +25 -4
  5. package/bundled/completions/zsh +44 -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 +2 -2
  9. package/bundled/docs/configuring.md +3 -6
  10. package/bundled/docs/deploying.md +1 -1
  11. package/bundled/docs/field-guide.md +4 -4
  12. package/bundled/docs/github-pages.md +1 -0
  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 +8 -12
  17. package/bundled/docs/nav.yml +5 -1
  18. package/bundled/docs/netlify.md +4 -2
  19. package/bundled/docs/patrol.md +48 -0
  20. package/bundled/docs/plugins.md +6 -6
  21. package/bundled/docs/robots.md +85 -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 +1 -1
  25. package/bundled/docs/templates.md +1 -1
  26. package/bundled/docs/trailheads/from-hugo.md +5 -3
  27. package/bundled/docs/trailheads/from-jekyll.md +54 -13
  28. package/bundled/docs/trailheads/from-mkdocs.md +15 -12
  29. package/bundled/docs/trailheads/from-vitepress.md +13 -11
  30. package/bundled/docs/trailheads.md +3 -3
  31. package/bundled/docs/where-values-come-from.md +5 -5
  32. package/bundled/docs/writing-plugins.md +69 -0
  33. package/bundled/ssqch.d.ts +118 -44
  34. package/bundled/starter/engines/index.edge +1 -0
  35. package/bundled/starter/engines/index.ejs +1 -0
  36. package/bundled/starter/engines/index.hbs +1 -0
  37. package/bundled/starter/engines/index.liquid +1 -0
  38. package/bundled/starter/engines/layout.edge +7 -0
  39. package/bundled/starter/engines/layout.ejs +4 -0
  40. package/bundled/starter/engines/layout.hbs +4 -0
  41. package/bundled/starter/engines/layout.liquid +4 -0
  42. package/bundled/starter/src/_data/site.json +1 -0
  43. package/bundled/starter/src/_includes/layout.jinja +4 -0
  44. package/bundled/starter/src/index.jinja +1 -0
  45. package/bundled/starter/ssqch.config.js +14 -1
  46. package/bundled/starter-docs/engines/edge/base.edge +7 -0
  47. package/bundled/starter-docs/engines/edge/doc.edge +4 -0
  48. package/bundled/starter-docs/engines/ejs/base.ejs +4 -0
  49. package/bundled/starter-docs/engines/ejs/doc.ejs +4 -0
  50. package/bundled/starter-docs/engines/hbs/base.hbs +4 -0
  51. package/bundled/starter-docs/engines/hbs/doc.hbs +3 -0
  52. package/bundled/starter-docs/engines/liquid/base.liquid +4 -0
  53. package/bundled/starter-docs/engines/liquid/doc.liquid +4 -0
  54. package/bundled/starter-docs/src/_data/site.json +1 -0
  55. package/bundled/starter-docs/src/_includes/base.jinja +4 -0
  56. package/bundled/starter-docs/src/_includes/doc.jinja +4 -0
  57. package/bundled/starter-docs/src/assets/docs.css +4 -0
  58. package/bundled/starter-docs/src/assets/docs.js +17 -0
  59. package/bundled/starter-docs/ssqch.config.js +14 -1
  60. package/lib/assets.js +9 -9
  61. package/lib/chunk-25WERNDD.js +112 -0
  62. package/lib/{chunk-4ZMNLWE4.js → chunk-2BJFGKOE.js} +2 -2
  63. package/lib/{chunk-M2BBE2C3.js → chunk-3ZTRIO6O.js} +18 -17
  64. package/lib/{chunk-57HLSKZS.js → chunk-4AZFCSGJ.js} +2 -2
  65. package/lib/{chunk-ULQHJ4TS.js → chunk-55WXDGO4.js} +3 -3
  66. package/lib/{chunk-JX43SJHU.js → chunk-6FY77I4M.js} +24 -22
  67. package/lib/{chunk-RY3KLUQ3.js → chunk-6OUCRDYI.js} +267 -202
  68. package/lib/{chunk-EVFNYUTR.js → chunk-6U5VIQVY.js} +5 -5
  69. package/lib/{chunk-N3IZ44XY.js → chunk-7U5GWTEH.js} +88 -54
  70. package/lib/{chunk-VTYQ3JKL.js → chunk-AIJNG6MJ.js} +2 -2
  71. package/lib/{chunk-IIBZPHAW.js → chunk-C2Q7JKFI.js} +8 -8
  72. package/lib/{chunk-6CSH757V.js → chunk-DFJFHULZ.js} +33 -8
  73. package/lib/{chunk-XVV7JJK7.js → chunk-ENWDM2RW.js} +40 -39
  74. package/lib/{chunk-JUALMFW3.js → chunk-ER72RPD6.js} +1 -1
  75. package/lib/{chunk-RFREB3SI.js → chunk-F3JPNFCZ.js} +7 -7
  76. package/lib/{chunk-LLOA3QXV.js → chunk-FENJHLNM.js} +3 -2
  77. package/lib/{chunk-UU43WIZG.js → chunk-FJML7INB.js} +4 -2
  78. package/lib/{chunk-IZCF4UH3.js → chunk-FQZDUDFK.js} +1 -1
  79. package/lib/chunk-GM5SHCTU.js +272 -0
  80. package/lib/{chunk-GVHQ37JE.js → chunk-GSNRAGKQ.js} +10 -5
  81. package/lib/{chunk-L2IY4P6O.js → chunk-GU7BBYWB.js} +3 -3
  82. package/lib/{chunk-RGYJQYW3.js → chunk-HDKU6LRI.js} +32 -5
  83. package/lib/{chunk-IQUGLVZY.js → chunk-K5WZ2VYK.js} +4 -4
  84. package/lib/{chunk-JVT5ZRRH.js → chunk-OOKBXQAY.js} +5 -5
  85. package/lib/{chunk-MOLTDO5A.js → chunk-SNQOHNXE.js} +1 -1
  86. package/lib/{chunk-Z3XH4KWX.js → chunk-SPIFZBIW.js} +1 -1
  87. package/lib/{chunk-FNNXRVSU.js → chunk-T5IUI7W7.js} +10 -10
  88. package/lib/{chunk-5HEZ3WUQ.js → chunk-TGSVSG2G.js} +2 -2
  89. package/lib/{chunk-3GROJ3TY.js → chunk-U2KEMVXO.js} +24 -17
  90. package/lib/{chunk-4B3N44SN.js → chunk-UHRBPZ4A.js} +3 -3
  91. package/lib/{chunk-GWWA5Y3X.js → chunk-ULCT3PAV.js} +1 -1
  92. package/lib/{chunk-7RGEWDLF.js → chunk-UZNUS7RP.js} +10 -8
  93. package/lib/{chunk-DZ5F5XSI.js → chunk-V3G2QGL3.js} +10 -105
  94. package/lib/{chunk-DOHOKUGB.js → chunk-VILOEVK7.js} +50 -26
  95. package/lib/{chunk-DXMDXHV7.js → chunk-WGAIE3DD.js} +15 -14
  96. package/lib/{chunk-G3RFQDKO.js → chunk-WUCRAV36.js} +8 -6
  97. package/lib/{chunk-52ROOMBZ.js → chunk-XYAWJTHM.js} +9 -9
  98. package/lib/{chunk-L3K7MMFC.js → chunk-YA23NDMW.js} +2 -2
  99. package/lib/{chunk-R7PBREXL.js → chunk-YNJNMQWU.js} +8 -5
  100. package/lib/{chunk-AK7ZKSZP.js → chunk-ZMG25MXF.js} +17 -16
  101. package/lib/cli.js +56 -34
  102. package/lib/elements.js +9 -9
  103. package/lib/from-hugo.js +36 -0
  104. package/lib/from-jekyll.js +41 -0
  105. package/lib/from-mkdocs.js +49 -0
  106. package/lib/from-vitepress.js +49 -0
  107. package/lib/image.js +10 -10
  108. package/lib/links.js +9 -9
  109. package/lib/llms.js +619 -54
  110. package/lib/minify.js +10 -10
  111. package/lib/redirects.js +9 -9
  112. package/lib/robots.js +87 -0
  113. package/lib/rss.js +22 -12
  114. package/lib/sass.js +10 -10
  115. package/lib/sitemap.js +22 -33
  116. package/lib/ssqch.js +5 -5
  117. package/lib/vue.js +14 -13
  118. package/package.json +21 -1
  119. package/types/from-hugo.d.ts +5 -0
  120. package/types/from-jekyll.d.ts +11 -0
  121. package/types/from-mkdocs.d.ts +11 -0
  122. package/types/from-vitepress.d.ts +5 -0
  123. package/types/index.d.ts +45 -29
  124. package/types/llms.d.ts +18 -8
  125. package/types/robots.d.ts +13 -0
  126. package/types/sass.d.ts +1 -1
  127. package/types/sitemap.d.ts +3 -5
  128. package/wasm/markdown.wasm +0 -0
  129. /package/lib/{chunk-JX43SJHU.js.LEGAL.txt → chunk-6FY77I4M.js.LEGAL.txt} +0 -0
  130. /package/lib/{chunk-R7PBREXL.js.LEGAL.txt → chunk-YNJNMQWU.js.LEGAL.txt} +0 -0
@@ -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)).
@@ -85,35 +85,23 @@ declare module "ssqch" {
85
85
  taskLists?: boolean;
86
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
87
  autolinks?: boolean | "fuzzy" | "email";
88
- /** A single newline inside a paragraph (or a list item) becomes a `<br>`, as markdown-it's `breaks: true` makes it. Default `false`. */
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.*`. A container closes inside the block it opened in (a list item's closes in that item). `"markdown-it"` reads them as markdown-it-container (and VitePress) does: a closing `:::` indented less than four spaces closes the innermost open container, so Prettier's `:::` indented under the list it ends works. Default `true`. */
95
- containers?: boolean | "markdown-it";
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
+ containers?: boolean;
96
96
  /** A term, then `: definition` lines. Default `false`. */
97
97
  definitionLists?: boolean;
98
98
  /** Curly quotes, dashes and ellipses. Default `false`. */
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. One inside a line of text renders through the same template in its place, with `container.inline` true (one with no template 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`. `"vitepress"`: Markdown as VitePress reads and writes it: Vue's `<script>`, `<style>` and `<ClientOnly>` left out, `-vue` fences, `[[toc]]`, and VitePress's markup for headings, links, code blocks, tables and the `tip`, `info`, `warning`, `danger`, `details`, `raw` and `code-group` containers, as built-in hooks a site's own templates replace; with `headingIds: "vitepress"`, `autolinks: "email"` and `containers: "markdown-it"` unless set. */
116
- dialect?: "python-markdown" | "vitepress" | false;
117
105
  highlight?: boolean | { css?: string | false; languages?: Record<string, Highlighter>; classes?: "prism" | "pygments" | "chroma" | Partial<Record<TokenKind, string>> };
118
106
  }
119
107
 
@@ -231,11 +219,47 @@ declare module "ssqch" {
231
219
  plugins?: Plugin[];
232
220
  }
233
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
+
234
258
  export type Plugin =
235
- | ConfigParts
259
+ | PluginParts
236
260
  | BuiltinPlugin
237
261
  | RustPlugin
238
- | ((context: ConfigContext) => MaybePromise<ConfigParts | BuiltinPlugin | RustPlugin | false | null | undefined>)
262
+ | ((context: ConfigContext) => MaybePromise<PluginParts | BuiltinPlugin | RustPlugin | false | null | undefined>)
239
263
  | false
240
264
  | null
241
265
  | undefined;
@@ -264,21 +288,13 @@ declare module "ssqch" {
264
288
  deepMerge?: boolean;
265
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`. */
266
290
  leaveNoTrace?: boolean;
267
- /** Another name for `leaveNoTrace`. Set one of them. */
268
- clean?: boolean;
269
291
  /** Globs (relative to the input folder) of files that aren't pages, like `["drafts/**", "notes/*.wip.md"]`. */
270
292
  ignore?: string | string[];
271
293
  /** Page bundles: copy the other files in a folder whose page is `index.*` (images, downloads) next to the page. Default `false`. */
272
294
  bundles?: boolean;
273
295
  /** Printing an undefined value (`{{ titel }}`) is an error, in every template language. Conditionals and defaults still work. Default `false`. */
274
296
  strict?: boolean;
275
- /** 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. */
276
- trimAfterFrontMatter?: boolean;
277
- /** 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`. */
278
- jekyllTemplates?: boolean;
279
- /** 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. */
280
- mkdocsTemplates?: boolean | string;
281
- /** 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. */
282
298
  jinja?: { autoescape?: boolean };
283
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`). */
284
300
  lastModified?: "git" | "file" | false;
@@ -286,9 +302,9 @@ declare module "ssqch" {
286
302
  dateFallback?: "git" | "file";
287
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. */
288
304
  timeZone?: string;
289
- /** 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`, as VitePress without `cleanUrls`, Hugo's `uglyURLs` and Docusaurus's `trailingSlash: false` do. An index page is its folder either way (`guide/index.md` is `/guide/`). */
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`.) */
290
306
  urls?: "folders" | "html";
291
- /** 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. */
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.) */
292
308
  layoutAliases?: Record<string, string>;
293
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. */
294
310
  base?: string;
@@ -537,14 +553,12 @@ declare module "ssqch/sitemap" {
537
553
  import type { BuiltinPlugin } from "ssqch";
538
554
 
539
555
  export interface SitemapPluginOptions {
540
- /** 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. */
541
- 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;
542
558
  /** URL globs to leave out, like `["/tags/**"]`. Pages with `sitemap: false` and 404 pages are always left out. */
543
559
  exclude?: string[];
544
- /** Add `<lastmod>` from each page's date. Default `true` (`false` with `format: "vitepress"`). */
560
+ /** Add `<lastmod>` from each page's date. Default `true`. */
545
561
  lastmod?: boolean;
546
- /** How the file is written: `"ssqch"` (the default: one tag per line, pages by URL) or `"vitepress"`, the sitemap VitePress's `sitemap` option writes (one line, its five namespaces, pages in the order of their files, no `<lastmod>` unless `lastmod: true`), so a move from VitePress compares byte for byte. */
547
- format?: "ssqch" | "vitepress";
548
562
  /** Where to write it. Default `"/sitemap.xml"`. */
549
563
  output?: string;
550
564
  /** List every page of a list split into pages (`/2/`, `/3/`), not just the first. Pagination with `size: 1` (a page per tag, say) is always listed. Default `false`. */
@@ -557,6 +571,42 @@ declare module "ssqch/sitemap" {
557
571
  export function sitemapPlugin(options: SitemapPluginOptions): BuiltinPlugin;
558
572
  }
559
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
+
560
610
  declare module "ssqch/vue" {
561
611
  import type { BuiltinPlugin } from "ssqch";
562
612
  export interface VuePluginOptions {
@@ -577,28 +627,52 @@ declare module "ssqch/vue" {
577
627
 
578
628
  declare module "ssqch/llms" {
579
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> }
580
632
  export interface LlmsPluginOptions {
581
633
  /** The `# heading` of `llms.txt`. Default: `site.title` in the site's data, or the home page's title. */
582
634
  title?: string;
583
635
  /** A line under it, as `> description`. */
584
636
  description?: string;
585
- /** The site's address, like `"https://example.com"`, for whole links. Default: links from the site's root. */
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. */
586
640
  url?: string;
587
- /** URL globs of pages to leave out, like `["/blog/**"]`. 404 pages are always left out. */
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`. */
588
642
  exclude?: string[];
589
- /** A Markdown copy of each listed page beside its URL (`/guide/intro.html` and `/guide/intro.md`; `/guide/` is `/guide.md`), which `llms.txt` links to. Default `true`; with `false`, it links to the pages. */
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. */
590
644
  copies?: boolean;
591
645
  /** `/llms-full.txt`, every listed page's Markdown in one file, each after a `url:` line. Default `true`. */
592
646
  full?: boolean;
593
- /** A hidden `<div hidden aria-hidden="true">` at the top of each listed page's `<body>`, naming its Markdown copy, for a model that reads the HTML. Default `false`: a build adds no markup of its own unless asked. */
594
- hint?: boolean;
595
- /** 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"). */
596
- section?: (page: { url: string; inputPath: string; outputPath: string; date: Date; data: Record<string, any> }) => string | undefined;
597
- }
598
- /** Writes `/llms.txt` (the pages that came from Markdown, with links to their Markdown), a Markdown copy of each, and `/llms-full.txt`, for language models, as llmstxt.org describes. */
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, with "Optional" (links an agent can skip) last. Inside a file of `paths`, the default is the page's folder under that path. */
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
+ /** Parts of the site with an `llms.txt` of their own, as llms.txt's v2 has them: `["/docs/"]` writes `/docs/llms.txt` with the pages under `/docs/`, and `/llms.txt` lists that file in their place. An item is a URL path that starts and ends with `/`, or an object with its `path` and the file's `title` (its heading; default the site's title and the folder's name), `description` and `details`. A page belongs to the deepest path it's under. A path with no listed pages writes no file, and the build warns. */
652
+ paths?: Array<string | LlmsPath>;
653
+ /** The most characters an `llms.txt` has: past it, pages from the end move into "Optional" without their descriptions until it fits. A file that wouldn't fit even so stays as it is, and the build warns. Default `50000` (where `ssqch patrol` warns); `false` for no limit. */
654
+ budget?: number | false;
655
+ }
656
+ /** A part of the site with an `llms.txt` of its own, in `paths`. */
657
+ export interface LlmsPath { path: string; title?: string; description?: string; details?: string }
658
+ /** 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 functions `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">`, and `llmsTxt(page.url)`, the `llms.txt` that covers the page, for its `<link rel="describedby">`. */
599
659
  export function llmsPlugin(options?: LlmsPluginOptions): BuiltinPlugin;
600
660
  }
601
661
 
662
+ declare module "ssqch/robots" {
663
+ import type { BuiltinPlugin } from "ssqch";
664
+ export interface RobotsPluginOptions {
665
+ /** 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. */
666
+ ai?: { training?: boolean; search?: boolean; fetch?: boolean };
667
+ /** URL paths no crawler should read, like `["/drafts/"]`, as `Disallow:` lines in everyone's group. */
668
+ disallow?: string[];
669
+ /** 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. */
670
+ sitemap?: boolean | string;
671
+ }
672
+ /** 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. */
673
+ export function robotsPlugin(options?: RobotsPluginOptions): BuiltinPlugin;
674
+ }
675
+
602
676
  declare module "ssqch/elements" {
603
677
  import type { BuiltinPlugin } from "ssqch";
604
678
 
@@ -641,7 +715,7 @@ declare module "ssqch/sass" {
641
715
  style?: "compressed" | "expanded";
642
716
  /** More folders `@use` and `@import` look in, relative to the project root. */
643
717
  loadPaths?: string[];
644
- /** `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`. */
718
+ /** `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.) */
645
719
  charset?: boolean;
646
720
  }
647
721
 
@@ -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>
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  layout: layout.jinja
3
3
  ---
4
+ <h1><%= site.title %></h1>
4
5
  <p><%= site.description %></p>
5
6
 
6
7
  <h2>Posts</h2>
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  layout: layout.hbs
3
3
  ---
4
+ <h1>{{site.title}}</h1>
4
5
  <p>{{site.description}}</p>
5
6
 
6
7
  <h2>Posts</h2>
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  layout: layout.liquid
3
3
  ---
4
+ <h1>{{ site.title }}</h1>
4
5
  <p>{{ site.description }}</p>
5
6
 
6
7
  <h2>Posts</h2>
@@ -5,6 +5,13 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title>{{ title ? `${title} | ${site.title}` : site.title }}</title>
7
7
  <meta name="description" content="{{ description || site.description }}">
8
+ <link rel="canonical" href="{{ site.url }}{{ page.url }}">
9
+ {{-- For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). --}}
10
+ @let(copy = markdownCopy(page.url))
11
+ @if(copy)
12
+ <link rel="alternate" type="text/markdown" href="{{ copy }}">
13
+ @end
14
+ <link rel="describedby" href="/llms.txt">
8
15
  <style>
9
16
  /* Ranger Station '76: soft white (or green charcoal in dark mode), neutral text, pine
10
17
  headings, burnt orange links, and a four-color stripe under the header. */
@@ -5,6 +5,10 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title><% if (locals.title) { %><%= title %> | <% } %><%= site.title %></title>
7
7
  <meta name="description" content="<%= locals.description || site.description %>">
8
+ <link rel="canonical" href="<%= site.url %><%= page.url %>">
9
+ <%# For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). %>
10
+ <% const copy = markdownCopy(page.url); if (copy) { %><link rel="alternate" type="text/markdown" href="<%= copy %>"><% } %>
11
+ <link rel="describedby" href="/llms.txt">
8
12
  <style>
9
13
  /* Ranger Station '76: soft white (or green charcoal in dark mode), neutral text, pine
10
14
  headings, burnt orange links, and a four-color stripe under the header. */
@@ -5,6 +5,10 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title>{{#if title}}{{title}} | {{/if}}{{site.title}}</title>
7
7
  <meta name="description" content="{{#if description}}{{description}}{{else}}{{site.description}}{{/if}}">
8
+ <link rel="canonical" href="{{site.url}}{{page.url}}">
9
+ {{!-- For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). --}}
10
+ {{#with (markdownCopy page.url)}}<link rel="alternate" type="text/markdown" href="{{this}}">{{/with}}
11
+ <link rel="describedby" href="/llms.txt">
8
12
  <style>
9
13
  /* Ranger Station '76: soft white (or green charcoal in dark mode), neutral text, pine
10
14
  headings, burnt orange links, and a four-color stripe under the header. */
@@ -5,6 +5,10 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title>{% if title %}{{ title }} | {% endif %}{{ site.title }}</title>
7
7
  <meta name="description" content="{{ description | default: site.description }}">
8
+ <link rel="canonical" href="{{ site.url }}{{ page.url }}">
9
+ {% comment %} For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). {% endcomment %}
10
+ {% assign copy = page.url | markdownCopy %}{% if copy != "" %}<link rel="alternate" type="text/markdown" href="{{ copy }}">{% endif %}
11
+ <link rel="describedby" href="/llms.txt">
8
12
  <style>
9
13
  /* Ranger Station '76: soft white (or green charcoal in dark mode), neutral text, pine
10
14
  headings, burnt orange links, and a four-color stripe under the header. */
@@ -1,4 +1,5 @@
1
1
  {
2
2
  "title": "Field Notes",
3
+ "url": "https://example.com",
3
4
  "description": "An amateur investigation, with corrections. Built with SiteSquatch."
4
5
  }
@@ -5,6 +5,10 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title>{% if title %}{{ title }} | {% endif %}{{ site.title }}</title>
7
7
  <meta name="description" content="{{ description or site.description }}">
8
+ <link rel="canonical" href="{{ site.url }}{{ page.url }}">
9
+ {# For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). #}
10
+ {% if markdownCopy(page.url) %}<link rel="alternate" type="text/markdown" href="{{ markdownCopy(page.url) }}">{% endif %}
11
+ <link rel="describedby" href="/llms.txt">
8
12
  <style>
9
13
  /* Ranger Station '76: soft white (or green charcoal in dark mode), neutral text, pine
10
14
  headings, burnt orange links, and a four-color stripe under the header. */
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  layout: layout.jinja
3
3
  ---
4
+ <h1>{{ site.title }}</h1>
4
5
  <p>{{ site.description }}</p>
5
6
 
6
7
  <h2>Posts</h2>
@@ -1,9 +1,15 @@
1
1
  // The site's config. `ssqch build` builds it into dist/, and `ssqch serve`
2
2
  // serves it with live reload. ssqch.d.ts gives your editor the types.
3
- import { defineConfig } from "ssqch";
3
+ import { defineConfig, readData } from "ssqch";
4
4
  import { imagePlugin } from "ssqch/image";
5
5
  import { linksPlugin } from "ssqch/links";
6
+ import { llmsPlugin } from "ssqch/llms";
6
7
  import { minifyPlugin } from "ssqch/minify";
8
+ import { robotsPlugin } from "ssqch/robots";
9
+ import { sitemapPlugin } from "ssqch/sitemap";
10
+
11
+ // The site's address, from src/_data/site.json: put yours there.
12
+ const { url } = readData("src/_data/site.json");
7
13
 
8
14
  export default defineConfig(({ env }) => ({
9
15
  dirs: { input: "src", output: "dist" },
@@ -24,6 +30,13 @@ export default defineConfig(({ env }) => ({
24
30
  imagePlugin({ formats: ["webp", "auto"], widths: [400, 800, 1200] }),
25
31
  // Broken internal links fail a production build.
26
32
  linksPlugin(),
33
+ // What crawlers and agents read: sitemap.xml, robots.txt, and llms.txt with a
34
+ // Markdown copy of each page. `ssqch patrol` checks them after a build.
35
+ sitemapPlugin({ url }),
36
+ // `false` keeps that kind of AI crawler out: training (collecting pages to train
37
+ // models), search (AI search answers) or fetch (a page a person asked about).
38
+ robotsPlugin({ ai: { training: true, search: true, fetch: true } }),
39
+ llmsPlugin({ url }),
27
40
  env === "production" && minifyPlugin(),
28
41
  ],
29
42
  }));
@@ -5,6 +5,13 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title>{{ title ? title + ' | ' : '' }}{{ site.name }}</title>
7
7
  <meta name="description" content="{{ description || site.description }}">
8
+ <link rel="canonical" href="{{ site.url }}{{ page.url }}">
9
+ {{-- For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). --}}
10
+ @let(copy = markdownCopy(page.url))
11
+ @if(copy)
12
+ <link rel="alternate" type="text/markdown" href="{{ copy }}">
13
+ @end
14
+ <link rel="describedby" href="/llms.txt">
8
15
  <meta name="generator" content="{{ ssqch.generator }}">
9
16
  <link rel="stylesheet" href="/highlight.css">
10
17
  <link rel="stylesheet" href="/assets/docs.css">
@@ -17,6 +17,10 @@ sidebar: true
17
17
  {{{ content }}}
18
18
 
19
19
  <footer class="page-footer">
20
+ @let(copy = markdownCopy(page.url))
21
+ @if(copy)
22
+ <p class="page-markdown"><a href="{{ copy }}">View as Markdown</a> <button type="button" data-copy-markdown="{{ copy }}" hidden>Copy as Markdown</button></p>
23
+ @end
20
24
  @if(site.editUrl)
21
25
  <p><a href="{{ site.editUrl }}{{ page.inputPath.replace('./', '') }}">Edit this page</a></p>
22
26
  @end
@@ -5,6 +5,10 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title><% if (locals.title) { %><%= title %> | <% } %><%= site.name %></title>
7
7
  <meta name="description" content="<%= locals.description || site.description %>">
8
+ <link rel="canonical" href="<%= site.url %><%= page.url %>">
9
+ <%# For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). %>
10
+ <% const copy = markdownCopy(page.url); if (copy) { %><link rel="alternate" type="text/markdown" href="<%= copy %>"><% } %>
11
+ <link rel="describedby" href="/llms.txt">
8
12
  <meta name="generator" content="<%= ssqch.generator %>">
9
13
  <link rel="stylesheet" href="/highlight.css">
10
14
  <link rel="stylesheet" href="/assets/docs.css">
@@ -17,6 +17,10 @@ sidebar: true
17
17
  <%- content %>
18
18
 
19
19
  <footer class="page-footer">
20
+ <%_ const copy = markdownCopy(page.url); _%>
21
+ <%_ if (copy) { _%>
22
+ <p class="page-markdown"><a href="<%= copy %>">View as Markdown</a> <button type="button" data-copy-markdown="<%= copy %>" hidden>Copy as Markdown</button></p>
23
+ <%_ } _%>
20
24
  <%_ if (site.editUrl) { _%>
21
25
  <p><a href="<%= site.editUrl %><%= page.inputPath.replace("./", "") %>">Edit this page</a></p>
22
26
  <%_ } _%>
@@ -5,6 +5,10 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title>{{#if title}}{{title}} | {{/if}}{{site.name}}</title>
7
7
  <meta name="description" content="{{#if description}}{{description}}{{else}}{{site.description}}{{/if}}">
8
+ <link rel="canonical" href="{{site.url}}{{page.url}}">
9
+ {{!-- For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). --}}
10
+ {{#with (markdownCopy page.url)}}<link rel="alternate" type="text/markdown" href="{{this}}">{{/with}}
11
+ <link rel="describedby" href="/llms.txt">
8
12
  <meta name="generator" content="{{ssqch.generator}}">
9
13
  <link rel="stylesheet" href="/highlight.css">
10
14
  <link rel="stylesheet" href="/assets/docs.css">
@@ -16,6 +16,9 @@ sidebar: true
16
16
  {{{content}}}
17
17
 
18
18
  <footer class="page-footer">
19
+ {{#with (markdownCopy page.url)}}
20
+ <p class="page-markdown"><a href="{{this}}">View as Markdown</a> <button type="button" data-copy-markdown="{{this}}" hidden>Copy as Markdown</button></p>
21
+ {{/with}}
19
22
  {{#if site.editUrl}}
20
23
  <p><a href="{{site.editUrl}}{{sourcePath page.inputPath}}">Edit this page</a></p>
21
24
  {{/if}}
@@ -5,6 +5,10 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <title>{% if title and title != "" %}{{ title }} | {% endif %}{{ site.name }}</title>
7
7
  <meta name="description" content="{{ description | default: site.description }}">
8
+ <link rel="canonical" href="{{ site.url }}{{ page.url }}">
9
+ {% comment %} For agents: the page as Markdown and the site's map (llmsPlugin() in ssqch.config.js). {% endcomment %}
10
+ {% assign copy = page.url | markdownCopy %}{% if copy != "" %}<link rel="alternate" type="text/markdown" href="{{ copy }}">{% endif %}
11
+ <link rel="describedby" href="/llms.txt">
8
12
  <meta name="generator" content="{{ ssqch.generator }}">
9
13
  <link rel="stylesheet" href="/highlight.css">
10
14
  <link rel="stylesheet" href="/assets/docs.css">
@@ -17,6 +17,10 @@ sidebar: true
17
17
  {{ content }}
18
18
 
19
19
  <footer class="page-footer">
20
+ {% assign copy = page.url | markdownCopy %}
21
+ {% if copy != "" %}
22
+ <p class="page-markdown"><a href="{{ copy }}">View as Markdown</a> <button type="button" data-copy-markdown="{{ copy }}" hidden>Copy as Markdown</button></p>
23
+ {% endif %}
20
24
  {% if site.editUrl and site.editUrl != "" %}
21
25
  <p><a href="{{ site.editUrl }}{{ page.inputPath | replace_first: './', '' }}">Edit this page</a></p>
22
26
  {% endif %}
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "name": "Squatch Docs",
3
+ "url": "https://example.com",
3
4
  "description": "Documentation built with SiteSquatch.",
4
5
  "editUrl": ""
5
6
  }