# Writing

Every page is a Markdown file in `docs/`, written in **Clay Flavored Markdown** (CFM): the Markdown you know from GitHub, plus syntax highlighting, alerts and components. Clay checks your links on every build.

::: cards
- [Pages](https://clay-doc.github.io/clay-example-repo/4.x/writing/pages.md)
- [Markdown](https://clay-doc.github.io/clay-example-repo/4.x/writing/markdown.md)
- [Code Blocks](https://clay-doc.github.io/clay-example-repo/4.x/writing/code-blocks.md)
- [Alerts](https://clay-doc.github.io/clay-example-repo/4.x/writing/alerts.md)
- [Components](https://clay-doc.github.io/clay-example-repo/4.x/writing/components.md)
- [Links & Images](https://clay-doc.github.io/clay-example-repo/4.x/writing/links-and-images.md)
- [HTML](https://clay-doc.github.io/clay-example-repo/4.x/writing/html.md)
- [Snippets & Variables](https://clay-doc.github.io/clay-example-repo/4.x/writing/snippets-and-variables.md)
- [Generated Docs](https://clay-doc.github.io/clay-example-repo/4.x/writing/generated-docs.md)
:::

## A page at a glance

One file, from front matter to components:

::: tabs
== Result
**Setup** is the page's title in the sidebar; its text starts like this:

> [!TIP]
> Already installed? Skip to [the configuration](https://clay-doc.github.io/clay-example-repo/4.x/configuration/clay-yaml.md).

::: code-group
```bash [npm]
npm install --save-dev clay-doc
```
```bash [pnpm]
pnpm add --save-dev clay-doc
```
:::
== Markdown
````markdown
---
title: Setup
icon: fa-solid fa-wrench
description: Install and configure the project in five minutes.
---

# Setting up the project

> [!TIP]
> Already installed? Skip to [the configuration](../configuration/clay-yaml.md).

::: code-group
```bash [npm]
npm install --save-dev clay-doc
```
```bash [pnpm]
pnpm add --save-dev clay-doc
```
:::
````
:::

## What to use when

| You want to … | Use |
|---------------|-----|
| Show a command or a file | a [code block](https://clay-doc.github.io/clay-example-repo/4.x/writing/code-blocks.md), with its file name, highlighted lines or a diff |
| Show the same thing for npm, pnpm and yarn, or for each system | [tabs or a code group](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/tabs.md) |
| Walk readers through something in order | [steps](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/steps.md) |
| Point out a tip, a warning or a risk | an [alert](https://clay-doc.github.io/clay-example-repo/4.x/writing/alerts.md) |
| Hide what only some readers need | [details](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/details.md) |
| Lead readers to other pages | [cards](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/cards.md) or [links](https://clay-doc.github.io/clay-example-repo/4.x/writing/links-and-images.md) |
| Explain how parts fit together | a [diagram](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/diagrams.md) or a [file tree](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/file-trees.md) |
| Suggest what to ask an AI assistant or agent | a [prompt](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/prompts.md) |
| Mark something as new or deprecated | a [badge](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/badges.md) |

## Key ideas

- **One file, one page.** `docs/guides/setup.md` becomes `/guides/setup`.
- **Links work like on GitHub.** Link to the `.md` file; Clay turns it into the page's URL and reports links that lead nowhere.
- **Files next to your pages are published.** Images and downloads in `docs/` keep their relative paths.
- **Plain text stays plain.** Components are written as text too, so every page reads well in an editor and on GitHub.

---

All pages of these docs, as Markdown for language models: https://clay-doc.github.io/clay-example-repo/4.x/llms.txt