How Superfile Implements Code Syntax Highlighting with Chroma

Superfile implements code syntax highlighting in its file preview pane by leveraging the Chroma lexer library to detect file types and the ansichroma wrapper to convert tokens into ANSI escape sequences for terminal display.

The open-source terminal file manager superfile integrates the Chroma syntax highlighting library to render colorized source code previews directly in the UI. This implementation combines file type detection, configurable rendering backends, and terminal-friendly ANSI output. Understanding how superfile uses Chroma reveals a lightweight, pure-Go approach to code syntax highlighting without external dependencies.

How Chroma Syntax Highlighting Works in Superfile

The implementation centers on a pipeline that transforms raw file content into colorized terminal output. The workflow resides primarily in src/internal/ui/preview/render.go and relies on three core components: the Chroma lexer registry, a custom ansichroma wrapper, and superfile's configuration system.

File Type Detection with Chroma Lexers

When a user selects a text file in the preview pane, superfile determines the appropriate syntax highlighter using Chroma's lexer matching system. The renderTextPreview function calls lexers.Match(filepath.Base(itemPath)) to identify a lexer based on the file extension.

This operation occurs at lines 99-101 in src/internal/ui/preview/render.go:

format := lexers.Match(filepath.Base(itemPath))

If the filename matches a known pattern—such as .go, .py, or .md—Chroma returns a corresponding lexer configuration. The lexer name (format.Config().Name) becomes a critical parameter for the highlighting engine.

The ansichroma Wrapper for Terminal Output

Superfile does not use Chroma's HTML or native formatters directly. Instead, it delegates token-to-text conversion to ansichroma, a thin wrapper package that translates Chroma tokens into ANSI escape codes suitable for terminal emulators.

The highlighter invocation occurs around lines 31-33 in the preview renderer:

fileContent, err = ansichroma.HightlightString(
    fileContent,
    format.Config().Name,
    common.Theme.CodeSyntaxHighlightTheme,
    bg,
)

This function signature accepts the raw file content, the determined lexer name, the active theme from superfile's configuration, and an optional background color. The ansichroma package (github.com/yorukot/ansichroma) handles the tokenization and color mapping, returning a string embedded with ANSI sequences that the terminal interprets as colored text.

Reading File Content Within Limits

Before highlighting occurs, superfile respects display constraints using utils.ReadFileContent. This utility, defined in src/pkg/utils/file_preview/utils.go, loads the file content while truncating it to the preview pane's width and height limits. This prevents processing entire multi-megabyte files when only a viewportful of content is visible.

Configuring the Highlighting Backend

Superfile offers flexibility through the CodePreviewer configuration option defined in src/internal/common/config_type.go (lines 96-98). This setting determines whether the built-in Chroma pipeline or an external tool renders the preview.

• Built-in Chroma (default): When Config.CodePreviewer is empty, superfile uses the ansichroma.HightlightString method described above. This approach requires no external binaries and operates entirely within the Go runtime.

• External Bat: If configured to use bat, superfile shells out to the external bat command via getBatSyntaxHighlightedContent, piping file content through the command-line tool and capturing its ANSI output.

The default configuration prioritizes the pure-Go implementation, ensuring functionality across environments without requiring the installation of bat.

Complete Implementation Flow

The following simplified example illustrates the complete rendering flow from src/internal/ui/preview/render.go:

func (m *Model) renderTextPreview(r *rendering.Renderer, itemPath string,
    previewWidth, previewHeight int) string {

    // Detect lexer based on file extension
    format := lexers.Match(filepath.Base(itemPath))
    
    // Load content with size constraints
    fileContent, err := utils.ReadFileContent(itemPath, previewWidth, previewHeight)
    if err != nil {
        return err.Error()
    }

    // Apply syntax highlighting if lexer found
    if format != nil {
        bg := ""
        if !common.Config.TransparentBackground {
            bg = common.Theme.FilePanelBG
        }
        
        fileContent, err = ansichroma.HightlightString(
            fileContent,
            format.Config().Name,
            common.Theme.CodeSyntaxHighlightTheme,
            bg,
        )
        if err != nil {
            // Fallback to plain text on error
        }
    }

    r.AddLines(fileContent)
    return r.Render()
}

This workflow demonstrates how superfile balances performance—by limiting file reads—with rich formatting through Chroma's extensive language support.

Summary

• Superfile uses Chroma lexers (github.com/alecthomas/chroma/v2/lexers) to detect file types based on extensions in src/internal/ui/preview/render.go.
• The ansichroma package (github.com/yorukot/ansichroma) converts Chroma tokens into ANSI escape sequences for terminal display.
• Configuration in src/internal/common/config_type.go allows toggling between built-in Chroma highlighting and external bat rendering.
• File content is read with size constraints via utils.ReadFileContent to optimize performance for large files.
• The theme and background colors integrate with superfile's existing UI theming system through common.Theme.CodeSyntaxHighlightTheme.

Frequently Asked Questions

What library does superfile use for syntax highlighting?

Superfile uses the Chroma library (github.com/alecthomas/chroma/v2) for tokenization and lexing, wrapped by the custom ansichroma package (github.com/yorukot/ansichroma) to generate ANSI escape codes for terminal output. This combination provides support for hundreds of programming languages without requiring external dependencies by default.

How does superfile determine which language to highlight for a file?

Superfile determines the language by calling lexers.Match(filepath.Base(itemPath)) from the Chroma lexer package, passing the filename (including extension). Chroma's registry matches the extension against its supported languages and returns the appropriate lexer configuration, which superfile then uses to select the correct syntax rules.

Can I use an external highlighter instead of Chroma in superfile?

Yes. Superfile supports using the external bat command for syntax highlighting through the CodePreviewer configuration option in src/internal/common/config_type.go. When this option is configured, superfile executes bat with appropriate flags and pipes the file content through it, capturing the ANSI-colored output for display in the preview pane.

Where is the syntax highlighting logic located in the superfile source code?

The core highlighting logic resides in src/internal/ui/preview/render.go, specifically within the renderTextPreview function (around lines 99-101 for lexer detection and lines 31-33 for the ansichroma call). Configuration options are defined in src/internal/common/config_type.go, while file reading utilities are in src/pkg/utils/file_preview/utils.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}