2023-03-06 17:27:17 +08:00
# Adding new languages to Helix
In order to add a new language to Helix, you will need to follow the steps
below.
2021-11-07 09:31:12 +08:00
2022-02-15 07:23:35 +08:00
## Language configuration
2021-11-07 09:31:12 +08:00
2023-03-06 17:27:17 +08:00
1. Add a new `[[language]]` entry in the `languages.toml` file and provide the
necessary configuration for the new language. For more information on
language configuration, refer to the
[language configuration section ](../languages.md ) of the documentation.
2022-05-24 00:10:48 +08:00
A new language server can be added by extending the `[language-server]` table in the same file.
2023-03-06 17:27:17 +08:00
2. If you are adding a new language or updating an existing language server
configuration, run the command `cargo xtask docgen` to update the
[Language Support ](../lang-support.md ) documentation.
2022-02-15 07:23:35 +08:00
2023-03-06 17:27:17 +08:00
> 💡 If you are adding a new Language Server configuration, make sure to update
> the
> [Language Server Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
> with the installation instructions.
2022-04-09 14:47:32 +08:00
2022-02-15 07:23:35 +08:00
## Grammar configuration
2023-03-06 17:27:17 +08:00
1. If a tree-sitter grammar is available for the new language, add a new
`[[grammar]]` entry to the `languages.toml` file.
2. If you are testing the grammar locally, you can use the `source.path` key
with an absolute path to the grammar. However, before submitting a pull
request, make sure to switch to using `source.git` .
2021-11-07 09:31:12 +08:00
## Queries
2023-03-06 17:27:17 +08:00
1. In order to provide syntax highlighting and indentation for the new language,
you will need to add queries.
2. Create a new directory for the language with the path
`runtime/queries/<name>/` .
3. Refer to the
[tree-sitter website ](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries )
for more information on writing queries.
2023-12-16 12:29:26 +08:00
4. A list of highlight captures can be found [on the themes page ](https://docs.helix-editor.com/themes.html#scopes ).
2023-03-06 17:27:17 +08:00
> 💡 In Helix, the first matching query takes precedence when evaluating
> queries, which is different from other editors such as Neovim where the last
> matching query supersedes the ones before it. See
> [this issue](https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090)
> for an example.
## Common issues
- If you encounter errors when running Helix after switching branches, you may
need to update the tree-sitter grammars. Run the command `hx --grammar fetch`
to fetch the grammars and `hx --grammar build` to build any out-of-date
grammars.
- If a parser is causing a segfault, or you want to remove it, make sure to
remove the compiled parser located at `runtime/grammars/<name>.so` .
2023-12-16 12:29:26 +08:00
- If you are attempting to add queries and Helix is unable to locate them, ensure that the environment variable `HELIX_RUNTIME` is set to the location of the `runtime` folder you're developing in.
