On this page

Upgrading to Clay 3

Clay 3 moves three things into the docs themselves: folder names, the start page and older versions. Everything else, your pages, links, translations and the rest of clay.yaml, stays as it is. Until you have moved them, clay build reports what is left with a warning, and --strict fails.

#At a glance

Clay 2	Clay 3
`dir-meta.yaml`	an `index.md` in each folder
`index` in `clay.yaml`	`docs/index.md`
`versions/<name>/docs/`	`docs-archive/<name>/`

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

Suggested prompt

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

#Steps

Update Clay.

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

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

yarn add --dev clay-doc@3

Move folder names into index.md files. Each entry of dir-meta.yaml becomes the front matter of an index.md in that folder; name becomes title:
dir-meta.yaml
```
- path: "guides"
  name: "Guides"
  icon: "fa-solid fa-book-open"
  order: 3
```
docs/guides/index.md
```
---
title: Guides
icon: fa-solid fa-book-open
order: 3
---
```
Names per language (name: {en: Guides, de: Anleitungen}) go into translations of the index.md: index.de.md with title: Anleitungen. Then delete dir-meta.yaml. An index.md with only front matter just names its folder; add text below it, and it becomes the folder’s page, see index pages.

Move the start page into docs/index.md. For a similar look, a large header and the top-level pages below it, set hero and list:

clay.yaml

index:
  title: "Welcome to My Project"
  description: "Everything you need to know."
  icon: "fa-solid fa-rocket"

docs/index.md

---
title: Welcome to My Project
description: Everything you need to know.
icon: fa-solid fa-rocket
hero: true
list: true
---

Values per language go into docs/index.de.md and so on. Then remove index from clay.yaml.

Move older versions into docs-archive/. They move one level up, and their dir-meta.yaml turns into index.md files as in step 2:
- versions/1.x/docsClay 2
- docs-archive/1.xClay 3
```
mkdir docs-archive
git mv versions/1.x/docs docs-archive/1.x
```
Check.
```
npx clay build --strict
```
When the build passes, the upgrade is done. Links to index.md files and to folders lead to the folders’ pages, so existing links keep working.

#What else is new

In the sidebar, a folder’s title opens its page; the arrow shows and hides its pages.
clay edit creates, renames, moves and deletes pages and folders, edits all front matter, and works in every version and language.
Section headings show a # link to copy.

Continue with upgrading to Clay 4.