On this page
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.
PagesHow Markdown files become pages, how pages get their titles and which front matter fields Clay reads.MarkdownClay Flavored Markdown - GitHub's Markdown plus alerts, components, math and diagrams - from headings and lists to tables and task lists, with examples.Code BlocksSyntax highlighting for over 200 languages, file names, highlighted lines, diffs, focus and a copy button.AlertsSix kinds of callouts for notes, tips and warnings, written with GitHub's alert syntax.ComponentsTabs, steps, cards, folded sections, prompts, badges, math, diagrams and file trees, written in plain Markdown.Links & ImagesLinking between pages like on GitHub, linking to sections, adding images and offering downloads.HTMLUsing HTML inside Markdown, videos and embeds, and what Clay removes to keep your site safe.Snippets & VariablesWrite a text once and use it on many pages, include code from your project, and fill in values like the current version.Generated DocsAPI reference from your code, and other pages that tools write, generated before every build.
#A page at a glance
One file, from front matter to components:
Setup is the page’s title in the sidebar; its text starts like this:
Tip
Already installed? Skip to the configuration.
---
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, 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 |
| Walk readers through something in order | steps |
| Point out a tip, a warning or a risk | an alert |
| Hide what only some readers need | details |
| Lead readers to other pages | cards or links |
| Explain how parts fit together | a diagram or a file tree |
| Suggest what to ask an AI assistant or agent | a prompt |
| Mark something as new or deprecated | a badge |
#Key ideas
- One file, one page.
docs/guides/setup.mdbecomes/guides/setup. - Links work like on GitHub. Link to the
.mdfile; 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.