# Code Blocks

Fence code with three backticks and name its language. Clay highlights it with [Shiki](https://shiki.style), the highlighter of VS Code, in matching colors for the light and the dark theme.

````markdown
```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```
````

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

Every code block has a copy button in its top right corner; on touch screens it is always visible.

## Languages

Clay detects the languages your docs use and loads only those, so you never configure them. Any [language Shiki knows](https://shiki.style/languages) works, under its name or a common alias: `js`, `ts`, `py`, `sh`, `yml`, `md` and so on. A block with an unknown language, or none, is shown as plain text.

```go
package main

import "fmt"

func main() {
    fmt.Println("Hello from Go")
}
```

```rust
fn main() {
    println!("Hello from Rust");
}
```

```sql
SELECT title, updated FROM pages WHERE language = 'en' ORDER BY updated DESC;
```

## Highlighting lines

Put the line numbers in braces after the language, as single lines or ranges: `ts {2}` or `ts {1,3-4}`.

```ts {2}
const site = loadSite(root);
const pages = site.pages.filter(page => !page.isDir);
console.log(`${pages.length} pages`);
```

## Notations in comments

Some changes are easier to mark on the line itself. Add a comment with a notation at the end of the line; Clay removes the comment and marks the line:

| Notation | Effect |
|----------|--------|
| `// [!code highlight]` | Highlights the line |
| `// [!code ++]` | Marks the line as added (green, with `+`) |
| `// [!code --]` | Marks the line as removed (red, with `-`) |
| `// [!code focus]` | Dims the other lines until the reader hovers the block |
| `// [!code warning]` | Marks the line as a warning (yellow) |
| `// [!code error]` | Marks the line as an error (red) |
| `// [!code word:name]` | Highlights every `name` in the block |

Use the comment syntax of the block's language: `#` in Python, YAML or shell, `<!-- -->` in HTML, `--` in SQL.

A diff:

```js
export default defineConfig({
  title: "My Project", // [!code --]
  title: "My Documentation", // [!code ++]
  base: "/docs/",
});
```

A highlighted line and a warning:

```python
config = load_config("clay.yaml")
config["baseURL"] = "/docs/"  # [!code highlight]
build(config, strict=False)  # [!code warning]
```

Focus on one line:

```yaml
title: "My Project"
baseURL: "/my-project/" # [!code focus]
siteURL: "https://example.com"
```

Highlighted words:

```ts
// [!code word:edition]
const edition = editionOf(route.path, versions, languages);
const nav = navs[edition.prefix];
```

## Showing code fences

To show a code block inside a code block, as this page does, fence the outer block with four backticks:

`````markdown
````markdown
```js
console.log("inside");
```
````
`````

## Inline code

Single backticks mark code within a sentence: `npm install --save-dev clay-doc`. Inline code is not highlighted.

---

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