Unnamed repository; edit this file 'description' to name the repository.
Diffstat (limited to 'book/src/guides/adding_languages.md')
| -rw-r--r-- | book/src/guides/adding_languages.md | 74 |
1 files changed, 35 insertions, 39 deletions
diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md index f9824215..6598b9bf 100644 --- a/book/src/guides/adding_languages.md +++ b/book/src/guides/adding_languages.md @@ -1,49 +1,45 @@ -## Adding new languages to Helix - -In order to add a new language to Helix, you will need to follow the steps -below. +# Adding languages ## Language configuration -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. - A new language server can be added by extending the `[language-server]` table in the same file. -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. +To add a new language, you need to add a `[[language]]` entry to the +`languages.toml` (see the [language configuration section]). -> 💡 If you are adding a new Language Server configuration, make sure to update -> the -> [Language Server Wiki](https://github.com/helix-editor/helix/wiki/Language-Server-Configurations) -> with the installation instructions. +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][lang-support] docs before creating a pull request. +When adding a Language Server configuration, be sure to update the +[Language Server Wiki][install-lsp-wiki] with installation notes. ## Grammar configuration -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`. +If a tree-sitter grammar is available for the language, add a new `[[grammar]]` +entry to `languages.toml`. + +You may use the `source.path` key rather than `source.git` with an absolute path +to a locally available grammar for testing, but switch to `source.git` before +submitting a pull request. ## Queries -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/3-syntax-highlighting.html#highlights) - for more information on writing queries. -4. A list of highlight captures can be found [on the themes page](https://docs.helix-editor.com/themes.html#scopes). - -## 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`. -- 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. +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](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries) +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][neovim-query-precedence] 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` + +[language configuration section]: ../languages.md +[neovim-query-precedence]: https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090 +[install-lsp-wiki]: https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers +[lang-support]: ../lang-support.md |