ssqch 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/README.md +8 -4
  2. package/bin/ssqch.js +14 -48
  3. package/bundled/README.md +1314 -0
  4. package/bundled/completions/bash +840 -0
  5. package/bundled/completions/elvish +286 -0
  6. package/bundled/completions/fish +182 -0
  7. package/bundled/completions/powershell +318 -0
  8. package/bundled/completions/zsh +510 -0
  9. package/bundled/ssqch.d.ts +540 -0
  10. package/bundled/starter/engines/index.edge +11 -0
  11. package/bundled/starter/engines/index.ejs +11 -0
  12. package/bundled/starter/engines/index.hbs +11 -0
  13. package/bundled/starter/engines/index.liquid +11 -0
  14. package/bundled/starter/engines/layout.edge +35 -0
  15. package/bundled/starter/engines/layout.ejs +35 -0
  16. package/bundled/starter/engines/layout.hbs +35 -0
  17. package/bundled/starter/engines/layout.liquid +35 -0
  18. package/bundled/starter/gitignore +3 -0
  19. package/bundled/starter/jsconfig.json +11 -0
  20. package/bundled/starter/src/404.md +8 -0
  21. package/bundled/starter/src/_blueprints/posts.md +5 -0
  22. package/bundled/starter/src/_data/site.json +4 -0
  23. package/bundled/starter/src/_includes/layout.jinja +35 -0
  24. package/bundled/starter/src/index.jinja +11 -0
  25. package/bundled/starter/src/posts/i-know-what-i-saw.md +11 -0
  26. package/bundled/starter/src/posts/posts.json +4 -0
  27. package/bundled/starter/src/posts/raiders-of-the-lost-path.md +27 -0
  28. package/bundled/starter/src/posts/the-cache-of-the-wild.md +26 -0
  29. package/bundled/starter/src/posts/the-stump-has-moved.md +15 -0
  30. package/bundled/starter/src/posts/upon-further-review-a-stump.md +18 -0
  31. package/bundled/starter/ssqch.config.js +29 -0
  32. package/bundled/starter-docs/engines/edge/base.edge +41 -0
  33. package/bundled/starter-docs/engines/edge/containers/details.edge +5 -0
  34. package/bundled/starter-docs/engines/edge/containers/tab.edge +4 -0
  35. package/bundled/starter-docs/engines/edge/containers/tabs.edge +5 -0
  36. package/bundled/starter-docs/engines/edge/doc.edge +59 -0
  37. package/bundled/starter-docs/engines/edge/hooks/heading.edge +2 -0
  38. package/bundled/starter-docs/engines/ejs/base.ejs +41 -0
  39. package/bundled/starter-docs/engines/ejs/containers/details.ejs +5 -0
  40. package/bundled/starter-docs/engines/ejs/containers/tab.ejs +4 -0
  41. package/bundled/starter-docs/engines/ejs/containers/tabs.ejs +5 -0
  42. package/bundled/starter-docs/engines/ejs/doc.ejs +59 -0
  43. package/bundled/starter-docs/engines/ejs/hooks/heading.ejs +2 -0
  44. package/bundled/starter-docs/engines/hbs/base.hbs +41 -0
  45. package/bundled/starter-docs/engines/hbs/containers/details.hbs +5 -0
  46. package/bundled/starter-docs/engines/hbs/containers/tab.hbs +4 -0
  47. package/bundled/starter-docs/engines/hbs/containers/tabs.hbs +5 -0
  48. package/bundled/starter-docs/engines/hbs/doc.hbs +58 -0
  49. package/bundled/starter-docs/engines/hbs/hooks/heading.hbs +2 -0
  50. package/bundled/starter-docs/engines/liquid/base.liquid +41 -0
  51. package/bundled/starter-docs/engines/liquid/containers/details.liquid +5 -0
  52. package/bundled/starter-docs/engines/liquid/containers/tab.liquid +4 -0
  53. package/bundled/starter-docs/engines/liquid/containers/tabs.liquid +5 -0
  54. package/bundled/starter-docs/engines/liquid/doc.liquid +60 -0
  55. package/bundled/starter-docs/engines/liquid/hooks/heading.liquid +2 -0
  56. package/bundled/starter-docs/gitignore +4 -0
  57. package/bundled/starter-docs/src/404.md +12 -0
  58. package/bundled/starter-docs/src/_blueprints/docs.md +5 -0
  59. package/bundled/starter-docs/src/_data/nav.yml +10 -0
  60. package/bundled/starter-docs/src/_data/site.json +5 -0
  61. package/bundled/starter-docs/src/_includes/base.jinja +41 -0
  62. package/bundled/starter-docs/src/_includes/containers/details.jinja +5 -0
  63. package/bundled/starter-docs/src/_includes/containers/tab.jinja +4 -0
  64. package/bundled/starter-docs/src/_includes/containers/tabs.jinja +5 -0
  65. package/bundled/starter-docs/src/_includes/doc.jinja +59 -0
  66. package/bundled/starter-docs/src/_includes/hooks/heading.jinja +2 -0
  67. package/bundled/starter-docs/src/assets/docs.css +257 -0
  68. package/bundled/starter-docs/src/assets/docs.js +67 -0
  69. package/bundled/starter-docs/src/docs/docs.json +1 -0
  70. package/bundled/starter-docs/src/docs/guides/deploying.md +77 -0
  71. package/bundled/starter-docs/src/docs/guides/writing.md +65 -0
  72. package/bundled/starter-docs/src/docs/index.md +29 -0
  73. package/bundled/starter-docs/src/docs/install.md +42 -0
  74. package/bundled/starter-docs/src/index.md +13 -0
  75. package/bundled/starter-docs/ssqch.config.js +40 -0
  76. package/bundled/trailheads/from-component-frameworks.md +116 -0
  77. package/bundled/trailheads/from-docusaurus.md +55 -0
  78. package/bundled/trailheads/from-eleventy.md +140 -0
  79. package/bundled/trailheads/from-hexo.md +92 -0
  80. package/bundled/trailheads/from-jekyll.md +79 -0
  81. package/bundled/trailheads/from-mkdocs.md +45 -0
  82. package/bundled/trailheads/from-zola.md +71 -0
  83. package/lib/assets.js +235 -3
  84. package/lib/chunk-3A647I3N.js +384 -0
  85. package/lib/chunk-3GYLOC6Y.js +1017 -0
  86. package/lib/chunk-3K3ANWZ2.js +118 -0
  87. package/lib/chunk-3NYSSA2C.js +22 -0
  88. package/lib/chunk-47P4YREZ.js +1287 -0
  89. package/lib/chunk-4Q6WMTER.js +32 -0
  90. package/lib/chunk-76NTVE34.js +338 -0
  91. package/lib/chunk-7PWCYHTJ.js +1350 -0
  92. package/lib/chunk-7RDRZHJD.js +217 -0
  93. package/lib/chunk-7SD7K567.js +57 -0
  94. package/lib/chunk-7XLK2GEG.js +54 -0
  95. package/lib/chunk-AD3HAW3W.js +10 -0
  96. package/lib/chunk-BEGC7YP6.js +502 -0
  97. package/lib/chunk-CMUWRPSQ.js +113 -0
  98. package/lib/chunk-CZ4XQC56.js +999 -0
  99. package/lib/chunk-D2XE2GTY.js +71 -0
  100. package/lib/chunk-DDV6JEC2.js +46 -0
  101. package/lib/chunk-DELWRJAO.js +37409 -0
  102. package/lib/chunk-DELWRJAO.js.LEGAL.txt +27 -0
  103. package/lib/chunk-F65YUXZ7.js +334 -0
  104. package/lib/chunk-FVZ5JBRI.js +115 -0
  105. package/lib/chunk-GRWMGC7D.js +4435 -0
  106. package/lib/chunk-GRWMGC7D.js.LEGAL.txt +41 -0
  107. package/lib/chunk-GUKSZ2XM.js +207 -0
  108. package/lib/chunk-HPXAZ2HU.js +251 -0
  109. package/lib/chunk-HXCLCXRT.js +20 -0
  110. package/lib/chunk-I3PS26CI.js +48 -0
  111. package/lib/chunk-IAFM5ITE.js +11 -0
  112. package/lib/chunk-II5DEH3Q.js +209 -0
  113. package/lib/chunk-IJWHOFRP.js +44 -0
  114. package/lib/chunk-LPHNACE4.js +29 -0
  115. package/lib/chunk-MI6EJWA2.js +175 -0
  116. package/lib/chunk-NCWFYT74.js +1541 -0
  117. package/lib/chunk-NKXEPHRZ.js +136 -0
  118. package/lib/chunk-NNUKIGOO.js +160 -0
  119. package/lib/chunk-R7K3D5W5.js +3957 -0
  120. package/lib/chunk-RNJFPFXE.js +29 -0
  121. package/lib/chunk-SF4I6Z7S.js +25 -0
  122. package/lib/chunk-SURPOAW7.js +44 -0
  123. package/lib/chunk-SXMJ52IK.js +572 -0
  124. package/lib/chunk-TICWN55Z.js +20 -0
  125. package/lib/chunk-TVU3OPPK.js +146 -0
  126. package/lib/chunk-UU43WIZG.js +29 -0
  127. package/lib/chunk-VJWQSYEG.js +119 -0
  128. package/lib/chunk-XMXBHXZR.js +75 -0
  129. package/lib/chunk-YTHQBMDJ.js +211 -0
  130. package/lib/cli.js +547 -0
  131. package/lib/elements.js +180 -3
  132. package/lib/image.js +27 -3
  133. package/lib/links.js +464 -3
  134. package/lib/minify.js +69 -3
  135. package/lib/redirects.js +152 -3
  136. package/lib/rss.js +139 -3
  137. package/lib/sass.js +256 -3
  138. package/lib/sitemap.js +113 -3
  139. package/lib/ssqch.js +28 -0
  140. package/package.json +83 -80
  141. package/src/serve/live.js +174 -0
  142. package/src/serve/not-found.html +31 -0
  143. package/types/globals.d.ts +3 -2
  144. package/types/image.d.ts +7 -3
  145. package/types/index.d.ts +28 -9
  146. package/types/links.d.ts +1 -1
  147. package/types/minify.d.ts +1 -1
  148. package/types/rss.d.ts +1 -1
  149. package/types/sass.d.ts +1 -1
  150. package/types/sitemap.d.ts +2 -0
  151. package/wasm/markdown.wasm +0 -0
  152. package/wasm/minify.wasm +0 -0
  153. package/wasm/sass.wasm +0 -0
  154. package/lib/index.js +0 -3
  155. package/platforms.json +0 -6
@@ -0,0 +1,540 @@
1
+ // Type definitions for ssqch.config.js and the modules built into ssqch.
2
+ // Written by `ssqch types`. Editors use them for autocomplete and checking;
3
+ // the build doesn't read them. Regenerate after upgrading ssqch.
4
+
5
+ // A config and its data files run on Node, so `process` is Node's own. These are the parts
6
+ // they most often use, declared the way @types/node declares them, so a project that installs
7
+ // those types gets theirs too.
8
+ declare namespace NodeJS {
9
+ interface ProcessEnv {
10
+ /** The build's environment (`--env`): `"production"` for `ssqch build`, `"development"` for `ssqch serve`. */
11
+ SSQCH_ENV?: string;
12
+ [name: string]: string | undefined;
13
+ }
14
+ interface Process {
15
+ /** The environment variables, with `SSQCH_ENV` set to the build's environment when it isn't set. */
16
+ env: ProcessEnv;
17
+ /** The project root. */
18
+ cwd(): string;
19
+ /** `"darwin"`, `"linux"` or `"win32"`. */
20
+ platform: string;
21
+ }
22
+ }
23
+ declare var process: NodeJS.Process;
24
+
25
+ declare module "ssqch" {
26
+ /** What a config function gets: which build this is. */
27
+ export interface ConfigContext {
28
+ /** `"production"` for `ssqch build`, `"development"` for `ssqch serve` (unless `--env` says otherwise). */
29
+ env: "production" | "development";
30
+ /** True while running `ssqch serve`. */
31
+ serving: boolean;
32
+ }
33
+
34
+ /** The data of the pages each schema covers, by schema name. `ssqch types` fills this in from the config's `schemas`. */
35
+ export interface Schemas {}
36
+
37
+ /** A page in a collection, oldest first. */
38
+ export interface CollectionItem<Data = Record<string, any>> {
39
+ /** The page's URL, or `false` for `permalink: false`. */
40
+ url: string | false;
41
+ date: Date;
42
+ /** The template's path, like `./src/posts/pine.md`. */
43
+ inputPath: string;
44
+ /** The file name without extensions (`pine` for `pine.md`; empty for an `index` page). */
45
+ fileSlug: string;
46
+ filePathStem: string;
47
+ /** Where the page is written, or `false`. */
48
+ outputPath: string | false;
49
+ /** `url`, `inputPath`, `date` and the rest, plus `headings` from the rendered body. */
50
+ page: Record<string, unknown> & { headings?: Heading[]; excerpt?: string; lastModified?: Date };
51
+ /** The page's data: front matter, data files and the rest of the cascade. */
52
+ data: Data & Record<string, any>;
53
+ /** The rendered body, without layouts. */
54
+ templateContent: string;
55
+ content: string;
56
+ }
57
+
58
+ /** A heading in a page's rendered body (`page.headings`). */
59
+ export interface Heading {
60
+ level: number;
61
+ /** The heading's `id`, if it has one. */
62
+ id?: string;
63
+ /** Its text, without tags or anything marked `aria-hidden="true"`. */
64
+ text: string;
65
+ }
66
+
67
+ /** What a token is: its `hl-*` class without the prefix. */
68
+ export type TokenKind = "comment" | "keyword" | "operator" | "string" | "regexp" | "escape" | "number" | "constant" | "builtin" | "property" | "attribute" | "function" | "type" | "parameter" | "tag" | "heading" | "strong" | "emphasis" | "link" | "inserted" | "deleted";
69
+
70
+ /** A piece of highlighted code. Without a `kind` (or as a string), it's plain text. */
71
+ export type Token = [text: string, kind?: TokenKind | null] | { text: string; kind?: TokenKind | null } | string;
72
+
73
+ /** A site's language for `markdown.highlight.languages`: a function that cuts the code into tokens whose text adds up to the code, another language's name (`"chordpro"`, an alias), or the path of a `.sublime-syntax` grammar from the project root. */
74
+ export type Highlighter = ((code: string, lang: string) => Token[]) | string;
75
+
76
+ /** How Markdown renders. */
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`), or `false` for none. A `{#id}` on the heading always wins. */
79
+ headingIds?: "github" | "blackfriday" | "ascii" | false | ((text: string) => string);
80
+ /** `## Heading {#id .class key=value}`. Default `true`. */
81
+ headingAttributes?: boolean;
82
+ /** `[^1]` references, with the notes at the end of the page. Default `true`. */
83
+ footnotes?: boolean;
84
+ /** `- [ ]` and `- [x]` items. Default `true`. */
85
+ taskLists?: boolean;
86
+ /** Bare `https://` and `www.` URLs become links. Default `true`. */
87
+ autolinks?: boolean;
88
+ /** GitHub's `> [!NOTE]` alerts: note, tip, important, warning and caution. Default `true`. */
89
+ alerts?: boolean;
90
+ /** `::: name args` blocks, rendered by `_includes/containers/name.*`. Default `true`. */
91
+ containers?: boolean;
92
+ /** A term, then `: definition` lines. Default `false`. */
93
+ definitionLists?: boolean;
94
+ /** Curly quotes, dashes and ellipses. Default `false`. */
95
+ smartPunctuation?: boolean;
96
+ /** Lines indented four spaces are code blocks. `false` renders them as ordinary Markdown (HTML indented inside Markdown, say); fences are still code. Default `true`. */
97
+ indentedCode?: boolean;
98
+ /** 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. Default `false`. */
99
+ highlight?: boolean | { css?: string | false; languages?: Record<string, Highlighter> };
100
+ }
101
+
102
+ /** What a collection function gets. */
103
+ export interface Pages {
104
+ /** Every page in collections, oldest first. */
105
+ all(): CollectionItem[];
106
+ /** Pages with this tag. A tag with a schema gives pages with that schema's fields. */
107
+ byTag<Tag extends keyof Schemas>(tag: Tag): CollectionItem<Schemas[Tag]>[];
108
+ byTag(tag: string): CollectionItem[];
109
+ /** Pages with all of these tags. */
110
+ byTags(...tags: string[]): CollectionItem[];
111
+ /** Pages whose input path matches a glob (or any of several): `"src/posts/*.md"`. */
112
+ byGlob(glob: string | string[]): CollectionItem[];
113
+ }
114
+
115
+ /** What a transform gets with the content. */
116
+ export interface TransformPage {
117
+ url: string;
118
+ inputPath: string;
119
+ outputPath: string;
120
+ }
121
+
122
+ /** What `beforeBuild` and `afterBuild` hooks get. */
123
+ export interface BuildEvent {
124
+ env: "production" | "development";
125
+ serving: boolean;
126
+ /** The build was run with `--quiet`: print only warnings and errors. */
127
+ quiet: boolean;
128
+ /** The build was run with `--verbose`. */
129
+ verbose: boolean;
130
+ /** Folders relative to the project root, like `./src/`. */
131
+ dirs: { input: string; output: string; includes: string; data: string };
132
+ /** The files the build wrote (`afterBuild` only). */
133
+ written?: string[];
134
+ }
135
+
136
+ type MaybePromise<T> = T | Promise<T>;
137
+ /** A function, or `{ run: "command" }` to run a program in the project root (through `sh -c`, or `cmd /C` on Windows). It gets `SSQCH_ENV`, `SSQCH_SERVING`, `SSQCH_QUIET`, `SSQCH_INPUT` and `SSQCH_OUTPUT`; a failure fails the build. */
138
+ type Hook = ((event: BuildEvent) => MaybePromise<void>) | { run: string };
139
+ /** Renders a template's body (front matter removed) with the page's data. */
140
+ type EngineRender = (source: string, data: Record<string, any>) => MaybePromise<string>;
141
+
142
+ /**
143
+ * A field's type: `"string"`, `"number"`, `"integer"`, `"boolean"`, `"date"`, `"file"` (a path to a file that exists), `"object"`, `"array"` or `"any"`;
144
+ * a literal (`"'draft'"`, `"1"`, `"true"`, `"null"`); a union (`"'draft' | 'published'"`); a list (`"string[]"`); and `?` at the end for optional (`"string?"`).
145
+ * Or an object of fields, a one-item array (`[{ name: "string" }]` is a list of objects), or a function that returns `true`, `false` or what's wrong.
146
+ */
147
+ export type SchemaType = string | ((value: any, page: Record<string, any>) => boolean | string | void) | SchemaFields | [SchemaType];
148
+ /** `{ field: type }`. A key ending in `?` is optional too: `"author?": { name: "string" }`. */
149
+ export interface SchemaFields {
150
+ [field: string]: SchemaType;
151
+ }
152
+ /** What a kind of page's data has to look like. Checked on every build; a problem names the file and the field. */
153
+ export interface Schema {
154
+ fields: SchemaFields;
155
+ /** Globs (relative to the input folder) of the files this covers. Without it, the schema covers the pages tagged with its name (`all` is every page in collections). */
156
+ files?: string | string[];
157
+ /** Front matter keys that aren't fields: `"allow"` (the default), `"warn"` or `"error"`. */
158
+ unknown?: "allow" | "warn" | "error";
159
+ }
160
+
161
+ /** Where a theme comes from: a folder, a pinned git URL, or the same as an object. */
162
+ export type ThemeSource = string | { git: string; ref: string; dir?: string };
163
+
164
+ /** A built-in plugin, as returned by `imagePlugin()` and the others. */
165
+ export interface BuiltinPlugin {
166
+ name: string;
167
+ builtin: string;
168
+ options?: Record<string, unknown>;
169
+ }
170
+
171
+ /** A plugin written in Rust: one `.wasm` file built with the `ssqch-plugin` crate, which ssqch runs in Node's WebAssembly on every platform. An npm package's default export returns this: `export default (options) => ({ name: "hello", rust: { wasm: fileURLToPath(new URL("./hello.wasm", import.meta.url)), options } })`. Its transform, filters and engines come from the manifest inside the file, so none are listed here; a name the config already uses is an error, and so is a file built for another plugin ABI. */
172
+ export interface RustPlugin {
173
+ /** Shows up in error messages. */
174
+ name: string;
175
+ rust: {
176
+ /** The absolute path to the plugin's `.wasm` file. */
177
+ wasm: string;
178
+ /** The plugin's options, as JSON. The plugin checks them when the config loads (an unknown or misspelled option fails the build, and says which fields it has). */
179
+ options?: unknown;
180
+ };
181
+ }
182
+
183
+ /** Everything a plugin can add. The config itself can set these too. */
184
+ export interface ConfigParts {
185
+ /** Shows up in error messages. */
186
+ name?: string;
187
+ /** Functions templates can call: `{{ slug(title) }}`. Async functions are awaited. */
188
+ filters?: Record<string, (...args: any[]) => unknown>;
189
+ /** Data for every template. A value that's a function (sync or async) is called on each build, and its answer is that name's value. */
190
+ data?: Record<string, unknown>;
191
+ /** Custom collections, from the pages in collections. */
192
+ collections?: Record<string, (pages: Pages) => unknown>;
193
+ /** Run on every output file. Return the content, changed or not. */
194
+ transforms?: Record<string, (content: string, page: TransformPage) => MaybePromise<string>>;
195
+ /** Template engines of your own, by file extension: a function, or an object with `render`. Return the rendered text. */
196
+ engines?: Record<string, EngineRender | { render: EngineRender }>;
197
+ /** Files or folders to copy: a path, or `{ from: to }`, or an array of them. */
198
+ passthrough?: string | Record<string, string> | Array<string | Record<string, string>>;
199
+ /** More paths for `ssqch serve` to watch. */
200
+ watch?: string | string[];
201
+ /** Run before each build: a function, `{ run: "command" }`, or a list of them. */
202
+ beforeBuild?: Hook | Hook[];
203
+ /** Run after each build, with `written` (the files the build wrote). */
204
+ afterBuild?: Hook | Hook[];
205
+ /** More config, from plugins. A plugin is an object with any of these keys, a function that returns one, a built-in plugin (`imagePlugin()`), and plugins written in Rust (`{ name, rust: { wasm, options } }`). `false`, `null` and `undefined` are skipped. */
206
+ plugins?: Plugin[];
207
+ }
208
+
209
+ export type Plugin =
210
+ | ConfigParts
211
+ | BuiltinPlugin
212
+ | RustPlugin
213
+ | ((context: ConfigContext) => MaybePromise<ConfigParts | BuiltinPlugin | RustPlugin | false | null | undefined>)
214
+ | false
215
+ | null
216
+ | undefined;
217
+
218
+ export interface Config extends ConfigParts {
219
+ /** Folders. `includes` and `data` are relative to `input`. */
220
+ dirs?: {
221
+ /** Default `.`. */
222
+ input?: string;
223
+ /** Default `_site`. */
224
+ output?: string;
225
+ /** Default `_includes`. */
226
+ includes?: string;
227
+ /** Default `_data`. */
228
+ data?: string;
229
+ };
230
+ /** File extensions to render. Default `["jinja", "md", "html"]`. Add `"edge"` for Edge, `"liquid"` for Liquid, `"njk"` for Nunjucks, `"j2"` for Jinja in `.j2` files, `"hbs"` / `"handlebars"` for Handlebars, `"mustache"`, or `"ejs"` for EJS. */
231
+ templateFormats?: string[];
232
+ /** The engine that runs over `.md` files first: `"jinja"` (the default), `"edge"`, `"liquid"`, `"njk"`, `"hbs"`, `"ejs"`, or `false` for none. */
233
+ markdownEngine?: string | false;
234
+ /** The engine that runs over `.html` files first. Default `"jinja"`; `false` for none. */
235
+ htmlEngine?: string | false;
236
+ /** Heading IDs, footnotes and the other Markdown extensions. */
237
+ markdown?: MarkdownOptions;
238
+ /** Merge objects and concatenate arrays through the data cascade. Default `true`. */
239
+ deepMerge?: boolean;
240
+ /** 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`. */
241
+ leaveNoTrace?: boolean;
242
+ /** Another name for `leaveNoTrace`. Set one of them. */
243
+ clean?: boolean;
244
+ /** Globs (relative to the input folder) of files that aren't pages, like `["drafts/**", "notes/*.wip.md"]`. */
245
+ ignore?: string | string[];
246
+ /** Page bundles: copy the other files in a folder whose page is `index.*` (images, downloads) next to the page. Default `false`. */
247
+ bundles?: boolean;
248
+ /** Printing an undefined value (`{{ titel }}`) is an error, in every template language. Conditionals and defaults still work. Default `false`. */
249
+ strict?: boolean;
250
+ /** `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`). */
251
+ lastModified?: "git" | "file" | false;
252
+ /** 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. */
253
+ timeZone?: string;
254
+ /** 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. */
255
+ base?: string;
256
+ /** A theme under the site: a folder (`"themes/docs"`), or a git repository pinned to a tag or a commit's full hash (`"https://github.com/you/theme#v1.2.0"`, with `#v1.2.0:folder` for a theme in a folder of its repository), fetched once and kept in `.cache/ssqch/themes/`. The site's own includes, data, pages and files win over the theme's, one by one. In a list, earlier themes sit on top of later ones. */
257
+ theme?: ThemeSource | ThemeSource[];
258
+ /** Content schemas, by name: `{ posts: { fields: { title: "string", date: "date" } } }` checks every page tagged `posts`. */
259
+ schemas?: Record<string, Schema>;
260
+ /** Size budgets by kind of file, checked after each build: a file over its kind's budget is an `over-budget` warning. Sizes are bytes or strings like `"150 KB"` and `"1.5 MB"` (powers of 1,000). */
261
+ budgets?: Partial<Record<"pages" | "images" | "css" | "javascript" | "fonts" | "media" | "documents" | "data" | "other" | "total", number | string>>;
262
+ /** What `ssqch serve` runs besides the server. (The server builds in a process of its own, starts it again when the config or a module it imports changes, and listens on 127.0.0.1 only.) */
263
+ serve?: {
264
+ /** Programs to start with the server and stop with it, like the watchers of your CSS and JavaScript tools: `["npx postcss src/app.css -o dist/app.css --watch"]`. Their output is shown with the tool's name in front. They get `SSQCH_ENV`, `SSQCH_SERVING` (`true`), `SSQCH_QUIET`, `SSQCH_INPUT` and `SSQCH_OUTPUT`, as build commands do. Builds don't run them. */
265
+ run?: string | string[];
266
+ };
267
+ }
268
+
269
+ /** Returns its argument. It's there so the config reads as one, and for these types. */
270
+ export function defineConfig<T extends Config | ((context: ConfigContext) => MaybePromise<Config>)>(config: T): T;
271
+ /** Render Markdown with the site's `markdown` options (render hooks and containers are for templates). `inline` drops the `<p>` around a single paragraph. */
272
+ export function markdown(text: string, options?: { inline?: boolean }): string;
273
+ /** Read a JSON, YAML or TOML file (from the project root) into data: `readData("src/_data/sites/en.yml")`. */
274
+ export function readData(path: string): any;
275
+ /** A file that `files()` found. */
276
+ export interface FoundFile {
277
+ /** From the project root, with `/`: `"images/albums/v1/20011222_08.JPG"`. */
278
+ path: string;
279
+ /** Where a passthrough copy to the same path is served: from the input folder when the file is inside it (`src/images/a.jpg` is `/images/a.jpg`), otherwise from the project root (`/images/albums/v1/20011222_08.JPG`). */
280
+ url: string;
281
+ /** The file name: `"20011222_08.JPG"`. */
282
+ name: string;
283
+ /** The name without its extension: `"20011222_08"`. */
284
+ stem: string;
285
+ /** The extension, lowercase, without the dot: `"jpg"`. */
286
+ ext: string;
287
+ /** From the start of the name (`20011222_08.JPG`, `2001-12-22-camp.jpg`, at midnight UTC), or the file's modification time. */
288
+ date: Date;
289
+ /** Where `date` came from: `"name"`, or `"modified"` (the modification time, which says when the file was copied or edited, not when a photo was taken). */
290
+ dateFrom: "name" | "modified";
291
+ /** Bytes. */
292
+ size: number;
293
+ /** Pixels, with `{ dimensions: true }`; `null` for a file whose size ssqch can't read (it reads PNG, JPEG, GIF, TIFF, WebP, HEIF, AVIF, BMP, PSD, ICO and QOI). */
294
+ width?: number | null;
295
+ /** Pixels, with `{ dimensions: true }`; `null` for a file whose size ssqch can't read (it reads PNG, JPEG, GIF, TIFF, WebP, HEIF, AVIF, BMP, PSD, ICO and QOI). */
296
+ height?: number | null;
297
+ }
298
+ /** The files a glob matches, from the project root and ignoring case, sorted by path, as data: `files("images/albums/v1/*.{jpg,png}")`. `{ dimensions: true }` reads each image's width and height from its header, once: they're kept in `.cache/ssqch/image-sizes.json` until the file changes. No match is an empty list. */
299
+ export function files(pattern: string, options?: { dimensions?: boolean }): FoundFile[];
300
+ /** How `slugify` writes a slug. */
301
+ export interface SlugifyOptions {
302
+ /** Between words: a dash by default, `"_"` for `taco_bake`. */
303
+ separator?: string;
304
+ /** `"drop"` (the default): `Drew's Brownies` is `drews-brownies`. `"separate"`: an apostrophe splits words like other punctuation, `drew-s-brownies`, to keep a site's existing URLs. */
305
+ apostrophes?: "drop" | "separate";
306
+ }
307
+ /** The `slugify` template filter, for data files: `slugify("Taco Bake", { separator: "_" })` is `"taco_bake"`. Lowercase letters and digits, with `separator` (a dash by default) for each run of anything else. A string is the separator. */
308
+ export function slugify(text: string, options?: SlugifyOptions | string): string;
309
+ /** A `slugify` that counts, so every slug it makes is different: the first "Misc Pictures" is `misc-pictures`, the next `misc-pictures-1`, then `misc-pictures-2`. Make one per list, in a data file, and store the slug with each item, so a paginated page's permalink and the links to it agree. */
310
+ export function slugger(options?: SlugifyOptions): (text: string) => string;
311
+ const ssqch: { defineConfig: typeof defineConfig; markdown: typeof markdown; readData: typeof readData; files: typeof files; slugify: typeof slugify; slugger: typeof slugger };
312
+ export default ssqch;
313
+ }
314
+
315
+ declare module "ssqch/image" {
316
+ import type { BuiltinPlugin } from "ssqch";
317
+
318
+ export type ImageFormat = "avif" | "webp" | "jpeg" | "jpg" | "png" | "gif" | "svg" | "auto";
319
+ /** A format name. Known names autocomplete; ssqch rejects an unknown one when it builds. */
320
+ type FormatName = ImageFormat | (string & {});
321
+
322
+ export interface ImagePluginOptions {
323
+ /** Output formats; the last is the `<img>` fallback. `"auto"` keeps the source's format. */
324
+ formats?: FormatName[];
325
+ /** Widths to generate (never wider than the original). */
326
+ widths?: number[];
327
+ /** Attributes added to every `<img>`, like `{ loading: "lazy" }`. */
328
+ defaultAttributes?: Record<string, string>;
329
+ /** Folder in the output for generated images. Default `img`. */
330
+ outputDir?: string;
331
+ /** URL path they're served from. Default `/img/`. */
332
+ urlPath?: string;
333
+ /** WebP quality, sharp's: a whole number from 1 to 100. Default 75. */
334
+ webpQuality?: number;
335
+ /** AVIF quality, sharp's: a whole number from 1 to 100. Default 41. */
336
+ avifQuality?: number;
337
+ /** sharp's AVIF effort: a whole number from 0 (fastest) to 9 (slowest, smallest files). Default 2. */
338
+ avifEffort?: number;
339
+ /** JPEG quality, sharp's (mozjpeg): a whole number from 1 to 100. Default 89. */
340
+ jpegQuality?: number;
341
+ /** A width larger than the original is clamped to it only when the width before it is this many times smaller. Default 1.25. */
342
+ minimumThreshold?: number;
343
+ /** Delete generated images the build didn't use. Only for full builds. */
344
+ prune?: boolean;
345
+ /** Remember image ids between builds in `.cache/ssqch`. Default `true`. */
346
+ hashCache?: boolean;
347
+ /** Point links to local images at a generated copy. Default `true`. */
348
+ linkedImages?: boolean;
349
+ /** Where images are encoded and kept between builds, from the project root; the output gets links to them. Default `.cache/ssqch/img`. `false` encodes straight into the output. */
350
+ cacheDir?: string | false;
351
+ }
352
+
353
+ /** One generated file. */
354
+ export interface ImageEntry {
355
+ format: string;
356
+ width: number;
357
+ height: number;
358
+ url: string;
359
+ /** The MIME type, like `image/webp`. */
360
+ sourceType: string;
361
+ /** `url width`, for a `srcset`. */
362
+ srcset: string;
363
+ filename: string;
364
+ outputPath: string;
365
+ size: number;
366
+ }
367
+
368
+ /** Turns every local `<img>` in HTML output into a `<picture>`, with AVIF, WebP and fallback sources encoded by sharp. `[ssqch] Encoded ...` lines come as each image's files are done, while pages go on rendering. */
369
+ export function imagePlugin(options?: ImagePluginOptions): BuiltinPlugin;
370
+
371
+ /** Generate one image's files with the plugin's settings and cache. Keyed by format, smallest first; with `"auto"` in `formats`, its files are under `auto` too. */
372
+ export function image(src: string, options?: ImageCallOptions): Promise<Record<string, ImageEntry[]>>;
373
+
374
+ /** One generated copy of an image, from `imageUrl()`. A remote URL comes back as only `{ url }`. */
375
+ export interface ImageUrl {
376
+ url: string;
377
+ width?: number;
378
+ height?: number;
379
+ /** The MIME type, like `image/png`. */
380
+ type?: string;
381
+ /** The format it's in, like `png`. */
382
+ format?: string;
383
+ }
384
+
385
+ /** The URL (and size and type) of one generated copy of an image, for `og:image`, JSON-LD and feeds: `imageUrl("/content/logo.png", { width: 1200 })`. `src` is a site path, from the input folder. Also a template function. */
386
+ export function imageUrl(src: string, options?: { width?: number | "auto"; format?: FormatName }): ImageUrl;
387
+
388
+ /** What `image()` takes for one image. Encoder settings go on `imagePlugin()`. */
389
+ export interface ImageCallOptions {
390
+ /** Widths to generate; `"auto"` is the original's. Default `["auto"]`. */
391
+ widths?: Array<number | "auto">;
392
+ /** Output formats. Default `["webp", "jpeg"]`. */
393
+ formats?: FormatName[];
394
+ /** The output's URL path without the width and extension, instead of a name from a hash: `"/assets/sponsors/acme"` writes `/assets/sponsors/acme-200.webp`. Without a leading `/`, it's inside the image output folder. */
395
+ name?: string;
396
+ }
397
+ }
398
+
399
+ declare module "ssqch/rss" {
400
+ import type { BuiltinPlugin } from "ssqch";
401
+
402
+ /** Adds the filters getNewestCollectionItemDate, dateToRfc3339, dateToRfc822, absoluteUrl, htmlToAbsoluteUrls and feedHtml. */
403
+ export function rssPlugin(): BuiltinPlugin;
404
+ /** The newest `date` in a collection, for a feed's `updated`. */
405
+ export function getNewestCollectionItemDate(collection: unknown[]): Date | undefined;
406
+ /** A date as RFC 3339 (`2024-06-01T00:00:00Z`), for Atom feeds. */
407
+ export function dateToRfc3339(date: Date | string): string;
408
+ /** A date as RFC 822 (`Sat, 01 Jun 2024 00:00:00 +0000`), for RSS feeds. */
409
+ export function dateToRfc822(date: Date | string): string;
410
+ /** A URL made absolute against the site's address: `absoluteUrl(post.url, "https://example.com")`. */
411
+ export function absoluteUrl(url: string, base: string): string;
412
+ /** Every link and image in some HTML made absolute, for a feed's content. */
413
+ export function htmlToAbsoluteUrls(html: string, base: string): string;
414
+ /** A post's HTML for a feed: each local image points at one generated copy (`width` 1200 and the source's format by default), page-only attributes go, and every URL is made absolute against `base`, the post's address. The images are made by the image plugin, so the config needs `imagePlugin()` too. */
415
+ export function feedHtml(html: string, base: string, options?: { width?: number | "auto"; format?: string }): string;
416
+ }
417
+
418
+ declare module "ssqch/minify" {
419
+ import type { BuiltinPlugin } from "ssqch";
420
+
421
+ export interface MinifyOptions {
422
+ /** Default `true`. */
423
+ collapseWhitespace?: boolean;
424
+ /** Default `true`. */
425
+ removeComments?: boolean;
426
+ /** Default `true`. */
427
+ shortDoctype?: boolean;
428
+ /** Drop boolean attributes' values (`defer="defer"` to `defer`) and extra whitespace in `class`, `srcset`, URLs and the viewport `<meta>`. Default `true`. */
429
+ shortenAttributes?: boolean;
430
+ }
431
+
432
+ /** Minifies HTML output, after the image transform, with ssqch's own minifier (Rust, as WebAssembly): it doesn't write html-minifier-terser's bytes. */
433
+ export function minifyPlugin(options?: MinifyOptions): BuiltinPlugin;
434
+ /** Minify one string of HTML, with the plugin's options. */
435
+ export function minify(html: string, options?: MinifyOptions): string;
436
+ }
437
+
438
+ declare module "ssqch/assets" {
439
+ import type { BuiltinPlugin } from "ssqch";
440
+
441
+ export interface AssetsPluginOptions {
442
+ /** URL paths of files in the output to fingerprint, like `["/assets/index.css"]`. */
443
+ files: string[];
444
+ /** Default: production builds only. */
445
+ fingerprint?: boolean;
446
+ /** Add `integrity="sha384-..."` (subresource integrity) to the `<link>` and `<script>` elements that load a fingerprinted file. Default `false`. */
447
+ integrity?: boolean;
448
+ }
449
+
450
+ /** Renames each file to `name.<hash>.ext` in production builds and rewrites the links to it. */
451
+ export function assetsPlugin(options: AssetsPluginOptions): BuiltinPlugin;
452
+ }
453
+
454
+ declare module "ssqch/links" {
455
+ import type { BuiltinPlugin } from "ssqch";
456
+
457
+ export interface LinksPluginOptions {
458
+ /** Check `#fragments` against the target page's ids. Default `true`. */
459
+ anchors?: boolean;
460
+ /** URL path prefixes to skip, like `["/downloads/"]`. */
461
+ ignore?: string[];
462
+ /** Fail the build on a broken link. Default: production builds only. A build lists the first 20 broken links; `--verbose` lists them all. */
463
+ fail?: boolean;
464
+ /** The site's address, like `"https://example.com"`, so absolute links to it are checked too. Default: the address `sitemap.xml` uses. */
465
+ url?: string;
466
+ }
467
+
468
+ /** Checks every internal link and anchor after each build: in HTML attributes, `<meta>` URLs, JSON-LD, and feeds and other XML. */
469
+ export function linksPlugin(options?: LinksPluginOptions): BuiltinPlugin;
470
+ }
471
+
472
+ declare module "ssqch/sitemap" {
473
+ import type { BuiltinPlugin } from "ssqch";
474
+
475
+ export interface SitemapPluginOptions {
476
+ /** The site's address, like `"https://example.com"`. */
477
+ url: string;
478
+ /** URL globs to leave out, like `["/tags/**"]`. Pages with `sitemap: false` and 404 pages are always left out. */
479
+ exclude?: string[];
480
+ /** Add `<lastmod>` from each page's date. Default `true`. */
481
+ lastmod?: boolean;
482
+ /** Where to write it. Default `"/sitemap.xml"`. */
483
+ output?: string;
484
+ /** 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`. */
485
+ paginated?: boolean;
486
+ /** A page's translations, as `<xhtml:link rel="alternate" hreflang>` links under its `<loc>` (Google's way to list them): a function that gets each page (`url`, `inputPath`, `outputPath`, `date`, `data`) and returns `[{ hreflang: "fr", href: "/fr/guide/" }]`, the page itself included, or nothing. An `href` from the site's root gets the `url` and `base` in front. It's called at once, for each page in the sitemap. */
487
+ alternates?: (page: { url: string; inputPath: string; outputPath: string; date: Date; data: Record<string, any> }) => Array<{ hreflang: string; href: string }> | undefined | null;
488
+ }
489
+
490
+ /** Writes `sitemap.xml` listing every HTML page. */
491
+ export function sitemapPlugin(options: SitemapPluginOptions): BuiltinPlugin;
492
+ }
493
+
494
+ declare module "ssqch/elements" {
495
+ import type { BuiltinPlugin } from "ssqch";
496
+
497
+ export interface ElementsPluginOptions {
498
+ /** The folder with the elements' files, relative to the project root. Default: `elements` in the input folder. */
499
+ dir?: string;
500
+ /** Where that folder goes in the output. Default `"/elements/"`. */
501
+ url?: string;
502
+ /** When scripts load, for tags without `ssqch:load`: with the page (`"eager"`, the default), when the browser is idle, or when the element scrolls into view. */
503
+ load?: "eager" | "idle" | "visible";
504
+ }
505
+
506
+ /** Custom elements: `like-button.js` in the elements folder loads on the pages that have a `<like-button>`, and nowhere else. */
507
+ export function elementsPlugin(options?: ElementsPluginOptions): BuiltinPlugin;
508
+ }
509
+
510
+ declare module "ssqch/redirects" {
511
+ import type { BuiltinPlugin } from "ssqch";
512
+
513
+ export interface RedirectsPluginOptions {
514
+ /** Write a redirect page (meta refresh, canonical link, `noindex`) at each old URL. Default `true`. */
515
+ pages?: boolean;
516
+ /** Add `/old /new 301` lines to `_redirects`, after any your own `_redirects` template writes. Default `false`. */
517
+ netlify?: boolean;
518
+ /** Redirects that aren't a page's `aliases`: `{ "/old/": "/new/" }`. The new URL can be on another site. */
519
+ redirects?: Record<string, string>;
520
+ }
521
+
522
+ /** Redirects from each page's `aliases` front matter and from `redirects`. */
523
+ export function redirectsPlugin(options?: RedirectsPluginOptions): BuiltinPlugin;
524
+ }
525
+
526
+ declare module "ssqch/sass" {
527
+ import type { BuiltinPlugin } from "ssqch";
528
+
529
+ export interface SassPluginOptions {
530
+ /** Sources (relative to the project root) to output URL paths. A folder compiles every `.scss` and `.sass` file in it that doesn't start with `_`, keeping their paths: `{ "src/scss": "/css" }`. A file compiles to the path given: `{ "src/app.scss": "/app.css" }`. */
531
+ files: Record<string, string>;
532
+ /** Default: `"compressed"` for production builds, `"expanded"` otherwise. */
533
+ style?: "compressed" | "expanded";
534
+ /** More folders `@use` and `@import` look in, relative to the project root. */
535
+ loadPaths?: string[];
536
+ }
537
+
538
+ /** Compiles Sass at the start of each build, with grass (Rust, as WebAssembly: no Dart Sass), so fingerprinting and the link checker see the CSS. */
539
+ export function sassPlugin(options: SassPluginOptions): BuiltinPlugin;
540
+ }
@@ -0,0 +1,11 @@
1
+ ---
2
+ layout: layout.edge
3
+ ---
4
+ <p>{{ site.description }}</p>
5
+
6
+ <h2>Posts</h2>
7
+ <ul>
8
+ @each(post in collections.newestPosts)
9
+ <li><a href="{{ post.url }}">{{ post.data.title }}</a> ({{ readableDate(post.date) }})</li>
10
+ @end
11
+ </ul>
@@ -0,0 +1,11 @@
1
+ ---
2
+ layout: layout.jinja
3
+ ---
4
+ <p><%= site.description %></p>
5
+
6
+ <h2>Posts</h2>
7
+ <ul>
8
+ <%_ for (const post of collections.newestPosts) { _%>
9
+ <li><a href="<%= post.url %>"><%= post.data.title %></a> (<%= readableDate(post.date) %>)</li>
10
+ <%_ } _%>
11
+ </ul>
@@ -0,0 +1,11 @@
1
+ ---
2
+ layout: layout.hbs
3
+ ---
4
+ <p>{{site.description}}</p>
5
+
6
+ <h2>Posts</h2>
7
+ <ul>
8
+ {{#each collections.newestPosts}}
9
+ <li><a href="{{url}}">{{data.title}}</a> ({{readableDate date}})</li>
10
+ {{/each}}
11
+ </ul>
@@ -0,0 +1,11 @@
1
+ ---
2
+ layout: layout.liquid
3
+ ---
4
+ <p>{{ site.description }}</p>
5
+
6
+ <h2>Posts</h2>
7
+ <ul>
8
+ {% for post in collections.newestPosts %}
9
+ <li><a href="{{ post.url }}">{{ post.data.title }}</a> ({{ post.date | readableDate }})</li>
10
+ {% endfor %}
11
+ </ul>
@@ -0,0 +1,35 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>{{ title ? `${title} | ${site.title}` : site.title }}</title>
7
+ <meta name="description" content="{{ description || site.description }}">
8
+ <style>
9
+ /* Ranger Station '76: soft white (or green charcoal in dark mode), neutral text, pine
10
+ headings, burnt orange links, and a four-color stripe under the header. */
11
+ :root { color-scheme: light dark; --page: #fafaf7; --text: #29332c; --heading: #233b2b; --muted: #5e6a61; --link: #a23e20; --rule: #dcddd4; --stripe-pine: #233b2b; }
12
+ @media (prefers-color-scheme: dark) { :root { --page: #1b201d; --text: #e5e9e1; --heading: #d6e4c8; --muted: #a2aca3; --link: #f0a17d; --rule: #3a413b; --stripe-pine: #2e5a3c; } }
13
+ body { font-family: system-ui, sans-serif; line-height: 1.6; max-width: 40rem; margin: 2rem auto; padding: 0 1rem; color: var(--text); background: var(--page); }
14
+ h1, h2, h3 { color: var(--heading); }
15
+ a { color: var(--link); text-decoration: underline; text-underline-offset: 0.18em; }
16
+ header { padding-bottom: 0.75rem; border-bottom: 5px solid; border-image: linear-gradient(to right, var(--stripe-pine) 0 25%, #a23e20 25% 50%, #e8af43 50% 75%, #a9b66a 75%) 1; }
17
+ header a { color: var(--heading); font-weight: 700; font-size: 1.15rem; text-decoration: none; }
18
+ footer { margin-top: 3rem; padding-top: 0.75rem; border-top: 1px solid var(--rule); color: var(--muted); font-size: 0.9rem; }
19
+ img { max-width: 100%; height: auto; }
20
+ :focus-visible { outline: 2px solid var(--link); outline-offset: 2px; }
21
+ </style>
22
+ </head>
23
+ <body>
24
+ <header><a href="/">{{ site.title }}</a></header>
25
+ <main>
26
+ @if(title)
27
+ <h1>{{ title }}</h1>
28
+ @end
29
+ {{{ content }}}
30
+ </main>
31
+ <footer>
32
+ <p>Built with SiteSquatch {{ ssqch.version }}. Allegedly.</p>
33
+ </footer>
34
+ </body>
35
+ </html>