File-Based Config

A config file sets engine-wide defaults, feature toggles, and style overrides without writing Go code. Kazari loads configuration from kazari.config.yaml, .yml, or .json files.

Auto-discovery

Pass a directory path to WithConfigDir. Kazari searches for config files in this order:

kazari.config.yaml
kazari.config.yml
kazari.config.json

The first file found is loaded; others are ignored even if they exist. If no file is found, the engine is not affected.

1
engine := kazari.New(
2
    kazari.WithConfigDir("./config"),
3
    kazari.WithHighlighter(hl),
4
    kazari.WithCopyButton(true), // overrides the file config value if set
5
)

If the file exists but fails to parse or validate, WithConfigDir logs a warning and continues without applying the config. It does not return an error or panic.

Loading manually

To load a config file directly by path:

1
opts, err := kazari.LoadConfig("kazari.config.yaml")
2
if err != nil {
3
    log.Fatal(err)
4
}
5
engine := kazari.New(append(opts, kazari.WithHighlighter(hl))...)

To parse raw bytes (for example, from an embedded file):

1
fc, err := kazari.ParseConfig(data, "yaml") // "yaml" or "json"
2
if err != nil {
3
    log.Fatal(err)
4
}
5
opts, err := kazari.FileConfigToOptions(fc)

Themes

1
themes:
2
  light: "github-light"
3
  dark: "github-dark"

Field	Type	Default	Description
`themes.light`	`string`	`"github-light"`	Light theme name (passed to the highlighter)
`themes.dark`	`string`	`"github-dark"`	Dark theme name (empty string for single-theme)

Dark mode

1
darkMode:
2
  kind: "selector"
3
  selector: ".dark"

Field	Type	Default	Description
`darkMode.kind`	`string`	`"selector"`	One of: `selector`, `mediaQuery`, `both`
`darkMode.selector`	`string`	`".dark"`	CSS selector for dark mode (required for `selector` and `both` kinds)

selector toggles dark mode via a class (e.g., .dark on <html>). mediaQuery uses @media (prefers-color-scheme: dark). both emits both so a manual toggle can override OS preference.

Feature toggles

All feature toggles are optional booleans. Omitted fields keep the engine default.

1
copyButton: true
2
fullscreenButton: true
3
wrapButton: true
4
themeToggleButton: false
5
lineNumbers: false
6
frameDetection: true
7
fileNameExtraction: true
8
languageBadge: true
9
themedScrollbars: true
10
themedSelection: false
11
contentExclusion: false
12
mermaidPassThrough: true
13
terminalCommentStripping: true
14
dataLineCount: true
15
fileIcons: true
16
links: false
17
styleReset: true
18
minify: true

Config key	Default	Go API
`copyButton`	`true`	`WithCopyButton`
`fullscreenButton`	`true`	`WithFullscreenButton`
`wrapButton`	`true`	`WithWrapButton`
`themeToggleButton`	`false`	`WithThemeToggle`
`lineNumbers`	`false`	`WithLineNumbers`
`frameDetection`	`true`	`WithFrameDetection`
`fileNameExtraction`	`true`	`WithFileNameExtraction`
`languageBadge`	`true`	`WithLanguageBadge`
`themedScrollbars`	`true`	`WithThemedScrollbars`
`themedSelection`	`false`	`WithThemedSelectionColors`
`contentExclusion`	`false`	`WithContentExclusion` (deprecated no-op)
`mermaidPassThrough`	`true`	`WithMermaidPassThrough`
`terminalCommentStripping`	`true`	`WithTerminalCommentStripping`
`dataLineCount`	`true`	`WithDataLineCount`
`fileIcons`	`true`	`WithFileIcons`
`links`	`false`	`WithLinks`
`styleReset`	`true`	`WithStyleReset`
`minify`	`true`	`WithMinify`

Engine settings

1
tabWidth: 2
2
minContrast: 5.5
3
cascadeLayer: "kazari"
4
themeCSSRoot: ":root"
5
terminalDotStyle: "colored"
6
languageIconMode: "none"
7
locale: "en-US"

Field	Type	Default	Description
`tabWidth`	`int`	`2`	Spaces per tab for indentation calculation
`minContrast`	`float`	`5.5`	Minimum WCAG contrast ratio for syntax colors. Set to `0` to disable
`cascadeLayer`	`string`	`"kazari"`	CSS `@layer` name for the generated stylesheet
`themeCSSRoot`	`string`	`":root"`	CSS selector for emitting theme variables
`terminalDotStyle`	`string`	`"colored"`	Terminal frame dot style: `colored` or `minimal`
`languageIconMode`	`string`	`"none"`	Language icon display mode: `none`, `iconOnly`, or `iconAndText`
`locale`	`string`	`"en-US"`	Locale for UI strings (copy button labels, etc.)

Block defaults

1
defaults:
2
  wrap: false
3
  preserveIndent: true
4
  hangingIndent: 0
5
  lineNumbers: false
6
  frame: "auto"

Field	Type	Default	Description
`defaults.wrap`	`bool`	`false`	Enable word wrap
`defaults.preserveIndent`	`bool`	`true`	Preserve leading indentation on wrapped lines
`defaults.hangingIndent`	`int`	`0`	Extra indent (in `ch`) for continuation lines
`defaults.lineNumbers`	`bool`	`false`	Show line numbers
`defaults.frame`	`string`	`"auto"`	Frame style: `auto`, `code`, `terminal`, `none`

Language defaults

Per-language overrides. Keys accept comma-separated language names to apply the same config to multiple languages:

1
languageDefaults:
2
  "bash,sh,zsh":
3
    wrap: true
4
    frame: "terminal"
5
  "python":
6
    lineNumbers: true
7
  "go":
8
    lineNumbers: true
9
    frame: "code"

Each language group accepts the same five fields as defaults. Language defaults override engine defaults but are overridden by per-block meta strings.

Collapsible

Setting any collapsible field enables collapsible sections. When a collapsible section is present in the config file, unset subfields use these defaults:

1
collapsible:
2
  lineThreshold: 15
3
  previewLines: 5
4
  defaultCollapsed: true
5
  preserveIndent: true
6
  style: "github"
7
  expandButtonText: ""
8
  collapseButtonText: ""
9
  expandedAnnouncement: ""
10
  collapsedAnnouncement: ""

Field	Type	Default	Description
`collapsible.lineThreshold`	`int`	`15`	Blocks with more lines than this are collapsible
`collapsible.previewLines`	`int`	`5`	Number of visible lines when collapsed
`collapsible.defaultCollapsed`	`bool`	`true`	Whether blocks start collapsed
`collapsible.preserveIndent`	`bool`	`true`	Keep indentation in preview lines
`collapsible.style`	`string`	`"github"`	Collapse style: `github`, `collapsibleStart`, `collapsibleEnd`, `collapsibleAuto`
`collapsible.expandButtonText`	`string`		Custom expand button label
`collapsible.collapseButtonText`	`string`		Custom collapse button label
`collapsible.expandedAnnouncement`	`string`		Screen reader announcement when expanded
`collapsible.collapsedAnnouncement`	`string`		Screen reader announcement when collapsed

Output panel

1
outputPanel: true
2
outputDefaultCollapsed: false
3
outputSeparator: "---output---"

Field	Type	Default	Description
`outputPanel`	`bool`	`false`	Enable the output panel feature for separating code from command output
`outputDefaultCollapsed`	`bool`	`false`	Whether output panels start collapsed
`outputSeparator`	`string`	`"---output---"`	Separator string that splits code from output content in a fenced block

When enabled, a code block whose content contains the separator string is split into two panels: the code above the separator and the output below it. The separator line itself is not rendered.

Language aliases

1
languageAliases:
2
  javascript: "js"
3
  typescript: "ts"

Maps alias names to language names recognized by the highlighter. When a code block uses an alias as its language, the engine resolves it to the target name before tokenization.

UI string overrides

1
uiStrings:
2
  "copy.label": "Copy"
3
  "copy.success": "Copied!"

Overrides localized UI strings (button labels, announcements). See the Localization page for the full list of string keys.

Style overrides

The styleOverrides map sets CSS custom property values. Three value formats are accepted.

Plain string: same value for both light and dark themes.

1
styleOverrides:
2
  radius: "0.5rem"
3
  toolbar-height: "2.5rem"

Array: dark value first, light value second.

1
styleOverrides:
2
  editor-bg: ["#1e293b", "#f8fafc"]
3
  editor-fg: ["#e2e8f0", "#1e293b"]

Map: explicit dark and light keys (either or both may be omitted).

1
styleOverrides:
2
  editor-bg:
3
    dark: "#1e293b"
4
    light: "#f8fafc"

Setting only one side overrides that theme value while leaving the other from the theme:

1
styleOverrides:
2
  editor-bg:
3
    dark: "#1e293b"

Key normalization

Bare names are automatically prefixed with --kz-. Keys that already start with -- are used as-is.

Config key	Resolved CSS variable
`radius`	`--kz-radius`
`editor-bg`	`--kz-editor-bg`
`--kz-shadow`	`--kz-shadow` (kept as-is)
`--custom-var`	`--custom-var` (kept as-is)

Validation

Config files are validated in two passes. The first pass runs during decoding: the YAML decoder rejects unknown keys and type mismatches at parse time. JSON uses DisallowUnknownFields for the same behavior. The second pass checks value constraints immediately after decoding.

Both passes must succeed before the config is applied.

Validated fields

Field	Rule	Valid	Invalid
`darkMode.kind`	Must be one of the allowed values	`"selector"`, `"mediaQuery"`, `"both"`	`"auto"`, `"css"`
`darkMode.selector`	Required when kind is `selector` or `both`	`".dark"`, `"#app"`	omitted with kind `"selector"`
`tabWidth`	Integer >= 1	`2`, `4`, `8`	`0`, `-1`
`minContrast`	Float in range [0, 21]	`5.5`, `4.5`, `0` (disabled), `21` (max)	`-1.0`, `22.0`
`terminalDotStyle`	Must be one of the allowed values	`"colored"`, `"minimal"`	`"round"`
`languageIconMode`	Must be one of the allowed values	`"none"`, `"iconOnly"`, `"iconAndText"`	`"icon"`
`defaults.frame`	Must be one of the allowed values	`"auto"`, `"code"`, `"terminal"`, `"none"`	`"editor"`
`defaults.hangingIndent`	Integer >= 0	`0`, `2`, `4`	`-1`
`languageDefaults.*.frame`	Same as `defaults.frame`	`"auto"`, `"code"`, `"terminal"`, `"none"`	`"editor"`
`languageDefaults.*.hangingIndent`	Integer >= 0	`0`, `2`, `4`	`-1`
`collapsible.lineThreshold`	Integer >= 1	`10`, `20`	`0`, `-5`
`collapsible.previewLines`	Integer >= 1	`3`, `5`	`0`, `-1`
`collapsible.style`	Must be one of the allowed values	`"github"`, `"collapsibleStart"`, `"collapsibleEnd"`, `"collapsibleAuto"`	`"accordion"`

Style override validation

Each key in styleOverrides must match one of three formats:

Format	Valid	Invalid
String	`"0.5rem"`, `"'Fira Code', monospace"`	`42`, `true` (non-string types)
Array	`["#1e293b", "#ffffff"]` (exactly 2 string elements)	`["#1e293b"]` (wrong length), `[42, "#fff"]` (non-string)
Map	`{light: "#fff", dark: "#000"}`, `{dark: "#000"}`	`{}` (empty), `{light: 42}` (non-string value)

Unknown fields

Both YAML and JSON parsers reject unknown fields at decode time:

1
# This produces a parse error:
2
unknownField: true

1
kazari: parsing YAML config: line 5: field unknownField not found in type kazari.FileConfig

Error reporting

How validation errors reach the application depends on the loading path.

LoadConfig() / ParseConfig() (direct API) return errors directly. The caller decides how to handle them:

1
opts, err := kazari.LoadConfig("kazari.config.yaml")
2
if err != nil {
3
    log.Fatalf("bad config: %v", err)
4
}
5
engine := kazari.New(append([]kazari.Option{kazari.WithHighlighter(hl)}, opts...)...)

WithConfigDir() (discovery-based loading) does not return an error because it runs inside kazari.New() as a functional option. Config errors are routed through the WarningHandler. If no handler is set, errors are printed via log.Print:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithWarningHandler(func(msg string) {
4
        log.Printf("kazari warning: %s", msg)
5
    }),
6
    kazari.WithConfigDir("."),
7
)

WithWarningHandler must appear before WithConfigDir in the option list so the handler is registered when the config file is loaded. If no handler is set, the default log.Print fallback ensures errors are never silently dropped.

When no config file is found in the directory, WithConfigDir is a silent no-op (no warning, no error).

Composition with the Go API

WithConfigDir is an option like any other. Its position in the New() call determines priority:

1
engine := kazari.New(
2
    kazari.WithCopyButton(false),   // overridden by file config (comes before WithConfigDir)
3
    kazari.WithConfigDir("./cfg"),  // file config applied here
4
    kazari.WithHighlighter(hl),     // not in file config, always applied
5
    kazari.WithMinify(true),        // comes after file config, takes precedence
6
)

Options are applied in order. WithCopyButton(false) is set first, then overridden by the file config because WithConfigDir comes after it. WithMinify(true) comes after the file config, so it takes precedence over any minify value in the file.

For scalar fields, the last writer wins. For map fields (styleOverrides, languageDefaults, languageAliases, uiStrings), keys from both sources coexist. When the same key appears in both, the later option's value is used.

Go-API-only options

These options accept Go functions, interfaces, or structs and cannot be expressed in a config file. Pass them directly to kazari.New():

Option	Purpose
`WithHighlighter(hl)`	Sets the syntax highlighter (Nuri or Chroma adapter). Required.
`WithThemeCustomizer(f)`	Transforms extracted theme colors before CSS generation
`WithThemeAdjustments(adj)`	Tints theme colors in OKLCH space before the theme customizer
`WithPostRender(f)`	Registers a callback that receives rendered HTML and block metadata
`WithWarningHandler(f)`	Sets the function that receives non-fatal warnings
`WithFileIconResolver(f)`	Custom function mapping file extensions to icon SVG strings
All other engine options have a corresponding config file key and can be set in either layer.

Complete example

1
themes:
2
  light: "github-light"
3
  dark: "github-dark"
4
5
darkMode:
6
  kind: "selector"
7
  selector: ".dark"
8
9
copyButton: true
10
fullscreenButton: true
11
wrapButton: true
12
themeToggleButton: true
13
lineNumbers: true
14
frameDetection: true
15
fileNameExtraction: true
16
languageBadge: true
17
themedScrollbars: true
18
links: true
19
styleReset: true
20
minify: true
21
fileIcons: true
22
23
outputPanel: true
24
outputDefaultCollapsed: false
25
26
tabWidth: 2
27
minContrast: 5.5
28
cascadeLayer: "kazari"
29
terminalDotStyle: "colored"
30
languageIconMode: "none"
31
locale: "en-US"
32
33
styleOverrides:
34
  radius: "0.3rem"
35
  font-size: "1rem"
36
  font-family: "'Fira Code', monospace"
37
  code-padding-block: "1.5rem"
38
  shadow:
39
    light: "0 2px 8px rgba(0,0,0,0.1)"
40
    dark: "none"
41
  editor-bg:
42
    light: "#ffffff"
43
    dark: "#1e293b"
44
45
defaults:
46
  wrap: false
47
  preserveIndent: true
48
  lineNumbers: false
49
  frame: "auto"
50
51
languageDefaults:
52
  "bash,sh,zsh":
53
    wrap: true
54
    frame: "terminal"
55
  "python":
56
    lineNumbers: true
57
58
collapsible:
59
  lineThreshold: 20
60
  previewLines: 5
61
  defaultCollapsed: true
62
  style: "github"
63
64
languageAliases:
65
  javascript: "js"
66
  typescript: "ts"
67
68
uiStrings:
69
  "copy.label": "Copy"
70
  "copy.success": "Copied!"

Process (CLI)

The process: key configures the kazari process command (skipUnlabeled, assetsBase, hashedAssets, concurrency, maxFileBytes). FileConfigToOptions ignores it; the CLI reads it from the parsed config directly. See CLI Configuration for the full field table.