chroma Documentation

Technical Documentation: alecthomas/chroma

ℹ️ Provenance: Hybrid Fusion: alecthomas/chroma (README + 2 In-Tree Chapters) · CodeWiki Reference · Recency: Active (< 180 days)

1. Project Overview & Quickstart (alecthomas/chroma) Copy Chapter

[!NOTE]
v3 alpha available. Chroma v3 replaces the custom Iterator type with Go's built-in iter.Seq[Token], removes the EOF sentinel, and bumps the module path to github.com/alecthomas/chroma/v3. See the v3.0.0-alpha.1 release for migration details.

A general purpose syntax highlighter in pure Go

Chroma takes source code and other structured text and converts it into syntax
highlighted HTML, ANSI-coloured text, etc.

Chroma is based heavily on Pygments, and includes
translators for Pygments lexers and styles.

Table of Contents Copy Chapter

1. Supported languages
2. Try it
3. Using the library
   1. Quick start
   2. Identifying the language
   3. Formatting the output
   4. The HTML formatter
4. More detail
   1. Lexers
   2. Formatters
   3. Styles
5. Command-line interface
6. Testing lexers
7. What's missing compared to Pygments?

Supported languages Copy Chapter

I will attempt to keep this section up to date, but an authoritative list can be
displayed with chroma --list.

Try it Copy Chapter

Try out various languages and styles on the Chroma Playground.

Using the library Copy Chapter

This is version 2 of Chroma, use the import path:

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

Chroma, like Pygments, has the concepts of
lexers,
formatters and
styles.

Lexers convert source text into a stream of tokens, styles specify how token
types are mapped to colours, and formatters convert tokens and styles into
formatted output.

A package exists for each of these, containing a global Registry variable
with all of the registered implementations. There are also helper functions
for using the registry in each package, such as looking up lexers by name or
matching filenames, etc.

In all cases, if a lexer, formatter or style can not be determined, nil will
be returned. In this situation you may want to default to the Fallback
value in each respective package, which provides sane defaults.

Quick start Copy Section

A convenience function exists that can be used to simply format some source
text, without any effort:

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

Identifying the language Copy Section

To highlight code, you'll first have to identify what language the code is
written in. There are three primary ways to do that:

1. Detect the language from its filename.

   go Copy

   lexer := lexers.Match("foo.go")

2. Explicitly specify the language by its Chroma syntax ID (a full list is available from lexers.Names()).

   go Copy

   lexer := lexers.Get("go")

3. Detect the language from its content.

   go Copy

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

In all cases, nil will be returned if the language can not be identified.

if lexer == nil {
  lexer = lexers.Fallback
}

At this point, it should be noted that some lexers can be extremely chatty. To
mitigate this, you can use the coalescing lexer to coalesce runs of identical
token types into a single token:

lexer = chroma.Coalesce(lexer)

Formatting the output Copy Section

Once a language is identified you will need to pick a formatter and a style (theme).

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

Then obtain an iterator over the tokens:

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

And finally, format the tokens from the iterator:

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

The HTML formatter Copy Section

By default the html registered formatter generates standalone HTML with
embedded CSS. More flexibility is available through the formatters/html package.

Firstly, the output generated by the formatter can be customised with the
following constructor options:

• Standalone() - generate standalone HTML with embedded CSS.
• WithClasses() - use classes rather than inlined style attributes.
• ClassPrefix(prefix) - prefix each generated CSS class.
• TabWidth(width) - Set the rendered tab width, in characters.
• WithLineNumbers() - Render line numbers (style with LineNumbers).
• WithLinkableLineNumbers() - Make the line numbers linkable and be a link to themselves.
• HighlightLines(ranges) - Highlight lines in these ranges (style with LineHighlight).
• WithLinePrompts(prompt, ranges) - Render non-selectable prompts before lines in these ranges.
• LineNumbersInTable() - Use a table for formatting line numbers and code, rather than spans.
• BaseLineNumber(n) - Set the first line number; highlight and prompt ranges follow it.
• WrapLongLines(true) - Wrap long lines instead of scrolling.
• PreventSurroundingPre(true) - Emit the highlighted spans without the surrounding ``.
• InlineCode(true) - Generate output suitable for inline <code> elements.
• WithPreWrapper(wrapper) - Customise the wrapping `` element.
• WithCustomCSS(css) - Add custom CSS per token type.
• WithModeClasses(true) - Scope generated CSS by the style's light/dark mode class.

If WithClasses() is used, the corresponding CSS can be obtained from the formatter with:

formatter := html.New(html.WithClasses(true))
err := formatter.WriteCSS(w, style)

For light/dark theme switching, enable WithModeClasses(true) and write the
CSS for both styles into one stylesheet. Each rule is scoped by its style's
mode class (eg. .chroma.dark), so the theme can be toggled at runtime by
swapping the mode class on the wrapper element.

More detail Copy Chapter

Lexers Copy Section

Lexers are community maintained. Please use
Discussions for lexer
requests and lexer highlighting bugs.

See the Pygments documentation
for details on implementing lexers. Most concepts apply directly to Chroma,
but see existing lexer implementations for real examples.

In many cases lexers can be automatically converted directly from Pygments by
using the included Python 3 script pygments2chroma_xml.py. I use something like
the following:

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

A list of all lexers available in Pygments can be found in pygments-lexers.txt.

Formatters Copy Section

Chroma supports HTML output, as well as terminal output in 8 colour, 256 colour, and true-colour.

A noop formatter is included that outputs the token text only, and a tokens
formatter outputs raw tokens. The latter is useful for debugging lexers.

Styles Copy Section

Chroma styles are defined in XML. The style entries use the
same syntax as Pygments. All Pygments styles have been converted to Chroma using the _tools/style.py
script.

Style names are case-insensitive. For example, monokai and Monokai are treated as the same style.

When you work with one of Chroma's styles,
know that the Background token type provides the default style for tokens. It does so
by defining a foreground color and background color.

For example, this gives each token name not defined in the style a default color
of #f8f8f8 and uses #000000 for the highlighted code block's background:

<entry type="Background" style="#f8f8f2 bg:#000000"/>

Also, token types in a style file are hierarchical. For instance, when CommentSpecial is not defined, Chroma uses the token style from Comment. So when several comment tokens use the same color, you'll only need to define Comment and override the one that has a different color.

For a quick overview of the available styles and how they look, check out the Chroma Style Gallery.

Command-line interface Copy Chapter

A command-line interface to Chroma is included.

Binaries are available to install from the releases page.

The CLI can be used as a preprocessor to colorise output of less(1),
see documentation for the LESSOPEN environment variable.

The --fail flag can be used to suppress output and return with exit status
1 to facilitate falling back to some other preprocessor in case chroma
does not resolve a specific lexer to use for the given file. For example:

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

Replace cat with your favourite fallback preprocessor.

When invoked as .lessfilter, the --fail flag is automatically turned
on under the hood for easy integration with lesspipe shipping with
Debian and derivatives;
for that setup the chroma executable can be just symlinked to ~/.lessfilter.

Projects using Chroma Copy Chapter

• moor is a full-blown pager that colorizes
  its input using Chroma
• Hugo is a static site generator that uses Chroma for syntax
  highlighting code examples
• f4 is asynchronious cross platform Far Manager clone in Go
  that uses Chroma for syntax highlighting in built-in editor

Testing lexers Copy Chapter

If you edit some lexers and want to try it, open a shell in cmd/chromad and run:

go run . --csrf-key=securekey

A Link will be printed. Open it in your Browser. Now you can test on the Playground with your local changes.

If you want to run the tests and the lexers, open a shell in the root directory and run:

go test ./lexers

When updating or adding a lexer, please add tests. See lexers/README.md for more.

What's missing compared to Pygments? Copy Chapter

• Quite a few lexers, for various reasons (pull-requests welcome):
  • Pygments lexers for complex languages often include custom code to
    handle certain aspects, such as Raku's ability to nest code inside
    regular expressions. These require time and effort to convert.
  • I mostly only converted languages I had heard of, to reduce the porting cost.
• Some more esoteric features of Pygments are omitted for simplicity.
• Though the Chroma API supports content detection, very few languages support them.
  I have plans to implement a statistical analyser at some point, but not enough time.

2. In-Tree Documentation Chapters (alecthomas/chroma) Copy Chapter

File: README.md Copy Chapter

[!NOTE]
v3 alpha available. Chroma v3 replaces the custom Iterator type with Go's built-in iter.Seq[Token], removes the EOF sentinel, and bumps the module path to github.com/alecthomas/chroma/v3. See the v3.0.0-alpha.1 release for migration details.

A general purpose syntax highlighter in pure Go

Chroma takes source code and other structured text and converts it into syntax
highlighted HTML, ANSI-coloured text, etc.

Chroma is based heavily on Pygments, and includes
translators for Pygments lexers and styles.

Table of Contents Copy Chapter

1. Supported languages
2. Try it
3. Using the library
   1. Quick start
   2. Identifying the language
   3. Formatting the output
   4. The HTML formatter
4. More detail
   1. Lexers
   2. Formatters
   3. Styles
5. Command-line interface
6. Testing lexers
7. What's missing compared to Pygments?

Supported languages Copy Chapter

I will attempt to keep this section up to date, but an authoritative list can be
displayed with chroma --list.

Try it Copy Chapter

Try out various languages and styles on the Chroma Playground.

Using the library Copy Chapter

This is version 2 of Chroma, use the import path:

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

Chroma, like Pygments, has the concepts of
lexers,
formatters and
styles.

Lexers convert source text into a stream of tokens, styles specify how token
types are mapped to colours, and formatters convert tokens and styles into
formatted output.

A package exists for each of these, containing a global Registry variable
with all of the registered implementations. There are also helper functions
for using the registry in each package, such as looking up lexers by name or
matching filenames, etc.

In all cases, if a lexer, formatter or style can not be determined, nil will
be returned. In this situation you may want to default to the Fallback
value in each respective package, which provides sane defaults.

Quick start Copy Section

A convenience function exists that can be used to simply format some source
text, without any effort:

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

Identifying the language Copy Section

To highlight code, you'll first have to identify what language the code is
written in. There are three primary ways to do that:

1. Detect the language from its filename.

   go Copy

   lexer := lexers.Match("foo.go")

2. Explicitly specify the language by its Chroma syntax ID (a full list is available from lexers.Names()).

   go Copy

   lexer := lexers.Get("go")

3. Detect the language from its content.

   go Copy

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

In all cases, nil will be returned if the language can not be identified.

if lexer == nil {
  lexer = lexers.Fallback
}

At this point, it should be noted that some lexers can be extremely chatty. To
mitigate this, you can use the coalescing lexer to coalesce runs of identical
token types into a single token:

lexer = chroma.Coalesce(lexer)

Formatting the output Copy Section

Once a language is identified you will need to pick a formatter and a style (theme).

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

Then obtain an iterator over the tokens:

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

And finally, format the tokens from the iterator:

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

The HTML formatter Copy Section

By default the html registered formatter generates standalone HTML with
embedded CSS. More flexibility is available through the formatters/html package.

Firstly, the output generated by the formatter can be customised with the
following constructor options:

• Standalone() - generate standalone HTML with embedded CSS.
• WithClasses() - use classes rather than inlined style attributes.
• ClassPrefix(prefix) - prefix each generated CSS class.
• TabWidth(width) - Set the rendered tab width, in characters.
• WithLineNumbers() - Render line numbers (style with LineNumbers).
• WithLinkableLineNumbers() - Make the line numbers linkable and be a link to themselves.
• HighlightLines(ranges) - Highlight lines in these ranges (style with LineHighlight).
• WithLinePrompts(prompt, ranges) - Render non-selectable prompts before lines in these ranges.
• LineNumbersInTable() - Use a table for formatting line numbers and code, rather than spans.
• BaseLineNumber(n) - Set the first line number; highlight and prompt ranges follow it.
• WrapLongLines(true) - Wrap long lines instead of scrolling.
• PreventSurroundingPre(true) - Emit the highlighted spans without the surrounding ``.
• InlineCode(true) - Generate output suitable for inline <code> elements.
• WithPreWrapper(wrapper) - Customise the wrapping `` element.
• WithCustomCSS(css) - Add custom CSS per token type.
• WithModeClasses(true) - Scope generated CSS by the style's light/dark mode class.

If WithClasses() is used, the corresponding CSS can be obtained from the formatter with:

formatter := html.New(html.WithClasses(true))
err := formatter.WriteCSS(w, style)

For light/dark theme switching, enable WithModeClasses(true) and write the
CSS for both styles into one stylesheet. Each rule is scoped by its style's
mode class (eg. .chroma.dark), so the theme can be toggled at runtime by
swapping the mode class on the wrapper element.

More detail Copy Chapter

Lexers Copy Section

Lexers are community maintained. Please use
Discussions for lexer
requests and lexer highlighting bugs.

See the Pygments documentation
for details on implementing lexers. Most concepts apply directly to Chroma,
but see existing lexer implementations for real examples.

In many cases lexers can be automatically converted directly from Pygments by
using the included Python 3 script pygments2chroma_xml.py. I use something like
the following:

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

A list of all lexers available in Pygments can be found in pygments-lexers.txt.

Formatters Copy Section

Chroma supports HTML output, as well as terminal output in 8 colour, 256 colour, and true-colour.

A noop formatter is included that outputs the token text only, and a tokens
formatter outputs raw tokens. The latter is useful for debugging lexers.

Styles Copy Section

Chroma styles are defined in XML. The style entries use the
same syntax as Pygments. All Pygments styles have been converted to Chroma using the _tools/style.py
script.

Style names are case-insensitive. For example, monokai and Monokai are treated as the same style.

When you work with one of Chroma's styles,
know that the Background token type provides the default style for tokens. It does so
by defining a foreground color and background color.

For example, this gives each token name not defined in the style a default color
of #f8f8f8 and uses #000000 for the highlighted code block's background:

<entry type="Background" style="#f8f8f2 bg:#000000"/>

Also, token types in a style file are hierarchical. For instance, when CommentSpecial is not defined, Chroma uses the token style from Comment. So when several comment tokens use the same color, you'll only need to define Comment and override the one that has a different color.

For a quick overview of the available styles and how they look, check out the Chroma Style Gallery.

Command-line interface Copy Chapter

A command-line interface to Chroma is included.

Binaries are available to install from the releases page.

The CLI can be used as a preprocessor to colorise output of less(1),
see documentation for the LESSOPEN environment variable.

The --fail flag can be used to suppress output and return with exit status
1 to facilitate falling back to some other preprocessor in case chroma
does not resolve a specific lexer to use for the given file. For example:

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

Replace cat with your favourite fallback preprocessor.

When invoked as .lessfilter, the --fail flag is automatically turned
on under the hood for easy integration with lesspipe shipping with
Debian and derivatives;
for that setup the chroma executable can be just symlinked to ~/.lessfilter.

Projects using Chroma Copy Chapter

• moor is a full-blown pager that colorizes
  its input using Chroma
• Hugo is a static site generator that uses Chroma for syntax
  highlighting code examples
• f4 is asynchronious cross platform Far Manager clone in Go
  that uses Chroma for syntax highlighting in built-in editor

Testing lexers Copy Chapter

If you edit some lexers and want to try it, open a shell in cmd/chromad and run:

go run . --csrf-key=securekey

A Link will be printed. Open it in your Browser. Now you can test on the Playground with your local changes.

If you want to run the tests and the lexers, open a shell in the root directory and run:

go test ./lexers

When updating or adding a lexer, please add tests. See lexers/README.md for more.

What's missing compared to Pygments? Copy Chapter

• Quite a few lexers, for various reasons (pull-requests welcome):
  • Pygments lexers for complex languages often include custom code to
    handle certain aspects, such as Raku's ability to nest code inside
    regular expressions. These require time and effort to convert.
  • I mostly only converted languages I had heard of, to reduce the porting cost.
• Some more esoteric features of Pygments are omitted for simplicity.
• Though the Chroma API supports content detection, very few languages support them.
  I have plans to implement a statistical analyser at some point, but not enough time.

File: lexers/README.md Copy Chapter

Chroma lexers

All lexers in Chroma should now be defined in XML unless they require custom code.

Lexer tests Copy Chapter

The tests in this directory feed a known input testdata/<name>.actual into the parser for <name> and check
that its output matches <name>.expected.

It is also possible to perform several tests on a same parser <name>, by placing know inputs *.actual into a
directory testdata/<name>/.

Running the tests Copy Section

Run the tests as normal:

go test ./lexers

Update existing tests Copy Section

When you add a new test data file (*.actual), you need to regenerate all tests. That's how Chroma creates the *.expected test file based on the corresponding lexer.

To regenerate all tests, type in your terminal:

RECORD=true go test ./lexers

This first sets the RECORD environment variable to true. Then it runs go test on the ./lexers directory of the Chroma project.

(That environment variable tells Chroma it needs to output test data. After running go test ./lexers you can remove or reset that variable.)

Windows users

Windows users will find that the RECORD=true go test ./lexers command fails in both the standard command prompt terminal and in PowerShell.

Instead we have to perform both steps separately:

• Set the RECORD environment variable to true.
  • In the regular command prompt window, the set command sets an environment variable for the current session: set RECORD=true. See this page for more.
  • In PowerShell, you can use the $env:RECORD = 'true' command for that. See this article for more.
  • You can also make a persistent environment variable by hand in the Windows computer settings. See this article for how.
• When the environment variable is set, run go test ./lexers.

Chroma will now regenerate the test files and print its results to the console window.

--- METRICS ---

• Files Extracted: 3
• Estimated Token Budget: ~7808 tokens
• Recency Window: Active (< 180 days)
• Canonical Reference: https://codewiki.google/github.com/alecthomas/chroma