Chroma

Chroma is a pure-Go syntax highlighter modeled directly on Pygments, reusing its lexer and style concepts so that Chroma can import Pygments-defined lexers and themes with a conversion script. It tokenizes source text with a registry of over 200 language lexers and renders the result through pluggable formatters, making it the engine behind syntax highlighting in tools like Hugo, Glamour, and many static site generators and terminal applications written in Go.

The library separates concerns cleanly into lexers (tokenize text into a stream), styles (map token types to colors, defined in Pygments-compatible XML), and formatters (render tokens using a style into HTML, ANSI terminal escapes, SVG, or JSON). A quick.Highlight convenience function chains all three together with sensible fallbacks when the caller doesn’t know or care about the specific lexer, formatter, or style to use.

What You Get

• A registry of 200+ language lexers selectable by name, file extension, MIME type, or content-based analysis (lexers.Match, lexers.Get, lexers.Analyse)
• Formatters for HTML (with class-based or inline-style CSS, line numbers, line highlighting, and light/dark mode class scoping), ANSI 8/256/true-color terminal output, SVG, and raw JSON tokens
• A large catalog of Pygments-compatible XML styles/themes (Monokai, Dracula, Nord, Catppuccin, GitHub, Solarized, and dozens more) plus the ability to define custom styles programmatically
• A quick.Highlight one-call API that auto-detects the lexer from content when none is specified and falls back to sane defaults for lexer, formatter, and style
• A chroma CLI and _tools/pygments2chroma_xml.py script for listing available lexers/styles and converting new Pygments lexers into Chroma’s XML format
• A token-coalescing decorator (chroma.Coalesce) that merges consecutive same-type tokens to reduce output verbosity from chatty lexers

Common Use Cases

• Rendering syntax-highlighted code blocks in static site generators and documentation tools (Chroma is the highlighter behind Hugo’s built-in code fences)
• Adding colorized code output to terminal applications and CLI tools via the ANSI/true-color formatters
• Generating highlighted HTML snippets for blog engines, wikis, or CMS platforms that need to embed code samples
• Building developer tools that need language auto-detection for pasted or uploaded source files without the caller specifying a language
• Exporting highlighted code as SVG for embedding in documentation images or presentations

Under The Hood

Architecture Chroma is organized around three small interfaces wired together by a registry: a Lexer (Config() + Tokenise() returning an iter.Seq[Token]), a Formatter (Format(w, style, iterator)), and a Style (a Pygments-style XML-backed color table). The LexerRegistry in registry.go indexes lexers by name, alias, filename glob, and MIME type, and Analyse scores arbitrary text against every registered lexer’s heuristics to pick the best match when the caller doesn’t know the language. The quick package composes these three lookups (lexer → formatter → style, each falling back to a sane default) into a single Highlight call, and a Coalesce decorator wraps any lexer to merge runs of same-type tokens before they reach the formatter — a clean example of the decorator pattern applied to an iterator pipeline.

Tech Stack Written in modern Go using the iter.Seq[Token] standard-library iterator type for lexer output, with style and lexer definitions expressed as embedded XML mirroring Pygments’ own format. Dependencies are minimal and purpose-built: alecthomas/repr for debug representations, dlclark/regexp2 for regex features Go’s native regexp package doesn’t support (needed to faithfully port Pygments’ regex-heavy lexers), and alecthomas/assert for testing. The CLI (cmd/chroma) adds alecthomas/kong for argument parsing and terminal color-capability detection via mattn/go-isatty/go-colorable. A companion chromad web playground compiles a WASM build of the library for browser-side highlighting.

Code Quality The repository ships extensive _test.go files alongside nearly every core source file (lexer, style, coalesce, delegate, mutators, regexp, remap, xml, colour), uses table-driven tests with the alecthomas/assert library, and enforces a strict golangci-lint configuration with default: all linters enabled (a small, deliberate set disabled). CI runs on GitHub Actions with a dedicated workflow, and an AGENTS.md file codifies contribution conventions, including a strict comment-discipline rule that discourages comments explaining implementation details. Error handling is idiomatic Go (explicit error returns, no swallowed errors observed in the core tokenizer/formatter paths).

What Makes It Unique Chroma’s defining choice is deliberately mirroring Pygments’ data model and XML style format rather than inventing its own, which lets the project reuse Pygments’ large corpus of community-maintained lexers and themes via an automated conversion script (pygments2chroma_xml.py) instead of hand-porting each one. Combined with a formatter-agnostic token stream (the same tokenized output drives HTML, ANSI terminal, SVG, and JSON renderers) and a WASM-compiled browser playground built from the same core, this gives Chroma unusually broad output-format coverage for a single Go highlighting library.