ssqch 0.8.0 → 0.10.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 (87) hide show
  1. package/README.md +3 -1
  2. package/bundled/docs/agents.md +70 -0
  3. package/bundled/docs/benchmarks.md +29 -0
  4. package/bundled/docs/build-summary.md +27 -0
  5. package/bundled/docs/comparing-builds.md +51 -0
  6. package/bundled/docs/configuring.md +138 -0
  7. package/bundled/docs/content-schemas.md +54 -0
  8. package/bundled/docs/css-and-javascript.md +33 -0
  9. package/bundled/docs/data-files.md +55 -0
  10. package/bundled/docs/deploying.md +47 -0
  11. package/bundled/docs/field-guide.md +144 -0
  12. package/bundled/docs/footprint.md +27 -0
  13. package/bundled/docs/github-pages.md +41 -0
  14. package/bundled/docs/index.md +26 -0
  15. package/bundled/docs/install.md +27 -0
  16. package/bundled/docs/known-gaps.md +18 -0
  17. package/bundled/docs/markdown.md +114 -0
  18. package/bundled/docs/multilingual.md +14 -0
  19. package/bundled/docs/nav.yml +50 -0
  20. package/bundled/docs/netlify.md +30 -0
  21. package/bundled/docs/new-pages.md +42 -0
  22. package/bundled/docs/plugins.md +13 -0
  23. package/bundled/docs/rust-plugins.md +32 -0
  24. package/bundled/docs/seo.md +19 -0
  25. package/bundled/docs/template-languages.md +106 -0
  26. package/bundled/docs/templates.md +37 -0
  27. package/bundled/docs/themes.md +31 -0
  28. package/bundled/{trailheads → docs/trailheads}/from-component-frameworks.md +7 -3
  29. package/bundled/{trailheads → docs/trailheads}/from-docusaurus.md +7 -4
  30. package/bundled/{trailheads → docs/trailheads}/from-eleventy.md +7 -4
  31. package/bundled/{trailheads → docs/trailheads}/from-hexo.md +7 -4
  32. package/bundled/docs/trailheads/from-jekyll.md +82 -0
  33. package/bundled/{trailheads → docs/trailheads}/from-mkdocs.md +8 -5
  34. package/bundled/{trailheads → docs/trailheads}/from-zola.md +6 -3
  35. package/bundled/docs/trailheads.md +38 -0
  36. package/bundled/docs/where-values-come-from.md +57 -0
  37. package/bundled/ssqch.d.ts +20 -10
  38. package/lib/assets.js +15 -7
  39. package/lib/{chunk-N5QTGQ5N.js → chunk-2LEOPLTZ.js} +2 -2
  40. package/lib/{chunk-AMBFWPZ4.js → chunk-3EPHKJEG.js} +3 -3
  41. package/lib/{chunk-BRK4MXXO.js → chunk-3HHRKG33.js} +65 -18
  42. package/lib/{chunk-EIT4ZDT4.js → chunk-5DNDSNTP.js} +61 -5
  43. package/lib/{chunk-NUKCUDC4.js → chunk-7HXCQEGA.js} +3 -3
  44. package/lib/{chunk-6XYSFG6V.js → chunk-BGCBSQ4A.js} +3067 -3054
  45. package/lib/{chunk-RI2L3VGO.js → chunk-CB6YFUXU.js} +19 -11
  46. package/lib/{chunk-JSPSMIJ2.js → chunk-DMVJ53SM.js} +9 -9
  47. package/lib/{chunk-FYGE634X.js → chunk-DW7VMJEZ.js} +9 -9
  48. package/lib/{chunk-GSKVRAHF.js → chunk-E5UB2YY7.js} +6 -6
  49. package/lib/{chunk-DHHQKW4F.js → chunk-EEJDLCD3.js} +7 -7
  50. package/lib/{chunk-TWCVHOKO.js → chunk-HDQ4SRWM.js} +125 -4
  51. package/lib/{chunk-JRT7TQQP.js → chunk-HGJ5VWUR.js} +1 -1
  52. package/lib/{chunk-C35KIPAR.js → chunk-JWCCVTTR.js} +98 -7
  53. package/lib/{chunk-EZZUUPI4.js → chunk-JXZT5L7W.js} +2 -2
  54. package/lib/{chunk-KBGE5MCY.js → chunk-LAV3DEY4.js} +1 -1
  55. package/lib/{chunk-IRHRK7XB.js → chunk-LCPSKHAV.js} +1 -1
  56. package/lib/{chunk-3PHCFZEU.js → chunk-N4O5MDIB.js} +2 -2
  57. package/lib/{chunk-TDGBQNGW.js → chunk-NFJJKDRI.js} +1 -1
  58. package/lib/{chunk-UGEGUUBT.js → chunk-NUUEOGLZ.js} +8 -8
  59. package/lib/{chunk-VVPZ5PDP.js → chunk-Q4LFTYK2.js} +11 -11
  60. package/lib/{chunk-TN6EEDX2.js → chunk-QMA7CK7B.js} +51 -6
  61. package/lib/{chunk-CDEPYU7W.js → chunk-RJFWTW2Y.js} +2 -2
  62. package/lib/{chunk-YSH2NMIE.js → chunk-RKFZSVNF.js} +6 -6
  63. package/lib/{chunk-GOE4ZSAB.js → chunk-RM5Q3KFB.js} +9 -9
  64. package/lib/{chunk-37KSIVNY.js → chunk-RVBNVGZV.js} +3 -3
  65. package/lib/{chunk-HR2RU2LY.js → chunk-SA5KSJ4Y.js} +11 -7
  66. package/lib/{chunk-BOBPVAX2.js → chunk-SRNLKWXL.js} +424 -78
  67. package/lib/{chunk-WP3RPVUM.js → chunk-Y2ESFAAD.js} +2 -3
  68. package/lib/{chunk-WMOVCQO6.js → chunk-ZM6TU2JB.js} +6 -6
  69. package/lib/cli.js +32 -25
  70. package/lib/elements.js +7 -7
  71. package/lib/image.js +8 -8
  72. package/lib/links.js +10 -10
  73. package/lib/minify.js +7 -7
  74. package/lib/redirects.js +8 -8
  75. package/lib/rss.js +20 -19
  76. package/lib/sass.js +45 -10
  77. package/lib/sitemap.js +36 -11
  78. package/lib/ssqch.js +4 -4
  79. package/package.json +2 -2
  80. package/types/image.d.ts +5 -5
  81. package/types/index.d.ts +12 -4
  82. package/types/rss.d.ts +1 -1
  83. package/types/sitemap.d.ts +2 -0
  84. package/wasm/markdown.wasm +0 -0
  85. package/bundled/README.md +0 -1247
  86. package/lib/{chunk-6XYSFG6V.js.LEGAL.txt → chunk-BGCBSQ4A.js.LEGAL.txt} +3 -3
  87. /package/lib/{chunk-BOBPVAX2.js.LEGAL.txt → chunk-SRNLKWXL.js.LEGAL.txt} +0 -0
package/lib/sass.js CHANGED
@@ -5,30 +5,30 @@ import {
5
5
  } from "./chunk-3NYSSA2C.js";
6
6
  import {
7
7
  Options
8
- } from "./chunk-JRT7TQQP.js";
8
+ } from "./chunk-HGJ5VWUR.js";
9
9
  import {
10
10
  BUILTINS,
11
11
  cssWithBase,
12
12
  debugString,
13
13
  wasi
14
- } from "./chunk-TN6EEDX2.js";
15
- import "./chunk-IRHRK7XB.js";
14
+ } from "./chunk-QMA7CK7B.js";
15
+ import "./chunk-LCPSKHAV.js";
16
16
  import "./chunk-NKXEPHRZ.js";
17
17
  import "./chunk-AD3HAW3W.js";
18
18
  import "./chunk-DDV6JEC2.js";
19
19
  import {
20
20
  WebAssembly
21
- } from "./chunk-EIT4ZDT4.js";
21
+ } from "./chunk-5DNDSNTP.js";
22
22
  import "./chunk-FVZ5JBRI.js";
23
- import "./chunk-TDGBQNGW.js";
23
+ import "./chunk-NFJJKDRI.js";
24
24
  import "./chunk-UU43WIZG.js";
25
- import "./chunk-C35KIPAR.js";
25
+ import "./chunk-JWCCVTTR.js";
26
26
  import "./chunk-CMUWRPSQ.js";
27
27
  import {
28
28
  BuildError,
29
29
  bail,
30
30
  messageOf
31
- } from "./chunk-6XYSFG6V.js";
31
+ } from "./chunk-BGCBSQ4A.js";
32
32
  import {
33
33
  comparePaths,
34
34
  displayPath,
@@ -97,7 +97,7 @@ BUILTINS.set("ssqch/sass", (config, given) => {
97
97
  config.fileBuilders.push(["ssqch/sass", (config2) => {
98
98
  const chosen = style ?? (config2.env === "production" && !config2.serving ? "compressed" : "expanded");
99
99
  const used = startReading(config2, "ssqch/sass");
100
- const compiler = new Compiler(config2.root, used);
100
+ const compiler = new Compiler(config2.root, used, loadPaths.map((dir) => path.resolve(config2.root, dir)));
101
101
  const options = JSON.stringify({ style: chosen, loadPaths: loadPaths.map((dir) => compiler.name(path.resolve(config2.root, dir))) });
102
102
  const out = [];
103
103
  for (const [from, to] of files) {
@@ -119,9 +119,44 @@ var active;
119
119
  var Compiler = class {
120
120
  root;
121
121
  used;
122
- constructor(root, used) {
122
+ loadPaths;
123
+ constructor(root, used, loadPaths = []) {
123
124
  this.root = root;
124
125
  this.used = used;
126
+ this.loadPaths = loadPaths;
127
+ }
128
+ /**
129
+ * A stylesheet as grass should read it. Two things other compilers take that grass doesn't:
130
+ *
131
+ * - Front matter (Jekyll's `---` lines at the top of a site's main stylesheet) becomes blank
132
+ * lines, so error lines still match the file. Sass can't start with `---`, so nothing that
133
+ * compiled before reads differently.
134
+ * - An `@import`, `@use` or `@forward` that names its extension (`"primer-core/index.scss"`)
135
+ * is found in the load paths too: grass 0.13 looks for one only beside the importing file
136
+ * (`find_import`, "todo: consider load paths"), and Dart Sass and Ruby Sass look in both.
137
+ * Where the file isn't beside the importer but is in a load path, the import names it from
138
+ * the importer's folder. primer's packages all import this way (opensource.guide, osg #10).
139
+ */
140
+ source(file, data) {
141
+ if (!isSass(file)) return data;
142
+ let text = data.toString("utf8");
143
+ const front = /^---[ \t]*\r?\n(?:[\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/.exec(text);
144
+ if (front) text = front[0].replace(/[^\n]/g, "") + text.slice(front[0].length);
145
+ const dir = path.dirname(file);
146
+ const exists = (base, name) => {
147
+ const full = path.resolve(base, name);
148
+ const partial = path.join(path.dirname(full), `_${path.basename(full)}`);
149
+ return fs.existsSync(full) ? full : fs.existsSync(partial) ? partial : void 0;
150
+ };
151
+ const changed = text.replace(/@(import|use|forward)(\s+)([^;{}]+)/g, (statement, rule, space, rest) => `@${rule}${space}${rest.replace(/(["'])([^"'\n]+\.s[ac]ss)\1/g, (quoted, q, name) => {
152
+ if (path.isAbsolute(name) || /^[a-z]+:/i.test(name) || exists(dir, name)) return quoted;
153
+ for (const load of this.loadPaths) {
154
+ const found = exists(load, name);
155
+ if (found) return `${q}${slashes(path.relative(dir, path.join(path.dirname(found), path.basename(name))))}${q}`;
156
+ }
157
+ return quoted;
158
+ })}`);
159
+ return front || changed !== text ? Buffer.from(changed, "utf8") : data;
125
160
  }
126
161
  /** A path as grass sees it: from the root for the site's own files, else whole; with `/`. */
127
162
  name(file) {
@@ -196,7 +231,7 @@ function instance() {
196
231
  read: (ptr, len, out) => {
197
232
  const file = active.file(text(ptr, len));
198
233
  try {
199
- const data = fs.readFileSync(file);
234
+ const data = active.source(file, fs.readFileSync(file));
200
235
  active.used.add(realPath(file));
201
236
  return reply(out, 0, data);
202
237
  } catch (e) {
package/lib/sitemap.js CHANGED
@@ -2,29 +2,29 @@ import { createRequire as __ssqchCreateRequire } from "node:module";
2
2
  const require = __ssqchCreateRequire(import.meta.url);
3
3
  import {
4
4
  Options
5
- } from "./chunk-JRT7TQQP.js";
5
+ } from "./chunk-HGJ5VWUR.js";
6
6
  import {
7
7
  BUILTINS,
8
8
  debugString,
9
9
  escapeHtml,
10
10
  isoDay
11
- } from "./chunk-TN6EEDX2.js";
12
- import "./chunk-IRHRK7XB.js";
11
+ } from "./chunk-QMA7CK7B.js";
12
+ import "./chunk-LCPSKHAV.js";
13
13
  import "./chunk-NKXEPHRZ.js";
14
14
  import "./chunk-AD3HAW3W.js";
15
15
  import "./chunk-DDV6JEC2.js";
16
- import "./chunk-EIT4ZDT4.js";
16
+ import "./chunk-5DNDSNTP.js";
17
17
  import "./chunk-FVZ5JBRI.js";
18
18
  import {
19
19
  globSet
20
- } from "./chunk-TDGBQNGW.js";
20
+ } from "./chunk-NFJJKDRI.js";
21
21
  import "./chunk-UU43WIZG.js";
22
- import "./chunk-C35KIPAR.js";
22
+ import "./chunk-JWCCVTTR.js";
23
23
  import "./chunk-CMUWRPSQ.js";
24
24
  import {
25
25
  bail,
26
26
  toDate
27
- } from "./chunk-6XYSFG6V.js";
27
+ } from "./chunk-BGCBSQ4A.js";
28
28
  import {
29
29
  compareText
30
30
  } from "./chunk-VJWQSYEG.js";
@@ -42,7 +42,9 @@ function isLaterPage(data) {
42
42
  return number > 0 && size > 1;
43
43
  }
44
44
  BUILTINS.set("ssqch/sitemap", (config, given) => {
45
- const o = new Options(given, ["url", "exclude", "lastmod", "output", "paginated"]);
45
+ const o = new Options(given, ["url", "exclude", "lastmod", "output", "paginated", "alternates"]);
46
+ const alternates = o.get("alternates");
47
+ if (alternates !== void 0 && typeof alternates !== "function") bail(`alternates must be a function that gets each page and returns its translations, like (page) => [{ hreflang: "fr", href: "/fr/" }] (got ${typeof alternates})`);
46
48
  const url = o.string("url");
47
49
  if (url === void 0) bail(`url is required: the site's address, like "https://example.com"`);
48
50
  const exclude = o.list("exclude") ?? [];
@@ -60,20 +62,43 @@ BUILTINS.set("ssqch/sitemap", (config, given) => {
60
62
  const trimmed = url.replace(/\/+$/, "");
61
63
  const withBase = trimmed.endsWith(config2.base) ? trimmed : trimmed + config2.base;
62
64
  const entries = [];
65
+ const absolute = (href) => href.startsWith("/") ? withBase + href : href;
66
+ const linksOf = (p) => {
67
+ if (!alternates) return [];
68
+ let out;
69
+ try {
70
+ out = alternates(p);
71
+ } catch (e) {
72
+ bail(`alternates(), for ${p.url}: ${e instanceof Error ? e.message : String(e)}`);
73
+ }
74
+ if (out === void 0 || out === null) return [];
75
+ if (out instanceof Promise) bail("alternates() answered with a promise; it has to answer at once (work the translations out in data or a collection first)");
76
+ if (!Array.isArray(out)) bail(`alternates(), for ${p.url}: expected a list of { hreflang, href } (got ${typeof out})`);
77
+ return out.map((a) => {
78
+ const { hreflang, href } = a ?? {};
79
+ if (typeof hreflang !== "string" || hreflang === "" || typeof href !== "string" || !(href.startsWith("/") || /^https?:\/\//.test(href))) bail(`alternates(), for ${p.url}: each one is { hreflang: "fr", href: "/fr/page/" } (an href from the site's root, or a whole address), got ${JSON.stringify(a) ?? String(a)}`);
80
+ return [hreflang, absolute(href)];
81
+ });
82
+ };
63
83
  for (const p of pages) {
64
84
  if (path.extname(p.outputPath) !== ".html") continue;
65
85
  if (p.data.sitemap === false) continue;
66
86
  if (!paginated && isLaterPage(p.data)) continue;
67
87
  if (p.url === "/404.html" || p.url === "/404/") continue;
68
88
  if (excluded(p.url)) continue;
69
- entries.push([p.url, isoDay(toDate(p.data.page?.lastModified) ?? p.date)]);
89
+ entries.push([p.url, isoDay(toDate(p.data.page?.lastModified) ?? p.date), linksOf(p)]);
70
90
  }
71
91
  entries.sort((a, b) => compareText(a[0], b[0]) || compareText(a[1], b[1]));
72
92
  const loc = escapeHtml(withBase);
73
- let xml = '<?xml version="1.0" encoding="utf-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';
74
- for (const [pageUrl, date] of entries) {
93
+ const xhtml = entries.some((e) => e[2].length) ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : "";
94
+ let xml = `<?xml version="1.0" encoding="utf-8"?>
95
+ <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${xhtml}>
96
+ `;
97
+ for (const [pageUrl, date, links] of entries) {
75
98
  xml += ` <url>
76
99
  <loc>${loc}${escapeHtml(pageUrl)}</loc>
100
+ `;
101
+ for (const [hreflang, href] of links) xml += ` <xhtml:link rel="alternate" hreflang="${escapeHtml(hreflang)}" href="${escapeHtml(href)}"/>
77
102
  `;
78
103
  if (lastmod) xml += ` <lastmod>${date}</lastmod>
79
104
  `;
package/lib/ssqch.js CHANGED
@@ -8,13 +8,13 @@ import {
8
8
  readData,
9
9
  slugger,
10
10
  slugify
11
- } from "./chunk-EIT4ZDT4.js";
11
+ } from "./chunk-5DNDSNTP.js";
12
12
  import "./chunk-FVZ5JBRI.js";
13
- import "./chunk-TDGBQNGW.js";
13
+ import "./chunk-NFJJKDRI.js";
14
14
  import "./chunk-UU43WIZG.js";
15
- import "./chunk-C35KIPAR.js";
15
+ import "./chunk-JWCCVTTR.js";
16
16
  import "./chunk-CMUWRPSQ.js";
17
- import "./chunk-6XYSFG6V.js";
17
+ import "./chunk-BGCBSQ4A.js";
18
18
  import "./chunk-VJWQSYEG.js";
19
19
  import "./chunk-I3PS26CI.js";
20
20
  export {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ssqch",
3
- "version": "0.8.0",
3
+ "version": "0.10.0",
4
4
  "description": "SiteSquatch (ssqch): a fast static site generator, configured with JavaScript",
5
5
  "keywords": [
6
6
  "static site generator",
@@ -12,7 +12,7 @@
12
12
  "liquid",
13
13
  "edge"
14
14
  ],
15
- "homepage": "https://github.com/reverentgeek/sitesquatch#readme",
15
+ "homepage": "https://sitesquatch.dev",
16
16
  "repository": {
17
17
  "type": "git",
18
18
  "url": "git+https://github.com/reverentgeek/sitesquatch.git",
package/types/image.d.ts CHANGED
@@ -17,13 +17,13 @@ export interface ImagePluginOptions {
17
17
  outputDir?: string;
18
18
  /** URL path they're served from. Default `/img/`. */
19
19
  urlPath?: string;
20
- /** WebP quality, sharp's: a whole number from 1 to 100. Default 75 (0.7's 75 too: WebP's numbers didn't change). */
20
+ /** WebP quality, sharp's: a whole number from 1 to 100. Default 75. */
21
21
  webpQuality?: number;
22
- /** AVIF quality, sharp's: a whole number from 1 to 100. Default 41, which looks like 0.7's default of 50 (0.7's 60 is 48; the changelog has the table). */
22
+ /** AVIF quality, sharp's: a whole number from 1 to 100. Default 41. */
23
23
  avifQuality?: number;
24
- /** sharp's AVIF effort: a whole number from 0 (fastest) to 9 (slowest, smallest files). Default 2. Replaces 0.7's `avifSpeed`: speed 8 is effort 2, speed 4 is effort 3. */
24
+ /** sharp's AVIF effort: a whole number from 0 (fastest) to 9 (slowest, smallest files). Default 2. */
25
25
  avifEffort?: number;
26
- /** JPEG quality, sharp's (mozjpeg): a whole number from 1 to 100. Default 89, which looks like 0.7's default of 80. */
26
+ /** JPEG quality, sharp's (mozjpeg): a whole number from 1 to 100. Default 89. */
27
27
  jpegQuality?: number;
28
28
  /** A width larger than the original is clamped to it only when the width before it is this many times smaller. Default 1.25. */
29
29
  minimumThreshold?: number;
@@ -52,7 +52,7 @@ export interface ImageEntry {
52
52
  size: number;
53
53
  }
54
54
 
55
- /** Turns every local `<img>` in HTML output into a `<picture>`, encoded by sharp (AVIF needs no build feature). `[ssqch] Encoded ...` lines come as each image's files are done, while pages go on rendering. */
55
+ /** 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. */
56
56
  export function imagePlugin(options?: ImagePluginOptions): BuiltinPlugin;
57
57
 
58
58
  /** 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. */
package/types/index.d.ts CHANGED
@@ -52,7 +52,7 @@ export type Highlighter = ((code: string, lang: string) => Token[]) | string;
52
52
 
53
53
  /** How Markdown renders. */
54
54
  export interface MarkdownOptions {
55
- /** Automatic heading `id`s: `"github"` (the default), `"blackfriday"` (Hugo's older style: `a-b` for `A -- B`), or `false` for none. A `{#id}` on the heading always wins. */
55
+ /** 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. */
56
56
  headingIds?: "github" | "blackfriday" | "ascii" | false | ((text: string) => string);
57
57
  /** `## Heading {#id .class key=value}`. Default `true`. */
58
58
  headingAttributes?: boolean;
@@ -100,6 +100,10 @@ export interface TransformPage {
100
100
  export interface BuildEvent {
101
101
  env: "production" | "development";
102
102
  serving: boolean;
103
+ /** The build was run with `--quiet`: print only warnings and errors. */
104
+ quiet: boolean;
105
+ /** The build was run with `--verbose`. */
106
+ verbose: boolean;
103
107
  /** Folders relative to the project root, like `./src/`. */
104
108
  dirs: { input: string; output: string; includes: string; data: string };
105
109
  /** The files the build wrote (`afterBuild` only). */
@@ -107,7 +111,7 @@ export interface BuildEvent {
107
111
  }
108
112
 
109
113
  type MaybePromise<T> = T | Promise<T>;
110
- /** 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_INPUT` and `SSQCH_OUTPUT`; a failure fails the build. */
114
+ /** 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. */
111
115
  type Hook = ((event: BuildEvent) => MaybePromise<void>) | { run: string };
112
116
  /** Renders a template's body (front matter removed) with the page's data. */
113
117
  type EngineRender = (source: string, data: Record<string, any>) => MaybePromise<string>;
@@ -159,7 +163,7 @@ export interface ConfigParts {
159
163
  name?: string;
160
164
  /** Functions templates can call: `{{ slug(title) }}`. Async functions are awaited. */
161
165
  filters?: Record<string, (...args: any[]) => unknown>;
162
- /** Data for every template. A function (sync or async) is called on each build. */
166
+ /** 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. */
163
167
  data?: Record<string, unknown>;
164
168
  /** Custom collections, from the pages in collections. */
165
169
  collections?: Record<string, (pages: Pages) => unknown>;
@@ -222,6 +226,10 @@ export interface Config extends ConfigParts {
222
226
  strict?: boolean;
223
227
  /** `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`). */
224
228
  lastModified?: "git" | "file" | false;
229
+ /** The date of a page with no date of its own (in its data or its file name): `"git"` for the last commit that changed its file, the same in every checkout, or `"file"` (the default) for the file's modification time, which is when the checkout wrote it. Either way it sorts after the dated pages, by path. Needs the full history in CI (`fetch-depth: 0`). */
230
+ dateFallback?: "git" | "file";
231
+ /** 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. */
232
+ timeZone?: string;
225
233
  /** 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. */
226
234
  base?: string;
227
235
  /** 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. */
@@ -232,7 +240,7 @@ export interface Config extends ConfigParts {
232
240
  budgets?: Partial<Record<"pages" | "images" | "css" | "javascript" | "fonts" | "media" | "documents" | "data" | "other" | "total", number | string>>;
233
241
  /** 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.) */
234
242
  serve?: {
235
- /** 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. Builds don't run them. */
243
+ /** 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. */
236
244
  run?: string | string[];
237
245
  };
238
246
  }
package/types/rss.d.ts CHANGED
@@ -10,7 +10,7 @@ export function getNewestCollectionItemDate(collection: unknown[]): Date | undef
10
10
  export function dateToRfc3339(date: Date | string): string;
11
11
  /** A date as RFC 822 (`Sat, 01 Jun 2024 00:00:00 +0000`), for RSS feeds. */
12
12
  export function dateToRfc822(date: Date | string): string;
13
- /** A URL made absolute against the site's address: `absoluteUrl(post.url, "https://example.com")`. */
13
+ /** A URL made absolute against the site's address: `absoluteUrl(post.url, "https://example.com")`. As a template filter, it puts the site's `base` in front of a URL from the root that doesn't have it yet; called from code, it resolves as `new URL(url, base)` does. */
14
14
  export function absoluteUrl(url: string, base: string): string;
15
15
  /** Every link and image in some HTML made absolute, for a feed's content. */
16
16
  export function htmlToAbsoluteUrls(html: string, base: string): string;
@@ -13,6 +13,8 @@ export interface SitemapPluginOptions {
13
13
  output?: string;
14
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`. */
15
15
  paginated?: boolean;
16
+ /** 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. */
17
+ alternates?: (page: { url: string; inputPath: string; outputPath: string; date: Date; data: Record<string, any> }) => Array<{ hreflang: string; href: string }> | undefined | null;
16
18
  }
17
19
 
18
20
  /** Writes `sitemap.xml` listing every HTML page. */
Binary file