Languages

Helix supports ~180 languages out of the box. Each is declared in languages.toml at the repo root.

File structure

# Language definitions
[[language]]
name = "rust"
scope = "source.rust"
file-types = ["rs"]
shebangs = []
roots = ["Cargo.toml", "Cargo.lock"]
auto-format = true
comment-tokens = ["//"]
block-comment-tokens = [{ start = "/*", end = "*/" }]
indent = { tab-width = 4, unit = "    " }
language-servers = [ "rust-analyzer" ]
formatter = { command = "rustfmt", args = ["--edition", "2021"] }

[language.debugger]
name = "lldb-vscode"
transport = "stdio"
command = "lldb-vscode"

# Tree-sitter grammars
[[grammar]]
name = "rust"
source = { git = "https://github.com/tree-sitter/tree-sitter-rust", rev = "..." }

# Language servers (referenced by language entries)
[language-server.rust-analyzer]
command = "rust-analyzer"
config = { check = { command = "clippy" } }

The schema is implemented in helix_core::syntax::config::Configuration (helix-core/src/syntax/config.rs). Every field has a Rust counterpart.

Important fields per language

Field	Purpose
name	Language ID. Must be unique.
scope	Tree-sitter scope name (source.<lang>). Used for theming and injections.
file-types	Match by extension (string) or path glob ({ glob = "..." }).
shebangs	Match by #! interpreter on the first line.
injection-regex	Match by regex on file content (used for embedded blocks).
roots	File names that mark the workspace root (used for LSP).
auto-format	Format on save when a formatter or LSP supports it.
comment-tokens / block-comment-tokens	Used by Ctrl-c toggle commenting.
indent	{ tab-width, unit } — unit is "\t" or N spaces.
language-servers	Names from [language-server.*] blocks. Multiple are allowed.
formatter	External command run on :format and on save.
text-width	Per-language override of editor.text-width.
soft-wrap	Per-language soft-wrap override.
rulers	Per-language column rulers.
auto-pairs	Per-language auto-pair table override.
language-id	LSP language ID (if it differs from name).
workspace-lsp-roots	Extra workspace roots beyond roots.
persistent-diagnostic-sources	Diagnostic providers that should not be cleared on document close.

Per-language servers

[[language]]
name = "rust"
language-servers = [ "rust-analyzer", "scls" ]   # multiple servers per language

[language-server.scls]
command = "simple-completion-language-server"
only-features = ["completion"]

Each server can be feature-gated with only-features or except-features. The full list of features is in LanguageServerFeature in helix-core/src/syntax/config.rs:

format, goto-definition, goto-declaration, goto-type-definition, goto-reference, goto-implementation,
signature-help, hover, document-highlight, completion, code-action, workspace-command,
document-symbols, workspace-symbols, diagnostics, rename-symbol, inlay-hints,
document-colors, document-links, snippets

Tree-sitter grammars

[[grammar]]
name = "rust"
source = { git = "https://github.com/tree-sitter/tree-sitter-rust", rev = "abc1234" }

source can be:

• { git = URL, rev = COMMIT, subpath = "optional/dir" } — fetched by hx --grammar fetch.
• { path = "/local/path" } — for local development.

Pinning by commit hash (not tag/branch) is mandatory — it makes builds reproducible and lets cargo xtask query-check catch grammar API changes.

Workspace overrides

Workspace-local <repo>/.helix/languages.toml is merged onto the global config:

[[language]]
name = "rust"
language-servers = [ "rust-analyzer" ]   # replaces the global list
formatter = { command = "leptosfmt", args = ["--stdin"] }   # overrides

Tables merge per-key (depth 3 via helix_loader::merge_toml_values); arrays are replaced wholesale.

Validating

cargo xtask query-check rust       # validate runtime/queries/rust/*.scm
cargo xtask query-check            # all languages

CI runs the full validation. Adding a new language usually means:

1. Adding a [[language]] entry.
2. Adding the [[grammar]] entry with a pinned commit.
3. Adding runtime/queries/<name>/highlights.scm (and others as appropriate).
4. Running hx --grammar fetch && hx --grammar build to verify the build.
5. Running cargo xtask query-check to validate the queries.
6. Running cargo xtask docgen to update the generated language support table.

Auto-generated language support

The full feature matrix per language is generated:

cargo xtask docgen
cat book/src/generated/lang-support.md

This is the canonical "is language X supported" reference.

See also

• features/syntax-highlighting — tree-sitter pipeline.
• features/language-servers — LSP integration.
• book/src/languages.md — user-facing documentation.