# Add code blocks

Use fenced code blocks for commands, manifest fragments, source snippets, and Markdown syntax examples. A fenced block keeps whitespace intact and gives DocInsight a language id for syntax highlighting.

## Add a fenced block

Put three backticks before and after the code:

markdown

    ```pascal
    var
      Items: IList<string>;
    begin
      Items := TCollections.CreateList<string>;
    end;
    ```

Add the language id after the opening fence:

markdown

    ```json
    {
      "output": {
        "default_targets": ["site"]
      }
    }
    ```

The first word after the opening fence is the language identifier.

## Choose a language

The Learn theme provides syntax highlighting for these commonly used identifiers:

Content | Language identifiers
--- | ---
Plain text | `text`
Delphi and Pascal | `pascal`, `delphi`
Web and markup | `html`, `xml`, `markdown`
Data and configuration | `json`, `yaml`, `toml`, `ini`
Query and patch text | `sql`, `diff`
Shell source | `bash`, `sh`, `powershell`, `bat`, `cmd`

Use semantic identifiers for commands and transcripts:

Identifier | Use for
--- | ---
`shell` | Commands intended to work across shells, without output
`bash` | Bash-specific commands or scripts
`powershell` | PowerShell commands or scripts
`console` | Generic interaction or output when the command language is not important
`shell-session` | A shell transcript containing literal prompts, commands, and output
`powershell-session` | A PowerShell transcript containing literal prompts, commands, and output

Use `shell` for command-only examples and `console` for command output when prompt-aware highlighting is not needed. In session blocks, prompts are part of the authored content and remain copyable.

Keep a `shell` command on one line when it should work across terminals. Line continuation is shell-specific: Bash uses a trailing `\`, PowerShell uses a trailing backtick (```), and Command Prompt uses a trailing `^`. Use `bash`, `powershell`, `bat`, or `cmd` when an example depends on one of those syntaxes.

An unknown language identifier is preserved, but the Learn theme displays it without syntax highlighting.

## Configure code display

Add attributes after the language identifier. Use braces when you use the `#id` or `.class` shorthand:

markdown

    ```pascal {title="Collections.pas" line-numbers=20 highlight="2,3-4" #create-list-example .compact}
    function CreateList<T>: IList<T>;
    begin
      Result := TCollections.CreateList<T>;
    end;
    ```

DocInsight renders the example as follows:

Collections.pas

    function CreateList<T>: IList<T>;
    begin
      Result := TCollections.CreateList<T>;
    end;

The displayed line numbers begin at 20, while `highlight="2,3-4"` highlights the second through fourth source lines. The `id` and `class` attributes are added to the generated HTML but do not necessarily produce a visible change unless the theme or custom styles use them.

Code blocks support these display attributes:

Attribute | Purpose
--- | ---
`title` | Adds a title above the code block. Quote a title that contains spaces.
`line-numbers` | Shows line numbers beginning at 1. Set `line-numbers=N` to begin at the positive integer `N`.
`highlight` | Highlights one-based code lines and inclusive ranges, such as `"2,4-6"`.
`#id` | Adds an HTML `id` attribute. This shorthand requires braces.
`.class` | Adds an HTML class. This shorthand requires braces and can be repeated.

Highlight numbers refer to lines inside the fenced block, even when `line-numbers=N` changes the displayed line numbers. `docinsight check` reports unsupported attributes, invalid values, and highlighted lines outside the block.

The `#id` and `.class` shorthands require braces; the equivalent `id="..."` and `class="..."` attributes can be used without shorthand syntax.