Line Numbers

Line numbers appear in a gutter column to the left of the code. They are off by default, excluded from text selection and clipboard copy, and marked aria-hidden for screen readers.

Enable line numbers

Add showLineNumbers to the meta string:

1
```go title="main.go" showLineNumbers
2
func main() {
3
    cfg := loadConfig()
4
    svc := newService(cfg)
5
    svc.Run()
6
}
7
```

1
func main() {
2
    cfg := loadConfig()
3
    svc := newService(cfg)
4
    svc.Run()
5
}

→ Line numbers 1 through 5 appear in a gutter column to the left of the code.

To disable line numbers on a specific block when the engine default is on, use showLineNumbers=false.

Enable globally with the Go API:

1
kazari.WithLineNumbers(true)

Or in the config file:

1
lineNumbers: true

WithLineNumbers(true) is shorthand for WithDefaults(BlockDefaults{LineNumbers: true}). Both write to the same field.

Custom start number

Change where numbering begins with startLineNumber=N:

1
```go title="calc.go (lines 22-24)" showLineNumbers startLineNumber=22
2
func add(a, b int) int {
3
    return a + b
4
}
5
```

22
func add(a, b int) int {
23
    return a + b
24
}

→ Line numbers start at 22, with the gutter auto-sized for two-digit numbers.

Any integer is accepted, including zero and negative values. The first line displays the start number, and each subsequent line increments by 1.

There is no config file equivalent for startLineNumber. It is always set per block via the meta string or Options.StartLineNumber.

Gutter width

The gutter auto-sizes based on the digit count of the highest line number. For 1- and 2-digit ranges, the default width of 2ch applies. For 3+ digits (starting at line 100 or a block with 100+ lines), the width expands automatically via an inline --kz-ln-width style on the <code> element.

The minus sign counts as one character for negative start numbers. No JavaScript is involved; the width is computed at render time.

Per-language defaults

Set line numbers on by default for specific languages with WithLanguageDefaults:

1
kazari.WithLanguageDefaults(map[string]kazari.BlockDefaults{
2
    "go,typescript": {LineNumbers: true},
3
    "bash,sh,zsh":   {LineNumbers: false},
4
})

1
languageDefaults:
2
  "go,typescript":
3
    lineNumbers: true
4
  "bash,sh,zsh":
5
    lineNumbers: false

Language keys are comma-separated and matched case-insensitively. Per-block meta always overrides language defaults. See Configuration Layers for the full cascade.

On highlighted lines

Line numbers on highlighted lines (mark, ins, del) switch to a brighter color and higher opacity to remain readable against the marker background:

1
func main() {
2
    cfg := loadConfig()
3
    svc := newService(cfg)
4
    svc.Run()
5
}

→ Lines 2 and 3 have brighter line numbers than the unmarked lines. These are controlled by --kz-ln-highlight-fg and --kz-ln-highlight-opacity.

Configuration

Config file keys: lineNumbers (engine-wide), defaults.lineNumbers, languageDefaults.<lang>.lineNumbers.

CSS variables

See the CSS Variables reference for the complete list.

Edge cases

• Line numbers work in all frame types: editor, terminal, and frameless.
• ANSI blocks (lang="ansi") support line numbers.
• Collapsible sections preserve line numbers; they are never renumbered. Summary and gap rows render empty gutter placeholders to maintain alignment.
• startLineNumber is per-block only; there is no engine-wide or config file setting for it.