From 827c9ac50694240b91fa43ae3457732c526b1bb4 Mon Sep 17 00:00:00 2001 From: omentic Date: Wed, 1 Nov 2023 04:44:44 +0000 Subject: deploy: 9663740245e2c18e160f6563d2f114f59d27b7c9 --- guides/adding_languages.html | 289 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 guides/adding_languages.html (limited to 'guides/adding_languages.html') diff --git a/guides/adding_languages.html b/guides/adding_languages.html new file mode 100644 index 00000000..13781aba --- /dev/null +++ b/guides/adding_languages.html @@ -0,0 +1,289 @@ + + + + + + Adding languages + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

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. +
  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.
    3. +
+
+

💡 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. +
  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.
    3. +
+

Queries

+
    +
  1. In order to provide syntax highlighting and indentation for the new language, +you will need to add queries.
    2. +
  2. Create a new directory for the language with the path +runtime/queries/<name>/.
    3. +
  3. Refer to the +tree-sitter website +for more information on writing queries.
    4. +
  4. A list of highlight captures can be found on the themes page.
    5. +
+
+

💡 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 +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.
    • +
  • 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.
    • +
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + -- cgit v1.2.3-70-g09d2