{"id":50907814,"url":"https://github.com/jdevalk/specification.website","last_synced_at":"2026-07-03T23:01:02.264Z","repository":{"id":361136979,"uuid":"1253236308","full_name":"jdevalk/specification.website","owner":"jdevalk","description":"Website specification — HTML, accessibility, security, SEO, agent-readiness. Platform-agnostic, sourced, MIT.","archived":false,"fork":false,"pushed_at":"2026-07-01T06:25:27.000Z","size":12639,"stargazers_count":734,"open_issues_count":0,"forks_count":47,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-07-01T08:16:36.239Z","etag":null,"topics":["accessibility","agent-readiness","astro","cloudflare-pages","llms-txt","mcp","seo","specification","web-security","web-standards","well-known"],"latest_commit_sha":null,"homepage":"https://specification.website","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdevalk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T09:13:26.000Z","updated_at":"2026-07-01T06:25:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jdevalk/specification.website","commit_stats":null,"previous_names":["jdevalk/specification.website"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jdevalk/specification.website","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdevalk%2Fspecification.website","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdevalk%2Fspecification.website/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdevalk%2Fspecification.website/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdevalk%2Fspecification.website/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdevalk","download_url":"https://codeload.github.com/jdevalk/specification.website/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdevalk%2Fspecification.website/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35104115,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","agent-readiness","astro","cloudflare-pages","llms-txt","mcp","seo","specification","web-security","web-standards","well-known"],"created_at":"2026-06-16T07:00:33.038Z","updated_at":"2026-07-03T23:01:02.260Z","avatar_url":"https://github.com/jdevalk.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# The Website Specification\n\n[![CI](https://github.com/jdevalk/specification.website/actions/workflows/ci.yml/badge.svg)](https://github.com/jdevalk/specification.website/actions/workflows/ci.yml)\n[![Lint](https://github.com/jdevalk/specification.website/actions/workflows/lint.yml/badge.svg)](https://github.com/jdevalk/specification.website/actions/workflows/lint.yml)\n[![Format](https://github.com/jdevalk/specification.website/actions/workflows/format.yml/badge.svg)](https://github.com/jdevalk/specification.website/actions/workflows/format.yml)\n[![Links](https://github.com/jdevalk/specification.website/actions/workflows/links.yml/badge.svg)](https://github.com/jdevalk/specification.website/actions/workflows/links.yml)\n[![Security](https://github.com/jdevalk/specification.website/actions/workflows/security.yml/badge.svg)](https://github.com/jdevalk/specification.website/actions/workflows/security.yml)\n[![Code licence: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](LICENSE)\n[![Content licence: CC BY 4.0](https://img.shields.io/badge/content-CC%20BY%204.0-blue.svg)](https://creativecommons.org/licenses/by/4.0/)\n[![Deployed on Cloudflare Pages](https://img.shields.io/badge/deploy-Cloudflare%20Pages-orange.svg)](https://specification.website)\n\nThe website specification — from `\u003ctitle\u003e` to `/.well-known/security.txt`, from WCAG contrast to `llms.txt`. Platform-agnostic, sourced on every page, written for humans and agents. MIT licensed, open for pull requests.\n\n**Live site:** \u003chttps://specification.website\u003e\n**MCP server:** \u003chttps://mcp.specification.website/mcp\u003e\n\n## What this is\n\nThe web is a layer cake of standards: WHATWG defines HTML, W3C ratifies WCAG, the IETF publishes the RFCs behind security headers and `/.well-known/` URIs, IANA registers the namespaces, search engines publish their own rules, browsers add quirks. Almost nobody carries the whole picture.\n\nThis site collects the slices into one platform-agnostic specification — sources cited on every page.\n\nIt is _not_ a framework. It is _not_ a tutorial. It is a spec, in the same way the HTML Living Standard is a spec: outcomes, requirements, references.\n\n## What this is not\n\n- Not platform-specific. No \"use this Next.js plugin\" advice — the spec describes the outcome, you choose the implementation.\n- Not opinion. Where there is no settled standard, the spec says so.\n- Not a marketing site. No newsletter capture. No cookies. Aggregate Plausible analytics; that's it.\n\n## Categories\n\n- **Foundations** — HTML, head, document basics.\n- **SEO** — search visibility.\n- **Accessibility** — WCAG-aligned rules.\n- **Security** — headers, transport, policies.\n- **Well-Known URIs** — agreed paths under `/.well-known/`.\n- **Agent Readiness** — making a site legible to AI agents.\n- **Performance** — Core Web Vitals, caching, fonts.\n- **Privacy** — consent, signals, respecting choice.\n- **Resilience** — graceful failure.\n- **Internationalisation** — language, locale, direction.\n\n## Development\n\nRequirements: Node.js 22.12+, npm.\n\n```bash\nnpm install\nnpm run dev      # http://localhost:31337\nnpm run build    # static output in ./dist\nnpm run preview  # serve ./dist on port 31337\n```\n\nThe dev server runs on port `31337` by convention (because of course it does).\n\n## Adding or changing a spec page\n\n1. Find the right category under `src/content/spec/\u003ccategory\u003e/`.\n2. Copy an existing `.md` file — for example, `src/content/spec/foundations/title.md`.\n3. Fill in the front matter (see schema in [`src/content.config.ts`](src/content.config.ts)). At minimum: `title`, `summary`, `category`, `status`, `order`, and `sources`.\n4. Write the body. Sections: `## What it is`, `## Why it matters`, `## How to implement`, `## Common mistakes`, `## Verification`.\n5. Open a PR.\n\nThe build will fail if the schema is invalid — that is intentional.\n\nEverything derived from the spec content updates automatically: `/spec/`, `/checklist/`, `/llms.txt`, `/llms-full.txt`, `/sitemap-index.xml`, `/rss.xml`, per-page `.md` endpoints, the Pagefind search index, and the MCP server's bundled data. Never hand-edit those; edit the source markdown.\n\n## Status levels\n\n- **Required** — the web platform contract breaks without it.\n- **Recommended** — modern sites should do it.\n- **Optional** — depends on context.\n- **Avoid** — outdated, harmful, or actively superseded.\n\n## Sources\n\nEvery page cites at least one source. The site draws on:\n\n- [WHATWG HTML Living Standard](https://html.spec.whatwg.org/)\n- [MDN Web Docs](https://developer.mozilla.org/)\n- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and the Understanding documents\n- [IETF RFCs](https://www.rfc-editor.org/) for protocol-level items\n- [sitemaps.org](https://www.sitemaps.org/), [schema.org](https://schema.org/), [llmstxt.org](https://llmstxt.org/)\n- [Google Search Central](https://developers.google.com/search), [web.dev](https://web.dev/)\n- [Yoast Developer Portal](https://developer.yoast.com/)\n- [Equalize Digital Accessibility Checker docs](https://equalizedigital.com/accessibility-checker/documentation/)\n- [WP Accessibility Knowledge Base](https://wpaccessibility.org/)\n- [Is It Agent Ready?](https://isitagentready.com/)\n- [Overlay Fact Sheet](https://overlayfactsheet.com/)\n\n## MCP server\n\nA separate Cloudflare Worker in [`mcp/`](mcp/) exposes the spec to MCP-aware agents. See [`mcp/README.md`](mcp/README.md) for tools, the connection config, and how to deploy.\n\n## Licence\n\nContent is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Code is licensed under [MIT](LICENSE). Use it, fork it, ship it.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Three rules: cite your sources, stay platform-agnostic, be honest about status.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) or [/.well-known/security.txt](https://specification.website/.well-known/security.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdevalk%2Fspecification.website","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdevalk%2Fspecification.website","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdevalk%2Fspecification.website/lists"}