git.iko.soy/helix
on aef00a3 help sign in
helix/book/src/guides/adding_languages.md
45 lines 2.1 kB history raw
1# Adding languages
3## Language configuration
5To add a new language, you need to add a `[[language]]` entry to the
6`languages.toml` (see the [language configuration section]).
8When adding a new language or Language Server configuration for an existing
9language, run `cargo xtask docgen` to add the new configuration to the
10[Language Support][lang-support] docs before creating a pull request.
11When adding a Language Server configuration, be sure to update the
12[Language Server Wiki][install-lsp-wiki] with installation notes.
14## Grammar configuration
16If a tree-sitter grammar is available for the language, add a new `[[grammar]]`
17entry to `languages.toml`.
19You may use the `source.path` key rather than `source.git` with an absolute path
20to a locally available grammar for testing, but switch to `source.git` before
21submitting a pull request.
23## Queries
25For a language to have syntax-highlighting and indentation among
26other things, you have to add queries. Add a directory for your
27language with the path `runtime/queries/<name>/`. The tree-sitter
28[website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries)
29gives more info on how to write queries.
31> NOTE: When evaluating queries, the first matching query takes
32precedence, which is different from other editors like neovim where
33the last matching query supersedes the ones before it. See
34[this issue][neovim-query-precedence] for an example.
36## Common Issues
38- 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.
40- If a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in `runtime/grammar/<name>.so`
42[language configuration section]: ../languages.md
43[neovim-query-precedence]: https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090
44[install-lsp-wiki]: https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers
45[lang-support]: ../lang-support.md