@chassis-ui/docs 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @chassis-ui/docs
 
+## 0.6.2
+
+### Patch Changes
+
+- Add the `staticPath` key of `config.yml`: the URL path that the pages load the static files from, `/static` by default. A site that is served under a path of another host, such as `chassis-ui.com/css`, sets it to `/css/static` and rewrites that path to `/static`, so that its files no longer depend on the `Referer` header to be found. The layouts, the `Icon` shortcode and the scripts of the package use it, and `getStaticPath()` of `@chassis-ui/docs/site` returns a URL under it for the site's own files. See [A site under a prefix](https://github.com/chassis-ui/website/tree/main/packages/docs#a-site-under-a-prefix) in the README.
+
+## 0.6.1
+
+### Patch Changes
+
+- A code block can take focus, so that a keyboard can scroll one that is wider than the page. The Google Fonts stylesheet is linked from the head instead of imported by the styles, so the browser requests it with the page, not after the stylesheet that imported it.
+- Google Analytics loads only after the visitor accepts. When `analytics.googleId` is set, production builds show a consent banner at the bottom of the page, and nothing is sent to Google and no cookie is set before the visitor accepts. The choice is kept in `localStorage`, so the sites served from one host share it. The footer has a "Cookie settings" button that opens the banner again, and a "Privacy" link to `/privacy/`. Declining stops Google Analytics and deletes its cookies.
+- The head no longer links `safari-pinned-tab.svg` as a `mask-icon`. The docs build of chassis-assets has no such file, so every page asked for one that returned 404. Safari has used the regular favicon for pinned tabs since version 12.
+- The header and the footer link Chassis React: "React" in the navigation of the header, "React Components" among the docs of the footer and "Chassis React" among its GitHub links. The footer lists the projects in the order of the header. The "Privacy" link and the "Cookie settings" button moved from the last column of the footer to below the license.
+- The package installs a `chassis-docs` command with the build steps that every Chassis site shares, so that a site no longer needs its own copies of them. `chassis-docs vendor` builds the `vendor/assets` submodule at the pinned commit. `chassis-docs sync-submodules` moves it to the latest `app/docs` and builds it, and works on a fresh CI checkout too. `chassis-docs html-validate` and `chassis-docs vnu` validate the built HTML. The two validators need `html-validate` and `vnu-jar`, which are optional peer dependencies. See [Commands](https://github.com/chassis-ui/website/tree/main/packages/docs#commands) in the README.
+- The "Skip to main content" link of the header has a target on every page. `BaseLayout` gives its `<main>` the id `content`, which only the docs layout had set, on its title. A page that fills the `main` slot of `BaseLayout` sets the id on an element of its own.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -34,6 +34,8 @@ pnpm add @chassis-ui/docs
 }
 ```
 
+Two more are optional. They are needed by the [commands](#commands) that validate HTML: `html-validate` `^11.0.0` and `vnu-jar` `>=26.0.0`.
+
 A site also installs `@astrojs/mdx` and the rest of the Chassis stack, `@chassis-ui/tokens` and `@chassis-ui/icons`.
 
 ## Setup
@@ -104,23 +106,24 @@ repo: 'https://github.com/chassis-ui/css'
 currentVersion: '0.5.2'
 ```
 
-| Key                                           | Required | Meaning                                                                                           |
-| --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
-| `title`, `subtitle`, `description`, `authors` | yes      | Used in the page title and the meta tags                                                          |
-| `baseURL`                                     | yes      | Canonical URL of the site                                                                         |
-| `docsPath`                                    | yes      | URL path of the docs pages. Starts with `/`                                                       |
-| `repo`                                        | yes      | URL of the repository                                                                             |
-| `currentVersion`                              | yes      | Version that the site documents. Links to source files use the tag `v<currentVersion>`            |
-| `githubOrg`                                   | no       | GitHub organisation name, not a URL. The header links to it                                       |
-| `figmaHandle`                                 | no       | Figma Community handle. The header links to it                                                    |
-| `xUsername`                                   | no       | X handle. Used in the social meta tags                                                            |
-| `analytics.googleId`                          | no       | Google Analytics ID. Loaded in production builds only                                             |
-| `anchors.min`, `anchors.max`                  | no       | Heading levels that get an anchor link. Default 2 to 5                                            |
-| `toc.min`, `toc.max`                          | no       | Heading levels in the table of contents. Default 2 to 6                                           |
-| `sourceDir`                                   | no       | Directory that `file` props are relative to, from the site's root, e.g. `"../css"`. Default `"."` |
-| `sourcePath`                                  | no       | The same directory from the root of the repository, e.g. `"packages/css"`                         |
-| `sitePath`                                    | no       | The site's root from the root of the repository, e.g. `"packages/site"`                           |
-| `siteBranch`                                  | no       | The branch that "View on GitHub" links to. Default `main`                                         |
+| Key                                           | Required | Meaning                                                                                                                    |
+| --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `title`, `subtitle`, `description`, `authors` | yes      | Used in the page title and the meta tags                                                                                   |
+| `baseURL`                                     | yes      | Canonical URL of the site                                                                                                  |
+| `docsPath`                                    | yes      | URL path of the docs pages. Starts with `/`                                                                                |
+| `staticPath`                                  | no       | URL path that the pages load the static files from. Default `/static`. See [A site under a prefix](#a-site-under-a-prefix) |
+| `repo`                                        | yes      | URL of the repository                                                                                                      |
+| `currentVersion`                              | yes      | Version that the site documents. Links to source files use the tag `v<currentVersion>`                                     |
+| `githubOrg`                                   | no       | GitHub organisation name, not a URL. The header links to it                                                                |
+| `figmaHandle`                                 | no       | Figma Community handle. The header links to it                                                                             |
+| `xUsername`                                   | no       | X handle. Used in the social meta tags                                                                                     |
+| `analytics.googleId`                          | no       | Google Analytics ID. In production builds, loaded after the visitor accepts in a consent banner                            |
+| `anchors.min`, `anchors.max`                  | no       | Heading levels that get an anchor link. Default 2 to 5                                                                     |
+| `toc.min`, `toc.max`                          | no       | Heading levels in the table of contents. Default 2 to 6                                                                    |
+| `sourceDir`                                   | no       | Directory that `file` props are relative to, from the site's root, e.g. `"../css"`. Default `"."`                          |
+| `sourcePath`                                  | no       | The same directory from the root of the repository, e.g. `"packages/css"`                                                  |
+| `sitePath`                                    | no       | The site's root from the root of the repository, e.g. `"packages/site"`                                                    |
+| `siteBranch`                                  | no       | The branch that "View on GitHub" links to. Default `main`                                                                  |
 
 `file` props are those of `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and `<Code filePath>`.
 
@@ -179,7 +182,7 @@ export const collections = {
 
 ### 4. Provide the static files
 
-The layouts link to files under `/static/`, which the site puts into its `public` directory:
+The layouts link to files under `/static/`, which the site puts into `static/` of its `public` directory:
 
 | URL                                                                  | From                                      |
 | -------------------------------------------------------------------- | ----------------------------------------- |
@@ -187,10 +190,33 @@ The layouts link to files under `/static/`, which the site puts into its `public
 | `/static/icons/chassis-icons.svg`, `/static/icons/chassis-icons.css` | the `icons` folder of `@chassis-ui/icons` |
 | `/static/images/*`: logo, favicons, social image                     | the docs build of `chassis-assets`        |
 
+`chassis-docs vendor` builds the docs build of `chassis-assets` in the `vendor/assets` submodule. See [Commands](#commands).
+
 These helpers find the folders, whether `node_modules` is in the site's root or in the root of the repository: `getChassisCSSFsPath()`, `getChassisIconsFsPath()`, `getChassisAssetsFsPath()` and `getChassisTokensFsPath()`. Each takes `{ root, dir }`.
 
 A site that type-checks with `astro check` declares the `@chassis-ui/css` module, which has no types: `declare module '@chassis-ui/css'`.
 
+#### A site under a prefix
+
+A site that is served under a path of another host, such as `chassis-ui.com/css`, cannot use `/static/` there: that path belongs to the host's own site. It loads its static files under a path of its own instead:
+
+```yaml
+# config.yml
+staticPath: '/css/static'
+```
+
+The layouts, the `Icon` shortcode and the scripts of the package then link `/css/static/css/chassis.min.css` and so on. The files do not move: they stay in `static/` of the `public` directory. Two rewrites make the path answer:
+
+- on the host, from `/css/static/*` to `/static/*` of the site's deployment. chassis-ui.com has one for each Chassis site.
+- in the site's own `vercel.json`, from `/css/static/(.*)` to `/static/$1`, so that the deployment also works when it is opened directly.
+
+Two kinds of URL are the site's own to move:
+
+- URLs that the site writes itself, in its pages and components. `getStaticPath('images/hero.png')` of `@chassis-ui/docs/site` returns the URL under `staticPath`.
+- The files that Astro builds, when the site puts them under `static/` with `build.assets`. Astro's `build.assetsPrefix` adds the prefix to them, `'/css'` here.
+
+A social image named in the frontmatter as `static/images/…` is read from the `public` directory and linked under `staticPath`.
+
 ### 5. Use the layouts
 
 ```astro
@@ -229,6 +255,7 @@ chassisDocs({
 | `getCallout(name)`                                 | An entry of the `callouts` collection                               |
 | `getSiteRoot()`, `getSiteFsPath(file)`             | Absolute path of the site's root, or of a file in it                |
 | `getPublicFsPath(file)`                            | Absolute path of a file in the `public` directory                   |
+| `getStaticPath(file)`                              | URL path of a static file, under `staticPath` of the config         |
 | `getSourceFsPath(file)`                            | Absolute path of a file that a `file` prop names                    |
 | `getSourceUrl(file)`                               | URL of a source file on GitHub, at the tag of the current version   |
 | `getSiteFileUrl(filePath)`                         | URL of a file of the site on GitHub, on the site's branch           |
@@ -238,6 +265,88 @@ chassisDocs({
 
 Code that runs while Astro loads its configuration uses the library functions of the root entry instead: `loadConfig()`, `loadData()`, `loadSidebar()` and the path helpers.
 
+## Commands
+
+The package installs a `chassis-docs` command with the build steps that every Chassis site shares. Call it from the scripts of `package.json`:
+
+```json
+{
+  "scripts": {
+    "vendor": "chassis-docs vendor",
+    "sync-submodules": "chassis-docs sync-submodules",
+    "lint:html": "chassis-docs html-validate _site",
+    "lint:vnu": "chassis-docs vnu _site"
+  }
+}
+```
+
+| Command                              | What it does                                                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chassis-docs vendor`                | Checks out the `vendor/assets` submodule at the commit that the repository pins, pulls its Git LFS files, installs its dependencies and runs its `pnpm assets:site` |
+| `chassis-docs sync-submodules`       | Moves `vendor/assets` to the latest commit of the `app/docs` branch and builds it. Commit the new pointer afterwards                                                |
+| `chassis-docs html-validate [paths]` | Validates the HTML files in `paths` with [html-validate](https://html-validate.org)                                                                                 |
+| `chassis-docs vnu [paths]`           | Validates `paths` with the [Nu Html Checker](https://validator.github.io/validator/). Skipped, with a warning, when Java is missing                                 |
+| `chassis-docs help`                  | Lists the commands and their options                                                                                                                                |
+
+`vendor` and `sync-submodules` work from any folder of the repository. They need Git, Git LFS and pnpm. `sync-submodules --branch <name>`, or the `SUBMODULE_BRANCH` variable, follows another branch.
+
+Each command exits with 1 when it fails, so a script or CI job stops there.
+
+### Validating HTML
+
+`html-validate` and `vnu` take any number of files and folders, `_site` when none is given. Paths are relative to the folder the script runs in, which for a site in `packages/site` is that folder when the script is in its `package.json`, and the repository root when it is in the root one.
+
+What a site can change:
+
+| To                                  | Use                                   | Validator     | Adds to the defaults or replaces them |
+| ----------------------------------- | ------------------------------------- | ------------- | ------------------------------------- |
+| Skip a file or folder               | `--ignore <path>`, repeatable         | both          | adds                                  |
+| Check `static/icons` too            | `--no-default-ignore`                 | both          | removes the default                   |
+| Turn a rule off or change it        | `rules` in the file of `--config`     | html-validate | overrides the rule                    |
+| Use more presets or plugins         | `extends` in the file of `--config`   | html-validate | adds                                  |
+| Allow custom elements or attributes | `elements` in the file of `--config`  | html-validate | replaces                              |
+| Leave out a message                 | `--filter <regex>` or `--filter-file` | vnu           | adds                                  |
+
+The defaults:
+
+- Both skip `static/icons` in each path, where a site copies `@chassis-ui/icons`, whose preview page is not the site's.
+- `html-validate` extends `html-validate:recommended` and `html-validate:document`. It turns off `void-style`, since Astro writes void elements with a slash, `no-inline-style`, since Shiki writes inline styles, and `require-sri`. `heading-level` lets a page start at `h2`, as the dialogs of the layouts do.
+- `vnu` fails on warnings as well as errors, and leaves out "Trailing slash on void elements", which Astro writes.
+
+A site with its own exceptions keeps them in files next to its `package.json`, and names them in its scripts:
+
+```json
+{
+  "scripts": {
+    "lint:html": "chassis-docs html-validate _site --ignore _site/examples --config html-validate.json",
+    "lint:vnu": "chassis-docs vnu _site --ignore _site/examples --filter-file vnu-filters.txt"
+  }
+}
+```
+
+`html-validate.json`:
+
+```json
+{
+  "rules": {
+    "prefer-native-element": ["error", { "exclude": ["region"] }],
+    "prefer-button": "off"
+  }
+}
+```
+
+`vnu-filters.txt`, one regular expression per line, where a line that starts with `#` is a comment:
+
+```text
+# The docs show autocomplete on inputs of every type
+Attribute “autocomplete” is only allowed when the input type is.*
+Bad value “heading” for attribute “role” on element “summary”.
+```
+
+A filter is matched against the message as the output shows it, curly quotes included: `“role”`. A line copied from the output works.
+
+A rule or filter applies to every file that the command checks. To make an exception for one page only, skip the page with `--ignore`, or disable the rule inside the page's markup with a comment of html-validate, such as `<!-- [html-validate-disable-next prefer-button] -->`.
+
 ## Exports
 
 These import paths are the public API.
@@ -257,7 +366,26 @@ These import paths are the public API.
 
 No other path resolves: `exports` in `package.json` lists these and nothing else. The layouts and components are listed by name, so the folders inside `layouts/` and `components/` are not reachable.
 
-The integration provides four modules: `virtual:chassis-docs/config`, `virtual:chassis-docs/sidebar`, `virtual:chassis-docs/paths` and `virtual:chassis-docs/styles`. Use the functions of `@chassis-ui/docs/site` instead of importing them.
+The integration provides five modules: `virtual:chassis-docs/config`, `virtual:chassis-docs/sidebar`, `virtual:chassis-docs/paths`, `virtual:chassis-docs/static` and `virtual:chassis-docs/styles`. Use the functions of `@chassis-ui/docs/site` instead of importing them.
+
+## Compatibility
+
+"Requires" is what `package.json` of each version declares. "Built with" is what the website in this repository resolved and built when the version was released. CI also builds the [starter site](starter/) with the newest versions that its ranges accept.
+
+| `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                           |
+| ------------------ | -------------------------- | -------------------------- | ------------- | ------------------------------------ |
+| 0.6.2              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
+| 0.6.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
+| 0.6.0              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.5.3 |
+| 0.5.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.5.3 |
+| 0.5.0              | `^7.0.0`                   | `^0.5.0-0`                 | not declared  | not recorded                         |
+| 0.4.0              | `^7.0.0`                   | `^0.4.0`                   | not declared  | not recorded                         |
+| 0.3.0 to 0.3.10    | `^7.0.0`                   | `>=0.3.1` to `>=0.3.4`     | not declared  | not recorded                         |
+| 0.1.0 to 0.2.0     | `^5.0.0`, 0.1.0–0.1.1 `^4` | not declared               | not declared  | not recorded                         |
+
+`@chassis-ui/tokens` is not a dependency of the package. The styles take the design tokens that `@chassis-ui/css` carries: css 0.5 is built on tokens 0.5, css 0.4 on tokens 0.4. A site's own version of `@chassis-ui/tokens` matters only when the site puts it on the Sass load path in place of those. Tokens 0.6 renamed and removed some tokens, listed in its changelog.
+
+Before a release, the [canary](https://github.com/chassis-ui/website/blob/main/build/canary.js) builds the site of each Chassis repository whose range accepts the new version.
 
 ## Versioning
 
@@ -270,10 +398,11 @@ A change is breaking when it changes something that this README documents:
 
 - the import paths listed under [Exports](#exports), and what they export
 - the options of the integration
+- the commands of `chassis-docs`, their options and their defaults
 - the keys of `config.yml`, and the schemas of the sidebar and the content collections
 - the props and slots of the layouts, components and shortcodes
 - the `[[config:]]` and `[[docsref:]]` syntax
-- the URLs under `/static/` that the layouts link to
+- the URLs under `staticPath`, `/static/` by default, that the layouts link to
 - the supported versions of Node, Astro and `@chassis-ui/css`
 
 Everything else may change in a patch release: the rendered HTML, class names, the content of the styles, and every file that is not reachable through a documented import path.

package/bin/chassis-docs.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// The build and validation commands that every Chassis site shares. Run `chassis-docs help`.
+import { main } from '../src/cli/main.js'
+
+process.exitCode = await main(process.argv.slice(2))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "type": "module",
   "repository": {
     "type": "git",
@@ -23,6 +23,7 @@
     "design-system"
   ],
   "files": [
+    "bin",
     "src",
     "index.ts",
     "virtual.d.ts",
@@ -31,6 +32,9 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
+  "bin": {
+    "chassis-docs": "./bin/chassis-docs.js"
+  },
   "main": "index.ts",
   "exports": {
     ".": "./index.ts",
@@ -70,10 +74,20 @@
     "@pagefind/component-ui": "^1.0.0",
     "@shikijs/transformers": "^4.3.1",
     "astro": "^7.0.0",
+    "html-validate": "^11.0.0",
     "htmlparser2": "^12.0.0",
     "rehype-autolink-headings": "^7.0.0",
     "sass": "^1.101.0",
-    "shiki": "^4.3.1"
+    "shiki": "^4.3.1",
+    "vnu-jar": ">=26.0.0"
+  },
+  "peerDependenciesMeta": {
+    "html-validate": {
+      "optional": true
+    },
+    "vnu-jar": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@types/hast": "^3.0.5",

package/src/cli/assets.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { CommandError, log, run as defaultRun } from './shared.js'
+
+/** Where every Chassis site has chassis-assets as a submodule. */
+export const ASSETS_PATH = 'vendor/assets'
+
+/** The docs build of chassis-assets, inside the submodule. `getChassisAssetsFsPath()` reads it. */
+export const ASSETS_OUTPUT = 'dist/web/docs/chassis'
+
+/** The branch of chassis-assets that the docs sites follow. */
+export const DEFAULT_BRANCH = 'app/docs'
+
+/**
+ * The root of the repository that contains the working directory, so that the commands
+ * work from a site's folder too.
+ * @param {typeof defaultRun} run
+ */
+function repositoryRoot(run) {
+  return run('git', ['rev-parse', '--show-toplevel'], { quiet: true }).trim()
+}
+
+/**
+ * Checks out `vendor/assets` at the commit that the repository pins, and builds it.
+ * @param {{ root?: string, run?: typeof defaultRun }} [options]
+ */
+export function buildAssets({ run = defaultRun, root = repositoryRoot(run) } = {}) {
+  log(`Building ${ASSETS_PATH} at the pinned commit`)
+  run('git', ['submodule', 'update', '--init', ASSETS_PATH], { cwd: root })
+  buildCheckout(root, run)
+}
+
+/**
+ * Moves `vendor/assets` to the latest commit of `branch`, and builds it. The repository
+ * then has a changed submodule pointer to commit.
+ * @param {{ root?: string, branch?: string, run?: typeof defaultRun }} [options]
+ */
+export function syncAssets({
+  run = defaultRun,
+  root = repositoryRoot(run),
+  branch = DEFAULT_BRANCH
+} = {}) {
+  const dir = path.join(root, ASSETS_PATH)
+  const git = (args, quiet = true) => run('git', args, { cwd: dir, quiet })
+
+  log(`Moving ${ASSETS_PATH} to the latest ${branch}`)
+
+  if (!fs.existsSync(path.join(dir, '.git'))) {
+    run('git', ['submodule', 'update', '--init', ASSETS_PATH], { cwd: root })
+  }
+
+  if (git(['rev-parse', '--abbrev-ref', 'HEAD']).trim() !== branch) {
+    if (git(['status', '--porcelain']).trim()) {
+      throw new CommandError(
+        `${ASSETS_PATH} has uncommitted changes. Commit or discard them, then run the command again.`
+      )
+    }
+
+    // A fresh checkout, as on CI, has the submodule at a detached HEAD, fetched for the
+    // pinned commit only: there is neither a local branch nor a remote-tracking one.
+    git(['fetch', 'origin', branch])
+
+    if (hasLocalBranch(git, branch)) {
+      git(['checkout', branch])
+    } else {
+      git(['checkout', '-b', branch, 'FETCH_HEAD'])
+    }
+  }
+
+  git(['pull', '--ff-only', 'origin', branch])
+  buildCheckout(root, run)
+
+  const commit = git(['rev-parse', '--short', 'HEAD']).trim()
+  const moved = run('git', ['status', '--porcelain', '--', ASSETS_PATH], {
+    cwd: root,
+    quiet: true
+  }).trim()
+
+  if (moved) {
+    log(`${ASSETS_PATH} is at ${commit}. Check the site, then commit ${ASSETS_PATH} on its own.`)
+  } else {
+    log(`${ASSETS_PATH} is already at the latest ${branch}, ${commit}.`, 'success')
+  }
+}
+
+function hasLocalBranch(git, branch) {
+  try {
+    git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])
+    return true
+  } catch {
+    return false
+  }
+}
+
+function buildCheckout(root, run) {
+  const dir = path.join(root, ASSETS_PATH)
+
+  // The images are stored with Git LFS. Without it they are pointer files.
+  run('git', ['lfs', 'install', '--local'], { cwd: dir, quiet: true })
+  run('git', ['lfs', 'pull'], { cwd: dir })
+  run('pnpm', ['install', '--ignore-workspace'], { cwd: dir })
+  run('pnpm', ['assets:site'], { cwd: dir })
+
+  const output = path.join(dir, ASSETS_OUTPUT)
+
+  if (!fs.existsSync(output)) {
+    throw new CommandError(`The build of ${ASSETS_PATH} wrote nothing to ${ASSETS_OUTPUT}.`)
+  }
+
+  log(`Built ${path.join(ASSETS_PATH, ASSETS_OUTPUT)}`, 'success')
+}

package/src/cli/files.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { CommandError } from './shared.js'
+
+/** The default output folder of a Chassis site. */
+export const DEFAULT_PATHS = ['_site']
+
+/**
+ * The folders to skip when no `--ignore` is given: `static/icons` of each path, the files
+ * that a site copies from `@chassis-ui/icons`. They include a preview page of their own.
+ * @param {string[]} paths
+ */
+export function defaultIgnores(paths) {
+  return paths.map((dir) => path.join(dir, 'static/icons'))
+}
+
+/**
+ * Whether `file` is one of `ignores` or inside one of them.
+ * @param {string} file
+ * @param {string[]} ignores
+ */
+export function isIgnored(file, ignores) {
+  const target = path.resolve(file)
+
+  return ignores.some((ignore) => isInside(target, path.resolve(ignore)))
+}
+
+function isInside(target, dir) {
+  const relative = path.relative(dir, target)
+
+  return relative === '' || (relative.split(path.sep)[0] !== '..' && !path.isAbsolute(relative))
+}
+
+function checkExists(paths) {
+  for (const entry of paths) {
+    if (!fs.existsSync(entry)) {
+      throw new CommandError(`${entry} does not exist. Build the site first.`)
+    }
+  }
+}
+
+/**
+ * Lists the HTML files in `paths`, which are files or folders, leaving out `ignores` and
+ * `node_modules`.
+ * @param {string[]} paths
+ * @param {string[]} ignores
+ * @returns {string[]}
+ */
+export function findHtmlFiles(paths, ignores) {
+  const files = []
+
+  const visit = (entry) => {
+    if (isIgnored(entry, ignores)) return
+
+    if (fs.statSync(entry).isDirectory()) {
+      for (const name of fs.readdirSync(entry).sort()) {
+        if (name !== 'node_modules') visit(path.join(entry, name))
+      }
+    } else if (entry.endsWith('.html')) {
+      files.push(entry)
+    }
+  }
+
+  checkExists(paths)
+  paths.forEach(visit)
+
+  return files
+}
+
+/**
+ * Returns `paths` with `ignores` taken out. A folder that contains an ignored path is
+ * replaced by its entries, so that a checker that walks folders never reaches it.
+ * @param {string[]} paths
+ * @param {string[]} ignores
+ * @returns {string[]}
+ */
+export function expandPaths(paths, ignores) {
+  const result = []
+
+  const visit = (entry) => {
+    if (isIgnored(entry, ignores)) return
+
+    const target = path.resolve(entry)
+    const containsIgnored = ignores.some((ignore) => isInside(path.resolve(ignore), target))
+
+    if (containsIgnored && fs.statSync(entry).isDirectory()) {
+      for (const name of fs.readdirSync(entry).sort()) visit(path.join(entry, name))
+    } else {
+      result.push(entry)
+    }
+  }
+
+  checkExists(paths)
+  paths.forEach(visit)
+
+  return result
+}

package/src/cli/html-validate.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs'
+import { CommandError, importPeer, log } from './shared.js'
+import { findHtmlFiles } from './files.js'
+
+/** What the layouts and shortcodes of the package need. A site adds its own on top. */
+export const defaultConfig = {
+  extends: ['html-validate:recommended', 'html-validate:document'],
+  rules: {
+    // Astro writes void elements with a trailing slash
+    'void-style': 'off',
+    // Shiki highlights code with inline styles
+    'no-inline-style': 'off',
+    // The dialogs start at h2, and the `document` preset expects h1 in each sectioning root
+    'heading-level': ['error', { minInitialRank: 'h2', sectioningRoots: [] }],
+    // The layouts load their files from the site itself
+    'require-sri': 'off'
+  }
+}
+
+/**
+ * Adds a site's config to the default one: `extends` is appended, `rules` are merged,
+ * and `elements` is replaced.
+ * @param {Record<string, any>} base
+ * @param {Record<string, any>} [extra]
+ * @returns {Record<string, any>}
+ */
+export function mergeConfig(base, extra = {}) {
+  return {
+    ...base,
+    ...extra,
+    extends: [...(base.extends ?? []), ...(extra.extends ?? [])],
+    rules: { ...base.rules, ...extra.rules }
+  }
+}
+
+/**
+ * Reads a config file of html-validate.
+ * @param {string} file
+ */
+export function readConfig(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new CommandError(`Could not read ${file}: ${error.message}`, { cause: error })
+  }
+}
+
+// Validating hundreds of files at once runs out of file descriptors.
+async function mapWithConcurrency(limit, items, fn) {
+  const results = []
+  const running = new Set()
+
+  for (const item of items) {
+    const promise = fn(item).finally(() => running.delete(promise))
+
+    running.add(promise)
+    results.push(promise)
+
+    if (running.size >= limit) await Promise.race(running)
+  }
+
+  return Promise.all(results)
+}
+
+/**
+ * Validates the HTML files in `paths` with html-validate. Returns the exit code.
+ * @param {{ paths: string[], ignores: string[], config?: string }} options
+ */
+export async function htmlValidate({ paths, ignores, config }) {
+  const { HtmlValidate, Severity } = await importPeer('html-validate')
+  const validator = new HtmlValidate(mergeConfig(defaultConfig, config && readConfig(config)))
+  const files = findHtmlFiles(paths, ignores)
+
+  log(`Validating ${files.length} HTML files with html-validate`)
+
+  const reports = await mapWithConcurrency(10, files, async (file) => ({
+    file,
+    report: await validator.validateFile(file)
+  }))
+
+  let issueCount = 0
+  let fileCount = 0
+
+  for (const { file, report } of reports) {
+    const messages = (report.results[0]?.messages ?? []).filter(
+      (message) => message.severity >= Severity.WARN
+    )
+
+    if (messages.length === 0) continue
+
+    fileCount++
+    issueCount += messages.length
+    console.error(`\n${file}`)
+
+    for (const message of messages) {
+      const level = message.severity === Severity.ERROR ? 'error' : 'warning'
+
+      console.error(
+        `  ${message.line}:${message.column}  ${level}  ${message.message}  (${message.ruleId})`
+      )
+    }
+  }
+
+  if (issueCount > 0) {
+    log(`\n${issueCount} issues in ${fileCount} files.`, 'error')
+    return 1
+  }
+
+  log('Every HTML file is valid.', 'success')
+  return 0
+}