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.

npx clay edit

┌  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.

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, and ask whether the old address should redirect to the new one. Clay does not rewrite links to the entry; instead, it lists the links that broke, so you can fix them:

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). 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.

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.

#From scripts and AI agents

Every action of the editor is also a command that does one change and exits. Scripts and AI agents use these, since they have no terminal to drive the editor; clay edit without a command explains them when it runs without one.

Paths are relative to the docs, docs/ or with versions docs/latest/: guides/setup.md (the .md may be left out), guides for a folder, index.md for the start page. --lang works in another language, --docs-version in an older version, and --json prints the result as JSON.

npx clay edit set guides/setup.md title="Setting up" order=2 --json

{
  "ok": true,
  "written": ["docs/guides/setup.md"]
}

Run npx clay edit help for every command with examples, and npx clay check after changes: it reports broken links and settings without building. See AI & agents.