On this page

Installation

Clay is published on npm as clay-doc. It needs Node.js 22.22.3 or newer:

node --version   # v22.22.3 or newer

#Add Clay to a project

Install Clay as a development dependency of the project you want to document:

npm install --save-dev clay-doc

pnpm add --save-dev clay-doc

yarn add --dev clay-doc

This adds Clay to package.json and pins the exact version in the lockfile, so every build, on your machine or in CI, uses the same version.

Add scripts to package.json, so nobody has to remember the commands:

package.json

{
  "scripts": {
    "docs:dev": "clay dev",
    "docs:build": "clay build --strict",
    "docs:preview": "clay preview"
  }
}

Then npm run docs:dev starts the live preview.

Tip

Clay installs two commands, clay and clay-doc. They do the same; use whichever reads better in your scripts.

#Without installing

Documentation often lives in repositories written in Go, Python, Java or other languages, where a package.json would be out of place. You do not need one: npx runs Clay straight from npm in any folder with a clay.yaml and a docs/ folder.

npx clay-doc dev

Name a version, so every build uses the same one:

npx clay-doc@5 build --strict

Note

Tools like Dependabot cannot update a version written into a command, so you update it yourself.

#Updating Clay

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

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

yarn add --dev clay-doc@latest

Clay follows semantic versioning: minor and patch releases add features and fix bugs without breaking your docs. Major releases come with an upgrade guide, like upgrading to Clay 5. The changelog lists every change.

#Next

Build your first site with the quick start.