Code Blocks

Code blocks render with syntax highlighting, optional titles, line markers, copy controls, and grouped tabs. Most features are set in the opening fence.

```go title="main.go" {3-5}
package main
import "fmt"
func main() {
    fmt.Println("Hello, world!")
}
```

→ A framed Go code block appears with a main.go title and lines 3 through 5 highlighted.

Highlighting engines

Sarde embeds Kazari for code block presentation. Kazari can use Nuri or Chroma for syntax highlighting. Select the engine in sarde.yaml:

markdown:
  codeblocks:
    engine: nuri

Set the language after the opening fence.

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

Titles and frames

Add a title with title.

```yaml title="sarde.yaml"
site:
  title: "Biology Course"
```

→ A title bar labeled sarde.yaml appears above the block.

Frames control the visual chrome around a code block.

Override the frame when needed.

```sh frame=none
sarde build
```

Line numbers and highlights

Use showLineNumbers for a line-number gutter. Use startLineNumber when the snippet starts in the middle of a larger file.

```js showLineNumbers startLineNumber=10
const sunlight = true;
const water = true;
```

→ Line numbers appear in the gutter and start at 10.

Highlight lines with curly braces.

```python {3,5-7}
import csv
def read_observations():
    rows = load_csv("plants.csv")
    cleaned = remove_empty_rows(rows)
    validated = check_schema(cleaned)
    return validated
```

→ Line 3 and lines 5 through 7 are highlighted.

Add labels to highlighted ranges when the reason matters. The label sits on the first line of its range, over the start of that line, so begin the range on a blank line or the label covers the code.

```python {"Input":1-3} {"Validation":4-7}
data = read_file("plants.csv")
records = parse_csv(data)
cleaned = remove_empty_rows(records)
validated = check_schema(cleaned)
result = transform(validated)
```

Diff and inline markers

Use ins and del to show inserted and deleted lines.

```yaml ins={3} del={2}
site:
  title: "Old Course"
  title: "Biology Lab"
```

→ Deleted lines render in red and inserted lines render in green.

Inline markers highlight words or patterns within a line.

```python "photosynthesis" /plant_\w+/
result = photosynthesis_rate(plant_sample)
```

→ The exact word and matching pattern are highlighted inside the line.

Focus and collapse

Use focus to dim surrounding lines.

```python focus={3-4}
import os
def main():
    run_lesson_export()
if __name__ == "__main__":
    main()
```

→ Lines 3 and 4 stay fully visible. The other lines are dimmed.

Use collapse with a line range to fold part of a long example behind an expandable summary. Ranges count the lines of the code block, starting at 1.

```python collapse={1-3}
import csv
import json
import os
def export_lessons():
    pass
```

→ Lines 1 through 3 render as a collapsed summary row. Selecting it reveals them; the rest of the block stays visible.

Separate several ranges with commas, for example collapse={1-3,8-12}. A revealed section stays open unless you add collapseStyle: collapsible-start puts the summary row above the revealed lines, collapsible-end below, and collapsible-auto picks based on where the range sits.

Code groups

Group related code blocks with :::code-group. A code group closes only with a bare ::: and does not track nesting, so close it with ::: before the closing fence of any block that contains it; :::/code-group is not recognized.

:::code-group
```bash title="npm"
npm run build
```
```bash title="pnpm"
pnpm build
```
:::

→ A tabbed code block appears. Selecting a tab switches between package managers.

Common options

The opening fence accepts these options:

Configuration

Two files configure code blocks. sarde.yaml sets the engine and the highlighting themes. kazari.config.yaml at the project root sets Kazari's toolbar, frame, and styling options. sarde new site creates both.

markdown:
  codeblocks:
    engine: nuri
    light_theme: github-light
    dark_theme: github-dark
    dark_mode_selector: '[data-theme="dark"]'

A kazari.config.yaml that sets the toolbar buttons and the default frame:

copyButton: true
fullscreenButton: true
wrapButton: true
languageBadge: true
lineNumbers: false
defaults:
  wrap: false
  frame: auto

See Configuration for the full markdown.codeblocks reference. The Kazari documentation lists every kazari.config.yaml option and meta string token: Kazari docs.