Chroma Syntax Highlighter

For full control, follow these steps to manually tokenize and format code:

1. Get the Lexer, Style, and Formatter: Use lexers.Get, styles.Get, and formatters.Get. Always check for nil and use the respective Fallback if necessary.
2. Tokenize: Call lexer.Tokenise(nil, content) to get an iterator.
3. Format: Call formatter.Format(writer, style, iterator) to produce the final output.

style := styles.Get("swapoff")
if style == nil {
  style = styles.Fallback
}
formatter := formatters.Get("html")
if formatter == nil {
  formatter = formatters.Fallback
}

contents, err := io.ReadAll(r)
iterator, err := lexer.Tokenise(nil, string(contents))

err := formatter.Format(w, style, iterator)

To highlight code, you must first identify the language using one of three methods. If a method returns nil, you should use lexers.Fallback to ensure a lexer is available. You can also use chroma.Coalesce(lexer) to reduce the number of tokens by merging identical consecutive token types.

1. From filename: Use lexers.Match(filename).
2. By syntax ID: Use lexers.Get(syntaxID) (available IDs can be found via lexers.Names()).
3. From content: Use lexers.Analyse(content).

// 1. Match by filename
lexer := lexers.Match("foo.go")

// 2. Get by syntax ID
lexer := lexers.Get("go")

// 3. Analyse content
lexer := lexers.Analyse("package main\n\nfunc main()\n{\n}\n")

// Handle failed identification
if lexer == nil {
  lexer = lexers.Fallback
}

// Optional: Coalesce tokens to reduce verbosity
lexer = chroma.Coalesce(lexer)

To verify the correctness of Chroma lexers, you can run the existing test suite. The tests work by feeding input files from testdata/<name>.actual into the parser and comparing the output against <name>.expected. You can also group multiple test inputs for a single parser by placing them in testdata/<name>/.

go test ./lexers

To run the existing test suite for lexers, execute the following command from the root directory of the repository:

go test ./lexers

Chroma can be used as a preprocessor for less(1) via the LESSOPEN environment variable. Using the --fail flag allows the system to fall back to a different preprocessor (like cat) if Chroma cannot resolve a lexer for a specific file.

To set this up, export the following environment variable:

export LESSOPEN='| p() { chroma --fail "$1" || cat "$1"; }; p "%s"'

Note: When invoked as a .lessfilter, the --fail flag is enabled automatically.

If you are developing or editing lexers and want to test them in a browser-based playground:

1. Open a shell in cmd/chromad.
2. Run the following command:

go run . --csrf-key=securekey

3. Open the printed link in your browser to use the Playground with your local changes.

When adding new test data files (*.actual), you must regenerate the corresponding *.expected files. This is done by setting the RECORD environment variable to true before running the tests. This tells Chroma to output the test data into the expected files.

RECORD=true go test ./lexers

Chroma v3 uses the following module path:

import "github.com/alecthomas/chroma/v3"

The inline environment variable syntax RECORD=true go test ./lexers is not supported in standard Windows Command Prompt or PowerShell. You must set the environment variable in a separate step before running the test command.

Command Prompt:

set RECORD=true
go test ./lexers

PowerShell:

$env:RECORD = 'true'
go test ./lexers

Use the quick.Highlight convenience function to format source text with minimal setup. It allows you to specify the output writer, the source code, the language syntax ID, the formatter name, and the style name in a single call.

```go
err := quick.Highlight(os.Stdout, someSourceCode, "go", "html", "monokai")
```埋

You can automatically convert lexers from Pygments to Chroma's XML format using the provided Python 3 script pygments2chroma_xml.py. This is useful for porting community-maintained lexers.

Example conversion using uv:

uv run --script _tools/pygments2chroma_xml.py \
  pygments.lexers.jvm.KotlinLexer \
  > lexers/embedded/kotlin.xml

The libchromawasm package provides an experimental WebAssembly (WASM) build of Chroma intended for use with TinyGO. When loaded in a browser environment, it registers a global highlight function on the JavaScript window object.

JavaScript API Signature

/**
 * @param {string} source - The source code text to highlight.
 * @param {string} lexer - The name of the lexer (e.g., 'go', 'python'). If unknown, Chroma attempts to autodetect the language.
 * @param {string} styleName - The name of the color style to use.
 * @param {boolean} classes - Whether to use CSS classes for styling instead of inline styles.
 * @returns {{html: string, language: string, background: string}} An object containing the highlighted HTML, detected language, and background color.
 */
function highlight(source, lexer, styleName, classes) { ... }