book/src/guides/adding_languages.md · helix

1# Adding languages

2

3## Language configuration

4

5To add a new language, you need to add a `language` entry to the

6[`languages.toml`][languages.toml] found in the root of the repository;

7this `languages.toml` file is included at compilation time, and is

8distinct from the `languages.toml` file in the user's [configuration

9directory](../configuration.md).

10

11```toml

12[[language]]

13name = "mylang"

14scope = "scope.mylang"

15injection-regex = "^mylang$"

16file-types = ["mylang", "myl"]

17comment-token = "#"

18indent = { tab-width = 2, unit = " " }

19language-server = { command = "mylang-lsp", args = ["--stdio"] }

20```

21

22These are the available keys and descriptions for the file.

23

24| Key | Description |

25| ---- | ----------- |

26| `name` | The name of the language |

27| `scope` | A string like `source.js` that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually `source.<name>` or `text.<name>` in case of markup languages |

28| `injection-regex` | regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential [language injection][treesitter-language-injection] site. |

29| `file-types` | The filetypes of the language, for example `["yml", "yaml"]`. Extensions and full file names are supported. |

30| `shebangs` | The interpreters from the shebang line, for example `["sh", "bash"]` |

31| `roots` | A set of marker files to look for when trying to find the workspace root. For example `Cargo.lock`, `yarn.lock` |

32| `auto-format` | Whether to autoformat this language when saving |

33| `diagnostic-severity` | Minimal severity of diagnostic for it to be displayed. (Allowed values: `Error`, `Warning`, `Info`, `Hint`) |

34| `comment-token` | The token to use as a comment-token |

35| `indent` | The indent to use. Has sub keys `tab-width` and `unit` |

36| `language-server` | The Language Server to run. Has sub keys `command` and `args` |

37| `config` | Language Server configuration |

38| `grammar` | The tree-sitter grammar to use (defaults to the value of `name`) |

39

40When adding a new language or Language Server configuration for an existing

41language, run `cargo xtask docgen` to add the new configuration to the

42[Language Support][lang-support] docs before creating a pull request.

43When adding a Language Server configuration, be sure to update the

44[Language Server Wiki][install-lsp-wiki] with installation notes.

45

46## Grammar configuration

47

48If a tree-sitter grammar is available for the language, add a new `grammar`

49entry to `languages.toml`.

50

51```toml

52[[grammar]]

53name = "mylang"

54source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" }

55```

56

57Grammar configuration takes these keys:

58

59| Key | Description |

60| --- | ----------- |

61| `name` | The name of the tree-sitter grammar |

62| `source` | The method of fetching the grammar - a table with a schema defined below |

63

64Where `source` is a table with either these keys when using a grammar from a

65git repository:

66

67| Key | Description |

68| --- | ----------- |

69| `git` | A git remote URL from which the grammar should be cloned |

70| `rev` | The revision (commit hash or tag) which should be fetched |

71| `subpath` | A path within the grammar directory which should be built. Some grammar repositories host multiple grammars (for example `tree-sitter-typescript` and `tree-sitter-ocaml`) in subdirectories. This key is used to point `hx --grammar build` to the correct path for compilation. When omitted, the root of repository is used |

72

73Or a `path` key with an absolute path to a locally available grammar directory.

74

75## Queries

76

77For a language to have syntax-highlighting and indentation among

78other things, you have to add queries. Add a directory for your

79language with the path `runtime/queries/<name>/`. The tree-sitter

80[website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries)

81gives more info on how to write queries.

82

83> NOTE: When evaluating queries, the first matching query takes

84precedence, which is different from other editors like neovim where

85the last matching query supersedes the ones before it. See

86[this issue][neovim-query-precedence] for an example.

87

88## Common Issues

89

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

91

92- If a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in `runtime/grammar/<name>.so`

93

94[treesitter-language-injection]: https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection

95[languages.toml]: https://github.com/helix-editor/helix/blob/master/languages.toml

96[neovim-query-precedence]: https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090

97[install-lsp-wiki]: https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers

98[lang-support]: ../lang-support.md