# Markdown

Clay reads **Clay Flavored Markdown** (CFM): [GitHub Flavored Markdown](https://github.github.com/gfm/), the Markdown you know from READMEs and issues on GitHub, plus [alerts](https://clay-doc.github.io/clay-example-repo/writing/alerts.md), [components](https://clay-doc.github.io/clay-example-repo/writing/components.md), [math](https://clay-doc.github.io/clay-example-repo/writing/components/math.md) and [diagrams](https://clay-doc.github.io/clay-example-repo/writing/components/diagrams.md). Everything GitHub shows works in Clay too, and what Clay adds stays readable on GitHub. Each element below shows its result and its source; pick **Markdown** once to see the source everywhere.

## Headings

```markdown
## A section
### A subsection
```

`#` is the page heading; use it once per page. `##` and `###` headings appear in the contents of the page and become search results of their own. Every heading gets an anchor, built like GitHub builds them, so you can link to a section: the heading "Line breaks" below is reachable as [`#line-breaks`](#line-breaks). Hover a section heading, and a `#` link to it appears on its left, ready to copy.

## Emphasis

::: tabs
== Result
**bold**, *italic*, ~~strikethrough~~ and `inline code`
== Markdown
```markdown
**bold**, *italic*, ~~strikethrough~~ and `inline code`
```
:::

## Line breaks

A line break in your text is a line break on the page, like in GitHub comments. Separate paragraphs with an empty line.

::: tabs
== Result
First line
second line, in the same paragraph

A new paragraph
== Markdown
```markdown
First line
second line, in the same paragraph

A new paragraph
```
:::

> [!TIP]
> Keep each paragraph on one line in your editor and let it wrap the text. Hard-wrapped paragraphs show their line breaks on the page.

## Lists

::: tabs
== Result
- Coffee
- Tea
  - Green tea
  - Black tea

1. Install
2. Configure
3. Build
== Markdown
```markdown
- Coffee
- Tea
  - Green tea
  - Black tea

1. Install
2. Configure
3. Build
```
:::

For instructions in order, [steps](https://clay-doc.github.io/clay-example-repo/writing/components/steps.md) show a numbered list as a guide.

## Task lists

::: tabs
== Result
- [x] Write the docs
- [x] Build the site
- [ ] Publish it
== Markdown
```markdown
- [x] Write the docs
- [x] Build the site
- [ ] Publish it
```
:::

The boxes are read-only: they show what the Markdown says, and readers cannot tick them.

## Tables

Columns can be aligned left, centered or right with colons in the separator line:

::: tabs
== Result
| Command | Port | Purpose |
|:--------|:----:|--------:|
| dev     | 3000 | write   |
| preview | 4173 | check   |
== Markdown
```markdown
| Command | Port | Purpose |
|:--------|:----:|--------:|
| dev     | 3000 | write   |
| preview | 4173 | check   |
```
:::

## Quotes

::: tabs
== Result
> Documentation is a love letter that you write to your future self.
== Markdown
```markdown
> Documentation is a love letter that you write to your future self.
```
:::

A quote that starts with `[!NOTE]`, `[!TIP]` and similar becomes an [alert](https://clay-doc.github.io/clay-example-repo/writing/alerts.md).

## Horizontal rules

Three hyphens on their own line draw a line across the page:

```markdown
---
```

---

## Typography :badge[New in Clay 5]{tip}

Clay sets the text of your pages like a typesetter would: write it on the keyboard, and readers see the right characters.

| You write | Readers see |
|-----------|-------------|
| `->` `<-` `<->` `=>` `<=>` | → ← ↔ ⇒ ⇔ |
| `<=` `>=` `!=` | ≤ ≥ ≠ |
| `1--2`, `a -- b`, `a --- b` | 1–2, a – b, a — b |
| `...` | … |
| `(c)` `(r)` `(tm)` `+-` | © ® ™ ± |
| `"quotes"`, `'single'`, `it's` | “quotes”, ‘single’, it’s |

Quotes follow the language of the page: German pages get „Anführungszeichen“, French ones «guillemets». To use others, set `quotes` in [messages](https://clay-doc.github.io/clay-example-repo/configuration/clay-yaml.md), e.g. `quotes: "“”‘’"`: the opening and closing double quotes, then the single ones.

Only text changes. Code, links that show their address, HTML attributes, math, [prompts](https://clay-doc.github.io/clay-example-repo/writing/components/prompts.md) and the ids of headings stay as written, so links to sections keep working. Options like `--strict` stay too. To keep a single one as written, put a backslash in front: `\->` shows `->`.

## More than Markdown

::: cards
- [Links & Images](https://clay-doc.github.io/clay-example-repo/writing/links-and-images.md)
- [Code Blocks](https://clay-doc.github.io/clay-example-repo/writing/code-blocks.md)
- [Alerts](https://clay-doc.github.io/clay-example-repo/writing/alerts.md)
- [Components](https://clay-doc.github.io/clay-example-repo/writing/components.md)
- [HTML](https://clay-doc.github.io/clay-example-repo/writing/html.md)
:::

---

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