v4.0.0

4.0.0 (2026-10-16)

⚠ BREAKING CHANGES

• versions: docs-archive/ is no longer read. Run "clay version" to move docs/ into docs/latest/ and docs-archive// to docs//.
• markdown: files and folders whose name starts with "_" are no longer pages; they hold snippets.
• front-matter: the "cards" front matter key, renamed to "list" in Clay 3, is no longer read; rename it to "list".

Features

• a11y: add a skip link, focus rings, better contrast and axe tests (f093f26)
• agents: publish every page as Markdown with llms.txt, and a page menu (6a6a12e)
• alerts: draw the alert's color as a bar beside the box (ad28d77)
• analytics: count page views and events without cookies (543bc3d)
• checks: report links to missing sections (b73026f)
• cli: add clay edit commands and clay check for scripts and agents (af9bb7b)
• cli: run "generate" commands before build, dev and check (5ef7573)
• config: add tags to the head of every page with "head" (68af545)
• config: hide entries of the page menu (544f413)
• config: let settings live in files of their own (e8694e9)
• content: let the navbar and sidebar cast a shadow on the page (554323f)
• front-matter: stop reading the "cards" alias of "list" (f325651)
• markdown: add a prompt block for AI assistants and agents (0f273db)
• markdown: add snippets and variables (1fcf98a)
• markdown: add tabs, steps, cards, details, badges, math, diagrams and file trees (4deb503)
• markdown: embed videos, designs and code playgrounds (e417211)
• markdown: show the file name of a code block (681b9a8)
• navbar: slide new breadcrumbs in (907f05c)
• pages: fade a page in after navigating to it (943a767)
• redirects: keep old addresses of moved pages (4e2e0b4)
• search: group results by page and filter them by section (574e872)
• seo: draw a social image for every page (16e35c1)
• seo: draw Chinese, Japanese and Korean in social images (851c462)
• seo: point sites under a path to their sitemap (8db0994)
• sidebar: grow the highlight when it jumps between folder levels (8f2ad2f)
• theme: add your own colors, corners and fonts (3d28a10)
• toc: fold the contents up above the page on narrow screens (693059c)
• versions: keep every version in a folder of its own in docs/ (e9a4e24)

Bug Fixes

• app: block only /docs/ addresses and drop the old .md redirect (5953c7e)
• checks: check files and links written in HTML (a40db81)
• checks: check the links of folder and start pages (73b83bd)
• cli: keep bin/clay.mjs executable (f82f0e3)
• cli: name the cause when pages fail to render (48297bc)
• layout: only show scrollbars when the page scrolls (43bb61d)
• markdown: leave badges out of heading links (9e0d555)
• search: drop alert markers from indexed text (3f363f8)
• types: satisfy the stricter head and token types (eaba789)