On this page

Upgrading to Clay 4

Clay 4 changes three things: the front matter field cards is now list, files and folders whose name starts with _ are no longer pages: they hold snippets, and older versions move from docs-archive/ into docs/. Everything else, your pages, folders, links, translations and clay.yaml, stays as it is. Until you have renamed it, clay build reports each file that still uses cards with a warning, and --strict fails.

#At a glance

Clay 3	Clay 4
`cards: true` in an `index.md`	`list: true`
`docs/_drafts/idea.md` is a page	Files and folders starting with `_` are no pages
`docs/` and `docs-archive/1.x/`	`docs/latest/` and `docs/1.x/`, moved by `npx clay version`

A coding agent can do the upgrade:

Suggested prompt

Upgrade the Clay docs in this repository to Clay 4, following
https://clay-doc.github.io/clay-example-repo/guides/upgrading-to-clay-4.md.
The upgrade is done when `npx clay build --strict` passes.

#Steps

Update Clay.

npm install --save-dev clay-doc@4

pnpm add --save-dev clay-doc@4

yarn add --dev clay-doc@4

Rename cards to list. In each index.md that has cards: true, write list: true instead:
docs/guides/index.md
```
---
title: Guides
cards: true
---
```
docs/guides/index.md
```
---
title: Guides
list: true
---
```
Search your docs for it, or let the build list the files:
```
grep -rl "^cards:" docs docs-archive
```
Rename pages that start with _, if you have any, and the links to them. List them with:
```
find docs docs-archive -name "_*"
```
Move older versions, if you have docs-archive/:
```
npx clay version
```
It moves docs/ into docs/latest/ and each docs-archive/<name>/ to docs/<name>/, so that all versions sit at the same depth, and gives paths that lead out of docs/ one more ../. It shows every change and asks first; see the first version. Commit the move on its own.
Check.
```
npx clay build --strict
```
When the build passes, the upgrade is done.

#What else is new

AI & AgentsEvery Clay site is ready for language models - each page as Markdown, an llms.txt index - and clay search, clay edit and clay check let AI agents find, change and check the docs.ComponentsTabs, steps, cards, folded sections, prompts, badges, math, diagrams and file trees, written in plain Markdown.Build ChecksLinks to sections are checked too, and a page that fails to render says why.Snippets & VariablesWrite a text once and use it on many pages, include code from your project, and fill in values like the current version.SearchFull-text search over every page and section, with typo tolerance, highlighted matches and keyboard shortcuts.SEOEvery page gets a picture for link previews, and sites under a path the address of their sitemap.

theme in clay.yaml sets your own colors and fonts, and analytics counts page views without cookies, see themes and analytics.
Settings can live in files of their own, like variables: config/variables.yaml, see clay.yaml.
generate in clay.yaml runs tools that write pages before every build, like an API reference from code, see generated docs.
head in clay.yaml adds scripts and meta tags to every page, see clay.yaml.
Videos and embeds of YouTube, Vimeo, Figma and more, see HTML.
Old addresses of moved pages keep working with redirects in front matter, see redirects.
Code blocks show the name of their file: ```yaml [clay.yaml], see code blocks.
On narrower screens, the contents of a page fold up above it.
A “Skip to content” link, clearer keyboard focus and stronger contrast make the site easier to use with a keyboard and easier to read.
Moving around feels smoother: the sidebar mark follows you, new breadcrumbs slide in and pages fade in. With “reduce motion” turned on in the system, nothing moves.