# Technical Documentation: alecthomas/chroma > ℹ️ **Provenance:** Hybrid Fusion: `alecthomas/chroma` (README + 2 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/alecthomas/chroma) · Recency: Active (< 180 days) ## 1. Project Overview & Quickstart (alecthomas/chroma) > [!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](https://github.com/alecthomas/chroma/releases/tag/v3.0.0-alpha.1) release for migration details. # A general purpose syntax highlighter in pure Go [](https://pkg.go.dev/github.com/alecthomas/chroma/v3) [](https://github.com/alecthomas/chroma/actions/workflows/ci.yml) [](https://invite.slack.golangbridge.org/) 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](http://pygments.org/), and includes translators for Pygments lexers and styles. ## Table of Contents 1. [Supported languages](#supported-languages) 2. [Try it](#try-it) 3. [Using the library](#using-the-library) 1. [Quick start](#quick-start) 2. [Identifying the language](#identifying-the-language) 3. [Formatting the output](#formatting-the-output) 4. [The HTML formatter](#the-html-formatter) 4. [More detail](#more-detail) 1. [Lexers](#lexers) 2. [Formatters](#formatters) 3. [Styles](#styles) 5. [Command-line interface](#command-line-interface) 6. [Testing lexers](#testing-lexers) 7. [What's missing compared to Pygments?](#whats-missing-compared-to-pygments) ## Supported languages | Prefix | Language | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | A | ABAP, ABNF, ActionScript, ActionScript 3, Ada, Agda, AL, Alloy, AMPL, Angular2, ANTLR, ApacheConf, APL, AppleScript, ArangoDB AQL, Arduino, ArmAsm, Arturo, Astro, ATL, AutoHotkey, AutoIt, Awk | B | Ballerina, Bash, Bash Session, Batchfile, Beef, BibTeX, Bicep, BlitzBasic, BNF, BQN, Brainfuck | C | C, C#, C++, C3, Caddyfile, Caddyfile Directives, Cap'n Proto, Cassandra CQL, Cedar, Ceylon, CFEngine3, cfstatement, ChaiScript, Chapel, Cheetah, Clojure, CMake, COBOL, CoffeeScript, Common Lisp, Coq, Core, Crystal, CSS, CSV, CUE, Cython | D | D, Dart, Dax, Desktop file, Devicetree, Diff, Django/Jinja, dns, Docker, DTD, Dylan | E | EBNF, Elixir, Elm, EmacsLisp, ERB, Erlang | F | Factor, Fennel, Fish, Forth, Fortran, FortranFixed, FSharp | G | Garden, GAS, GDScript, GDScript3, Gemfile.lock, Gemtext, Genshi, Genshi HTML, Genshi Text, Gettext, Gherkin, Gleam, GLSL, Gnuplot, Go, Go HTML Template, Go Template, Go Text Template, GraphQL, Groff, Groovy | H | Handlebars, Hare, Haskell, Haxe, Hexdump, HLB, HLSL, HolyC, HTML, HTTP, Hurl, Hy, Hyprlang | I | Idris, Igor, INI, Io, ISCdhcpd | J | J, Janet, Java, JavaScript, JQ, JSON, JSONata, Jsonnet, Julia, Jungle | K | Kakoune, KDL, Kotlin | L | Lateralus, Lean4, Lighttpd configuration file, LilyPond, LLVM, lox, Lua, Luau | M | Makefile, Mako, markdown, Markless, Mason, Materialize SQL dialect, Mathematica, Matlab, MCFunction, Meson, Metal, microcad, MiniZinc, MLIR, Modelica, Modula-2, Mojo, MonkeyC, MoonBit, MoonScript, MorrowindScript, Myghty, MySQL | N | NASM, Natural, NDISASM, Newspeak, Nginx configuration file, Nim, Nix, NSIS, Nu | O | Objective-C, ObjectPascal, OCaml, Octave, Odin, OnesEnterprise, OpenEdge ABL, OpenSCAD, Org Mode | P | PacmanConf, Perl, PHP, PHTML, Pig, PkgConfig, PL/pgSQL, plaintext, Plutus Core, Pony, PostgreSQL SQL dialect, PostScript, POVRay, PowerQuery, PowerShell, Prolog, Promela, PromQL, properties, Protocol Buffer, Protocol Buffer Text Format, PRQL, PSL, Puppet, Python, Python 2 | Q | QBasic, QML | R | R, Racket, Ragel, Raku, react, ReasonML, reg, Rego, reStructuredText, Rexx, RGBDS Assembly, Ring, RPGLE, RPMSpec, Ruby, Rust | S | SAS, Sass, Scala, scdoc, Scheme, Scilab, SCSS, Sed, Sieve, Smali, Smalltalk, Smarty, SNBT, Snobol, Solidity, SourcePawn, Spade, SPARQL, SQL, SquidConf, Standard ML, stas, Stylus, Svelte, Swift, SYSTEMD, systemverilog | T | TableGen, Tal, TASM, Tcl, Tcsh, Templ, Termcap, Terminfo, Terraform, TeX, Thrift, TOML, TradingView, Transact-SQL, Turing, Turtle, Twig, TypeScript, TypoScript, TypoScriptCssData, TypoScriptHtmlData, Typst | U | ucode | V | V, V shell, Vala, VB.net, verilog, VHDL, VHS, VimL, vue | W | WDTE, WebAssembly Text Format, WebGPU Shading Language, WebVTT, Whiley | X | XML, Xorg | Y | YAML, YAML+Jinja, YANG | Z | Z80 Assembly, Zed, Zig _I will attempt to keep this section up to date, but an authoritative list can be displayed with `chroma --list`._ ## Try it Try out various languages and styles on the [Chroma Playground](https://swapoff.org/chroma/playground/). ## Using the library This is version 2 of Chroma, use the import path: ```go import "github.com/alecthomas/chroma/v3" ``` Chroma, like Pygments, has the concepts of [lexers](https://github.com/alecthomas/chroma/tree/master/lexers), [formatters](https://github.com/alecthomas/chroma/tree/master/formatters) and [styles](https://github.com/alecthomas/chroma/tree/master/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 A convenience function exists that can be used to simply format some source text, without any effort: ```go err := quick.Highlight(os.Stdout, someSourceCode, "go", "html", "monokai") ``` ### Identifying the language 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 lexer := lexers.Match("foo.go") ``` 2. Explicitly specify the language by its Chroma syntax ID (a full list is available from `lexers.Names()`). ```go lexer := lexers.Get("go") ``` 3. Detect the language from its content. ```go 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. ```go 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: ```go lexer = chroma.Coalesce(lexer) ``` ### Formatting the output Once a language is identified you will need to pick a formatter and a style (theme). ```go 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: ```go contents, err := io.ReadAll(r) iterator, err := lexer.Tokenise(nil, string(contents)) ``` And finally, format the tokens from the iterator: ```go err := formatter.Format(w, style, iterator) ``` ### The HTML formatter 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 `` 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: ```go 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 ### Lexers Lexers are community maintained. Please use [Discussions](https://github.com/alecthomas/chroma/discussions/categories/-lexer-requests-and-bugs) for lexer requests and lexer highlighting bugs. See the [Pygments documentation](http://pygments.org/docs/lexerdevelopment/) 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: ```sh 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](https://github.com/alecthomas/chroma/blob/master/pygments-lexers.txt). ### Formatters 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 Chroma styles are defined in XML. The style entries use the [same syntax](http://pygments.org/docs/styles/) 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](https://github.com/alecthomas/chroma/tree/master/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: ```xml ``` 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](https://xyproto.github.io/splash/docs/). ## Command-line interface A command-line interface to Chroma is included. Binaries are available to install from [the releases page](https://github.com/alecthomas/chroma/releases). 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: ```shell 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](https://manpages.debian.org/lesspipe#USER_DEFINED_FILTERS); for that setup the `chroma` executable can be just symlinked to `~/.lessfilter`. ## Projects using Chroma * [`moor`](https://github.com/walles/moor) is a full-blown pager that colorizes its input using Chroma * [Hugo](https://gohugo.io/) is a static site generator that [uses Chroma for syntax highlighting code examples](https://gohugo.io/content-management/syntax-highlighting/) * [f4](https://github.com/unxed/f4) is asynchronious cross platform Far Manager clone in Go that uses Chroma for syntax highlighting in built-in editor ## Testing lexers If you edit some lexers and want to try it, open a shell in `cmd/chromad` and run: ```shell 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: ```shell go test ./lexers ``` When updating or adding a lexer, please add tests. See [lexers/README.md](lexers/README.md) for more. ## What's missing compared to Pygments? - 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) ## File: README.md > [!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](https://github.com/alecthomas/chroma/releases/tag/v3.0.0-alpha.1) release for migration details. # A general purpose syntax highlighter in pure Go [](https://pkg.go.dev/github.com/alecthomas/chroma/v3) [](https://github.com/alecthomas/chroma/actions/workflows/ci.yml) [](https://invite.slack.golangbridge.org/) 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](http://pygments.org/), and includes translators for Pygments lexers and styles. ## Table of Contents 1. [Supported languages](#supported-languages) 2. [Try it](#try-it) 3. [Using the library](#using-the-library) 1. [Quick start](#quick-start) 2. [Identifying the language](#identifying-the-language) 3. [Formatting the output](#formatting-the-output) 4. [The HTML formatter](#the-html-formatter) 4. [More detail](#more-detail) 1. [Lexers](#lexers) 2. [Formatters](#formatters) 3. [Styles](#styles) 5. [Command-line interface](#command-line-interface) 6. [Testing lexers](#testing-lexers) 7. [What's missing compared to Pygments?](#whats-missing-compared-to-pygments) ## Supported languages | Prefix | Language | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | A | ABAP, ABNF, ActionScript, ActionScript 3, Ada, Agda, AL, Alloy, AMPL, Angular2, ANTLR, ApacheConf, APL, AppleScript, ArangoDB AQL, Arduino, ArmAsm, Arturo, Astro, ATL, AutoHotkey, AutoIt, Awk | B | Ballerina, Bash, Bash Session, Batchfile, Beef, BibTeX, Bicep, BlitzBasic, BNF, BQN, Brainfuck | C | C, C#, C++, C3, Caddyfile, Caddyfile Directives, Cap'n Proto, Cassandra CQL, Cedar, Ceylon, CFEngine3, cfstatement, ChaiScript, Chapel, Cheetah, Clojure, CMake, COBOL, CoffeeScript, Common Lisp, Coq, Core, Crystal, CSS, CSV, CUE, Cython | D | D, Dart, Dax, Desktop file, Devicetree, Diff, Django/Jinja, dns, Docker, DTD, Dylan | E | EBNF, Elixir, Elm, EmacsLisp, ERB, Erlang | F | Factor, Fennel, Fish, Forth, Fortran, FortranFixed, FSharp | G | Garden, GAS, GDScript, GDScript3, Gemfile.lock, Gemtext, Genshi, Genshi HTML, Genshi Text, Gettext, Gherkin, Gleam, GLSL, Gnuplot, Go, Go HTML Template, Go Template, Go Text Template, GraphQL, Groff, Groovy | H | Handlebars, Hare, Haskell, Haxe, Hexdump, HLB, HLSL, HolyC, HTML, HTTP, Hurl, Hy, Hyprlang | I | Idris, Igor, INI, Io, ISCdhcpd | J | J, Janet, Java, JavaScript, JQ, JSON, JSONata, Jsonnet, Julia, Jungle | K | Kakoune, KDL, Kotlin | L | Lateralus, Lean4, Lighttpd configuration file, LilyPond, LLVM, lox, Lua, Luau | M | Makefile, Mako, markdown, Markless, Mason, Materialize SQL dialect, Mathematica, Matlab, MCFunction, Meson, Metal, microcad, MiniZinc, MLIR, Modelica, Modula-2, Mojo, MonkeyC, MoonBit, MoonScript, MorrowindScript, Myghty, MySQL | N | NASM, Natural, NDISASM, Newspeak, Nginx configuration file, Nim, Nix, NSIS, Nu | O | Objective-C, ObjectPascal, OCaml, Octave, Odin, OnesEnterprise, OpenEdge ABL, OpenSCAD, Org Mode | P | PacmanConf, Perl, PHP, PHTML, Pig, PkgConfig, PL/pgSQL, plaintext, Plutus Core, Pony, PostgreSQL SQL dialect, PostScript, POVRay, PowerQuery, PowerShell, Prolog, Promela, PromQL, properties, Protocol Buffer, Protocol Buffer Text Format, PRQL, PSL, Puppet, Python, Python 2 | Q | QBasic, QML | R | R, Racket, Ragel, Raku, react, ReasonML, reg, Rego, reStructuredText, Rexx, RGBDS Assembly, Ring, RPGLE, RPMSpec, Ruby, Rust | S | SAS, Sass, Scala, scdoc, Scheme, Scilab, SCSS, Sed, Sieve, Smali, Smalltalk, Smarty, SNBT, Snobol, Solidity, SourcePawn, Spade, SPARQL, SQL, SquidConf, Standard ML, stas, Stylus, Svelte, Swift, SYSTEMD, systemverilog | T | TableGen, Tal, TASM, Tcl, Tcsh, Templ, Termcap, Terminfo, Terraform, TeX, Thrift, TOML, TradingView, Transact-SQL, Turing, Turtle, Twig, TypeScript, TypoScript, TypoScriptCssData, TypoScriptHtmlData, Typst | U | ucode | V | V, V shell, Vala, VB.net, verilog, VHDL, VHS, VimL, vue | W | WDTE, WebAssembly Text Format, WebGPU Shading Language, WebVTT, Whiley | X | XML, Xorg | Y | YAML, YAML+Jinja, YANG | Z | Z80 Assembly, Zed, Zig _I will attempt to keep this section up to date, but an authoritative list can be displayed with `chroma --list`._ ## Try it Try out various languages and styles on the [Chroma Playground](https://swapoff.org/chroma/playground/). ## Using the library This is version 2 of Chroma, use the import path: ```go import "github.com/alecthomas/chroma/v3" ``` Chroma, like Pygments, has the concepts of [lexers](https://github.com/alecthomas/chroma/tree/master/lexers), [formatters](https://github.com/alecthomas/chroma/tree/master/formatters) and [styles](https://github.com/alecthomas/chroma/tree/master/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 A convenience function exists that can be used to simply format some source text, without any effort: ```go err := quick.Highlight(os.Stdout, someSourceCode, "go", "html", "monokai") ``` ### Identifying the language 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 lexer := lexers.Match("foo.go") ``` 2. Explicitly specify the language by its Chroma syntax ID (a full list is available from `lexers.Names()`). ```go lexer := lexers.Get("go") ``` 3. Detect the language from its content. ```go 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. ```go 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: ```go lexer = chroma.Coalesce(lexer) ``` ### Formatting the output Once a language is identified you will need to pick a formatter and a style (theme). ```go 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: ```go contents, err := io.ReadAll(r) iterator, err := lexer.Tokenise(nil, string(contents)) ``` And finally, format the tokens from the iterator: ```go err := formatter.Format(w, style, iterator) ``` ### The HTML formatter 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 `` 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: ```go 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 ### Lexers Lexers are community maintained. Please use [Discussions](https://github.com/alecthomas/chroma/discussions/categories/-lexer-requests-and-bugs) for lexer requests and lexer highlighting bugs. See the [Pygments documentation](http://pygments.org/docs/lexerdevelopment/) 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: ```sh 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](https://github.com/alecthomas/chroma/blob/master/pygments-lexers.txt). ### Formatters 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 Chroma styles are defined in XML. The style entries use the [same syntax](http://pygments.org/docs/styles/) 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](https://github.com/alecthomas/chroma/tree/master/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: ```xml ``` 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](https://xyproto.github.io/splash/docs/). ## Command-line interface A command-line interface to Chroma is included. Binaries are available to install from [the releases page](https://github.com/alecthomas/chroma/releases). 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: ```shell 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](https://manpages.debian.org/lesspipe#USER_DEFINED_FILTERS); for that setup the `chroma` executable can be just symlinked to `~/.lessfilter`. ## Projects using Chroma * [`moor`](https://github.com/walles/moor) is a full-blown pager that colorizes its input using Chroma * [Hugo](https://gohugo.io/) is a static site generator that [uses Chroma for syntax highlighting code examples](https://gohugo.io/content-management/syntax-highlighting/) * [f4](https://github.com/unxed/f4) is asynchronious cross platform Far Manager clone in Go that uses Chroma for syntax highlighting in built-in editor ## Testing lexers If you edit some lexers and want to try it, open a shell in `cmd/chromad` and run: ```shell 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: ```shell go test ./lexers ``` When updating or adding a lexer, please add tests. See [lexers/README.md](lexers/README.md) for more. ## What's missing compared to Pygments? - 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 # Chroma lexers All lexers in Chroma should now be defined in XML unless they require custom code. ## Lexer tests The tests in this directory feed a known input `testdata/.actual` into the parser for `` and check that its output matches `.expected`. It is also possible to perform several tests on a same parser ``, by placing know inputs `*.actual` into a directory `testdata//`. ### Running the tests Run the tests as normal: ```go go test ./lexers ``` ### Update existing tests 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: ```go 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](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line) for more. + In PowerShell, you can use the `$env:RECORD = 'true'` command for that. See [this article](https://mcpmag.com/articles/2019/03/28/environment-variables-in-powershell.aspx) for more. + You can also make a persistent environment variable by hand in the Windows computer settings. See [this article](https://www.computerhope.com/issues/ch000549.htm) 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