Output Formats

Nuri provides six output methods. All follow the same pattern: pass code and an options struct, get formatted output.

HTML

1
html, err := h.CodeToHTML(ctx, `fmt.Println("hello")`, nuri.CodeToHTMLOptions{
2
  Lang:  "go",
3
  Theme: "github-dark",
4
})

Returns (string, error). Produces a <pre><code> element with inline color styles.

CodeToHTMLOptions is the most feature-rich options struct. Beyond Lang and Theme, it supports:

• Themes for multi-theme mode
• Transformers for notation comments, meta ranges, and custom hooks
• HighlightLines, FocusLines, InsertedLines, DeletedLines for line decorations
• ClassMap for style-to-class mode
• PreClass, CodeClass, PreAttrs, CodeAttrs for custom attributes on the wrapper elements

Use nuri.WithDefaults() to set site-wide defaults applied to every CodeToHTML call. Per-call non-zero fields override the defaults:

1
h, _ := nuri.New(ctx,
2
  nuri.WithFS(core.FS()),
3
  nuri.WithDefaults(nuri.CodeToHTMLOptions{
4
    Theme:    "github-dark",
5
    PreClass: "code-block",
6
  }),
7
)
8
9
// Only Lang is needed per call; Theme and PreClass carry over.
10
html, _ := h.CodeToHTML(ctx, code, nuri.CodeToHTMLOptions{Lang: "go"})

ANSI

1
ansi, err := h.CodeToANSI(ctx, `fmt.Println("hello")`, nuri.CodeToANSIOptions{
2
  Lang:  "go",
3
  Theme: "github-dark",
4
})
5
fmt.Print(ansi)

Returns (string, error). Produces ANSI escape sequences for terminal display. Use fmt.Print, not fmt.Println, since the output already contains newlines.

Color depth

ColorDepth controls the ANSI color encoding:

1
ansi, err := h.CodeToANSI(ctx, code, nuri.CodeToANSIOptions{
2
  Lang:       "go",
3
  Theme:      "github-dark",
4
  ColorDepth: nuri.ColorDepth256,
5
})

Indexed modes use perceptual nearest-color matching to map 24-bit theme colors to the available palette.

ANSI as an input language

Set Lang: "ansi" to tokenize text containing ANSI escape sequences. This parses existing terminal output and re-highlights it through a theme:

1
html, err := h.CodeToHTML(ctx, ansiInput, nuri.CodeToHTMLOptions{
2
  Lang:  "ansi",
3
  Theme: "github-dark",
4
})

SVG

1
svg, err := h.CodeToSVG(ctx, `fmt.Println("hello")`, nuri.CodeToSVGOptions{
2
  Lang:         "go",
3
  Theme:        "github-dark",
4
  FontSize:     16,
5
  CornerRadius: 12,
6
})

Returns (string, error). Produces a self-contained SVG document. Useful for generating images of code snippets without a browser.

SVG options

Zero values use the defaults listed above.

JSON

1
data, err := h.CodeToJSON(ctx, `fmt.Println("hello")`, nuri.CodeToJSONOptions{
2
  Lang:   "go",
3
  Theme:  "github-dark",
4
  Indent: true,
5
})

Returns ([]byte, error). Marshals the TokensResult struct directly to JSON. Set Indent: true for pretty-printed output with 2-space indentation.

The JSON structure mirrors TokensResult:

1
{
2
  "tokens": [[{"content": "fmt", "color": "#E1E4E8", ...}, ...]],
3
  "fg": "#e1e4e8",
4
  "bg": "#24292e",
5
  "themeName": "github-dark"
6
}

CodeToJSONOptions supports Themes for multi-theme output. When set, the JSON includes themeFG, themeBG, themeNames, and per-token themeStyles fields.

Plain text

1
text, err := h.CodeToPlainText(ctx, code, nuri.CodeToPlainTextOptions{
2
  Lang:  "go",
3
  Theme: "github-dark",
4
})

Returns (string, error). Reconstructs the source text from the token stream with no styling. Newlines separate lines; there is no trailing newline.

Use this to extract text content from a highlighting pipeline or to verify tokenizer coverage (the output should match the input).

Raw tokens

1
result, err := h.CodeToTokens(ctx, `fmt.Println("hello")`, nuri.CodeToTokensOptions{
2
  Lang:  "go",
3
  Theme: "github-dark",
4
})
5
6
for _, line := range result.Tokens {
7
  for _, tok := range line {
8
    fmt.Printf("%s → %s\n", tok.Content, tok.Color)
9
  }
10
}

Returns (*TokensResult, error). Gives programmatic access to the token grid with resolved colors and scope names.

Each ThemedToken has:

CodeToTokensOptions supports Themes for multi-theme resolution. Non-default theme styles appear in ThemedToken.ThemeStyles.

h.CodeToHighlightedTokens() is an alias for h.CodeToTokens(), retained for Shiki API compatibility.

Per-call overrides

All options structs accept MaxLineLength *int and TimeoutMs *int as per-call overrides for the constructor defaults. Pass nil to use the highlighter's default, or a pointer to an int to override for a single call.

Next steps

• Transformers for notation comments, meta ranges, and custom hooks (HTML only)
• Multi-Theme Mode for CSS variable emission and light/dark switching