On this page

Components

Markdown covers text, lists, tables and code. For the rest of what docs need, like the same command for three package managers, a guide in numbered steps or a diagram, Clay has components. They are plain text in your Markdown files: no HTML, nothing to install, and they stay readable in any editor and on GitHub.

Tabs and Code GroupsAlternatives in one place, like instructions per system or the same command for npm, pnpm and yarn; the reader's choice is remembered.StepsA numbered list as a guide, with a numbered circle for each step and a line that leads to the next.CardsLinks as a grid of cards, with the icon and description of the pages they lead to, or ones of your own.DetailsFolded sections that readers open when they need them, like FAQs, long logs and background.PromptsA suggested prompt for AI assistants and coding agents, shown as written, with a button to copy it.BadgesSmall labels in text and headings, like "New", "Beta" or "Deprecated", in the colors of the alerts.MathFormulas in LaTeX, inline or on a line of their own, typeset with KaTeX when the site is built.DiagramsFlowcharts, sequence diagrams, pie charts and more from text with Mermaid, in the colors of your site.File TreesFolders and files from an indented list, with icons by file type, comments and folders that fold.

#Three ways to write them

Kind	Looks like	Components
Containers	`::: name` … `:::` around Markdown	tabs, code groups, steps, cards, details, prompts
Inline	`:badge[New]`, $E = mc^2$	badges, math
Code blocks	a code block in the language `mermaid` or `tree`	diagrams, file trees

#Containers

A container starts with a line of three colons and the component’s name, and ends with a line of three colons on their own. Everything in between is normal Markdown.

::: details Why three colons?
They read well as plain text and are used by other documentation tools too, so your docs stay portable.
:::

Why three colons?

They read well as plain text and are used by other documentation tools too, so your docs stay portable.

The text after the name is the component’s title, where it has one, like the title of details.
Containers nest. A container may hold another one, for example tabs inside a folded section. Give the outer one more colons to make clear which line closes which:
```
:::: details Install on your system
::: tabs
== macOS
`brew install node`
== Windows
`winget install OpenJS.NodeJS`
:::
::::
```
Mistakes stay visible. A container with a name Clay does not know, or without its closing line, is shown as the text you wrote, so a typo does not hide content.
Code blocks are code. ::: inside a code block is shown as is; that is how these pages show the syntax.

#Search, links and the contents

Everything is searchable, including tabs that are not shown and folded sections. Opening a search result shows the tab or opens the section it is in.
Links are checked like all others, also inside cards and tabs, see build checks.
Headings inside containers get their # links and appear under “On this page”.

#Without JavaScript and on GitHub

Clay renders components when it builds the site, so pages show them before any JavaScript runs: tabs show their first tab, math is already typeset. Diagrams are the one exception; they are drawn in the browser and show their source until then.

On GitHub, your Markdown files show the components as the text you wrote, which stays readable. GitHub draws mermaid diagrams and $ math itself.