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.

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

These are the available keys and descriptions for the file.

Key	Description
`name`	The name of the language
`scope`	A 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-regex`	regex 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-types`	The filetypes of the language, for example `["yml", "yaml"]`. Extensions and full file names are supported.
`shebangs`	The interpreters from the shebang line, for example `["sh", "bash"]`
`roots`	A set of marker files to look for when trying to find the workspace root. For example `Cargo.lock`, `yarn.lock`
`auto-format`	Whether to autoformat this language when saving
`diagnostic-severity`	Minimal severity of diagnostic for it to be displayed. (Allowed values: `Error`, `Warning`, `Info`, `Hint`)
`comment-token`	The token to use as a comment-token
`indent`	The indent to use. Has sub keys `tab-width` and `unit`
`language-server`	The Language Server to run. Has sub keys `command` and `args`
`config`	Language Server configuration
`grammar`	The tree-sitter grammar to use (defaults to the value of `name`)

When adding a new language or Language Server configuration for an existing language, run cargo xtask docgen to add the new configuration to the Language Support docs before creating a pull request. When adding a Language Server configuration, be sure to update the Language Server Wiki with installation notes.

Grammar configuration

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

[[grammar]]
name = "mylang"
source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" }

Grammar configuration takes these keys:

Key	Description
`name`	The name of the tree-sitter grammar
`source`	The 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:

Key	Description
`git`	A git remote URL from which the grammar should be cloned
`rev`	The revision (commit hash or tag) which should be fetched
`subpath`	A 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.

Queries

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