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
package/types/index.d.ts CHANGED
@@ -62,35 +62,23 @@ export interface MarkdownOptions {
62
62
  taskLists?: boolean;
63
63
  /** 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`. */
64
64
  autolinks?: boolean | "fuzzy" | "email";
65
- /** A single newline inside a paragraph (or a list item) becomes a `<br>`, as markdown-it's `breaks: true` makes it. Default `false`. */
65
+ /** A single newline inside a paragraph (or a list item) becomes a `<br>`. Default `false`. (markdown-it's `breaks: true` writes the same.) */
66
66
  breaks?: boolean;
67
- /** 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`. */
67
+ /** 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.) */
68
68
  figures?: boolean;
69
69
  /** GitHub's `> [!NOTE]` alerts: note, tip, important, warning and caution. Default `true`. */
70
70
  alerts?: boolean;
71
- /** `::: 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`. */
72
- containers?: boolean | "markdown-it";
71
+ /** `::: 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`. */
72
+ containers?: boolean;
73
73
  /** A term, then `: definition` lines. Default `false`. */
74
74
  definitionLists?: boolean;
75
75
  /** Curly quotes, dashes and ellipses. Default `false`. */
76
76
  smartPunctuation?: boolean;
77
77
  /** Lines indented four spaces are code blocks. `false` renders them as ordinary Markdown (HTML indented inside Markdown, say); fences are still code. Default `true`. */
78
78
  indentedCode?: boolean;
79
- /** 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`. */
80
- encodeUrls?: boolean;
81
79
  /** 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`. */
82
- /** 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. */
83
- htmlMarkdown?: "kramdown" | false;
84
- /** 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`. */
85
- admonitions?: "mkdocs" | false;
86
- /** 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`. */
87
- tabs?: "mkdocs" | false;
88
- /** 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`. */
89
- shortcodes?: "hugo" | false;
90
80
  /** 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`. */
91
81
  sourceLinks?: boolean | "relative";
92
- /** 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. */
93
- dialect?: "python-markdown" | "vitepress" | false;
94
82
  highlight?: boolean | { css?: string | false; languages?: Record<string, Highlighter>; classes?: "prism" | "pygments" | "chroma" | Partial<Record<TokenKind, string>> };
95
83
  }
96
84
 
@@ -208,11 +196,47 @@ export interface ConfigParts {
208
196
  plugins?: Plugin[];
209
197
  }
210
198
 
199
+ /** What a plugin's Markdown steps and hooks get besides their text. */
200
+ export interface MarkdownStepContext {
201
+ /** The page's data, as its templates see it. */
202
+ data: Record<string, any>;
203
+ /** The page (`data.page`): `url`, `inputPath` and the rest. */
204
+ page: Record<string, any> | undefined;
205
+ /** The site's `urls`: `"html"` when pages are `/guide/intro.html`. */
206
+ urls: "folders" | "html";
207
+ /** Markdown rendered with the site's options and hooks; `{ inline: true }` leaves out the `<p>`. */
208
+ markdown(text: string, options?: { inline?: boolean }): string;
209
+ /** Whether the site or a plugin has the render hook or container `name` (`"heading"`, `"containers/tip"`). */
210
+ hasHook(name: string): boolean;
211
+ /** 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. */
212
+ renderHook(name: string, key: string, value: Record<string, any>): string;
213
+ }
214
+
215
+ /** A plugin's own steps in ssqch's Markdown. Each answers at once with text. */
216
+ export interface PluginMarkdown {
217
+ /** 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`. */
218
+ before?: (source: string, context: MarkdownStepContext) => string;
219
+ /** The HTML ssqch's Markdown wrote for the page, before its layouts. */
220
+ after?: (html: string, context: MarkdownStepContext) => string;
221
+ /** 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. */
222
+ hooks?: Record<string, (value: Record<string, any>, context: MarkdownStepContext) => string>;
223
+ }
224
+
225
+ /** A plugin: the config's parts, and what only a plugin can give. */
226
+ export interface PluginParts extends ConfigParts {
227
+ /** The plugin's name, for its errors. */
228
+ name?: string;
229
+ /** Steps in ssqch's Markdown, and render hooks as functions. */
230
+ markdown?: PluginMarkdown;
231
+ /** 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. */
232
+ defaults?: { markdown?: MarkdownOptions };
233
+ }
234
+
211
235
  export type Plugin =
212
- | ConfigParts
236
+ | PluginParts
213
237
  | BuiltinPlugin
214
238
  | RustPlugin
215
- | ((context: ConfigContext) => MaybePromise<ConfigParts | BuiltinPlugin | RustPlugin | false | null | undefined>)
239
+ | ((context: ConfigContext) => MaybePromise<PluginParts | BuiltinPlugin | RustPlugin | false | null | undefined>)
216
240
  | false
217
241
  | null
218
242
  | undefined;
@@ -241,21 +265,13 @@ export interface Config extends ConfigParts {
241
265
  deepMerge?: boolean;
242
266
  /** 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`. */
243
267
  leaveNoTrace?: boolean;
244
- /** Another name for `leaveNoTrace`. Set one of them. */
245
- clean?: boolean;
246
268
  /** Globs (relative to the input folder) of files that aren't pages, like `["drafts/**", "notes/*.wip.md"]`. */
247
269
  ignore?: string | string[];
248
270
  /** Page bundles: copy the other files in a folder whose page is `index.*` (images, downloads) next to the page. Default `false`. */
249
271
  bundles?: boolean;
250
272
  /** Printing an undefined value (`{{ titel }}`) is an error, in every template language. Conditionals and defaults still work. Default `false`. */
251
273
  strict?: boolean;
252
- /** 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. */
253
- trimAfterFrontMatter?: boolean;
254
- /** 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`. */
255
- jekyllTemplates?: boolean;
256
- /** 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. */
257
- mkdocsTemplates?: boolean | string;
258
- /** 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. */
274
+ /** 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. */
259
275
  jinja?: { autoescape?: boolean };
260
276
  /** `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`). */
261
277
  lastModified?: "git" | "file" | false;
@@ -263,9 +279,9 @@ export interface Config extends ConfigParts {
263
279
  dateFallback?: "git" | "file";
264
280
  /** 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. */
265
281
  timeZone?: string;
266
- /** 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/`). */
282
+ /** 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`.) */
267
283
  urls?: "folders" | "html";
268
- /** 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. */
284
+ /** 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.) */
269
285
  layoutAliases?: Record<string, string>;
270
286
  /** 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. */
271
287
  base?: string;
package/types/llms.d.ts CHANGED
@@ -1,23 +1,33 @@
1
1
  // ssqch/llms: from ssqch.d.ts, the types `ssqch types` writes.
2
2
  /// <reference path="./globals.d.ts" />
3
3
  import type { BuiltinPlugin } from "ssqch";
4
+ /** A page as `section` and `sort` get it. */
5
+ export interface LlmsPage { url: string; inputPath: string; outputPath: string; date: Date; data: Record<string, any> }
4
6
  export interface LlmsPluginOptions {
5
7
  /** The `# heading` of `llms.txt`. Default: `site.title` in the site's data, or the home page's title. */
6
8
  title?: string;
7
9
  /** A line under it, as `> description`. */
8
10
  description?: string;
9
- /** The site's address, like `"https://example.com"`, for whole links. Default: links from the site's root. */
11
+ /** 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. */
12
+ details?: string;
13
+ /** 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. */
10
14
  url?: string;
11
- /** URL globs of pages to leave out, like `["/blog/**"]`. 404 pages are always left out. */
15
+ /** 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`. */
12
16
  exclude?: string[];
13
- /** 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. */
17
+ /** 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. */
14
18
  copies?: boolean;
15
19
  /** `/llms-full.txt`, every listed page's Markdown in one file, each after a `url:` line. Default `true`. */
16
20
  full?: boolean;
17
- /** 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. */
18
- hint?: boolean;
19
- /** 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"). */
20
- section?: (page: { url: string; inputPath: string; outputPath: string; date: Date; data: Record<string, any> }) => string | undefined;
21
+ /** 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. */
22
+ section?: (page: LlmsPage) => string | undefined;
23
+ /** The pages' order, as `Array.prototype.sort` takes it: `(a, b) => a.data.order - b.data.order`. Default: by URL. */
24
+ sort?: (a: LlmsPage, b: LlmsPage) => number;
25
+ /** 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. */
26
+ paths?: Array<string | LlmsPath>;
27
+ /** 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. */
28
+ budget?: number | false;
21
29
  }
22
- /** 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. */
30
+ /** A part of the site with an `llms.txt` of its own, in `paths`. */
31
+ export interface LlmsPath { path: string; title?: string; description?: string; details?: string }
32
+ /** 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">`. */
23
33
  export function llmsPlugin(options?: LlmsPluginOptions): BuiltinPlugin;
@@ -0,0 +1,13 @@
1
+ // ssqch/robots: from ssqch.d.ts, the types `ssqch types` writes.
2
+ /// <reference path="./globals.d.ts" />
3
+ import type { BuiltinPlugin } from "ssqch";
4
+ export interface RobotsPluginOptions {
5
+ /** 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. */
6
+ ai?: { training?: boolean; search?: boolean; fetch?: boolean };
7
+ /** URL paths no crawler should read, like `["/drafts/"]`, as `Disallow:` lines in everyone's group. */
8
+ disallow?: string[];
9
+ /** 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. */
10
+ sitemap?: boolean | string;
11
+ }
12
+ /** 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. */
13
+ export function robotsPlugin(options?: RobotsPluginOptions): BuiltinPlugin;
package/types/sass.d.ts CHANGED
@@ -9,7 +9,7 @@ export interface SassPluginOptions {
9
9
  style?: "compressed" | "expanded";
10
10
  /** More folders `@use` and `@import` look in, relative to the project root. */
11
11
  loadPaths?: string[];
12
- /** `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`. */
12
+ /** `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.) */
13
13
  charset?: boolean;
14
14
  }
15
15
 
@@ -3,14 +3,12 @@
3
3
  import type { BuiltinPlugin } from "ssqch";
4
4
 
5
5
  export interface SitemapPluginOptions {
6
- /** 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. */
7
- url?: string;
6
+ /** 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. */
7
+ url: string;
8
8
  /** URL globs to leave out, like `["/tags/**"]`. Pages with `sitemap: false` and 404 pages are always left out. */
9
9
  exclude?: string[];
10
- /** Add `<lastmod>` from each page's date. Default `true` (`false` with `format: "vitepress"`). */
10
+ /** Add `<lastmod>` from each page's date. Default `true`. */
11
11
  lastmod?: boolean;
12
- /** 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. */
13
- format?: "ssqch" | "vitepress";
14
12
  /** Where to write it. Default `"/sitemap.xml"`. */
15
13
  output?: string;
16
14
  /** 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`. */
Binary file