On this page

Upgrading to Clay 2

Clay 1 needed two parts: the Clay frontend and Clay Oven, a separate Go tool that prepared the docs. Clay 2 is a single npm package, clay-doc, that does both. Your docs/ folder, clay.yaml, dir-meta.yaml, the environment variables and the URLs of your pages stay as they are; what changes is how you build.

#At a glance

Clay 1	Clay 2
Download Clay Oven, run `./clay-oven`	`npm install --save-dev clay-doc`, run `npx clay build`
Output in `output/`	Output in `publish/public`
`run-oven.sh` in CI	`npm ci` and `npx clay build --strict`
`-c`, `-d`, `-o`, `-fm` flags	`--root` and `--out`; the file names are fixed
`-nc`, `-ci` to skip prompts	No prompts anymore
`langs` in `clay.yaml`	Not needed: languages of code blocks are detected
No live preview	`npx clay dev`

A coding agent can do the upgrade, straight on to Clay 4:

Suggested prompt

Upgrade the Clay docs in this repository from Clay 1 and Clay Oven to Clay 4:
follow https://clay-doc.github.io/clay-example-repo/guides/upgrading-to-clay-2.md,
then upgrading-to-clay-3.md and upgrading-to-clay-4.md next to it, and install
clay-doc@4 directly. Update the CI workflow too. The upgrade is done when
`npx clay build --strict` passes.

#Steps

Install Clay.

npm init -y                       # only if there is no package.json yet
npm install --save-dev clay-doc@2

pnpm init                         # only if there is no package.json yet
pnpm add --save-dev clay-doc@2

yarn init -y                      # only if there is no package.json yet
yarn add --dev clay-doc@2

Clean up clay.yaml. Remove langs, if you have it. Clay 2 warns about it but works anyway.
Update .gitignore. Clay 2 writes into publish/; output/ from Clay Oven can go.
```
node_modules/
publish/
output/
```

Update CI. Replace the Clay Oven step in your workflow, and upload publish/public instead of output:

- name: Build docs
  run: curl -fsSL https://raw.githubusercontent.com/clay-doc/clay-oven/refs/heads/main/run-oven.sh | sh
- uses: actions/setup-node@v7
  with: 
    node-version: lts/*
    cache: npm
- run: npm ci
- run: npx clay build --strict

GitHub Pages has a complete workflow.

Check.
```
npx clay build --strict
```
Clay 2 checks links and settings more thoroughly than Clay Oven did. Fix what it reports, see build checks; when the build passes, the upgrade is done.

#What else is new

A live preview with clay dev.
Build checks for links and settings.
Search with typo tolerance, and SEO with a sitemap.
description and order in the front matter.
Versions and translations, see versions and translations.

Continue with upgrading to Clay 3.