On this page

Upgrading to Clay 5 Latest

Clay 5 adds pages for APIs from their OpenAPI documents, and request cells to try them. For an existing site, little changes: four new component names are taken, Clay now writes some tags into the head of every page that you may have added yourself, and it sets arrows, dashes and quotes in your text. Your pages, folders, versions, translations and clay.yaml stay as they are.

#At a glance

Clay 4	Clay 5
`::: request`, `::: fields`, `::: endpoints` and `::: credentials` are text	They are components
`og:locale`, a `favicon.ico` and an `apple-touch-icon` come from `head` in `clay.yaml`, if at all	Clay writes them, see SEO
`->`, `--`, `...` and `"quotes"` show as typed	They show as → – … and the quotes of the page’s language, see typography

A coding agent can do the upgrade:

Suggested prompt

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

#Steps

Update Clay.

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

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

yarn add --dev clay-doc@5

Look for the new component names. A line that starts with ::: request, ::: fields, ::: endpoints or ::: credentials was text and is now a component. Outside code blocks, such lines are rare; list them with:
```
grep -rnE "^:{3,} *(request|fields|endpoints|credentials)\b" docs
```
Put the ones that should stay text in a code block, or write \:::.
Remove head tags Clay now writes. Clay adds og:locale, a favicon.ico and an apple-touch-icon drawn from your favicon to every page. If head in clay.yaml adds them too, remove them there, so they are not in the page twice:
```
grep -nE "og:locale|apple-touch-icon|favicon\.ico" clay.yaml config/*.yaml
```
Check.
```
npx clay build --strict
```
When the build passes, the upgrade is done.

#What else is new

OpenAPIPages for every operation and schema of an API, below the docs in the navigation, and request cells to try it on the page.SEOIcons for search results and home screens, the site's name in search results, and the language of every page for link previews.

Saved versions keep their APIs: clay version copies the OpenAPI documents into the version, so its pages stay as they were. See versions.
footer in clay.yaml puts links and a line of text below every page, see clay.yaml.
The sidebar can be made wider or narrower by dragging its edge, and long titles end in “…”.
In the sidebar, the page you came from no longer stays marked after you follow a link in the text.