# Code blocks

Fenced code with highlighting, file names, tab labels and terminal sessions.

Fenced code blocks are highlighted at build time with Shiki, once for every code theme, so a reader can switch themes
without reloading. Each block has a copy button.

## Languages

These languages are highlighted:

| Fence language | Label |
|---|---|
| `go` | Go |
| `typescript`, `ts` | TypeScript |
| `javascript`, `js` | JavaScript |
| `json` | JSON |
| `yaml`, `yml` | YAML |
| `bash`, `sh`, `shell` | Shell |
| `python`, `py` | Python |
| `http` | HTTP |
| `html` | HTML |
| `css` | CSS |
| `markdown`, `md` | the fence language as written |
| `rust`, `rs` | Rust |
| `c` | C |
| `cpp`, `c++` | C++ |
| `asm` | Assembly |
| `cmake` | CMake |
| `tla` | TLA+ |

Any other language, such as `toml` or `diff`, is shown as plain text without an error, labelled with the fence
language as written. `text` gives an unhighlighted block labelled Text.

## File name and label

Add `title="..."` to the fence line to show a file name in the header, and `label="..."` to change the label.

````md
```yaml title="openapi.yaml"
openapi: 3.1.0
```
````

```yaml title="openapi.yaml"
openapi: 3.1.0
```

## Terminal sessions

A fence with the language `terminal` (or `console`, `shell-session`, `sh-session`) is labelled Terminal. Lines that
start with `$ ` get a muted prompt that is not part of the command you read; other lines are output. Terminal blocks
are not highlighted.

````md
```terminal
$ npx docsp check
Configuration is valid: 1 project(s).
```
````

```terminal
$ npx docsp check
Configuration is valid: 1 project(s).
```

## Tabs

To show the same example in several languages, wrap the blocks in `:::code-group`. See
[Directives](./directives.md#code-tabs).

## Symbol links in code

When the project has a `symbols` block, names in hand-written blocks of an indexed language link to the symbol they
match, and `::snippet` shows code from the source tree with every name linked. See
[Symbol index](../features/symbols.md).
