Commands

Clay is used through one command, clay (or its alias clay-doc), with a subcommand:

clay <command> [options]

Run it with npx clay … in a project that has Clay installed, or through scripts in package.json.

#clay dev

npx clay dev

Starts a development server at http://localhost:3000. It renders each page when you open it and reloads the browser whenever you change a page, an image or clay.yaml. Use it while writing; it is not meant to be put online.

While it runs, the terminal shows the address, warnings such as broken links, and each page it reloads:

┌  Clay 3.1.0 · dev
│
●  Loaded 40 pages from docs  languages de (30/30 translated) · 52ms
│
●  Started dev server  1.1s
│  ➜ Local:   http://localhost:3000/
│  ➜ Network: use --host to expose
│
│  ↻ Reloaded docs/writing/pages.md  10:24:31

--verbose shows the full output of Nuxt instead.

#clay build

npx clay build

Checks the docs, renders every page to HTML and writes the finished site to publish/public. While it runs, Clay shows its progress:

┌  Clay 2.1.0
│
●  Loaded 29 pages from docs  languages de (29/29 translated) · 310ms
│
●  Built client  199 modules · 960ms
│
●  Built server  126 modules · 420ms
│
◝  Prerendering pages · 41 routes

Without a terminal, for example in CI, it prints the finished steps as plain lines.

The build contains:

The build checks explain the warnings and --strict.

#clay preview

npx clay preview

Serves the last build at http://localhost:4173, behaving like GitHub Pages and most static hosts:

• the site is served under its baseURL,
• /guides/setup redirects to /guides/setup/,
• unknown addresses get the 404.html page with status 404.

Run it before you deploy: a page that works in clay preview works on the host. The terminal lists each address that got a 404, which points to a missing file or a wrong baseURL.

#clay edit

npx clay edit

Opens an editor in the terminal to create, edit, order, rename, move, delete and translate pages and folders, in every version and language, and to edit the settings in clay.yaml. See clay edit.

#clay version

npx clay version 2.x

Copies docs/ into docs-archive/2.x/, keeping the current state of the docs as an older version. In clay edit, V does the same. See versions.

#Options

Examples:

# Docs in a subfolder of a larger repository
npx clay build --root documentation

# Build into dist/public
npx clay build --out dist

# Preview on another port, reachable from other devices
npx clay preview --port 8080 --host