# Editing with clay edit
`clay edit` is an editor in the terminal for everything around your pages: creating pages and folders, their front matter, their order, renaming, moving and deleting them, translations, versions and the settings in `clay.yaml`. It writes the same files you would edit by hand, so you can mix both ways freely.
```bash
npx clay edit
```
```text
┌ Clay · edit Pages Settings latest · en
│
│ ⌂ Clay Documentation fa-solid fa-book-open
│ ◆ Introduction fa-solid fa-house
│ › ▾ Getting Started fa-solid fa-rocket
│ │ ◆ Installation fa-solid fa-download
│ │ ◆ Quick Start fa-solid fa-bolt
│ ▸ Writing fa-solid fa-pen-nib
│
└ ⏎ details · n page · f folder · m order · o move · r rename · x delete · v/V version · l language · tab · q
```
Changes are written right away, one file at a time, and the editor shows which files it wrote. Use git to review or undo them.
## Pages and folders
The **Pages** tab shows the start page (`⌂`), the folders (`▾`) and the pages (`◆`) in navigation order. Titles in gray are defaults, taken from the first heading or the file name.
| Key | Action |
|-----|--------|
| ↑ ↓ | Select an entry |
| ← → | Close and open folders |
| ⏎ | Open the details: all front matter fields of the entry |
| t / i | Edit the title / icon directly |
| n | Create a page in the selected folder (or next to the selected page) |
| f | Create a folder, with an `index.md` |
| m | Pick the entry up; move it with ↑ ↓, drop it with ⏎ |
| o | Move the entry into another folder |
| r | Rename the file or folder |
| x | Delete the entry, after asking |
| Tab | Switch to the settings |
| q | Quit |
New pages get their title as front matter and as their first heading, and a file name made from the title, which you can change before it is created. New folders get an `index.md` with their title and `list: true`.
Ordering numbers everything in the folder (`order: 1`, `2`, `3`, …) and writes only the files whose number changed.
Renaming and moving take the page's translations along. Clay does not rewrite links to the entry; instead, it lists the links that broke, so you can fix them:
```text
Moved setup.md → guides/setup.md · 2 link(s) broke: introduction.md: "setup.md" points to a missing page (/setup) …
```
## The details
⏎ opens all front matter fields of the selected entry: title, icon, description and order, and for folders and the start page also `list` and `hero` (see [index pages](https://clay-doc.github.io/clay-example-repo/3.x/organizing/index-pages.md)). Select a field and press ⏎ to change it; yes/no fields switch with ⏎. Esc leads back to the list.
In a text field, ⏎ applies and Esc cancels. Leave a field empty to remove the value and go back to the default. For a folder without an `index.md`, the editor creates one.
## Versions and languages
The header shows which version and language you are editing.
| Key | Action |
|-----|--------|
| v | Switch to the next version |
| V | Save the current docs as a new version, see [versions](https://clay-doc.github.io/clay-example-repo/3.x/versions-and-languages/versions.md) |
| l | Switch to the next language |
| c | Start a translation of the selected entry: copies the original into `*.de.md` and so on |
In another language, pages without a translation are marked **untranslated**. Setting a field of such a page creates the translation from the original first. The order is the same in every language, so it is changed in the default language.
## Settings
The **Settings** tab lists the settings of `clay.yaml`. Select one and press ⏎ to change it. Settings with a value per language are edited in the language shown in the header. Navbar links are added with **+ Add link** and removed with d.
Clay changes only the values you edit. Comments, quotes, the order of keys and the rest of each file stay as they were, so the diff in git shows exactly your change.
> [!TIP]
> Run `npx clay dev` in a second terminal: the site reloads with every change you make in the editor.
---
All pages of these docs, as Markdown for language models: https://clay-doc.github.io/clay-example-repo/3.x/llms.txt