Adding languages

Language configuration

To add a new language, you need to add a language entry to the languages.toml found in the root of the repository; this languages.toml file is included at compilation time, and is distinct from the languages.toml file in the user's configuration directory.

name = "mylang"
scope = "scope.mylang"
injection-regex = "^mylang$"
file-types = ["mylang", "myl"]
comment-token = "#"
indent = { tab-width = 2, unit = "  " }

These are the available keys and descriptions for the file.

nameThe name of the language
scopeA string like source.js that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually source.<name> or text.<name> in case of markup languages
injection-regexregex pattern that will be tested against a language name in order to determine whether this language should be used for a potential language injection site.
file-typesThe filetypes of the language, for example ["yml", "yaml"]. Extensions and full file names are supported.
shebangsThe interpreters from the shebang line, for example ["sh", "bash"]
rootsA set of marker files to look for when trying to find the workspace root. For example Cargo.lock, yarn.lock
auto-formatWhether to autoformat this language when saving
diagnostic-severityMinimal severity of diagnostic for it to be displayed. (Allowed values: Error, Warning, Info, Hint)
comment-tokenThe token to use as a comment-token
indentThe indent to use. Has sub keys tab-width and unit
configLanguage server configuration
grammarThe tree-sitter grammar to use (defaults to the value of name)

Grammar configuration

If a tree-sitter grammar is available for the language, add a new grammar entry to languages.toml.

name = "mylang"
source = { git = "", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" }

Grammar configuration takes these keys:

nameThe name of the tree-sitter grammar
sourceThe method of fetching the grammar - a table with a schema defined below

Where source is a table with either these keys when using a grammar from a git repository:

gitA git remote URL from which the grammar should be cloned
revThe revision (commit hash or tag) which should be fetched
subpathA path within the grammar directory which should be built. Some grammar repositories host multiple grammars (for example tree-sitter-typescript and tree-sitter-ocaml) in subdirectories. This key is used to point hx --grammar build to the correct path for compilation. When omitted, the root of repository is used

Or a path key with an absolute path to a locally available grammar directory.


For a language to have syntax-highlighting and indentation among other things, you have to add queries. Add a directory for your language with the path runtime/queries/<name>/. The tree-sitter website gives more info on how to write queries.

NOTE: When evaluating queries, the first matching query takes precedence, which is different from other editors like neovim where the last matching query supersedes the ones before it. See this issue for an example.

Common Issues

  • If you get errors when running after switching branches, you may have to update the tree-sitter grammars. Run hx --grammar fetch to fetch the grammars and hx --grammar build to build any out-of-date grammars.

  • If a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in runtime/grammar/<name>.so

  • The indents query is indents.toml, not indents.scm. See this issue for more information.