Snippets & Variables New in Clay 4

Some text belongs on many pages: a requirement, a warning, the current version. Write it once, and Clay fills it in wherever it is used when it builds the site. Search, link checks and the Markdown for agents all see the finished text.

#Variables

Define values in clay.yaml:

variables:
  major: "4"
  node: "20.19"

Use them in any page with two curly braces:

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

Clay {{major}} needs Node.js {{node}} or newer:

```bash
npm install --save-dev clay-doc@{{major}}
```

• Variables work everywhere in a page: in text, code blocks, links and front matter.
• Only names from variables are filled in. Other curly braces stay as written, so templates in code examples are safe.
• A backslash keeps a variable as written: \{{major}} shows {{major}}.
• Values can differ per language, like every text in clay.yaml: product: {en: "Docs", de: "Doku"}.
• Saved versions keep their values: clay version fills the variables in, so the old docs still name the old version.

#Snippets

Put a text you want to reuse in a file whose name, or whose folder’s name, starts with _: such files are no pages. Include it with an HTML comment on a line of its own:

<!--@include: ../_snippets/node-version.md-->

> [!NOTE]
> Clay {{major}} needs **Node.js {{node}}** or newer.

• The path is relative to the page, like a link. The snippet’s front matter is left out.
• Links and images in a snippet are relative to the page that includes it.
• Snippets can include snippets, relative to themselves, and variables are filled in everywhere.
• Indent the include, and the whole snippet is indented: includes work inside steps and lists.
• On GitHub, the include is an HTML comment and shows nothing.

#Code from your project

Includes work in code blocks too, with any file of the project, so examples in the docs stay the code that runs:

```ts
<!--@include: ../../src/client.ts#setup-->
```

Mark regions in comments of the file’s language; the marker lines are left out:

// #region setup
const client = createClient({token: process.env.TOKEN});
// #endregion

This site does the same with its own settings: the block below is included from its config/variables.yaml, between # #region values and # #endregion, and changes with it.

major: "4"
node: "20.19"

```yaml [config/variables.yaml]
<!--@include: ../../../config/variables.yaml#values-->
```

#Checks

The build reports includes it cannot fill in, and leaves them out:

docs/guides/setup.md: includes "../_snippets/gone.md", which does not exist; it is left out

The same goes for files outside the project, regions that do not exist and snippets that lead back to the page. With --strict, they fail the build, see build checks.