Configuration Layers

Every code block Kazari renders gets its final settings from a three-layer cascade. Engine defaults establish the baseline, language defaults refine behavior for specific languages, and per-block overrides give each block the final say. Higher layers override lower ones, and omitted values fall through to the layer below.

The cascade

1
Engine defaults
2
  └─ Language defaults
3
       └─ Per-block overrides (meta string or Options struct)

Kazari resolves five block properties through this cascade:

Feature toggles like WithCopyButton and WithCollapsible are engine-level only. They do not participate in the cascade and cannot be overridden per block.

Layer 1: Engine defaults

Set during engine construction via functional options passed to kazari.New(). These apply to every code block the engine renders.

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithThemes("github-light", "github-dark"),
4
    kazari.WithLineNumbers(true),
5
    kazari.WithDefaults(kazari.BlockDefaults{
6
        Wrap:  true,
7
        Frame: kazari.FrameCode,
8
    }),
9
)

WithDefaults sets block-level properties for all languages. Individual With* functions like WithLineNumbers modify the same defaults. Both approaches write to the same internal structure, so the last one in the option list wins.

Built-in defaults

When no options are provided, the engine starts with these values:

These come from DefaultConfig() and apply before any functional options run.

File-based configuration

Engine defaults can also come from a kazari.config.yaml (or .yml or .json) file instead of Go code:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithConfigDir("."),
4
)

The config file maps directly to functional options. WithConfigDir searches for a config file and applies its settings as options during engine construction. Options passed after WithConfigDir override the file:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithConfigDir("."),        // loads config file
4
    kazari.WithCopyButton(false),     // overrides config file's copyButton
5
)

See File-Based Config for the full schema and validation rules.

Layer 2: Language defaults

Apply block properties to all blocks of a specific language. Set via WithLanguageDefaults or the languageDefaults key in a config file.

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithLanguageDefaults(map[string]kazari.BlockDefaults{
4
        "bash,sh,zsh": {
5
            Wrap:  true,
6
            Frame: kazari.FrameTerminal,
7
        },
8
        "go": {
9
            LineNumbers: true,
10
        },
11
    }),
12
)

Comma-separated keys apply the same defaults to multiple languages. "bash,sh,zsh" sets all three to use terminal frames with word wrap.

The equivalent in a config file:

1
languageDefaults:
2
  "bash,sh,zsh":
3
    wrap: true
4
    frame: "terminal"
5
  "go":
6
    lineNumbers: true

Language defaults override engine defaults for matching blocks. When a code block's language matches a key, all five properties from that entry replace the engine defaults for that block. Non-matching blocks fall through to engine defaults unchanged.

When multiple comma-separated keys could match the same language, keys are sorted alphabetically and the first match wins.

Layer 3: Per-block overrides

Override any cascaded property for a single code block. Two interfaces provide per-block control: the meta string (for Markdown workflows) and the Options struct (for the Go API).

Meta string

The meta string follows the language identifier in a fenced code block:

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

Cascade-relevant meta string keys:

The meta string also carries non-cascade properties like title, theme, markers ({3-5}), focus lines, and collapse directives. These are per-block only and do not participate in the cascade.

Options struct

When calling engine.Render() directly, use the Options struct:

1
ln := true
2
html, err := engine.Render(code, kazari.Options{
3
    Lang:        "go",
4
    Title:       "main.go",
5
    LineNumbers: &ln,
6
    LineMarkers: []kazari.LineMarker{
7
        {Type: kazari.MarkerMark, Lines: []kazari.Range{{Start: 3, End: 5}}},
8
    },
9
})

Cascade properties in Options use pointer types (*bool, *int, *Frame). A nil pointer means "use the cascaded value." A non-nil pointer overrides it. This makes the distinction between "not specified" and "explicitly set to the zero value" unambiguous.

Resolution example

Given this engine setup:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithDefaults(kazari.BlockDefaults{
4
        LineNumbers: true,
5
        Frame:       kazari.FrameCode,
6
    }),
7
    kazari.WithLanguageDefaults(map[string]kazari.BlockDefaults{
8
        "bash,sh": {
9
            Frame: kazari.FrameTerminal,
10
            Wrap:  true,
11
        },
12
    }),
13
)

Three code blocks resolve differently:

Block A (```go)

Block B (```bash)

Block C (```bash showLineNumbers frame=none)

Block C shows all three layers in action: Wrap comes from the language default, Frame and LineNumbers come from the meta string, and the engine defaults are fully overridden.

What does not cascade

Engine-level features are set once during construction and apply uniformly. They cannot be overridden per language or per block.

Quick reference

This page explains how the cascade works. For a complete list of every option, config file field, and meta string key in one place, see the Reference section:

• Configuration Options lists every With* functional option and its corresponding config file field, type, and default value
• Meta String Syntax lists every key recognized in the fence info string with usage examples
• File-Based Config covers the full YAML/JSON schema and validation rules