# 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.

::: cards
- [Tabs and Code Groups](https://clay-doc.github.io/clay-example-repo/writing/components/tabs.md)
- [Steps](https://clay-doc.github.io/clay-example-repo/writing/components/steps.md)
- [Cards](https://clay-doc.github.io/clay-example-repo/writing/components/cards.md)
- [Details](https://clay-doc.github.io/clay-example-repo/writing/components/details.md)
- [Prompts](https://clay-doc.github.io/clay-example-repo/writing/components/prompts.md)
- [Badges](https://clay-doc.github.io/clay-example-repo/writing/components/badges.md)
- [Math](https://clay-doc.github.io/clay-example-repo/writing/components/math.md)
- [Diagrams](https://clay-doc.github.io/clay-example-repo/writing/components/diagrams.md)
- [File Trees](https://clay-doc.github.io/clay-example-repo/writing/components/file-trees.md)
:::

## Three ways to write them

| Kind | Looks like | Components |
|------|------------|------------|
| Containers | `::: name` … `:::` around Markdown | [tabs, code groups](https://clay-doc.github.io/clay-example-repo/writing/components/tabs.md), [steps](https://clay-doc.github.io/clay-example-repo/writing/components/steps.md), [cards](https://clay-doc.github.io/clay-example-repo/writing/components/cards.md), [details](https://clay-doc.github.io/clay-example-repo/writing/components/details.md), [prompts](https://clay-doc.github.io/clay-example-repo/writing/components/prompts.md) |
| Inline | `:badge[New]`, `$E = mc^2$` | [badges](https://clay-doc.github.io/clay-example-repo/writing/components/badges.md), [math](https://clay-doc.github.io/clay-example-repo/writing/components/math.md) |
| Code blocks | a code block in the language `mermaid` or `tree` | [diagrams](https://clay-doc.github.io/clay-example-repo/writing/components/diagrams.md), [file trees](https://clay-doc.github.io/clay-example-repo/writing/components/file-trees.md) |

## 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.

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

::: details 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](https://clay-doc.github.io/clay-example-repo/writing/components/details.md).
- **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:

  ```markdown
  :::: 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](https://clay-doc.github.io/clay-example-repo/publishing/build-checks.md).
- **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.

---

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