# Markdown and formatting

Clayo articles are markdown. Your agent writes it, Clayo renders it beautifully, and there is nothing proprietary to learn. This article covers what the renderer supports, from standard markdown through Clayo's directives.

## Standard markdown

Clayo renders GitHub-flavored markdown:

- Headings, bold, italic, strikethrough
- Ordered and unordered lists, including task lists
- Tables
- Blockquotes
- Links and bare-URL autolinks
- Images (see [Add images and captions](/articles/images-and-captions))
- Inline code and fenced code blocks

## Headings and the table of contents

Level 2 through level 4 headings appear in the table of contents on the right side of every article, with the current position highlighted as the reader scrolls. Each heading also gets a stable anchor with a hover copy-link button, so readers and teammates can link straight to a specific answer.

Start your headings at level 2. The article title is the page's only level 1 heading.

## Code blocks

Fenced code blocks support language tags for syntax highlighting:

````text
```python
import clayo
```
````

Use language tags consistently; they make examples easier to scan and copy.

## Directives: beyond markdown

Directives add richer blocks that plain markdown cannot express. They look like this in your article source:

```text
:::callout{type="tip"}
Publishing takes seconds, not minutes.
:::
```

And render like this:

:::callout{type="tip"}
Publishing takes seconds, not minutes.
:::

Clayo ships five directives:

| Directive | What it does |
| --- | --- |
| `callout` | Highlighted asides: info, tip, warning, or danger |
| `tabs` | Tabbed content, such as per-platform instructions |
| `accordion` | Collapsible items, ideal for FAQs |
| `video` | Embedded YouTube, Loom, or Vimeo players |
| `align` | Left, center, or right alignment for a block |

The full syntax rules live in [Directive syntax](/articles/directive-syntax), and every attribute and value is documented in the [Directives reference](/articles/directives-reference).

## You will rarely write any of this by hand

Your agent already knows the whole vocabulary: it can ask Clayo for the supported directives and their attributes at any time, so describing intent is enough.

```
Add a warning callout about rate limits to the API article.
Turn the install steps into tabs for macOS, Linux, and Windows.
```

If content ever includes a directive Clayo does not recognize, nothing breaks: the block renders as plain markdown and the save comes back with a warning the agent can fix. See [How authoring works](/articles/how-authoring-works) for how warnings behave.