How to Configure File Preview with Syntax Highlighting in Superfile: Chroma vs bat

Set code_previewer = "" (empty string) in ~/.config/superfile/config.toml to use the built-in Chroma library, or set code_previewer = "bat" to delegate syntax highlighting to the external bat command-line tool.

Superfile, the modern terminal file manager from the yorukot/superfile repository, provides a split-pane preview feature that renders source code with syntax highlighting. You can configure which rendering engine handles this highlighting by modifying a single configuration field, choosing between the integrated Chroma library or the external bat tool based on your theming preferences and environment.

Configuration Options

Superfile selects its highlighting engine based on the code_previewer field defined in the configuration struct at src/internal/common/config_type.go. This setting accepts specific string values that determine whether to use internal or external rendering.

Built-in Chroma Highlighter (Default)

When code_previewer = "" (empty string or omitted), Superfile uses its internal highlighter powered by the github.com/alecthomas/chroma/v2 library. This requires no external dependencies and works immediately after installation.

External bat Tool

When code_previewer = "bat", Superfile delegates highlighting to the bat program. This option provides the same color schemes and file-type detection available in standalone bat, but requires installing bat and ensuring it exists in your system $PATH.

Implementation Details

The selection logic resides in src/internal/ui/preview/render.go, where Superfile checks the configuration value at runtime:

if common.Config.CodePreviewer == "bat" {
    // Try to run `bat` – if it fails, show an informative message
    if !batInstalled {
        return r.AddLines(common.FilePreviewBatNotInstalledText).Render()
    }
    // …invoke bat and pipe its output…
} else {
    // Fallback to Chroma via ansichroma
    fileContent, err = ansichroma.HightlightString(
        fileContent, format.Config().Name, /* style options */)
}

When bat is selected but not found, the UI displays the FilePreviewBatNotInstalledText message rather than failing silently. Additional terminal capability utilities used by the preview system are provided in src/pkg/file_preview/utils.go.

Step-by-Step Configuration Guide

Follow these steps to switch between rendering engines:

1. Open the configuration file at ~/.config/superfile/config.toml (default location).

2. Set the code_previewer value under the [default] section:

   For Chroma (built-in):

   [default]
   code_previewer = ""

   For bat (external):

   [default]
   code_previewer = "bat"

3. Install bat (if required):

   # macOS (Homebrew)
   
   brew install bat
   
   # Debian/Ubuntu
   
   sudo apt-get install bat
   
   # Arch Linux
   
   sudo pacman -S bat

4. Restart Superfile to apply the configuration changes.

5. Verify by opening a source code file in the preview panel. The syntax colors should now reflect your selected engine's theme.

Key Source Files

File	Purpose
src/internal/common/config_type.go	Defines the CodePreviewer configuration field and accepted values.
src/internal/ui/preview/render.go	Contains runtime logic that switches between Chroma and bat based on configuration.
src/pkg/file_preview/utils.go	Provides helper utilities for terminal capabilities used by the preview renderer.

Summary

• Chroma (code_previewer = ""): Uses the internal github.com/alecthomas/chroma/v2 library via the ansichroma wrapper; requires no external setup.
• bat (code_previewer = "bat"): Delegates to external bat binary; requires installation and $PATH availability, but provides consistent theming with your bat configuration.
• Configuration changes take effect immediately after restarting Superfile.
• Missing bat binaries trigger a graceful error message in the preview panel rather than a crash.

Frequently Asked Questions

What happens if I configure code_previewer = "bat" without installing bat?

Superfile detects the missing binary and displays a "bat not installed" message in the preview panel. This check occurs in src/internal/ui/preview/render.go before attempting execution, preventing crashes and informing you of the missing dependency.

Can I customize themes when using the built-in Chroma option?

The built-in renderer passes style options through the ansichroma.HightlightString function. While Superfile provides sensible defaults, customizing themes currently requires modifying the parameters passed to this function in the source code, as the TOML configuration does not expose Chroma style options directly.

Does the bat option support all file types that standalone bat recognizes?

Yes. When code_previewer = "bat" is set, Superfile pipes file contents through the bat command, inheriting bat's automatic language detection and syntax definitions. Any language recognized by your installed bat version will render correctly in the preview pane.

Where is the configuration file located on Windows?

On Windows, Superfile looks for config.toml in %APPDATA%\superfile\ or %LOCALAPPDATA%\superfile\ depending on the build. The code_previewer setting functions identically across all supported platforms.

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