Adding new languages to Helix

In order to add a new language to Helix, you will need to follow the steps below.

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 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 documentation.

💡 If you are adding a new Language Server configuration, make sure to update the Language Server Wiki with the installation instructions.

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.

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 for more information on writing queries.

4. The highlight captures (@function, @type, …) and how they resolve are documented on the themes page: match the most specific scope that fits, capture the leaf node you mean, and remember that the last matching pattern (and the innermost node) wins.

5. Helix loads several query files from that directory; only highlights.scm is required:

   File	Purpose	Guide
   highlights.scm	syntax highlighting	highlights.md
   injections.scm	embed other languages in regions (strings, code fences)	injection.md
   indents.scm	indentation	indent.md
   textobjects.scm	textobjects and navigation (mif, ]f, …)	textobject.md
   locals.scm	scope tracking so locals highlight distinctly	locals.md
   tags.scm	document/workspace symbol pickers	tags.md
   rainbows.scm	rainbow brackets	rainbow_bracket_queries.md

   A query file may reuse another language’s with ; inherits: <lang> on the first line. Run cargo xtask query-check [language] to check that the queries are valid against the grammar.

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.
• Validate queries with cargo xtask query-check [language] (every query file must compile against the grammar). highlight-check and indent-check additionally run the real highlighter and indenter over the test fixtures catch mistakes.