Custom Languages & Themes

Register grammars and themes at construction time, at runtime, or from a filesystem.

At construction time

Pass WithGrammar and WithTheme with raw JSON bytes when creating the highlighter:

1
grammarJSON, _ := os.ReadFile("my-language.tmLanguage.json")
2
themeJSON, _ := os.ReadFile("my-theme.json")
3
4
h, err := nuri.New(ctx,
5
  nuri.WithFS(core.FS()),
6
  nuri.WithGrammar("my-language", grammarJSON),
7
  nuri.WithTheme("my-theme", themeJSON),
8
  nuri.WithAlias("ml", "my-language"),
9
  nuri.WithExtension("mlg", "my-language"),
10
)

At runtime

Add grammars and themes to a running highlighter:

1
grammarJSON, _ := os.ReadFile("hcl.tmLanguage.json")
2
if err := h.LoadLanguage("hcl", grammarJSON); err != nil {
3
  log.Fatal(err)
4
}
5
6
themeJSON, _ := os.ReadFile("catppuccin-latte.json")
7
if err := h.LoadTheme("catppuccin-latte", themeJSON); err != nil {
8
  log.Fatal(err)
9
}
10
11
h.RegisterAlias("terraform", "hcl")
12
h.RegisterExtension("tf", "hcl")

Runtime registration adds to the existing registry. Use this when loading grammars or themes on demand or from user-provided data.

From a filesystem

Point the highlighter at directories of grammar and theme JSON files:

1
h, err := nuri.New(ctx,
2
  nuri.WithGrammarFS(os.DirFS("./grammars")),
3
  nuri.WithThemeFS(os.DirFS("./themes")),
4
)

nuri.WithFS() is a shorthand when both grammars and themes live under a single root with grammars/ and themes/ subdirectories:

1
h, err := nuri.New(ctx, nuri.WithFS(os.DirFS("./assets")))

The filesystem is scanned at construction time. Grammars and themes load lazily on first use.

Expected JSON formats

Grammar (TextMate format)

1
{
2
  "scopeName": "source.example",
3
  "name": "Example Language",
4
  "patterns": [
5
    { "match": "\\b(func|return)\\b", "name": "keyword.control.example" }
6
  ],
7
  "repository": {}
8
}

scopeName is required. The format follows the standard TextMate grammar structure: patterns, repository, begin/end, captures, injections, and injectionSelector. Unknown fields are silently ignored.

Theme (VS Code format)

1
{
2
  "name": "My Theme",
3
  "type": "dark",
4
  "colors": {
5
    "editor.background": "#1e1e1e",
6
    "editor.foreground": "#d4d4d4"
7
  },
8
  "tokenColors": [
9
    {
10
      "scope": "keyword.control",
11
      "settings": {
12
        "foreground": "#569cd6",
13
        "fontStyle": "bold"
14
      }
15
    }
16
  ]
17
}

scope accepts a string ("keyword.control") or an array (["keyword", "storage"]). fontStyle is a space-separated string: "italic", "bold", "underline", "strikethrough". The semanticTokenColors field (present in real VS Code themes) is silently ignored.

Aliases

About 80 aliases are pre-registered from the upstream grammar collection. A sample:

Use nuri.WithAlias() or h.RegisterAlias() to add custom aliases.

File extension mapping

58 extensions are pre-registered. Extensions are stored without the leading dot and matched case-insensitively. nuri.WithExtension() and h.RegisterExtension() override existing mappings for a given extension.

Language detection

By filename

1
lang, found := h.DetectLanguage("src/main.go")
2
// lang = "go", found = true

h.DetectLanguage() accepts a filename or full path (it extracts the base name internally). It checks exact filenames first (Makefile, Dockerfile, Gemfile, Rakefile), then file extensions.

By content

1
lang, found := h.DetectLanguageByContent("#!/usr/bin/env python3")
2
// lang = "python", found = true

h.DetectLanguageByContent() runs firstLineMatch regular expressions from grammar JSON files against the provided string. This handles shebang lines and other first-line markers.

Inspecting loaded languages

1
names := h.LoadedLanguages()
2
// Returns sorted names of all currently cached grammars.

h.LoadedLanguages() returns the canonical names of grammars that have been loaded (either from the bundle or via LoadLanguage). Grammars are loaded lazily on first use, so the list grows as languages are highlighted.

Next steps

• Contrast Correction for WCAG 2.1 automatic color adjustment
• Performance & Concurrency for pool sizing and safety valves