Code Blocks

Fence code with three backticks and name its language. Clay highlights it with Shiki, the highlighter of VS Code, in matching colors for the light and the dark theme.

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

package main

import "fmt"

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

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

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

The same code in several languages or for several tools fits in a code group like the one above.

#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`);
```

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

#File names

Put the name of the file in square brackets after the language, and Clay shows it in a bar above the code, so readers see at once where the code goes:

title: "My Project"
baseURL: "/my-project/"

```yaml [clay.yaml]
title: "My Project"
baseURL: "/my-project/"
```

The name may contain folders and spaces, like [docs/guides/setup.md], and goes with highlighted lines: ts [src/client.ts] {2}. In a code group, the name in brackets labels the tab instead.

#Terminal

Shell code (bash, sh, shell, zsh, fish) looks like a terminal: a bar with a window’s three buttons on top, and a $ before each command. The $ is only drawn, so the copy button copies the commands alone. Comments, empty lines, lines continued with \ and the text of a heredoc get none:

# Install Clay and start writing
npm install --save-dev clay-doc
npx clay dev

```bash
# Install Clay and start writing
npm install --save-dev clay-doc
npx clay dev
```

To show a command together with what it prints, use console instead of bash. Clay adds no $ there: write $ before each command yourself, and every other line is shown as its output:

$ npx clay check
┌  Clay 5.0.0 · check
│
●  Checked 42 pages
│
└  No problems

Shell code with a file name is a script and keeps the file’s bar. Without the buttons, windowDots: false in the theme, shell code has no bar and keeps its $.

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

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

export default defineConfig({
  title: "My Project", 
  title: "My Documentation", 
  base: "/docs/",
});

config = load_config("clay.yaml")
config["baseURL"] = "/docs/"
build(config, strict=False)  

title: "My Project"
baseURL: "/my-project/"
siteURL: "https://example.com"

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
```js
console.log("inside");
```
````

#Inline code

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