A spec site with eighteen npm scripts, no npm test, and an install step that repoints your git hooks

Nine published artefacts, all generated from the source markdown

The most useful thing about this repository is a rule about what not to touch. Everything derived from the spec content regenerates automatically, and the instruction is not to hand-edit any of it.

The generated set is long: the spec index, a checklist, two flavours of the text file for language models, a sitemap index, an RSS feed, per-page markdown endpoints, the Pagefind search index, and the bundled data the MCP server serves.

That list is the design. One markdown file per rule, validated against a schema, is the only editable artefact, and everything a reader, a crawler or an agent consumes is a projection of it. Adding a rule therefore changes the checklist, both model-readable files, the feed, the search index and the agent's data in one commit, with no chance of the checklist disagreeing with the spec.

The sibling decision is that the outputs are deliberately redundant. A checklist for a person, a short text file for an agent deciding what to read, a full text file for an agent that wants everything, a feed for a reader, and a search index for someone who knows a phrase but not the rule name. Five audiences, one source.

Five required sections and six required fields, or the build fails

Adding a page is described as a five step procedure, and the schema is enforced rather than suggested.

Find the category directory under the spec content path, copy an existing markdown file, fill in the front matter, write the body, open a pull request. The front matter needs at minimum a title, a summary, a category, a status, an order and a sources list, with the schema itself defined in a TypeScript content configuration file at the source root.

The body has a fixed shape: what the rule is, why it matters, how to implement it, common mistakes, and how to verify it. Every page uses those five sections, which is what lets a reader compare two unrelated rules side by side.

And the build fails when the schema is invalid. The documentation marks that as intentional, which is the right call: a spec whose pages can be malformed in a way the site still renders is a spec that accumulates exceptions.

The consequence for contributors is concrete. A page missing one field or carrying a status the vocabulary does not define will not appear at all, so the local preview step matters more here than in a typical documentation site.

npm install repoints the repository's git hooks

One script in the manifest has a side effect outside the build, and it runs every time.

The prepare script executes a git configuration command that sets the repository's hooks path to the hooks directory in the tree, and it appends an or-true so a failure does not stop the install. Prepare runs on a plain dependency install, so anyone who clones the repository and types `npm install` has their local git configuration rewritten as a side effect of getting dependencies.

That is usually what the author intended, since a hooks directory in the tree implies the hooks should be used. It is still worth knowing about in two situations. If you install on a machine where the repository is a worktree, a submodule or a shared checkout, the change is not scoped to your clone. And if a pipeline restores a cached `node_modules` without running install, the hooks never get pointed at the tree, so the checks the hooks enforce silently do not happen.

npm install

The documented development surface is four commands on top of that:

npm run dev
npm run build
npm run preview

Node 22.12 or newer is the stated floor, and the dev server runs on port 31337 by convention, as the documentation puts it.

There is no npm test, and the checks live inside the build

The manifest defines eighteen scripts and none of them is called test.

What exists instead is spread across the lifecycle. The build script runs the Astro build, then Pagefind over the output directory, then an integrity check script. Pre-build and pre-dev both run an asset generation script. There are separate type-aware checks, a lint script over the whole tree, and separate write and check modes for formatting.

Two test-shaped commands do exist, and they are specific: one exercises WebSub, and one runs the adoption script's tests through the Node test runner with a type-stripping flag. A skill file has a signing script and a checking script. So the verification a contributor cares about is spread across five entry points rather than one, and the only thing guaranteed to run on every build is the integrity check.

That integrity check is also the piece doing the most work conceptually. It runs after the site is built, which is the only point at which the generated artefacts exist, so it is the natural place to check that the nine outputs are consistent with the content.

Outside the manifest, the repository also carries a Lighthouse configuration and a link checker configuration, and five separate continuous integration workflows, two of which are dedicated to link checking and security.

A static specification site with a BigQuery client in its dependencies

The README describes a static specification with one extra service, an MCP server. The repository describes rather more.

The manifest lists seven runtime dependencies: MDX integration, the RSS integration, the Astro framework itself, a Tailwind Vite plugin, Tailwind, DOMPurify for sanitising markup, and the Google Cloud BigQuery client.

That last one is the item that does not fit the description. A BigQuery client is a runtime dependency of a site whose build output is a static directory, and the presence of a `migrations/` directory, an `ops/` directory, a `functions/` directory and a `wrangler.toml` says there is data plumbing behind it. The `adoption` script and its test suite point the same way, since fetching adoption numbers is a data job rather than a page build.

The Cloudflare pieces are documented, at least partly. The MCP server is a separate Worker in its own directory, with its own readme covering tools, connection config and deployment, and the worker types package is a declared development dependency. The `functions/` directory and the Wrangler configuration are the shape of a second deployable.

So the honest description is a specification site plus a Worker for agents plus some data tooling, where only two of the three are explained to a reader. Someone evaluating whether to depend on this should read the operations and migration directories before assuming it is a folder of markdown.

The source list puts a vendor portal next to a ratified standard

The stated rule is that every page cites at least one source, and the drawing on is given as a list. Some of it is normative: the WHATWG HTML Living Standard, MDN, WCAG 2.2 with its Understanding documents, and the IETF RFCs for protocol-level items, with the IANA registries named as the other layer of the stack.

The rest is not. Search engine documentation, a web performance site, a commercial search optimisation vendor's developer portal, documentation for a commercial accessibility checker, a WordPress accessibility knowledge base, a site that appears to rate sites for agent readiness, and a site whose name refers to accessibility overlays.

That mix is defensible for a practical document, because those are where the actionable detail lives and a ratified standard rarely tells you what to type. It sits badly with the status vocabulary, though. A requirement marked Required is supposed to mean the platform contract breaks without it, and a requirement marked Avoid is supposed to be superseded or harmful. Neither of those is something a vendor's own marketing documentation can establish on its own.

The accessibility entries are the sharpest case. An overlay-related source sits in a list that also carries the W3C accessibility guidelines, in a document whose categories include Accessibility, and the file does not say how a source of that kind is weighted against a ratified one.

Four status levels, and a contributing rule about honesty

The status vocabulary is small and the definitions are tight.

Required means the web platform contract breaks without it. Recommended means modern sites should do it. Optional means it depends on context. Avoid means outdated, harmful, or actively superseded.

Three of the four are judgements, and Required is the only one that claims to be mechanical. That distinction is what makes the vocabulary usable: a reader can disagree with a Recommended and still follow it, but a Required is supposed to be demonstrable.

The same attitude runs through what the project says it is not. Not platform-specific, so no advice about which plugin to install; the outcome is specified and the implementation is the reader's choice. Not opinion, so where no standard has settled a question the document says so rather than picking a side. Not a marketing site, with no newsletter capture and no cookies, and a single aggregate analytics provider.

Contributing is governed by three rules, and the third is the interesting one: cite your sources, stay platform-agnostic, and be honest about status. Given that every page must carry sources and the status vocabulary has four levels, that last rule is the one that decides whether the document stays a specification or becomes a set of house preferences.

Editorial conclusion

This is worth reading if you want one place that states what a website should do and cites where each requirement comes from, and it is worth reading as an example of the generated-output discipline: nine artefacts, one source, and an explicit instruction never to edit the output. Two things to weigh. That the source list mixes normative standards with vendor guidance, so a requirement you want to cite in your own work may only be supported by a search engine's documentation or a commercial vendor's portal, which is a weaker footing than a ratified standard. And that the build fails on an invalid page schema by design, so a contribution that is one field short will be rejected rather than half-rendered. Before contributing, note that `npm install` repoints the repository's git hooks, the package is private with no published releases, and the manifest defines eighteen scripts while the documentation names four.

Frequently asked questions

Official sources

1. Issues
2. jdevalk/specification.website on GitHub
3. Project website
4. README