ssqch 0.8.0 → 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 (52) hide show
  1. package/README.md +2 -0
  2. package/bundled/README.md +144 -77
  3. package/bundled/ssqch.d.ts +17 -9
  4. package/bundled/trailheads/from-jekyll.md +79 -0
  5. package/lib/assets.js +7 -7
  6. package/lib/{chunk-RI2L3VGO.js → chunk-3A647I3N.js} +19 -11
  7. package/lib/{chunk-AMBFWPZ4.js → chunk-3K3ANWZ2.js} +3 -3
  8. package/lib/{chunk-WMOVCQO6.js → chunk-47P4YREZ.js} +6 -6
  9. package/lib/{chunk-C35KIPAR.js → chunk-76NTVE34.js} +98 -7
  10. package/lib/{chunk-TWCVHOKO.js → chunk-7PWCYHTJ.js} +125 -4
  11. package/lib/{chunk-JSPSMIJ2.js → chunk-7RDRZHJD.js} +9 -9
  12. package/lib/{chunk-JRT7TQQP.js → chunk-7SD7K567.js} +1 -1
  13. package/lib/{chunk-IRHRK7XB.js → chunk-7XLK2GEG.js} +1 -1
  14. package/lib/{chunk-YSH2NMIE.js → chunk-BEGC7YP6.js} +6 -6
  15. package/lib/{chunk-HR2RU2LY.js → chunk-CZ4XQC56.js} +6 -6
  16. package/lib/{chunk-DHHQKW4F.js → chunk-D2XE2GTY.js} +7 -7
  17. package/lib/{chunk-BOBPVAX2.js → chunk-DELWRJAO.js} +373 -52
  18. package/lib/{chunk-6XYSFG6V.js → chunk-GRWMGC7D.js} +15 -3
  19. package/lib/{chunk-N5QTGQ5N.js → chunk-GUKSZ2XM.js} +1 -1
  20. package/lib/{chunk-TDGBQNGW.js → chunk-HPXAZ2HU.js} +1 -1
  21. package/lib/{chunk-3PHCFZEU.js → chunk-II5DEH3Q.js} +2 -2
  22. package/lib/{chunk-FYGE634X.js → chunk-IJWHOFRP.js} +9 -9
  23. package/lib/{chunk-UGEGUUBT.js → chunk-LPHNACE4.js} +8 -8
  24. package/lib/{chunk-KBGE5MCY.js → chunk-MI6EJWA2.js} +1 -1
  25. package/lib/{chunk-EIT4ZDT4.js → chunk-NCWFYT74.js} +61 -5
  26. package/lib/{chunk-VVPZ5PDP.js → chunk-NNUKIGOO.js} +11 -11
  27. package/lib/{chunk-TN6EEDX2.js → chunk-R7K3D5W5.js} +28 -6
  28. package/lib/{chunk-37KSIVNY.js → chunk-RNJFPFXE.js} +3 -3
  29. package/lib/{chunk-CDEPYU7W.js → chunk-SF4I6Z7S.js} +2 -2
  30. package/lib/{chunk-GSKVRAHF.js → chunk-SURPOAW7.js} +6 -6
  31. package/lib/{chunk-BRK4MXXO.js → chunk-SXMJ52IK.js} +18 -11
  32. package/lib/{chunk-EZZUUPI4.js → chunk-TICWN55Z.js} +2 -2
  33. package/lib/{chunk-NUKCUDC4.js → chunk-TVU3OPPK.js} +3 -3
  34. package/lib/{chunk-GOE4ZSAB.js → chunk-XMXBHXZR.js} +9 -9
  35. package/lib/{chunk-WP3RPVUM.js → chunk-YTHQBMDJ.js} +1 -1
  36. package/lib/cli.js +32 -25
  37. package/lib/elements.js +7 -7
  38. package/lib/image.js +8 -8
  39. package/lib/links.js +7 -7
  40. package/lib/minify.js +7 -7
  41. package/lib/redirects.js +7 -7
  42. package/lib/rss.js +8 -8
  43. package/lib/sass.js +45 -10
  44. package/lib/sitemap.js +36 -11
  45. package/lib/ssqch.js +4 -4
  46. package/package.json +1 -1
  47. package/types/image.d.ts +5 -5
  48. package/types/index.d.ts +10 -4
  49. package/types/sitemap.d.ts +2 -0
  50. package/wasm/markdown.wasm +0 -0
  51. /package/lib/{chunk-BOBPVAX2.js.LEGAL.txt → chunk-DELWRJAO.js.LEGAL.txt} +0 -0
  52. /package/lib/{chunk-6XYSFG6V.js.LEGAL.txt → chunk-GRWMGC7D.js.LEGAL.txt} +0 -0
@@ -75,7 +75,7 @@ declare module "ssqch" {
75
75
 
76
76
  /** How Markdown renders. */
77
77
  export interface MarkdownOptions {
78
- /** 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. */
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
79
  headingIds?: "github" | "blackfriday" | "ascii" | false | ((text: string) => string);
80
80
  /** `## Heading {#id .class key=value}`. Default `true`. */
81
81
  headingAttributes?: boolean;
@@ -123,6 +123,10 @@ declare module "ssqch" {
123
123
  export interface BuildEvent {
124
124
  env: "production" | "development";
125
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;
126
130
  /** Folders relative to the project root, like `./src/`. */
127
131
  dirs: { input: string; output: string; includes: string; data: string };
128
132
  /** The files the build wrote (`afterBuild` only). */
@@ -130,7 +134,7 @@ declare module "ssqch" {
130
134
  }
131
135
 
132
136
  type MaybePromise<T> = T | Promise<T>;
133
- /** 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. */
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. */
134
138
  type Hook = ((event: BuildEvent) => MaybePromise<void>) | { run: string };
135
139
  /** Renders a template's body (front matter removed) with the page's data. */
136
140
  type EngineRender = (source: string, data: Record<string, any>) => MaybePromise<string>;
@@ -182,7 +186,7 @@ declare module "ssqch" {
182
186
  name?: string;
183
187
  /** Functions templates can call: `{{ slug(title) }}`. Async functions are awaited. */
184
188
  filters?: Record<string, (...args: any[]) => unknown>;
185
- /** Data for every template. A function (sync or async) is called on each build. */
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. */
186
190
  data?: Record<string, unknown>;
187
191
  /** Custom collections, from the pages in collections. */
188
192
  collections?: Record<string, (pages: Pages) => unknown>;
@@ -245,6 +249,8 @@ declare module "ssqch" {
245
249
  strict?: boolean;
246
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`). */
247
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;
248
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. */
249
255
  base?: string;
250
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. */
@@ -255,7 +261,7 @@ declare module "ssqch" {
255
261
  budgets?: Partial<Record<"pages" | "images" | "css" | "javascript" | "fonts" | "media" | "documents" | "data" | "other" | "total", number | string>>;
256
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.) */
257
263
  serve?: {
258
- /** 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. */
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. */
259
265
  run?: string | string[];
260
266
  };
261
267
  }
@@ -324,13 +330,13 @@ declare module "ssqch/image" {
324
330
  outputDir?: string;
325
331
  /** URL path they're served from. Default `/img/`. */
326
332
  urlPath?: string;
327
- /** WebP quality, sharp's: a whole number from 1 to 100. Default 75 (0.7's 75 too: WebP's numbers didn't change). */
333
+ /** WebP quality, sharp's: a whole number from 1 to 100. Default 75. */
328
334
  webpQuality?: number;
329
- /** 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). */
335
+ /** AVIF quality, sharp's: a whole number from 1 to 100. Default 41. */
330
336
  avifQuality?: number;
331
- /** 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. */
337
+ /** sharp's AVIF effort: a whole number from 0 (fastest) to 9 (slowest, smallest files). Default 2. */
332
338
  avifEffort?: number;
333
- /** JPEG quality, sharp's (mozjpeg): a whole number from 1 to 100. Default 89, which looks like 0.7's default of 80. */
339
+ /** JPEG quality, sharp's (mozjpeg): a whole number from 1 to 100. Default 89. */
334
340
  jpegQuality?: number;
335
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. */
336
342
  minimumThreshold?: number;
@@ -359,7 +365,7 @@ declare module "ssqch/image" {
359
365
  size: number;
360
366
  }
361
367
 
362
- /** 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. */
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. */
363
369
  export function imagePlugin(options?: ImagePluginOptions): BuiltinPlugin;
364
370
 
365
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. */
@@ -477,6 +483,8 @@ declare module "ssqch/sitemap" {
477
483
  output?: string;
478
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`. */
479
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;
480
488
  }
481
489
 
482
490
  /** Writes `sitemap.xml` listing every HTML page. */
@@ -0,0 +1,79 @@
1
+ # Trailhead: moving from Jekyll
2
+
3
+ Jekyll sites move well: Liquid runs as it is, `_layouts/`, `_includes/` and `_data/` keep their names, and `redirect_from`, `relative_url`, `markdownify` and `jsonify` work. What takes the time is the Ruby around the templates (Jekyll's `page` and `site`, its plugins) and kramdown, Jekyll's Markdown.
4
+
5
+ opensource.guide (382 pages in 29 languages, on GitHub Pages' gem) was moved this way as a study: the same 478 files, 95% of pages with the same text, and builds 5.9 times faster. Two thirds of the work was kramdown's `markdown="1"`, which ssqch doesn't read yet (below).
6
+
7
+ ## Build it both ways first
8
+
9
+ Build the Jekyll site from a fresh checkout twice and compare the two: a page that prints the build's time (an undated article gets `site.time`) differs on every build. Pin it with a second config file holding `time: 2026-01-01 00:00:00 +0000` (`jekyll build --config _config.yml,pin.yml`), and build ssqch with the same time: `SOURCE_DATE_EPOCH=1767225600`. GitHub Pages' gem needs `PAGES_REPO_NWO=owner/repo` in a checkout without a git remote. Then build with ssqch into an empty folder and compare the two with `ssqch diff jekyll-site ssqch-site`.
10
+
11
+ ## The config
12
+
13
+ Start with `templateFormats: ["liquid", "md", "html"]`, `markdownEngine: "liquid"` and `htmlEngine: "liquid"`, so Markdown and HTML pages run through Liquid first, as in Jekyll, and `dirs: { layouts: "_layouts" }`.
14
+
15
+ ```js
16
+ import { defineConfig, readData } from "ssqch";
17
+ import { sitemapPlugin } from "ssqch/sitemap";
18
+ import { redirectsPlugin } from "ssqch/redirects";
19
+
20
+ const site = readData("_config.yml");
21
+
22
+ export default defineConfig({
23
+ templateFormats: ["liquid", "md", "html"],
24
+ markdownEngine: "liquid",
25
+ htmlEngine: "liquid",
26
+ dirs: { layouts: "_layouts" },
27
+ ignore: ["Gemfile", "Gemfile.lock", "README.md", "script/**"],
28
+ data: { site },
29
+ plugins: [sitemapPlugin({ url: site.url }), redirectsPlugin()],
30
+ });
31
+ ```
32
+
33
+ | Jekyll (`_config.yml`) | ssqch (`ssqch.config.js`) |
34
+ | --- | --- |
35
+ | `title`, `description`, `url`, any key | `readData("_config.yml")` as `data: { site }`, so `site.title` still works |
36
+ | `exclude: [docs, Gemfile]` | `ignore: ["docs/**", "Gemfile"]`. A Bundler install (`vendor/bundle`) is skipped by itself. |
37
+ | `_data/locales/fr.yml` as `site.data.locales.fr` | `locales.fr`: `_data` is global data, and a folder in it is an object. Add `data: { site: { ...site, data: ... } }` only if templates must keep `site.data`. |
38
+ | `collections: { guides: { output: true, permalink: "/:path/" } }` | `collections: { guides: (c) => c.byGlob("_guides/**") }`, and `_guides/_guides.json` with the permalink: `{ "permalink": "{{ page.filePathStem \| remove_first: '/_guides' }}/" }` |
39
+ | `defaults` for a `path` | Directory data in that folder: `_guides/_guides.json` with `{ "layout": "guide" }` |
40
+ | `layouts_dir` | `dirs: { layouts: "_layouts" }` |
41
+ | `sass: { load_paths }` | `sassPlugin({ files, loadPaths })` from `ssqch/sass`. Front matter on a `.scss` file is fine. |
42
+ | `time:` | `SOURCE_DATE_EPOCH=1767225600 ssqch build` (seconds since 1970): `now()` and every undated page get that time, as with `time:` |
43
+
44
+ ## Templates
45
+
46
+ - **`page` and front matter:** in ssqch, front matter is at the top level (`{{ title }}`), and `page` has the file's facts (`page.url`, `page.inputPath`, `page.date`, `page.headings`). Rename `page.title` to `title` in layouts and includes (the build warns once for each `page.<key>` that's front matter, naming a page that reads it), and look for a template whose own variable has a front matter key's name (`{% assign lang = ... %}` next to `page.lang`).
47
+ - **`site.posts` and collections:** `collections.posts` (the pages tagged `posts`) and your own collections. Items have `url` and `data`: `post.data.title`, `| where: "data.lang", "fr"`.
48
+ - **Includes:** `{% include nav.html section="home" %}` works, with `include.section`, and so does `{% include_relative parts/intro.md %}`. A file read by `include_relative` is a page of its own too, if it's Markdown: give its folder `permalink: false` in directory data.
49
+ - **Plugin tags** (`{% seo %}`, `{% feed_meta %}`): the config's functions are Liquid tags, so each is a function in `filters` that returns the HTML (`{% seo title=false %}` calls `seo({ title: false })`), or an include. `ssqch docs seo` has a starting point.
50
+ - **Filters:** `relative_url`, `markdownify` and `jsonify` work, and `where` is fast. Math, `split` and blocks that only `assign` behave as in Ruby's Liquid (`"r>" | times: 1` is 0, which jekyll-toc depends on). Jekyll's own `sort` differs from Liquid's: it sorts a hash into `[key, value]` pairs and puts pages missing the property first, where ssqch's `sort` (Liquid's) does neither, so pass a list from the config, or `sort` then handle the missing ones. A whole float prints as `5` (Ruby writes `5.0`).
51
+ - **A table of contents:** `toc(page.headings, { class: "section-nav", itemClass: "toc-entry toc-h{level}" })` writes jekyll-toc's markup, so its CSS keeps working (`{{ page.headings | toc: class: "section-nav" }}` in Liquid). It reads the page's headings after it renders, so it goes in the layout.
52
+ - **Files with front matter:** Jekyll renders any file that starts with `---`. In ssqch a `.js` (or `.txt`) file needs an engine: `engines: { js: (s) => s }`, `"js"` in `templateFormats`, and `"render": "liquid,js"` with a `.js` permalink in that folder's directory data (the README's "Text files with front matter").
53
+
54
+ ## Plugins
55
+
56
+ | Jekyll | ssqch |
57
+ | --- | --- |
58
+ | jekyll-redirect-from | `redirect_from` works (ssqch calls it `aliases`), with `redirectsPlugin()`; `_includes/hooks/redirect.*` for its page's markup |
59
+ | jekyll-sitemap | `sitemapPlugin({ url })` |
60
+ | jekyll-feed | `rssPlugin()` and a feed template |
61
+ | jekyll-seo-tag | A `seo` function (a tag), or an include with the tags you use |
62
+ | jekyll-toc | `toc(page.headings, ...)`, above |
63
+ | jekyll-github-metadata | Data in the config (`site.github.repository_nwo`) |
64
+ | github-pages' default theme (jekyll-theme-primer) | Nothing: it writes `/assets/css/style.css`. Check whether a page links to it. |
65
+
66
+ ## Markdown
67
+
68
+ ssqch's Markdown is CommonMark; Jekyll's is kramdown. `markdown: { smartPunctuation: true, autolinks: false }` comes closest. What differs:
69
+
70
+ - **`markdown="1"`** on an HTML element (kramdown reads its content as Markdown): ssqch writes the element as it is, so Markdown inside stays text. It's on the way; count them first, with `grep -rc 'markdown="1"' .`. A container (`::: name`) is ssqch's way to wrap Markdown in HTML.
71
+ - **HTML blocks** end at a blank line in CommonMark, and at their end tag in kramdown: keep blank lines out of HTML elements, or a line indented by four spaces inside one becomes code.
72
+ - **Heading ids:** kramdown's GFM ids keep accents and other letters, as ssqch's do; headings inside HTML get kramdown's ASCII ids (`section`, `section-1`).
73
+ - **Bold next to punctuation** (`**完成。**下一步`) closes in kramdown but not in CommonMark.
74
+ - **Code:** GitHub Pages adds Rouge's `class="language-plaintext highlighter-rouge"` to code; ssqch doesn't (`markdown: { highlight: true }` highlights, with its own classes).
75
+ - Smart quotes next to non-Latin letters, and non-ASCII characters in link URLs (which ssqch percent-encodes), come out differently; readers see the same page.
76
+
77
+ ## Checking the move
78
+
79
+ `ssqch diff` lists the files that differ and how. Most of what's left after the steps above is Markdown: `markdown="1"`, then kramdown's spacing and quotes. `linksPlugin()` from `ssqch/links` checks every internal link and anchor on each build.
package/lib/assets.js CHANGED
@@ -2,27 +2,27 @@ 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-7SD7K567.js";
6
6
  import {
7
7
  BUILTINS,
8
8
  blake3Hex,
9
9
  rewriteHtml
10
- } from "./chunk-TN6EEDX2.js";
11
- import "./chunk-IRHRK7XB.js";
10
+ } from "./chunk-R7K3D5W5.js";
11
+ import "./chunk-7XLK2GEG.js";
12
12
  import "./chunk-NKXEPHRZ.js";
13
13
  import "./chunk-AD3HAW3W.js";
14
14
  import "./chunk-DDV6JEC2.js";
15
- import "./chunk-EIT4ZDT4.js";
15
+ import "./chunk-NCWFYT74.js";
16
16
  import "./chunk-FVZ5JBRI.js";
17
- import "./chunk-TDGBQNGW.js";
17
+ import "./chunk-HPXAZ2HU.js";
18
18
  import "./chunk-UU43WIZG.js";
19
- import "./chunk-C35KIPAR.js";
19
+ import "./chunk-76NTVE34.js";
20
20
  import "./chunk-CMUWRPSQ.js";
21
21
  import {
22
22
  bail,
23
23
  warn,
24
24
  warning
25
- } from "./chunk-6XYSFG6V.js";
25
+ } from "./chunk-GRWMGC7D.js";
26
26
  import {
27
27
  displayPath
28
28
  } from "./chunk-VJWQSYEG.js";
@@ -2,15 +2,15 @@ import { createRequire as __ssqchCreateRequire } from "node:module";
2
2
  const require = __ssqchCreateRequire(import.meta.url);
3
3
  import {
4
4
  withBase
5
- } from "./chunk-TN6EEDX2.js";
5
+ } from "./chunk-R7K3D5W5.js";
6
6
  import {
7
7
  slugOptions,
8
8
  slugWith
9
- } from "./chunk-EIT4ZDT4.js";
9
+ } from "./chunk-NCWFYT74.js";
10
10
  import {
11
11
  BuildError,
12
12
  isPlainObject
13
- } from "./chunk-6XYSFG6V.js";
13
+ } from "./chunk-GRWMGC7D.js";
14
14
  import {
15
15
  compareText
16
16
  } from "./chunk-VJWQSYEG.js";
@@ -77,8 +77,11 @@ function excerpt(html) {
77
77
  if (more) return html.slice(0, more.index).trim();
78
78
  return /<p(?:\s[^>]*)?>.*?<\/p>/is.exec(html)?.[0];
79
79
  }
80
- function toc(list, from, to, ordered) {
80
+ function toc(list, from, to, ordered, markup = {}) {
81
81
  const tag = ordered ? "ol" : "ul";
82
+ const attr = (name, value) => value ? ` ${name}="${escapeHtml(value)}"` : "";
83
+ const open = (outer) => `<${tag}${outer ? attr("id", markup.id) + attr("class", markup.class) : attr("class", markup.sublistClass)}>`;
84
+ const link = attr("class", markup.linkClass);
82
85
  const items = [];
83
86
  for (const v of list) {
84
87
  const h = v;
@@ -91,7 +94,7 @@ function toc(list, from, to, ordered) {
91
94
  const stack = [];
92
95
  for (const h of items) {
93
96
  if (!stack.length) {
94
- out += `<${tag}>`;
97
+ out += open(true);
95
98
  stack.push(h.level);
96
99
  } else {
97
100
  while (stack.length > 1 && h.level < stack[stack.length - 1]) {
@@ -99,13 +102,13 @@ function toc(list, from, to, ordered) {
99
102
  stack.pop();
100
103
  }
101
104
  if (h.level > stack[stack.length - 1]) {
102
- out += `<${tag}>`;
105
+ out += open(false);
103
106
  stack.push(h.level);
104
107
  } else {
105
108
  out += "</li>";
106
109
  }
107
110
  }
108
- out += `<li><a href="#${escapeHtml(h.id ?? "")}">${escapeText(h.text)}</a>`;
111
+ out += `<li${attr("class", markup.itemClass?.replaceAll("{level}", String(h.level)))}><a href="#${escapeHtml(h.id ?? "")}"${link}>${escapeText(h.text)}</a>`;
109
112
  }
110
113
  for (const _ of stack) out += `</li></${tag}>`;
111
114
  return out;
@@ -312,7 +315,7 @@ function fromPages(items) {
312
315
  // src/filters.ts
313
316
  var BUILTIN_FILTERS = [
314
317
  ["markdown", '`markdown(text)` renders Markdown with the site\'s options; `markdown(text, "inline")` without the `<p>`.'],
315
- ["toc", "`toc(page.headings)` is a table of contents; `toc(page.headings, { from: 2, to: 4, ordered: true })` picks the levels."],
318
+ ["toc", "`toc(page.headings)` is a table of contents; `toc(page.headings, { from: 2, to: 4, ordered: true })` picks the levels, and `id`, `class`, `sublistClass`, `itemClass` (`{level}` is the heading's) and `linkClass` set the markup's."],
316
319
  ["navTree", "`navTree(nav, page.url)` marks a navigation tree's entries `current`, `ancestor` or `open`."],
317
320
  ["navPager", "`navPager(nav, page.url)` is `{ previous, next }` in reading order."],
318
321
  ["navBreadcrumbs", "`navBreadcrumbs(nav, page.url)` is the entries from the top down to the page."],
@@ -347,12 +350,17 @@ function builtinFilters(markdown, config) {
347
350
  const words = splitWhitespace(htmlText(String(text))).length;
348
351
  return Math.max(Math.ceil(words / wpm), 1);
349
352
  });
353
+ const TOC_MARKUP = ["id", "class", "sublistClass", "itemClass", "linkClass"];
350
354
  filters.set("toc", (list, option, last) => {
351
355
  const headings2 = Array.isArray(list) ? list : [];
352
356
  let [from, to, ordered] = [2, 3, false];
357
+ const markup = {};
353
358
  if (isPlainObject(option)) {
354
- for (const key of Object.keys(option)) {
355
- if (!["from", "to", "ordered"].includes(key)) throw new BuildError(`toc: unknown option \`${key}\` (options: from, to, ordered)`);
359
+ for (const [key, value] of Object.entries(option)) {
360
+ if (TOC_MARKUP.includes(key)) {
361
+ if (value !== void 0 && value !== null && typeof value !== "string") throw new BuildError(`toc: \`${key}\` must be text (a class name, or names with spaces between)`);
362
+ if (value) markup[key] = value;
363
+ } else if (!["from", "to", "ordered"].includes(key)) throw new BuildError(`toc: unknown option \`${key}\` (options: from, to, ordered, ${TOC_MARKUP.join(", ")})`);
356
364
  }
357
365
  if (typeof option.from === "number") from = option.from;
358
366
  if (typeof option.to === "number") to = option.to;
@@ -362,7 +370,7 @@ function builtinFilters(markdown, config) {
362
370
  to = typeof last === "number" ? last : Math.max(to, from);
363
371
  }
364
372
  const level = (n) => Math.trunc(Math.min(Math.max(n, 1), 6));
365
- return toc(headings2, level(from), level(to), ordered);
373
+ return toc(headings2, level(from), level(to), ordered, markup);
366
374
  });
367
375
  filters.set("withBase", (url) => withBase(config.base, url === void 0 ? "" : String(url)));
368
376
  return filters;
@@ -2,11 +2,11 @@ import { createRequire as __ssqchCreateRequire } from "node:module";
2
2
  const require = __ssqchCreateRequire(import.meta.url);
3
3
  import {
4
4
  starterEngines
5
- } from "./chunk-WP3RPVUM.js";
5
+ } from "./chunk-YTHQBMDJ.js";
6
6
  import {
7
7
  DEFAULTS,
8
8
  configOptions
9
- } from "./chunk-TN6EEDX2.js";
9
+ } from "./chunk-R7K3D5W5.js";
10
10
  import {
11
11
  VERSION
12
12
  } from "./chunk-AD3HAW3W.js";
@@ -15,7 +15,7 @@ import {
15
15
  } from "./chunk-DDV6JEC2.js";
16
16
  import {
17
17
  red
18
- } from "./chunk-6XYSFG6V.js";
18
+ } from "./chunk-GRWMGC7D.js";
19
19
 
20
20
  // src/commands/capabilities.ts
21
21
  var MODULE_EXPORTS = [
@@ -5,18 +5,18 @@ import {
5
5
  } from "./chunk-3GYLOC6Y.js";
6
6
  import {
7
7
  findConfig
8
- } from "./chunk-TN6EEDX2.js";
9
- import "./chunk-IRHRK7XB.js";
8
+ } from "./chunk-R7K3D5W5.js";
9
+ import "./chunk-7XLK2GEG.js";
10
10
  import "./chunk-NKXEPHRZ.js";
11
11
  import {
12
12
  VERSION
13
13
  } from "./chunk-AD3HAW3W.js";
14
14
  import "./chunk-DDV6JEC2.js";
15
- import "./chunk-EIT4ZDT4.js";
15
+ import "./chunk-NCWFYT74.js";
16
16
  import "./chunk-FVZ5JBRI.js";
17
- import "./chunk-TDGBQNGW.js";
17
+ import "./chunk-HPXAZ2HU.js";
18
18
  import "./chunk-UU43WIZG.js";
19
- import "./chunk-C35KIPAR.js";
19
+ import "./chunk-76NTVE34.js";
20
20
  import "./chunk-CMUWRPSQ.js";
21
21
  import {
22
22
  TABLE,
@@ -25,7 +25,7 @@ import {
25
25
  readToml,
26
26
  red,
27
27
  tomlReason
28
- } from "./chunk-6XYSFG6V.js";
28
+ } from "./chunk-GRWMGC7D.js";
29
29
  import {
30
30
  compareText,
31
31
  isDir,
@@ -2,7 +2,7 @@ import { createRequire as __ssqchCreateRequire } from "node:module";
2
2
  const require = __ssqchCreateRequire(import.meta.url);
3
3
  import {
4
4
  BuildError
5
- } from "./chunk-6XYSFG6V.js";
5
+ } from "./chunk-GRWMGC7D.js";
6
6
  import {
7
7
  realPath
8
8
  } from "./chunk-VJWQSYEG.js";
@@ -54,22 +54,113 @@ function hookModules() {
54
54
  }
55
55
  return next(name, context);
56
56
  };
57
- try {
58
- return attempt(specifier);
59
- } catch (e) {
60
- const relative = specifier.startsWith("./") || specifier.startsWith("../") || path.isAbsolute(specifier) || specifier.startsWith("file:");
61
- if (!fromSite || !relative || !["ERR_MODULE_NOT_FOUND", "ERR_UNSUPPORTED_DIR_IMPORT"].includes(e?.code)) throw e;
62
- const [bare, query = ""] = specifier.split(/(?=\?)/, 2);
57
+ const withEndings = (name) => {
58
+ const [bare, query = ""] = name.split(/(?=\?)/, 2);
59
+ try {
60
+ return attempt(name);
61
+ } catch {
62
+ }
63
63
  for (const ending of ENDINGS) {
64
64
  try {
65
65
  return attempt(bare.replace(/\/$/, "") + ending + query);
66
66
  } catch {
67
67
  }
68
68
  }
69
+ return void 0;
70
+ };
71
+ try {
72
+ return attempt(specifier);
73
+ } catch (e) {
74
+ const hashAlias = specifier.startsWith("#") && ["ERR_PACKAGE_IMPORT_NOT_DEFINED", "ERR_INVALID_MODULE_SPECIFIER"].includes(e?.code);
75
+ if (!fromSite || !hashAlias && !["ERR_MODULE_NOT_FOUND", "ERR_UNSUPPORTED_DIR_IMPORT"].includes(e?.code)) throw e;
76
+ const relative = specifier.startsWith("./") || specifier.startsWith("../") || path.isAbsolute(specifier) || specifier.startsWith("file:");
77
+ if (relative) return withEndings(specifier) ?? (() => {
78
+ throw e;
79
+ })();
80
+ for (const file of aliasTargets(specifier, path.dirname(fileURLToPath(context.parentURL)))) {
81
+ const found = withEndings(pathToFileURL(file).href);
82
+ if (found) return found;
83
+ }
69
84
  throw e;
70
85
  }
71
86
  }
72
87
  }
88
+ var aliasesByDir = /* @__PURE__ */ new Map();
89
+ function parseJsonc(text) {
90
+ let out = "";
91
+ for (let i = 0; i < text.length; i++) {
92
+ const c = text[i];
93
+ if (c === '"') {
94
+ const end = /^"(?:[^"\\]|\\.)*"/.exec(text.slice(i))?.[0] ?? c;
95
+ out += end;
96
+ i += end.length - 1;
97
+ } else if (c === "/" && text[i + 1] === "/") {
98
+ while (i < text.length && text[i] !== "\n") i++;
99
+ out += "\n";
100
+ } else if (c === "/" && text[i + 1] === "*") {
101
+ const end = text.indexOf("*/", i + 2);
102
+ i = end === -1 ? text.length : end + 1;
103
+ } else out += c;
104
+ }
105
+ return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
106
+ }
107
+ function readAliases(file, seen = /* @__PURE__ */ new Set()) {
108
+ if (seen.has(file)) return null;
109
+ seen.add(file);
110
+ let json;
111
+ try {
112
+ json = parseJsonc(fs.readFileSync(file, "utf8"));
113
+ } catch {
114
+ return null;
115
+ }
116
+ const dir = path.dirname(file);
117
+ const options = json?.compilerOptions ?? {};
118
+ if (options.paths && typeof options.paths === "object") {
119
+ const base = typeof options.baseUrl === "string" ? path.resolve(dir, options.baseUrl) : dir;
120
+ const paths = Object.entries(options.paths).filter((e) => Array.isArray(e[1])).map(([k, v]) => [k, v.filter((t) => typeof t === "string")]);
121
+ return { base, paths };
122
+ }
123
+ const parents = (Array.isArray(json?.extends) ? json.extends : [json?.extends]).filter((x) => typeof x === "string" && (x.startsWith("./") || x.startsWith("../")));
124
+ for (const parent of parents) {
125
+ const found = readAliases(path.resolve(dir, parent.endsWith(".json") ? parent : `${parent}.json`), seen);
126
+ if (found) return found;
127
+ }
128
+ return null;
129
+ }
130
+ function aliasesFor(dir) {
131
+ if (aliasesByDir.has(dir)) return aliasesByDir.get(dir);
132
+ let found = null;
133
+ for (const name of ["tsconfig.json", "jsconfig.json"]) {
134
+ const file = path.join(dir, name);
135
+ if (fs.existsSync(file)) {
136
+ found = readAliases(file);
137
+ break;
138
+ }
139
+ }
140
+ if (!found && !fs.existsSync(path.join(dir, "tsconfig.json")) && !fs.existsSync(path.join(dir, "jsconfig.json"))) {
141
+ const up = path.dirname(dir);
142
+ if (up !== dir) found = aliasesFor(up);
143
+ }
144
+ aliasesByDir.set(dir, found);
145
+ return found;
146
+ }
147
+ function aliasTargets(specifier, fromDir) {
148
+ const aliases = aliasesFor(fromDir);
149
+ if (!aliases) return [];
150
+ let best;
151
+ for (const [pattern, targets] of aliases.paths) {
152
+ const at = pattern.indexOf("*");
153
+ if (at === -1) {
154
+ if (pattern === specifier) return targets.map((t) => path.resolve(aliases.base, t));
155
+ continue;
156
+ }
157
+ const prefix = pattern.slice(0, at), suffix = pattern.slice(at + 1);
158
+ if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix) || specifier.length < prefix.length + suffix.length) continue;
159
+ if (best && prefix.length <= best.pattern.indexOf("*")) continue;
160
+ best = { pattern, star: specifier.slice(prefix.length, specifier.length - suffix.length), targets };
161
+ }
162
+ return best ? best.targets.map((t) => path.resolve(aliases.base, t.replace("*", best.star))) : [];
163
+ }
73
164
  var versions = /* @__PURE__ */ new Map();
74
165
  async function importFile(file) {
75
166
  hookModules();
@@ -3,8 +3,8 @@ const require = __ssqchCreateRequire(import.meta.url);
3
3
  import {
4
4
  buildFiles,
5
5
  urlOf
6
- } from "./chunk-3PHCFZEU.js";
7
- import "./chunk-IRHRK7XB.js";
6
+ } from "./chunk-II5DEH3Q.js";
7
+ import "./chunk-7XLK2GEG.js";
8
8
  import {
9
9
  bytes,
10
10
  count
@@ -20,7 +20,7 @@ import {
20
20
  import {
21
21
  BuildError,
22
22
  bail
23
- } from "./chunk-6XYSFG6V.js";
23
+ } from "./chunk-GRWMGC7D.js";
24
24
  import {
25
25
  compareText
26
26
  } from "./chunk-VJWQSYEG.js";
@@ -327,7 +327,7 @@ function recordActions(ids2, oppositeCounts) {
327
327
  }
328
328
  function scanConfusingRun(actions, from, step) {
329
329
  let discards = 0, investigates = 0;
330
- for (let i = from, seen = 0; i >= 0 && i < actions.length && seen < CONFUSING_RECORD_SCAN_WINDOW; i += step, seen++) {
330
+ for (let i = from, seen2 = 0; i >= 0 && i < actions.length && seen2 < CONFUSING_RECORD_SCAN_WINDOW; i += step, seen2++) {
331
331
  if (actions[i] === DISCARD) discards++;
332
332
  else if (actions[i] === INVESTIGATE) investigates++;
333
333
  else break;
@@ -1218,12 +1218,133 @@ function diffJson(report, limit) {
1218
1218
  changed
1219
1219
  };
1220
1220
  }
1221
+ async function compareRuns(dirs, options) {
1222
+ const keep = (paths) => options.only ? paths.filter((p) => options.only.some((re) => re.test(p))) : paths;
1223
+ const walks = await Promise.allSettled(dirs.map(files));
1224
+ for (const walk of walks) if (walk.status === "rejected") throw walk.reason;
1225
+ const maps = walks.map((w) => keyed(keep(w.value), options.exact));
1226
+ const keys = [...new Set(maps.flatMap((m) => [...m.keys()]))].sort(compareText);
1227
+ const report = { runs: dirs, exact: options.exact, varies: [], steadyPages: 0, steadyFiles: 0 };
1228
+ const found = new Array(keys.length);
1229
+ let next = 0;
1230
+ const worker = async () => {
1231
+ while (next < keys.length) {
1232
+ const i = next++;
1233
+ const key = keys[i];
1234
+ const buffers = await Promise.all(maps.map(async (m, run) => {
1235
+ const file = m.get(key);
1236
+ return file === void 0 ? void 0 : Buffer.from(await fs.promises.readFile(path.join(dirs[run], file)));
1237
+ }));
1238
+ found[i] = varies(key, buffers, maps, options);
1239
+ }
1240
+ };
1241
+ await Promise.all(Array.from({ length: Math.min(READS_AT_ONCE, keys.length) }, worker));
1242
+ keys.forEach((key, i) => {
1243
+ const v = found[i];
1244
+ if (v) report.varies.push(v);
1245
+ else if (isPage(key)) report.steadyPages += 1;
1246
+ else report.steadyFiles += 1;
1247
+ });
1248
+ return report;
1249
+ }
1250
+ function seen(key, data, options) {
1251
+ const text = decode(data);
1252
+ if (text === void 0) return `b:${data.toString("base64")}`;
1253
+ const normal = normalize(text, options);
1254
+ if (isPage(key) && !options.exact) return `p:${tokens(normal).map((t) => `${t.tag ? 1 : 0}${t.text}`).join("\0")}`;
1255
+ return `t:${normal}`;
1256
+ }
1257
+ function varies(key, buffers, maps, options) {
1258
+ const groups = /* @__PURE__ */ new Map();
1259
+ buffers.forEach((data, run) => {
1260
+ const id = data === void 0 ? "missing" : seen(key, data, options);
1261
+ const list = groups.get(id);
1262
+ if (list) list.push(run);
1263
+ else groups.set(id, [run]);
1264
+ });
1265
+ if (groups.size === 1 && !groups.has("missing")) return void 0;
1266
+ const versions = [...groups].map(([id, runs]) => ({ runs, missing: id === "missing" }));
1267
+ versions.sort((a, b) => b.runs.length - a.runs.length || a.runs[0] - b.runs[0]);
1268
+ const present = versions.filter((v) => !v.missing);
1269
+ let sample;
1270
+ if (present.length >= 2) {
1271
+ const [x, y] = [present[0].runs[0], present[1].runs[0]];
1272
+ sample = comparePair(buffers[x], buffers[y], { key, before: maps[x].get(key), after: maps[y].get(key) }, options);
1273
+ }
1274
+ const first = buffers.find((b) => b !== void 0);
1275
+ const kind = decode(first) === void 0 ? "binary" : isPage(key) ? "page" : "text";
1276
+ return { path: key, url: urlOf(key), kind, versions, sample };
1277
+ }
1278
+ var named = (report, runs) => runs.map((r) => report.runs[r]).join(", ");
1279
+ function runsText(report, limit, color) {
1280
+ const paint = (code, s) => color ? `\x1B[${code}m${s}\x1B[0m` : s;
1281
+ let out = `Comparing ${count(report.runs.length)} builds: ${report.runs.join(", ")}
1282
+ `;
1283
+ out += report.exact ? "Comparing bytes (--exact).\n" : "Ignoring asset fingerprints, integrity hashes, the generator's version, and whitespace between tags (--exact compares bytes).\n";
1284
+ const steady = `${plural(report.steadyPages, "page", "pages")} and ${plural(report.steadyFiles, "other file", "other files")}`;
1285
+ if (!report.varies.length) return `${out}
1286
+ Every build is the same: ${steady}. The tracks match every time.
1287
+ `;
1288
+ out += `
1289
+ Varies (${report.varies.length})
1290
+ `;
1291
+ for (const file of report.varies) {
1292
+ const [most, ...rest] = file.versions;
1293
+ const onlyIn = most.missing && rest.length === 1;
1294
+ const others = rest.map((v) => v.missing ? `missing from ${named(report, v.runs)}` : onlyIn ? `only in ${named(report, v.runs)}` : `${named(report, v.runs)} differ${v.runs.length === 1 ? "s" : ""}`);
1295
+ const agree = most.missing ? `missing from ${named(report, most.runs)}` : `${named(report, most.runs)} agree${most.runs.length === 1 ? "s" : ""}`;
1296
+ out += ` ~ ${file.url} (${file.versions.length} versions: ${agree}; ${others.join("; ")})
1297
+ `;
1298
+ const sample = file.sample;
1299
+ if (!sample) continue;
1300
+ for (const note of sample.notes) out += ` ${note}
1301
+ `;
1302
+ let shown = 0;
1303
+ done: for (const hunk of sample.hunks) {
1304
+ for (const [sign, code, side] of [["-", "31", hunk.removed], ["+", "32", hunk.added]]) {
1305
+ for (const line of side) {
1306
+ if (limit > 0 && shown >= limit) break done;
1307
+ out += paint(code, ` ${sign} ${clip(line)}
1308
+ `);
1309
+ shown += 1;
1310
+ }
1311
+ }
1312
+ }
1313
+ if (sample.changedLines > shown) out += ` ... ${count(sample.changedLines - shown)} more changed ${sample.changedLines - shown === 1 ? "line" : "lines"} (--lines 0 shows all)
1314
+ `;
1315
+ }
1316
+ out += `
1317
+ ${plural(report.varies.length, "file varies", "files vary")} between builds made the same way; ${steady} are the same in all of them. Pin what changes (the build's time, random ids) before comparing another build with these, or leave it out with --ignore.
1318
+ `;
1319
+ return out;
1320
+ }
1321
+ function runsJson(report, limit) {
1322
+ const runs = report.runs.map((r) => r.replaceAll("\\", "/"));
1323
+ return {
1324
+ schemaVersion: 1,
1325
+ runs,
1326
+ exact: report.exact,
1327
+ same: report.varies.length === 0,
1328
+ summary: { varies: report.varies.length, steadyPages: report.steadyPages, steadyFiles: report.steadyFiles },
1329
+ varies: report.varies.map((f) => ({
1330
+ url: f.url,
1331
+ path: f.path,
1332
+ kind: f.kind,
1333
+ versions: f.versions.map((v) => ({ runs: v.runs.map((r) => runs[r]), missing: v.missing })),
1334
+ changedLines: f.sample?.changedLines ?? 0,
1335
+ hunks: f.sample ? firstLines(f.sample.hunks, limit) : []
1336
+ }))
1337
+ };
1338
+ }
1221
1339
  export {
1222
1340
  compare,
1341
+ compareRuns,
1223
1342
  diffJson,
1224
1343
  diffText,
1225
1344
  isSame,
1226
1345
  keyed,
1346
+ runsJson,
1347
+ runsText,
1227
1348
  tokens,
1228
1349
  withoutFingerprints
1229
1350
  };