feat(book/src/languages.md) (#979)

* feat(book/src/languages.md)

Add a section in the book about language-specific settings and the languages.toml file.

* Update book/src/languages.md

Co-authored-by: Gokul Soumya <gokulps15@gmail.com>

* feat(book/src/guides/adding_languages.md)

Add book section on adding a new language to the compile-time/root languages.toml file.

* Update book/src/guides/adding_languages.md

Co-authored-by: Blaž Hrastnik <blaz@mxxn.io>

* Update book/src/guides/adding_languages.md

Co-authored-by: Blaž Hrastnik <blaz@mxxn.io>

* refactor(revise book/src/languages.md)

Change the book page on language settings to match suggestions by archseer and mention both toml files.

Co-authored-by: Gokul Soumya <gokulps15@gmail.com>
Co-authored-by: Blaž Hrastnik <blaz@mxxn.io>

3 files changed, 68 insertions, 0 deletions

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 56f50e21..8cadb663 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -8,5 +8,7 @@
   - [Keymap](./keymap.md)
   - [Key Remapping](./remapping.md)
   - [Hooks](./hooks.md)
+  - [Languages](./languages.md)
 - [Guides](./guides/README.md)
+  - [Adding Languages](./guides/adding_languages.md)
   - [Adding Textobject Queries](./guides/textobject.md)
diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md
new file mode 100644
index 00000000..85c3d0e8
--- /dev/null
+++ b/book/src/guides/adding_languages.md
@@ -0,0 +1,52 @@
+# Adding languages
+
+## Submodules
+
+To add a new langauge, you should first add a tree-sitter submodule. To do this, you can run the command
+```sh
+$ git submodule add -f <repository> helix-syntax/languages/tree-sitter-<name>
+```
+For example, to add tree-sitter-ocaml you would run
+```sh
+$ git submodule add -f https://github.com/tree-sitter/tree-sitter-ocaml helix-syntax/languages/tree-sitter-ocaml
+```
+Make sure the submodule is shallow by doing
+```sh
+git config -f .gitmodules submodule.helix-syntax/languages/tree-sitter-<name>.shallow true
+```
+
+or you can manually add `shallow = true` to `.gitmodules`.
+
+## languages.toml
+
+Next, you need to add the language to the `languages.toml` found in the root of the repository; this `languages.toml` file is included at compilation time, and is distinct from the `language.toml` file in the user's [configuration directory](../configuration.md).
+
+These are the available keys and descriptions for the file.
+
+| Key           | Description                                                   |
+| ----          | -----------                                                   |
+| name          | The name of the language                                      |
+| 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 |
+| 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 site. [link](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection) |
+| file-types    | The filetypes of the language, for example `["yml", "yaml"]`  |
+| roots         | A set of marker files to look for when trying to find the workspace root. For example `Cargo.lock`, `yarn.lock` |
+| auto-format   | Whether to autoformat this language when saving               |
+| comment-token | The token to use as a comment-token                           |
+| indent        | The indent to use. Has sub keys `tab-width` and `unit`            |
+| config        | Language server configuration                                 |
+
+## Queries
+
+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.
+
+## Common Issues
+
+- If you get errors when building after switching branches, you may have to remove or update tree-sitter submodules. You can update submodules by running
+```sh
+$ git submodule update --init
+```
+- Make sure to not use the `--remote` flag. To remove submodules look inside the `.gitmodules` and remove directories that are not present inside of it.
+
+- If a parser is segfaulting or you want to remove the parser, make sure to remove the submodule *and* the compiled parser in `runtime/grammar/<name>.so`
+
+- The indents query is `indents.toml`, *not* `indents.scm`. See [this](https://github.com/helix-editor/helix/issues/114) issue for more information.
diff --git a/book/src/languages.md b/book/src/languages.md
new file mode 100644
index 00000000..cef61501
--- /dev/null
+++ b/book/src/languages.md
@@ -0,0 +1,14 @@
+# Languages
+
+Language-specific settings and settings for particular language servers can be configured in a `languages.toml` file placed in your [configuration directory](./configuration.md). Helix actually uses two `languages.toml` files, the [first one](https://github.com/helix-editor/helix/blob/master/languages.toml) is in the main helix repository; it contains the default settings for each language and is included in the helix binary at compile time. Users who want to see the available settings and options can either reference the helix repo's `languages.toml` file, or consult the table in the [adding languages](./guides/adding_languages.md) section.
+
+Changes made to the `languages.toml` file in a user's [configuration directory](./configuration.md) are merged with helix's defaults on start-up, such that a user's settings will take precedence over defaults in the event of a collision. For example, the default `languages.toml` sets rust's `auto-format` to `true`. If a user wants to disable auto-format, they can change the `languages.toml` in their [configuration directory](./configuration.md) to make the rust entry read like the example below; the new key/value pair `auto-format = false` will override the default when the two sets of settings are merged on start-up:
+
+```
+# in <config_dir>/helix/languages.toml
+
+[[language]]
+name = "rust"
+auto-format = false
+```
+