Quick Start

Render a syntax-highlighted code block and write it to an HTML file in under 30 lines of Go. By the end of this page, a working output.html opens in the browser with a framed, dual-theme code block.

Install

Kazari requires Go 1.25 or later and a syntax highlighter. Install Kazari and the Nuri adapter (recommended):

go get github.com/frostybee/kazari@latest
go get github.com/frostybee/nuri@latest

Chroma is also supported as an alternative highlighter. See the Chroma Adapter page for setup.

Create the engine

Set up a Nuri highlighter, wrap it with the Kazari adapter, and pass it to kazari.New():

1
ctx := context.Background()
2
hl, err := nuri.New(ctx, nuri.WithFS(core.FS()))
3
if err != nil {
4
    log.Fatal(err)
5
}
6
defer hl.Close(ctx)
7
8
engine := kazari.New(
9
    kazari.WithHighlighter(kazarinuri.New(ctx, hl)),
10
    kazari.WithThemes("github-light", "github-dark"),
11
)

WithThemes sets both a light and dark theme. Kazari bakes both sets of token colors into the HTML at build time via CSS custom properties. Theme switching is pure CSS with no JavaScript and no flash on toggle or page load. Dark mode defaults to a .dark class selector on the root element. See the Themes & Dark Mode page for other strategies.

Render a code block

Pass source code and a meta string to engine.RenderWithMeta():

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

The meta string controls per-block behavior. In this example:

Segment	Effect
`go`	Language for syntax highlighting
`title="main.go"`	Title displayed in the frame header
`showLineNumbers`	Show line numbers in the gutter
`{2}`	Highlight line 2 with a colored background

Assemble the page

Kazari returns three separate outputs. Combine them into a complete HTML file:

1
package main
2
3
import (
4
    "context"
5
    "log"
6
    "os"
7
8
    "github.com/frostybee/kazari"
9
    kazarinuri "github.com/frostybee/kazari/nuri"
10
    "github.com/frostybee/nuri"
11
    "github.com/frostybee/nuri/bundle/core"
12
)
13
14
func main() {
15
    ctx := context.Background()
16
    hl, err := nuri.New(ctx, nuri.WithFS(core.FS()))
17
    if err != nil {
18
        log.Fatal(err)
19
    }
20
    defer hl.Close(ctx)
21
22
    engine := kazari.New(
23
        kazari.WithHighlighter(kazarinuri.New(ctx, hl)),
24
        kazari.WithThemes("github-light", "github-dark"),
25
    )
26
27
    code := `func main() {
28
    cfg := loadConfig()
29
    svc := newService(cfg)
30
    svc.Run()
31
}`
32
    block, err := engine.RenderWithMeta(code, `go title="main.go" showLineNumbers {2}`)
33
    if err != nil {
34
        log.Fatal(err)
35
    }
36
37
    page := "<!DOCTYPE html><html><head><style>" +
38
        engine.CSS() +
39
        "</style></head><body>" +
40
        block +
41
        "<script>" + engine.JS() + "</script></body></html>"
42
43
    os.WriteFile("output.html", []byte(page), 0644)
44
}

Run the program and open output.html in a browser:

go run main.go

→ A framed code block appears with the title "main.go", line numbers, and line 2 highlighted in yellow.

Output structure

Each method returns a string. The consumer decides where to place them.

Method	Returns	Inject
`engine.CSS()`	Full stylesheet (structural rules + theme variables)	Once in `<head>`
`engine.JS()`	Scripts for interactive features (copy, fullscreen, collapse)	Once before `</body>`
`engine.Render()`	Per-block HTML	Once per code block
`engine.RenderWithMeta()`	Per-block HTML (parses a meta string)	Once per code block

engine.Assets() returns the same CSS and JS content with content-hashed filenames, suitable for production builds with cache busting. See Engine API for details.

Add features

Enable common features with functional options passed to kazari.New():

1
engine := kazari.New(
2
    kazari.WithHighlighter(kazarinuri.New(ctx, hl)),
3
    kazari.WithThemes("github-light", "github-dark"),
4
    kazari.WithCopyButton(true),
5
    kazari.WithLineNumbers(true),
6
    kazari.WithCollapsible(kazari.CollapsibleConfig{
7
        LineThreshold: 20,
8
        PreviewLines:  8,
9
    }),
10
)

Per-block settings override engine defaults via the meta string:

1
```go title="server.go" showLineNumbers {3-5} collapse

See Features for the full list of available options.

With Goldmark

Render fenced code blocks in Markdown through Goldmark:

1
import (
2
    kazarimd "github.com/frostybee/kazari/goldmark"
3
    "github.com/yuin/goldmark"
4
)
5
6
md := goldmark.New(
7
    goldmark.WithExtensions(kazarimd.New(engine)),
8
)

Add code group support for tabbed containers:

1
md := goldmark.New(
2
    goldmark.WithExtensions(
3
        kazarimd.New(engine),
4
        kazarimd.CodeGroups(engine),
5
    ),
6
)

See the Goldmark Extension page for configuration details.

Next steps

Configuration Layers explains the three-layer cascade: engine defaults, language defaults, and per-block meta strings
Features covers every feature with meta string syntax, Go API, and CSS variables
CSS Custom Properties shows how to customize colors, spacing, and fonts with --kz-* CSS variables
File-Based Config sets engine options from a kazari.config.yaml file without writing Go code
HTML Processor upgrades code blocks in output already built by another static site generator, with no Go integration required