# Upgrading to Clay 5 :badge[Latest]{tip}

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](https://clay-doc.github.io/clay-example-repo/features/openapi.md) |
| `og:locale`, a `favicon.ico` and an `apple-touch-icon` come from `head` in `clay.yaml`, if at all | Clay writes them, see [SEO](https://clay-doc.github.io/clay-example-repo/features/seo.md) |
| `->`, `--`, `...` and `"quotes"` show as typed | They show as → – … and the quotes of the page's language, see [typography](https://clay-doc.github.io/clay-example-repo/writing/markdown.md#typography) |

A coding agent can do the upgrade:

::: 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

::: steps
1. **Update Clay.**

   ::: code-group
   ```bash [npm]
   npm install --save-dev clay-doc@5
   ```
   ```bash [pnpm]
   pnpm add --save-dev clay-doc@5
   ```
   ```bash [yarn]
   yarn add --dev clay-doc@5
   ```
   :::

2. **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:

   ```bash
   grep -rnE "^:{3,} *(request|fields|endpoints|credentials)\b" docs
   ```

   Put the ones that should stay text in a code block, or write `\:::`.

3. **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:

   ```bash
   grep -nE "og:locale|apple-touch-icon|favicon\.ico" clay.yaml config/*.yaml
   ```

4. **Check.**

   ```bash
   npx clay build --strict
   ```

   When the build passes, the upgrade is done.
:::

## What else is new

::: cards
- [OpenAPI](https://clay-doc.github.io/clay-example-repo/features/openapi.md)
  Pages for every operation and schema of an API, below the docs in the navigation, and request cells to try it on the page.
- [SEO](https://clay-doc.github.io/clay-example-repo/features/seo.md) {fa-solid fa-chart-line}
  Icons 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](https://clay-doc.github.io/clay-example-repo/organizing/versions.md).
- `footer` in `clay.yaml` puts links and a line of text below every page, see [clay.yaml](https://clay-doc.github.io/clay-example-repo/configuration/clay-yaml.md#footer).
- 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.

---

All pages of these docs, as Markdown for language models: https://clay-doc.github.io/clay-example-repo/llms.txt