Nuri Adapter

The kazarinuri package connects Kazari to Nuri, a pure Go port of Shiki that uses TextMate grammars and VS Code themes. Nuri handles tokenization with VS Code-identical fidelity; Kazari adds the presentation layer.

Setup

Install both packages:

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

Wire the adapter at engine construction:

1
import (
2
    "context"
3
    "log"
4
5
    "github.com/frostybee/kazari"
6
    kazarinuri "github.com/frostybee/kazari/nuri"
7
    "github.com/frostybee/nuri"
8
    "github.com/frostybee/nuri/bundle/core"
9
)
10
11
func main() {
12
    ctx := context.Background()
13
14
    hl, err := nuri.New(ctx, nuri.WithFS(core.FS()))
15
    if err != nil {
16
        log.Fatal(err)
17
    }
18
    defer hl.Close(ctx)
19
20
    nuriHL := kazarinuri.New(ctx, hl)
21
22
    engine := kazari.New(
23
        kazari.WithHighlighter(nuriHL),
24
        kazari.WithThemes("github-light", "github-dark"),
25
    )
26
27
    // engine.CSS() and engine.JS() return styles and scripts to inject once per page.
28
    // engine.RenderWithMeta(code, meta) renders each code block.
29
}

core.FS() provides 39 bundled language grammars and 65 VS Code themes from the github.com/frostybee/nuri/bundle/core package. nuri.New compiles the embedded Oniguruma WASM engine and returns an error if initialization fails.

The kazarinuri.New(ctx, hl) call wraps the Nuri highlighter in an adapter that satisfies Kazari's Highlighter interface. Both the context and the Nuri pointer are required.

Language bundles

Nuri ships two language bundles. Both include the same 65 VS Code themes.

Both expose a single FS() fs.FS function returning an embedded filesystem with grammars/ and themes/ subdirectories. Pass the result to nuri.WithFS:

1
import "github.com/frostybee/nuri/bundle/full"
2
3
hl, err := nuri.New(ctx, nuri.WithFS(full.FS()))

To register a custom grammar or theme not included in either bundle, use nuri.WithGrammar or nuri.WithTheme alongside a bundle:

1
hl, err := nuri.New(ctx,
2
    nuri.WithFS(core.FS()),
3
    nuri.WithGrammar("mylang", grammarJSON),
4
    nuri.WithTheme("my-theme", themeJSON),
5
)

Dual-theme tokenization

NuriHighlighter implements the DualThemeTokenizer interface:

1
type DualThemeTokenizer interface {
2
    TokenizeDual(code, lang, lightTheme, darkTheme string) (light, dark [][]Token, err error)
3
}

When two themes are configured via kazari.WithThemes(light, dark), the engine detects this interface and calls TokenizeDual instead of calling Tokenize twice. A single Nuri tokenization pass produces both light and dark token streams with identical structure: same line count, same token count per line, same content, different colors.

This optimization reduces tokenization cost for dual-theme rendering. The Chroma adapter does not implement DualThemeTokenizer; it always requires two separate Tokenize calls.

Theme names

Pass Nuri-compatible theme names directly to kazari.WithThemes. Common pairs:

Theme names are passed to Nuri without mapping or aliasing. GetThemeColors returns an error for unrecognized theme names.

The full list of bundled themes is available in the Nuri documentation.

Theme colors

GetThemeColors reads VS Code-style color keys from the theme and returns a fully populated ThemeInfo:

All five fields are populated for standard VS Code themes. The Chroma adapter leaves SelectionBG and FoldBG empty because Chroma themes do not include editor color keys.

Nuri configuration

These nuri.New options control the tokenization engine. They are set on the Nuri highlighter, not on the Kazari engine.

Pool sizing example for a documentation site building many pages concurrently:

1
hl, err := nuri.New(ctx,
2
    nuri.WithFS(core.FS()),
3
    nuri.WithPoolSize(4),
4
    nuri.WithTimeoutMs(500),
5
)

SVG output

Nuri can render syntax-highlighted code as standalone SVG images, useful for README files, email content, or static exports where HTML and CSS are not available. This feature is called directly on the *nuri.Highlighter instance, not through the Kazari adapter.

1
svg, err := hl.CodeToSVG(ctx, code, nuri.CodeToSVGOptions{
2
    Lang:  "go",
3
    Theme: "github-dark",
4
})

CodeToSVGOptions fields

Examples

Custom font size:

1
svg, _ := hl.CodeToSVG(ctx, code, nuri.CodeToSVGOptions{
2
    Lang:     "go",
3
    Theme:    "github-dark",
4
    FontSize: 18,
5
})

Transparent background (no container fill):

1
noBG := false
2
svg, _ := hl.CodeToSVG(ctx, code, nuri.CodeToSVGOptions{
3
    Lang:           "go",
4
    Theme:          "github-dark",
5
    ShowBackground: &noBG,
6
    CornerRadius:   0,
7
})

Dual-theme output (generate separate SVGs for light and dark contexts):

1
lightSVG, _ := hl.CodeToSVG(ctx, code, nuri.CodeToSVGOptions{
2
    Lang:  "go",
3
    Theme: "github-light",
4
})
5
darkSVG, _ := hl.CodeToSVG(ctx, code, nuri.CodeToSVGOptions{
6
    Lang:  "go",
7
    Theme: "github-dark",
8
})

This produces two standalone images that can be toggled with CSS prefers-color-scheme media queries or displayed side by side.

Language loading

Nuri loads language grammars lazily. A language appears in GetLoadedLanguages() only after the first Tokenize or TokenizeDual call for that language. This is expected behavior and does not affect rendering.

When a block specifies an unknown language, the engine falls back to plaintext rendering and emits a warning through the configured warning handler.

The full list of supported languages is available in the Nuri documentation.

Context and lifecycle

The Nuri adapter captures the context.Context passed to kazarinuri.New and reuses it for every subsequent Tokenize, TokenizeDual, and GetThemeColors call. Kazari's Highlighter interface does not accept a per-call context, so cancellation must be managed at the Nuri highlighter level.

For long-running servers, pass a context tied to the server's lifecycle:

1
ctx, cancel := context.WithCancel(context.Background())
2
defer cancel()
3
4
hl, err := nuri.New(ctx, nuri.WithFS(core.FS()))
5
if err != nil {
6
    log.Fatal(err)
7
}
8
defer hl.Close(ctx)
9
10
nuriHL := kazarinuri.New(ctx, hl)

For CLI tools and SSGs that process a batch of files and exit, context.Background() is sufficient.