707457c · helix · git.iko.soy

git.iko.soy/helix

on master help sign in

Rewrite and refactor all documentation (#5534)

707457cDavid Else4 years ago

README.md+1−83

compare with master

unifiedsplit

@@ -45,92 +45,10 @@ Note: Only certain languages have indentation definitions at the moment. Check

46# Installation

48−Packages are available for various distributions (see [Installation docs](https://docs.helix-editor.com/install.html)).

48+[Installation documentation](https://docs.helix-editor.com/install.html).

49−

50−If you would like to build from source:

51−

52−```shell

53−git clone https://github.com/helix-editor/helix

54−cd helix

55−cargo install --locked --path helix-term

56−```

57−

58−This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`.

59−

60−Helix needs its runtime files so make sure to copy/symlink the `runtime/` directory into the

61−config directory (for example `~/.config/helix/runtime` on Linux/macOS, or `%AppData%/helix/runtime` on Windows).

62−

63−| OS | Command |

64−| -------------------- | ------------------------------------------------ |

65−| Windows (Cmd) | `xcopy /e /i runtime %AppData%\helix\runtime` |

66−| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` |

67−| Linux / macOS | `ln -s $PWD/runtime ~/.config/helix/runtime` |

68−

69−Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires

70−elevated privileges - i.e. PowerShell or Cmd must be run as administrator.

71−

72−**PowerShell:**

73−

74−```powershell

75−New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"

76−```

77−Note: "runtime" must be absolute path to the runtime directory.

78−

79−**Cmd:**

80−

81−```cmd

82−cd %appdata%\helix

83−mklink /D runtime "<helix-repo>\runtime"

84−```

85−

86−The runtime location can be overridden via the `HELIX_RUNTIME` environment variable.

87−

88−> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --locked --path helix-term`,

89−> tree-sitter grammars will be built in `$HELIX_RUNTIME/grammars`.

90−

91−If you plan on keeping the repo locally, an alternative to copying/symlinking

92−runtime files is to set `HELIX_RUNTIME=/path/to/helix/runtime`

93−(`HELIX_RUNTIME=$PWD/runtime` if you're in the helix repo directory).

94−

95−Packages already solve this for you by wrapping the `hx` binary with a wrapper

96−that sets the variable to the install dir.

97−

98−> NOTE: running via cargo also doesn't require setting explicit `HELIX_RUNTIME` path, it will automatically

99−> detect the `runtime` directory in the project root.

100−

101−If you want to customize your `languages.toml` config,

102−tree-sitter grammars may be manually fetched and built with `hx --grammar fetch` and `hx --grammar build`.

103−

104−In order to use LSP features like auto-complete, you will need to

105−[install the appropriate Language Server](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)

106−for a language.

107

108[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions)

50[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions)

109

110−## Adding Helix to your desktop environment

111−

112−If installing from source, to use Helix in desktop environments that supports [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder:

113−

114−```bash

115−cp contrib/Helix.desktop ~/.local/share/applications

116−cp contrib/helix.png ~/.local/share/icons

117−```

118−

119−To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`:

120−

121−```bash

122−sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop

123−sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop

124−```

125−

126−## macOS

127−

128−Helix can be installed on macOS through homebrew:

129−

130−```

131−brew install helix

132−```

133−

134# Contributing

52# Contributing

135

136Contributing guidelines can be found [here](./docs/CONTRIBUTING.md).

54Contributing guidelines can be found [here](./docs/CONTRIBUTING.md).

book/src/SUMMARY.md+5−5

@@ -6,13 +6,13 @@

6- [Usage](./usage.md)

7 - [Keymap](./keymap.md)

8 - [Commands](./commands.md)

9− - [Language Support](./lang-support.md)

9+ - [Language support](./lang-support.md)

10- [Migrating from Vim](./from-vim.md)

11- [Configuration](./configuration.md)

12 - [Themes](./themes.md)

13− - [Key Remapping](./remapping.md)

13+ - [Key remapping](./remapping.md)

14 - [Languages](./languages.md)

15- [Guides](./guides/README.md)

16− - [Adding Languages](./guides/adding_languages.md)

16+ - [Adding languages](./guides/adding_languages.md)

17− - [Adding Textobject Queries](./guides/textobject.md)

17+ - [Adding textobject queries](./guides/textobject.md)

18− - [Adding Indent Queries](./guides/indent.md)

18+ - [Adding indent queries](./guides/indent.md)

book/src/commands.md+1−1

@@ -1,5 +1,5 @@

1# Commands

3−Command mode can be activated by pressing `:`, similar to Vim. Built-in commands:

3+Command mode can be activated by pressing `:`. The built-in commands are:

5{{#include ./generated/typable-cmd.md}}

book/src/configuration.md+43−46

@@ -2,10 +2,10 @@

3To override global configuration parameters, create a `config.toml` file located in your config directory:

5−* Linux and Mac: `~/.config/helix/config.toml`

5+- Linux and Mac: `~/.config/helix/config.toml`

6−* Windows: `%AppData%\helix\config.toml`

6+- Windows: `%AppData%\helix\config.toml`

8−> Hint: You can easily open the config file by typing `:config-open` within Helix normal mode.

8+> 💡 You can easily open the config file by typing `:config-open` within Helix normal mode.

10Example config:

@@ -25,12 +25,10 @@ select = "underline"

25hidden = false

26```

28−You may also specify a file to use for configuration with the `-c` or

28+You can use a custom configuration file by specifying it with the `-c` or

29−`--config` CLI argument: `hx -c path/to/custom-config.toml`.

29+`--config` command line argument, for example `hx -c path/to/custom-config.toml`.

30−

31−It is also possible to trigger configuration file reloading by sending the `USR1`

30+Additionally, you can reload the configuration file by sending the USR1

32−signal to the helix process, e.g. via `pkill -USR1 hx`. This is only supported

31+signal to the Helix process on Unix operating systems, such as by using the command `pkill -USR1 hx`.

33−on unix operating systems.

35## Editor

33## Editor

@@ -38,23 +36,23 @@ on unix operating systems.

39| Key | Description | Default |

37| Key | Description | Default |

40|--|--|---------|

38|--|--|---------|

41−| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `5` |

39+| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling | `5` |

42−| `mouse` | Enable mouse mode. | `true` |

40+| `mouse` | Enable mouse mode | `true` |

43−| `middle-click-paste` | Middle click paste support. | `true` |

41+| `middle-click-paste` | Middle click paste support | `true` |

44−| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` |

42+| `scroll-lines` | Number of lines to scroll per scroll wheel step | `3` |

45−| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |

43+| `shell` | Shell to use when running external commands | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |

46−| `line-number` | Line number display: `absolute` simply shows each line's number, while `relative` shows the distance from the current line. When unfocused or in insert mode, `relative` will still show absolute line numbers. | `absolute` |

44+| `line-number` | Line number display: `absolute` simply shows each line's number, while `relative` shows the distance from the current line. When unfocused or in insert mode, `relative` will still show absolute line numbers | `absolute` |

47−| `cursorline` | Highlight all lines with a cursor. | `false` |

45+| `cursorline` | Highlight all lines with a cursor | `false` |

48−| `cursorcolumn` | Highlight all columns with a cursor. | `false` |

46+| `cursorcolumn` | Highlight all columns with a cursor | `false` |

49| `gutters` | Gutters to display: Available are `diagnostics` and `diff` and `line-numbers` and `spacer`, note that `diagnostics` also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty | `["diagnostics", "spacer", "line-numbers", "spacer", "diff"]` |

47| `gutters` | Gutters to display: Available are `diagnostics` and `diff` and `line-numbers` and `spacer`, note that `diagnostics` also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty | `["diagnostics", "spacer", "line-numbers", "spacer", "diff"]` |

50−| `auto-completion` | Enable automatic pop up of auto-completion. | `true` |

48+| `auto-completion` | Enable automatic pop up of auto-completion | `true` |

51−| `auto-format` | Enable automatic formatting on save. | `true` |

49+| `auto-format` | Enable automatic formatting on save | `true` |

52−| `auto-save` | Enable automatic saving on focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal. | `false` |

50+| `auto-save` | Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal | `false` |

53−| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` |

51+| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant | `400` |

54| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |

52| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |

55−| `auto-info` | Whether to display infoboxes | `true` |

53+| `auto-info` | Whether to display info boxes | `true` |

56−| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` |

54+| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative | `false` |

57−| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` |

55+| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file | `[]` |

58| `bufferline` | Renders a line at the top of the editor displaying open buffers. Can be `always`, `never` or `multiple` (only shown if more than one buffer is in use) | `never` |

56| `bufferline` | Renders a line at the top of the editor displaying open buffers. Can be `always`, `never` or `multiple` (only shown if more than one buffer is in use) | `never` |

59| `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` |

57| `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` |

@@ -125,10 +123,12 @@ The following statusline elements can be configured:

125

123

126### `[editor.cursor-shape]` Section

124### `[editor.cursor-shape]` Section

127

125

128−Defines the shape of cursor in each mode. Note that due to limitations

126+Defines the shape of cursor in each mode.

129−of the terminal environment, only the primary cursor can change shape.

130Valid values for these options are `block`, `bar`, `underline`, or `hidden`.

127Valid values for these options are `block`, `bar`, `underline`, or `hidden`.

131

128

129+> 💡 Due to limitations of the terminal environment, only the primary cursor can

130+> change shape.

131+

132| Key | Description | Default |

133| --- | ----------- | ------- |

134| `normal` | Cursor shape in [normal mode][normal mode] | `block` |

@@ -141,25 +141,22 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`.

141

142### `[editor.file-picker]` Section

143

144−Sets options for file picker and global search. All but the last key listed in

144+Set options for file picker and global search. Ignoring a file means it is

145−the default file-picker configuration below are IgnoreOptions: whether hidden

146−files and files listed within ignore files are ignored by (not visible in) the

147−helix file picker and global search. There is also one other key, `max-depth`

145+not visible in the Helix file picker and global search.

148−available, which is not defined by default.

149

146

150All git related options are only enabled in a git repository.

147All git related options are only enabled in a git repository.

151

148

152| Key | Description | Default |

149| Key | Description | Default |

153|--|--|---------|

150|--|--|---------|

154−|`hidden` | Enables ignoring hidden files. | true

151+|`hidden` | Enables ignoring hidden files | true

155|`follow-links` | Follow symlinks instead of ignoring them | true

152|`follow-links` | Follow symlinks instead of ignoring them | true

156|`deduplicate-links` | Ignore symlinks that point at files already shown in the picker | true

153|`deduplicate-links` | Ignore symlinks that point at files already shown in the picker | true

157−|`parents` | Enables reading ignore files from parent directories. | true

154+|`parents` | Enables reading ignore files from parent directories | true

158−|`ignore` | Enables reading `.ignore` files. | true

155+|`ignore` | Enables reading `.ignore` files | true

159−|`git-ignore` | Enables reading `.gitignore` files. | true

156+|`git-ignore` | Enables reading `.gitignore` files | true

160−|`git-global` | Enables reading global .gitignore, whose path is specified in git's config: `core.excludefile` option. | true

157+|`git-global` | Enables reading global `.gitignore`, whose path is specified in git's config: `core.excludefile` option | true

161−|`git-exclude` | Enables reading `.git/info/exclude` files. | true

158+|`git-exclude` | Enables reading `.git/info/exclude` files | true

162−|`max-depth` | Set with an integer value for maximum depth to recurse. | Defaults to `None`.

159+|`max-depth` | Set with an integer value for maximum depth to recurse | Defaults to `None`.

163

160

164### `[editor.auto-pairs]` Section

161### `[editor.auto-pairs]` Section

165

162

@@ -211,7 +208,7 @@ Search specific options.

211

208

212| Key | Description | Default |

209| Key | Description | Default |

213|--|--|---------|

210|--|--|---------|

214−| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` |

211+| `smart-case` | Enable smart case regex searching (case-insensitive unless pattern contains upper case characters) | `true` |

215| `wrap-around`| Whether the search should wrap after depleting the matches | `true` |

212| `wrap-around`| Whether the search should wrap after depleting the matches | `true` |

216

213

217### `[editor.whitespace]` Section

214### `[editor.whitespace]` Section

@@ -220,7 +217,7 @@ Options for rendering whitespace with visible characters. Use `:set whitespace.r

220

217

221| Key | Description | Default |

218| Key | Description | Default |

222|-----|-------------|---------|

219|-----|-------------|---------|

223−| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline`. | `"none"` |

220+| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline` | `"none"` |

224| `characters` | Literal characters to use when rendering whitespace. Sub-keys may be any of `tab`, `space`, `nbsp`, `newline` or `tabpad` | See example below |

221| `characters` | Literal characters to use when rendering whitespace. Sub-keys may be any of `tab`, `space`, `nbsp`, `newline` or `tabpad` | See example below |

225

222

226Example

223Example

@@ -248,7 +245,7 @@ Options for rendering vertical indent guides.

248

245

249| Key | Description | Default |

246| Key | Description | Default |

250| --- | --- | --- |

247| --- | --- | --- |

251−| `render` | Whether to render indent guides. | `false` |

248+| `render` | Whether to render indent guides | `false` |

252| `character` | Literal character to use for rendering the indent guide | `│` |

249| `character` | Literal character to use for rendering the indent guide | `│` |

253| `skip-levels` | Number of indent levels to skip | `0` |

250| `skip-levels` | Number of indent levels to skip | `0` |

254

251

@@ -273,7 +270,7 @@ gutters = ["diff", "diagnostics", "line-numbers", "spacer"]

273

270

274To customize the behavior of gutters, the `[editor.gutters]` section must

271To customize the behavior of gutters, the `[editor.gutters]` section must

275be used. This section contains top level settings, as well as settings for

272be used. This section contains top level settings, as well as settings for

276−specific gutter components as sub-sections.

273+specific gutter components as subsections.

277

274

278| Key | Description | Default |

275| Key | Description | Default |

279| --- | --- | --- |

276| --- | --- | --- |

@@ -315,13 +312,13 @@ Currently unused

315

312

316### `[editor.soft-wrap]` Section

313### `[editor.soft-wrap]` Section

317

314

318−Options for soft wrapping lines that exceed the view width

315+Options for soft wrapping lines that exceed the view width:

319

316

320| Key | Description | Default |

317| Key | Description | Default |

321| --- | --- | --- |

318| --- | --- | --- |

322−| `enable` | Whether soft wrapping is enabled. | `false` |

319+| `enable` | Whether soft wrapping is enabled | `false` |

323−| `max-wrap` | Maximum free space left at the end of the line. | `20` |

320+| `max-wrap` | Maximum free space left at the end of the line | `20` |

324−| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line. | `40` |

321+| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line | `40` |

325| `wrap-indicator` | Text inserted before soft wrapped lines, highlighted with `ui.virtual.wrap` | `↪ ` |

322| `wrap-indicator` | Text inserted before soft wrapped lines, highlighted with `ui.virtual.wrap` | `↪ ` |

326

323

327Example:

324Example:

book/src/guides/README.md+1−1

@@ -1,4 +1,4 @@

1# Guides

3This section contains guides for adding new language server configurations,

4−tree-sitter grammars, textobject queries, etc.

4+tree-sitter grammars, textobject queries, and other similar items.

book/src/guides/adding_languages.md+42−35

@@ -1,45 +1,52 @@

1−# Adding languages

1+# Adding new languages to Helix

3+In order to add a new language to Helix, you will need to follow the steps

4+below.

3## Language configuration

6## Language configuration

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

8+1. Add a new `[[language]]` entry in the `languages.toml` file and provide the

9+ necessary configuration for the new language. For more information on

10+ language configuration, refer to the

6−`languages.toml` (see the [language configuration section]).

11+ [language configuration section](../languages.md) of the documentation.

12+2. If you are adding a new language or updating an existing language server

13+ configuration, run the command `cargo xtask docgen` to update the

14+ [Language Support](../lang-support.md) documentation.

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

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

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

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

16+> 💡 If you are adding a new Language Server configuration, make sure to update

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

17+> the

18+> [Language Server Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)

19+> with the installation instructions.

14## Grammar configuration

21## Grammar configuration

16−If a tree-sitter grammar is available for the language, add a new `[[grammar]]`

23+1. If a tree-sitter grammar is available for the new language, add a new

17−entry to `languages.toml`.

24+ `[[grammar]]` entry to the `languages.toml` file.

18−

25+2. If you are testing the grammar locally, you can use the `source.path` key

19−You may use the `source.path` key rather than `source.git` with an absolute path

26+ with an absolute path to the grammar. However, before submitting a pull

20−to a locally available grammar for testing, but switch to `source.git` before

27+ request, make sure to switch to using `source.git`.

21−submitting a pull request.

23## Queries

29## Queries

25−For a language to have syntax-highlighting and indentation among

31+1. In order to provide syntax highlighting and indentation for the new language,

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

32+ you will need to add queries.

33+2. Create a new directory for the language with the path

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

34+ `runtime/queries/<name>/`.

35+3. Refer to the

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

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

29−gives more info on how to write queries.

37+ for more information on writing queries.

30−

38+

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

39+> 💡 In Helix, the first matching query takes precedence when evaluating

32−precedence, which is different from other editors like Neovim where

40+> queries, which is different from other editors such as Neovim where the last

33−the last matching query supersedes the ones before it. See

41+> matching query supersedes the ones before it. See

42+> [this issue](https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090)

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

43+> for an example.

35−

44+

36−## Common Issues

45+## Common issues

37−

46+

47+- If you encounter errors when running Helix after switching branches, you may

48+ need to update the tree-sitter grammars. Run the command `hx --grammar fetch`

38−- 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.

49+ to fetch the grammars and `hx --grammar build` to build any out-of-date

39−

50+ grammars.

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

51+- If a parser is causing a segfault, or you want to remove it, make sure to

41−

52+ remove the compiled parser located at `runtime/grammars/<name>.so`.

42−[language configuration section]: ../languages.md

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

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

45−[lang-support]: ../lang-support.md

book/src/guides/indent.md+2−2

@@ -1,4 +1,4 @@

1−# Adding Indent Queries

1+# Adding indent queries

3Helix uses tree-sitter to correctly indent new lines. This requires

4a tree-sitter grammar and an `indent.scm` query file placed in

@@ -36,7 +36,7 @@ changed by using a `#set!` declaration anywhere in the pattern:

36 (#set! "scope" "all"))

37```

39−## Capture Types

39+## Capture types

41- `@indent` (default scope `tail`):

42Increase the indent level by 1. Multiple occurrences in the same line

book/src/guides/textobject.md+7−9

@@ -1,14 +1,14 @@

1−# Adding Textobject Queries

1+# Adding textobject queries

3−Textobjects that are language specific ([like functions, classes, etc][textobjects])

3+Helix supports textobjects that are language specific, such as functions, classes, etc.

4−require an accompanying tree-sitter grammar and a `textobjects.scm` query file

4+These textobjects require an accompanying tree-sitter grammar and a `textobjects.scm` query file

5to work properly. Tree-sitter allows us to query the source code syntax tree

6and capture specific parts of it. The queries are written in a lisp dialect.

7More information on how to write queries can be found in the [official tree-sitter

8documentation][tree-sitter-queries].

10Query files should be placed in `runtime/queries/{language}/textobjects.scm`

11−when contributing. Note that to test the query files locally you should put

11+when contributing to Helix. Note that to test the query files locally you should put

12them under your local runtime directory (`~/.config/helix/runtime` on Linux

13for example).

@@ -28,9 +28,9 @@ The following [captures][tree-sitter-captures] are recognized:

29[Example query files][textobject-examples] can be found in the helix GitHub repository.

31−## Queries for Textobject Based Navigation

31+## Queries for textobject based navigation

33−[Tree-sitter based navigation][textobjects-nav] is done using captures in the

33+Tree-sitter based navigation in Helix is done using captures in the

34following order:

36- `object.movement`

@@ -38,12 +38,10 @@ following order:

38- `object.inside`

40For example if a `function.around` capture has been already defined for a language

41−in it's `textobjects.scm` file, function navigation should also work automatically.

41+in its `textobjects.scm` file, function navigation should also work automatically.

42`function.movement` should be defined only if the node captured by `function.around`

43doesn't make sense in a navigation context.

45−[textobjects]: ../usage.md#textobjects

46−[textobjects-nav]: ../usage.md#tree-sitter-textobject-based-navigation

47[tree-sitter-queries]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax

45[tree-sitter-queries]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax

48[tree-sitter-captures]: https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes

46[tree-sitter-captures]: https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes

49[textobject-examples]: https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=

47[textobject-examples]: https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=

book/src/install.md+152−109

@@ -1,180 +1,223 @@

1−# Installation

1+# Installing Helix

2−

3+

4+- [Pre-built binaries](#pre-built-binaries)

5+- [Linux, macOS, Windows and OpenBSD packaging status](#linux-macos-windows-and-openbsd-packaging-status)

6+- [Linux](#linux)

7+ - [Ubuntu](#ubuntu)

8+ - [Fedora/RHEL](#fedorarhel)

9+ - [Arch Linux community](#arch-linux-community)

10+ - [NixOS](#nixos)

11+- [macOS](#macos)

12+ - [Homebrew Core](#homebrew-core)

13+- [Windows](#windows)

14+ - [Scoop](#scoop)

15+ - [Chocolatey](#chocolatey)

16+ - [MSYS2](#msys2)

17+- [Building from source](#building-from-source)

18+ - [Configuring Helix's runtime files](#configuring-helixs-runtime-files)

19+ - [Validating the installation](#validating-the-installation)

20+ - [Configure the desktop shortcut](#configure-the-desktop-shortcut)

21+

22+

23+To install Helix, follow the instructions specific to your operating system.

24+Note that:

25+

26+- To get the latest nightly version of Helix, you need to

27+ [build from source](#building-from-source).

28+

29+- To take full advantage of Helix, install the language servers for your

30+ preferred programming languages. See the

31+ [wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)

32+ for instructions.

33+

34+## Pre-built binaries

35+

36+Download pre-built binaries from the

3−We provide pre-built binaries on the [GitHub Releases page](https://github.com/helix-editor/helix/releases).

37+[GitHub Releases page](https://github.com/helix-editor/helix/releases). Add the binary to your system's `$PATH` to use it from the command

38+line.

39+

40+## Linux, macOS, Windows and OpenBSD packaging status

41+

42+Helix is available for Linux, macOS and Windows via the official repositories listed below.

5[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions)

44[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions)

7−## OSX

46+## Linux

9−Helix is available in homebrew-core:

48+The following third party repositories are available:

11−```

50+### Ubuntu

12−brew install helix

13−```

15−## Linux

52+Helix is available via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor):

17−### NixOS

54+```sh

55+sudo add-apt-repository ppa:maveonair/helix-editor

56+sudo apt update

57+sudo apt install helix

58+```

19−A [flake](https://nixos.wiki/wiki/Flakes) containing the package is available in

60+### Fedora/RHEL

20−the project root. The flake can also be used to spin up a reproducible development

21−shell for working on Helix with `nix develop`.

23−Flake outputs are cached for each push to master using

62+Helix is available via `copr`:

24−[Cachix](https://www.cachix.org/). The flake is configured to

25−automatically make use of this cache assuming the user accepts

26−the new settings on first use.

28−If you are using a version of Nix without flakes enabled you can

64+```sh

29−[install Cachix cli](https://docs.cachix.org/installation); `cachix use helix` will

65+sudo dnf copr enable varlad/helix

30−configure Nix to use cached outputs when possible.

66+sudo dnf install helix

67+```

32−### Arch Linux

69+### Arch Linux community

34−Releases are available in the `community` repository.

71+Releases are available in the `community` repository:

73+```sh

74+sudo pacman -S helix

75+```

36−A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also available on the AUR, which builds the master branch.

76+Additionally, a [helix-git](https://aur.archlinux.org/packages/helix-git/) package is available

77+in the AUR, which builds the master branch.

38−### Fedora Linux

79+### NixOS

40−You can install the COPR package for Helix via

81+Helix is available as a [flake](https://nixos.wiki/wiki/Flakes) in the project

82+root. Use `nix develop` to spin up a reproducible development shell. Outputs are

83+cached for each push to master using [Cachix](https://www.cachix.org/). The

84+flake is configured to automatically make use of this cache assuming the user

85+accepts the new settings on first use.

42−```

87+If you are using a version of Nix without flakes enabled,

43−sudo dnf copr enable varlad/helix

88+[install Cachix CLI](https://docs.cachix.org/installation) and use

44−sudo dnf install helix

89+`cachix use helix` to configure Nix to use cached outputs when possible.

45−```

90+

91+## macOS

47−### Void Linux

93+### Homebrew Core

49−```

95+```sh

50−sudo xbps-install helix

96+brew install helix

51```

97```

53## Windows

99## Windows

100

55−Helix can be installed using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/)

101+Install on Windows using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/)

56or [MSYS2](https://msys2.org/).

102or [MSYS2](https://msys2.org/).

103

58−**Scoop:**

104+### Scoop

105

60−```

106+```sh

61scoop install helix

107scoop install helix

62```

108```

109

64−**Chocolatey:**

110+### Chocolatey

111

66−```

112+```sh

67choco install helix

113choco install helix

68```

114```

115

70−**MSYS2:**

116+### MSYS2

71−

72−Choose the [proper command](https://www.msys2.org/docs/package-naming/) for your system from below:

73−

74− - For 32 bit Windows 7 or above:

75−

76−```

77−pacman -S mingw-w64-i686-helix

78−```

79−

80− - For 64 bit Windows 7 or above:

81−

82−```

83−pacman -S mingw-w64-x86_64-helix

84−```

117

86− - For 64 bit Windows 8.1 or above:

118+For 64-bit Windows 8.1 or above:

119

88−```

120+```sh

89pacman -S mingw-w64-ucrt-x86_64-helix

121pacman -S mingw-w64-ucrt-x86_64-helix

90```

122```

123

92−## Build from source

124+## Building from source

125

126+Clone the repository:

127+

94−```

128+```sh

95git clone https://github.com/helix-editor/helix

129git clone https://github.com/helix-editor/helix

96cd helix

130cd helix

97−cargo install --path helix-term --locked

98```

131```

132

100−This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`.

133+Compile from source:

101−

102−If you are using the musl-libc instead of glibc the following environment variable must be set during the build

103−to ensure tree sitter grammars can be loaded correctly:

104

134

135+```sh

136+cargo install --path helix-term --locked

105```

137```

106−RUSTFLAGS="-C target-feature=-crt-static"

107−```

108−

109

138

110−Helix also needs its runtime files so make sure to copy/symlink the `runtime/` directory into the

139+This command will create the `hx` executable and construct the tree-sitter

111−config directory (for example `~/.config/helix/runtime` on Linux/macOS). This location can be overridden

140+grammars either in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME`

112−via the `HELIX_RUNTIME` environment variable.

141+(as described below). To build the tree-sitter grammars requires a c++ compiler to be installed, for example `gcc-c++`.

113

142

114−| OS | Command |

143+> 💡 If you are using the musl-libc instead of glibc the following environment variable must be set during the build

115−| -------------------- | ------------------------------------------------ |

144+> to ensure tree-sitter grammars can be loaded correctly:

116−| Windows (Cmd) | `xcopy /e /i runtime %AppData%\helix\runtime` |

145+>

117−| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` |

146+> ```sh

118−| Linux / macOS | `ln -s $PWD/runtime ~/.config/helix/runtime` |

147+> RUSTFLAGS="-C target-feature=-crt-static"

148+> ```

119

149

120−Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires

150+> 💡 Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch

121−elevated privileges - i.e. PowerShell or Cmd must be run as administrator.

151+> grammars with `hx --grammar fetch` (requires `git`) and compile them with

152+> `hx --grammar build` (requires a C++ compiler).

122

153

123−**PowerShell:**

154+### Configuring Helix's runtime files

124

155

125−```powershell

156+- **Linux and macOS**

126−New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"

127−```

128−Note: "runtime" must be the absolute path to the runtime directory.

129

157

130−**Cmd:**

158+Either set the `HELIX_RUNTIME` environment variable to point to the runtime files and add it to your `~/.bashrc` or equivalent:

131

159

132−```cmd

160+```sh

133−cd %appdata%\helix

161+HELIX_RUNTIME=/home/user-name/src/helix/runtime

134−mklink /D runtime "<helix-repo>\runtime"

135```

162```

136

163

137−The runtime location can be overridden via the `HELIX_RUNTIME` environment variable.

164+Or, create a symlink in `~/.config/helix` that links to the source code directory:

138

165

139−> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --path helix-term --locked`,

166+```sh

140−> tree-sitter grammars will be built in `$HELIX_RUNTIME/grammars`.

167+ln -s $PWD/runtime ~/.config/helix/runtime

168+```

141

169

142−If you plan on keeping the repo locally, an alternative to copying/symlinking

170+- **Windows**

143−runtime files is to set `HELIX_RUNTIME=/path/to/helix/runtime`

144−(`HELIX_RUNTIME=$PWD/runtime` if you're in the helix repo directory).

145

171

146−To use Helix in desktop environments that supports [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder:

172+Either set the `HELIX_RUNTIME` environment variable to point to the runtime files using the Windows setting (search for

173+`Edit environment variables for your account`) or use the `setx` command in

174+Cmd:

147

175

148−```bash

176+```sh

149−cp contrib/Helix.desktop ~/.local/share/applications

177+setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"

150```

178```

151

179

152−To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`:

180+> 💡 `%userprofile%` resolves to your user directory like

181+> `C:\Users\Your-Name\` for example.

153

182

154−```bash

183+Or, create a symlink in `%appdata%\helix\` that links to the source code directory:

155−sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop

156−sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop

157−```

158

184

159−Please note: there is no icon for Helix yet, so the system default will be used.

185+ | Method | Command |

186+ | ---------- | -------------------------------------------------------------------------------------- |

187+ | PowerShell | `New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"` |

188+ | Cmd | `cd %appdata%\helix` <br/> `mklink /D runtime "%userprofile%\src\helix\runtime"` |

160

189

161−## Finishing up the installation

190+ > 💡 On Windows, creating a symbolic link may require running PowerShell or

191+ > Cmd as an administrator.

162

192

163−To make sure everything is set up as expected you should finally run the helix healthcheck via

193+### Validating the installation

164

194

195+To make sure everything is set up as expected you should run the Helix health

196+check:

197+

165−```

198+```sh

166hx --health

199hx --health

167```

200```

168

201

169−For more information on the information displayed in the health check results refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck).

202+For more information on the health check results refer to

203+[Health check](https://github.com/helix-editor/helix/wiki/Healthcheck).

170

204

171−### Building tree-sitter grammars

205+### Configure the desktop shortcut

172

206

173−Tree-sitter grammars must be fetched and compiled if not pre-packaged.

207+If your desktop environment supports the

174−Fetch grammars with `hx --grammar fetch` (requires `git`) and compile them

208+[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html)

175−with `hx --grammar build` (requires a C++ compiler).

209+you can configure Helix to show up in the application menu by copying the

210+provided `.desktop` and icon files to their correct folders:

176

211

177−### Installing language servers

212+```sh

213+cp contrib/Helix.desktop ~/.local/share/applications

214+cp contrib/helix.png ~/.icons # or ~/.local/share/icons

215+```

216+

217+To use another terminal than the system default, you can modify the `.desktop`

218+file. For example, to use `kitty`:

178

219

179−Language servers can optionally be installed if you want their features (auto-complete, diagnostics etc.).

220+```sh

180−Follow the [instructions on the wiki page](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) to add your language servers of choice.

221+sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop

222+sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop

223+```

book/src/keymap.md+20−20

@@ -14,14 +14,14 @@

14 - [Space mode](#space-mode)

15 - [Popup](#popup)

16 - [Unimpaired](#unimpaired)

17−- [Insert Mode](#insert-mode)

17+- [Insert mode](#insert-mode)

18−- [Select / extend mode](#select--extend-mode)

18+- [Select / extend mode](#select-extend-mode)

19- [Picker](#picker)

20- [Prompt](#prompt)

22> 💡 Mappings marked (**LSP**) require an active language server for the file.

24−> 💡 Mappings marked (**TS**) require a tree-sitter grammar for the filetype.

24+> 💡 Mappings marked (**TS**) require a tree-sitter grammar for the file type.

26## Normal mode

@@ -109,7 +109,7 @@

109| Key | Description | Command |

110| ----- | ----------- | ------- |

111| `s` | Select all regex matches inside selections | `select_regex` |

112−| `S` | Split selection into subselections on regex matches | `split_selection` |

112+| `S` | Split selection into sub selections on regex matches | `split_selection` |

113| `Alt-s` | Split selection on newlines | `split_selection_on_newline` |

114| `Alt-_ ` | Merge consecutive selections | `merge_consecutive_selections` |

115| `&` | Align selection in columns | `align_selections` |

@@ -141,7 +141,7 @@

141

142### Search

143

144−Search commands all operate on the `/` register by default. Use `"<char>` to operate on a different one.

144+Search commands all operate on the `/` register by default. To use a different register, use `"<char>`.

145

146| Key | Description | Command |

147| ----- | ----------- | ------- |

@@ -175,9 +175,8 @@ Accessed by typing `z` in [normal mode](#normal-mode).

175

176View mode is intended for scrolling and manipulating the view without changing

177the selection. The "sticky" variant of this mode (accessed by typing `Z` in

178−normal mode) is persistent; use the Escape key to return to normal mode after

178+normal mode) is persistent and can be exited using the escape key. This is

179−usage (useful when you're simply looking over text and not actively editing

179+useful when you're simply looking over text and not actively editing it.

180−it).

181

180

182

181

183| Key | Description | Command |

182| Key | Description | Command |

@@ -225,7 +224,7 @@ Jumps to various locations.

225Accessed by typing `m` in [normal mode](#normal-mode).

224Accessed by typing `m` in [normal mode](#normal-mode).

226

225

227See the relevant section in [Usage](./usage.md) for an explanation about

226See the relevant section in [Usage](./usage.md) for an explanation about

228−[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage.

227+[surround](./usage.md#surround) and [textobject](./usage.md#navigating-using-tree-sitter-textobjects) usage.

229

228

230| Key | Description | Command |

229| Key | Description | Command |

231| ----- | ----------- | ------- |

230| ----- | ----------- | ------- |

@@ -242,7 +241,7 @@ TODO: Mappings for selecting syntax nodes (a superset of `[`).

242

241

243Accessed by typing `Ctrl-w` in [normal mode](#normal-mode).

242Accessed by typing `Ctrl-w` in [normal mode](#normal-mode).

244

243

245−This layer is similar to Vim keybindings as Kakoune does not support window.

244+This layer is similar to Vim keybindings as Kakoune does not support windows.

246

245

247| Key | Description | Command |

246| Key | Description | Command |

248| ----- | ------------- | ------- |

247| ----- | ------------- | ------- |

@@ -293,7 +292,7 @@ This layer is a kludge of mappings, mostly pickers.

293| `/` | Global search in workspace folder | `global_search` |

292| `/` | Global search in workspace folder | `global_search` |

294| `?` | Open command palette | `command_palette` |

293| `?` | Open command palette | `command_palette` |

295

294

296−> TIP: Global search displays results in a fuzzy picker, use `Space + '` to bring it back up after opening a file.

295+> 💡 Global search displays results in a fuzzy picker, use `Space + '` to bring it back up after opening a file.

297

296

298##### Popup

297##### Popup

299

298

@@ -306,7 +305,7 @@ Displays documentation for item under cursor.

306

305

307#### Unimpaired

306#### Unimpaired

308

307

309−Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired).

308+These mappings are in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired).

310

309

311| Key | Description | Command |

310| Key | Description | Command |

312| ----- | ----------- | ------- |

311| ----- | ----------- | ------- |

@@ -335,12 +334,13 @@ Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaire

335

334

336## Insert mode

335## Insert mode

337

336

338−Insert mode bindings are somewhat minimal by default. Helix is designed to

337+Insert mode bindings are minimal by default. Helix is designed to

339be a modal editor, and this is reflected in the user experience and internal

338be a modal editor, and this is reflected in the user experience and internal

340−mechanics. For example, changes to the text are only saved for undos when

339+mechanics. Changes to the text are only saved for undos when

341−escaping from insert mode to normal mode. For this reason, new users are

340+escaping from insert mode to normal mode.

341+

342−strongly encouraged to learn the modal editing paradigm to get the smoothest

342+> 💡 New users are strongly encouraged to learn the modal editing paradigm

343−experience.

343+> to get the smoothest experience.

344

345| Key | Description | Command |

346| ----- | ----------- | ------- |

@@ -370,8 +370,8 @@ with modal editors.

370| `Home` | Move to line start | `goto_line_start` |

371| `End` | Move to line end | `goto_line_end_newline` |

372

373−If you want to disable them in insert mode as you become more comfortable with modal editing, you can use

373+As you become more comfortable with modal editing, you may want to disable some

374−the following in your `config.toml`:

374+insert mode bindings. You can do this by editing your `config.toml` file.

375

376```toml

377[keys.insert]

@@ -387,7 +387,7 @@ end = "no_op"

387

388## Select / extend mode

389

390−This mode echoes Normal mode, but changes any movements to extend

390+Select mode echoes Normal mode, but changes any movements to extend

391selections rather than replace them. Goto motions are also changed to

392extend, so that `vgl` for example extends the selection to the end of

393the line.

book/src/lang-support.md+2−2

@@ -1,10 +1,10 @@

1# Language Support

3−The following languages and Language Servers are supported. In order to use

3+The following languages and Language Servers are supported. To use

4Language Server features, you must first [install][lsp-install-wiki] the

5appropriate Language Server.

7−Check the language support in your installed helix version with `hx --health`.

7+You can check the language support in your installed helix version with `hx --health`.

9Also see the [Language Configuration][lang-config] docs and the [Adding

10Languages][adding-languages] guide for more language configuration information.

book/src/languages.md+13−11

@@ -5,13 +5,15 @@ in `languages.toml` files.

6## `languages.toml` files

8−There are three possible `languages.toml` files. The first is compiled into

8+There are three possible locations for a `languages.toml` file:

9−Helix and lives in the [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml).

10−This provides the default configurations for languages and language servers.

10+1. In the Helix source code, this lives in the

11+ [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml).

12+ It provides the default configurations for languages and language servers.

13+

12−You may define a `languages.toml` in your [configuration directory](./configuration.md)

14+2. In your [configuration directory](./configuration.md). This overrides values

13−which overrides values from the built-in language configuration. For example

15+ from the built-in language configuration. For example to disable

14−to disable auto-LSP-formatting in Rust:

16+ auto-LSP-formatting in Rust:

16```toml

18```toml

17# in <config_dir>/helix/languages.toml

19# in <config_dir>/helix/languages.toml

@@ -21,10 +23,10 @@ name = "rust"

21auto-format = false

23auto-format = false

22```

24```

26+3. In a `.helix` folder in your project. Language configuration may also be

24−Language configuration may also be overridden local to a project by creating

27+ overridden local to a project by creating a `languages.toml` file in a

25−a `languages.toml` file under a `.helix` directory. Its settings will be merged

28+ `.helix` folder. Its settings will be merged with the language configuration

26−with the language configuration in the configuration directory and the built-in

29+ in the configuration directory and the built-in configuration.

27−configuration.

29## Language configuration

31## Language configuration

@@ -65,7 +67,7 @@ These configuration keys are available:

66### File-type detection and the `file-types` key

68### File-type detection and the `file-types` key

68−Helix determines which language configuration to use with the `file-types` key

70+Helix determines which language configuration to use based on the `file-types` key

69from the above section. `file-types` is a list of strings or tables, for

71from the above section. `file-types` is a list of strings or tables, for

70example:

72example:

book/src/remapping.md+9−10

@@ -1,18 +1,18 @@

1−# Key Remapping

1+# Key remapping

3−One-way key remapping is temporarily supported via a simple TOML configuration

3+Helix currently supports one-way key remapping through a simple TOML configuration

4file. (More powerful solutions such as rebinding via commands will be

5available in the future).

7−To remap keys, write a `config.toml` file in your `helix` configuration

7+To remap keys, create a `config.toml` file in your `helix` configuration

8−directory (default `~/.config/helix` in Linux systems) with a structure like

8+directory (default `~/.config/helix` on Linux systems) with a structure like

9this:

11```toml

12# At most one section each of 'keys.normal', 'keys.insert' and 'keys.select'

13[keys.normal]

14−C-s = ":w" # Maps the Ctrl-s to the typable command :w which is an alias for :write (save file)

14+C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file)

15−C-o = ":open ~/.config/helix/config.toml" # Maps the Ctrl-o to opening of the helix config file

15+C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file

16a = "move_char_left" # Maps the 'a' key to the move_char_left command

17w = "move_line_up" # Maps the 'w' key move_line_up

18"C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line

@@ -20,10 +20,9 @@ g = { a = "code_action" } # Maps `ga` to show possible code actions

20"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode

22[keys.insert]

23−"A-x" = "normal_mode" # Maps Alt-X to enter normal mode

23+"A-x" = "normal_mode" # Maps Alt-X to enter normal mode

24j = { k = "normal_mode" } # Maps `jk` to exit insert mode

25```

26−> NOTE: Typable commands can also be remapped, remember to keep the `:` prefix to indicate it's a typable command.

28## Minor modes

27## Minor modes

@@ -76,5 +75,5 @@ Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes

77Keys can be disabled by binding them to the `no_op` command.

76Keys can be disabled by binding them to the `no_op` command.

79−Commands can be found at [Keymap](https://docs.helix-editor.com/keymap.html) Commands.

78+A list of commands is available in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation

80−> Commands can also be found in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`.

79+ and in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`.

book/src/themes.md+53−45

@@ -1,14 +1,15 @@

1# Themes

3−To use a theme add `theme = "<name>"` to your [`config.toml`](./configuration.md) at the very top of the file before the first section or select it during runtime using `:theme <name>`.

3+To use a theme add `theme = "<name>"` to the top of your [`config.toml`](./configuration.md) file, or select it during runtime using `:theme <name>`.

5## Creating a theme

7−Create a file with the name of your theme as file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes`). The directory might have to be created beforehand.

7+Create a file with the name of your theme as the file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes` or `%AppData%\helix\themes` on Windows). The directory might have to be created beforehand.

9−The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes.

9+> 💡 The names "default" and "base16_default" are reserved for built-in themes

10+> and cannot be overridden by user-defined themes.

11−The default theme.toml can be found [here](https://github.com/helix-editor/helix/blob/master/theme.toml), and user submitted themes [here](https://github.com/helix-editor/helix/blob/master/runtime/themes).

12+### Overview

13Each line in the theme file is specified as below:

14Each line in the theme file is specified as below:

@@ -16,7 +17,7 @@ Each line in the theme file is specified as below:

16key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] }

17key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] }

17```

18```

19−where `key` represents what you want to style, `fg` specifies the foreground color, `bg` the background color, `underline` the underline `style`/`color`, and `modifiers` is a list of style modifiers. `bg`, `underline` and `modifiers` can be omitted to defer to the defaults.

20+Where `key` represents what you want to style, `fg` specifies the foreground color, `bg` the background color, `underline` the underline `style`/`color`, and `modifiers` is a list of style modifiers. `bg`, `underline` and `modifiers` can be omitted to defer to the defaults.

21To specify only the foreground color:

22To specify only the foreground color:

@@ -24,15 +25,30 @@ To specify only the foreground color:

24key = "#ffffff"

25key = "#ffffff"

25```

26```

27−if the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).

28+If the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).

29```toml

30```toml

30"key.key" = "#ffffff"

31"key.key" = "#ffffff"

31```

32```

34+For inspiration, you can find the default `theme.toml`

35+[here](https://github.com/helix-editor/helix/blob/master/theme.toml) and

36+user-submitted themes

37+[here](https://github.com/helix-editor/helix/blob/master/runtime/themes).

38+

39+### Using the linter

40+

41+Use the supplied linting tool to check for errors and missing scopes:

42+

43+```sh

44+cargo xtask themelint onedark # replace onedark with <name>

45+```

46+

47+## The details of theme creation

48+

33### Color palettes

49### Color palettes

35−It's recommended define a palette of named colors, and refer to them from the

51+It's recommended to define a palette of named colors, and refer to them in the

36configuration values in your theme. To do this, add a table called

52configuration values in your theme. To do this, add a table called

37`palette` to your theme file:

53`palette` to your theme file:

@@ -45,8 +61,8 @@ white = "#ffffff"

45black = "#000000"

61black = "#000000"

46```

62```

48−Remember that the `[palette]` table includes all keys after its header,

64+Keep in mind that the `[palette]` table includes all keys after its header,

49−so you should define the palette after normal theme options.

65+so it should be defined after the normal theme options.

51The default palette uses the terminal's default 16 colors, and the colors names

67The default palette uses the terminal's default 16 colors, and the colors names

52are listed below. The `[palette]` section in the config file takes precedence

68are listed below. The `[palette]` section in the config file takes precedence

@@ -73,9 +89,8 @@ over it and is merged into the default palette.

74### Modifiers

90### Modifiers

76−The following values may be used as modifiers.

92+The following values may be used as modifier, provided they are supported by

77−

78−Less common modifiers might not be supported by your terminal emulator.

93+your terminal emulator.

80| Modifier |

95| Modifier |

81| --- |

96| --- |

@@ -89,14 +104,13 @@ Less common modifiers might not be supported by your terminal emulator.

89| `hidden` |

104| `hidden` |

90| `crossed_out` |

105| `crossed_out` |

106

92−> Note: The `underlined` modifier is deprecated and only available for backwards compatibility.

107+> 💡 The `underlined` modifier is deprecated and only available for backwards compatibility.

93> Its behavior is equivalent to setting `underline.style="line"`.

108> Its behavior is equivalent to setting `underline.style="line"`.

109

95−### Underline Style

110+### Underline style

96−

97−One of the following values may be used as a value for `underline.style`.

111

112+One of the following values may be used as a value for `underline.style`, providing it is

99−Some styles might not be supported by your terminal emulator.

113+supported by your terminal emulator.

100

114

101| Modifier |

115| Modifier |

102| --- |

116| --- |

@@ -109,7 +123,7 @@ Some styles might not be supported by your terminal emulator.

109

123

110### Inheritance

124### Inheritance

111

125

112−Extend upon other themes by setting the `inherits` property to an existing theme.

126+Extend other themes by setting the `inherits` property to an existing theme.

113

127

114```toml

128```toml

115inherits = "boo_berry"

129inherits = "boo_berry"

@@ -124,19 +138,19 @@ berry = "#2A2A4D"

124

138

125### Scopes

139### Scopes

126

140

127−The following is a list of scopes available to use for styling.

141+The following is a list of scopes available to use for styling:

128

142

129#### Syntax highlighting

143#### Syntax highlighting

130

144

131These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme).

145These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme).

132

146

133−For a given highlight produced, styling will be determined based on the longest matching theme key. For example, the highlight `function.builtin.static` would match the key `function.builtin` rather than `function`.

147+When determining styling for a highlight, the longest matching theme key will be used. For example, if the highlight is `function.builtin.static`, the key `function.builtin` will be used instead of `function`.

134

148

135We use a similar set of scopes as

149We use a similar set of scopes as

136−[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also

150+[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also

137[TextMate](https://macromates.com/manual/en/language_grammars) scopes.

151[TextMate](https://macromates.com/manual/en/language_grammars) scopes.

138

152

139−- `attribute` - Class attributes, html tag attributes

153+- `attribute` - Class attributes, HTML tag attributes

140

154

141- `type` - Types

155- `type` - Types

142 - `builtin` - Primitive types provided by the language (`int`, `usize`)

156 - `builtin` - Primitive types provided by the language (`int`, `usize`)

@@ -144,7 +158,7 @@ We use a similar set of scopes as

144 - `variant`

158 - `variant`

145- `constructor`

159- `constructor`

146

160

147−- `constant` (TODO: constant.other.placeholder for %v)

161+- `constant` (TODO: constant.other.placeholder for `%v`)

148 - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)

162 - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)

149 - `boolean`

163 - `boolean`

150 - `character`

164 - `character`

@@ -162,11 +176,11 @@ We use a similar set of scopes as

162

176

163- `comment` - Code comments

177- `comment` - Code comments

164 - `line` - Single line comments (`//`)

178 - `line` - Single line comments (`//`)

165− - `block` - Block comments (e.g. (`/* */`)

179+ - `block` - Block comments (e.g. (`/* */`)

166 - `documentation` - Documentation comments (e.g. `///` in Rust)

180 - `documentation` - Documentation comments (e.g. `///` in Rust)

167

181

168- `variable` - Variables

182- `variable` - Variables

169− - `builtin` - Reserved language variables (`self`, `this`, `super`, etc)

183+ - `builtin` - Reserved language variables (`self`, `this`, `super`, etc.)

170 - `parameter` - Function parameters

184 - `parameter` - Function parameters

171 - `other`

185 - `other`

172 - `member` - Fields of composite data types (e.g. structs, unions)

186 - `member` - Fields of composite data types (e.g. structs, unions)

@@ -186,10 +200,10 @@ We use a similar set of scopes as

186 - `return`

200 - `return`

187 - `exception`

201 - `exception`

188 - `operator` - `or`, `in`

202 - `operator` - `or`, `in`

189− - `directive` - Preprocessor directives (`#if` in C)

203+ - `directive` - Preprocessor directives (`#if` in C)

190 - `function` - `fn`, `func`

204 - `function` - `fn`, `func`

191 - `storage` - Keywords describing how things are stored

205 - `storage` - Keywords describing how things are stored

192− - `type` - The type of something, `class`, `function`, `var`, `let`, etc.

206+ - `type` - The type of something, `class`, `function`, `var`, `let`, etc.

193 - `modifier` - Storage modifiers like `static`, `mut`, `const`, `ref`, etc.

207 - `modifier` - Storage modifiers like `static`, `mut`, `const`, `ref`, etc.

194

208

195- `operator` - `||`, `+=`, `>`

209- `operator` - `||`, `+=`, `>`

@@ -216,9 +230,9 @@ We use a similar set of scopes as

216 - `bold`

230 - `bold`

217 - `italic`

231 - `italic`

218 - `link`

232 - `link`

219− - `url` - urls pointed to by links

233+ - `url` - URLs pointed to by links

220− - `label` - non-url link references

234+ - `label` - non-URL link references

221− - `text` - url and image descriptions in links

235+ - `text` - URL and image descriptions in links

222 - `quote`

236 - `quote`

223 - `raw`

237 - `raw`

224 - `inline`

238 - `inline`

@@ -232,19 +246,19 @@ We use a similar set of scopes as

232

246

233#### Interface

247#### Interface

234

248

235−These scopes are used for theming the editor interface.

249+These scopes are used for theming the editor interface:

236

250

237- `markup`

251- `markup`

238 - `normal`

252 - `normal`

239− - `completion` - for completion doc popup ui

253+ - `completion` - for completion doc popup UI

240− - `hover` - for hover popup ui

254+ - `hover` - for hover popup UI

241 - `heading`

255 - `heading`

242− - `completion` - for completion doc popup ui

256+ - `completion` - for completion doc popup UI

243− - `hover` - for hover popup ui

257+ - `hover` - for hover popup UI

244 - `raw`

258 - `raw`

245 - `inline`

259 - `inline`

246− - `completion` - for completion doc popup ui

260+ - `completion` - for completion doc popup UI

247− - `hover` - for hover popup ui

261+ - `hover` - for hover popup UI

248

262

249

263

250| Key | Notes |

264| Key | Notes |

@@ -270,9 +284,9 @@ These scopes are used for theming the editor interface.

270| `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |

284| `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |

271| `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |

285| `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |

272| `ui.statusline.separator` | Separator character in statusline |

286| `ui.statusline.separator` | Separator character in statusline |

273−| `ui.popup` | Documentation popups (e.g Space + k) |

287+| `ui.popup` | Documentation popups (e.g. Space + k) |

274| `ui.popup.info` | Prompt for multiple key options |

288| `ui.popup.info` | Prompt for multiple key options |

275−| `ui.window` | Border lines separating splits |

289+| `ui.window` | Borderlines separating splits |

276| `ui.help` | Description box for commands |

290| `ui.help` | Description box for commands |

277| `ui.text` | Command prompts, popup text, etc. |

291| `ui.text` | Command prompts, popup text, etc. |

278| `ui.text.focus` | |

292| `ui.text.focus` | |

@@ -301,10 +315,4 @@ These scopes are used for theming the editor interface.

301| `diagnostic.warning` | Diagnostics warning (editing area) |

315| `diagnostic.warning` | Diagnostics warning (editing area) |

302| `diagnostic.error` | Diagnostics error (editing area) |

316| `diagnostic.error` | Diagnostics error (editing area) |

303

317

304−You can check compliance to spec with

305−

306−```shell

307−cargo xtask themelint onedark # replace onedark with <name>

308−```

309−

310[editor-section]: ./configuration.md#editor-section

318[editor-section]: ./configuration.md#editor-section

book/src/usage.md+114−92

@@ -1,22 +1,43 @@

1−# Usage

1+# Using Helix

3−(Currently not fully documented, see the [keymappings](./keymap.md) list for more.)

3+

4+- [Registers](#registers)

5+ - [User-defined registers](#user-defined-registers)

6+ - [Special registers](#special-registers)

7+- [Surround](#surround)

8+- [Selecting and manipulating text with textobjects](#selecting-and-manipulating-text-with-textobjects)

9+- [Navigating using tree-sitter textobjects](#navigating-using-tree-sitter-textobjects)

10+- [Moving the selection with syntax-aware motions](#moving-the-selection-with-syntax-aware-motions)

11+

13+For a full interactive introduction to Helix, refer to the

5−See [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction.

14+[tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) which

15+can be accessed via the command `hx --tutor` or `:tutor`.

16+

17+> 💡 Currently, not all functionality is fully documented, please refer to the

18+> [key mappings](./keymap.md) list.

7## Registers

20## Registers

9−Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with `"` being used to select a register:

22+In Helix, registers are storage locations for text and other data, such as the

23+result of a search. Registers can be used to cut, copy, and paste text, similar

24+to the clipboard in other text editors. Usage is similar to Vim, with `"` being

25+used to select a register.

26+

27+### User-defined registers

28+

29+Helix allows you to create your own named registers for storing text, for

30+example:

11- `"ay` - Yank the current selection to register `a`.

32- `"ay` - Yank the current selection to register `a`.

12- `"op` - Paste the text in register `o` after the selection.

33- `"op` - Paste the text in register `o` after the selection.

14−If there is a selected register before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:

35+If a register is selected before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:

16- `"hc` - Store the selection in register `h` and then change it (delete and enter insert mode).

37- `"hc` - Store the selection in register `h` and then change it (delete and enter insert mode).

17- `"md` - Store the selection in register `m` and delete it.

38- `"md` - Store the selection in register `m` and delete it.

19−### Special Registers

40+### Special registers

21| Register character | Contains |

42| Register character | Contains |

22| --- | --- |

43| --- | --- |

@@ -25,41 +46,90 @@ If there is a selected register before invoking a change or delete command, the

25| `"` | Last yanked text |

46| `"` | Last yanked text |

26| `_` | Black hole |

47| `_` | Black hole |

28−> There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the [keymap](keymap.md#space-mode) for the specifics.

49+The system clipboard is not directly supported by a special register. Instead, special commands and keybindings are provided. Refer to the

50+[key map](keymap.md#space-mode) for more details.

51+

29−> The black hole register works as a no-op register, meaning no data will be written to / read from it.

52+The black hole register is a no-op register, meaning that no data will be read or written to it.

31## Surround

54## Surround

33−Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) is built into

56+Helix includes built-in functionality similar to [vim-surround](https://github.com/tpope/vim-surround).

34−helix. The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):

57+The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):

36−![surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif)

59+![Surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif)

61+| Key Sequence | Action |

62+| --------------------------------- | --------------------------------------- |

38−- `ms` - Add surround characters

63+| `ms<char>` (after selecting text) | Add surround characters to selection |

39−- `mr` - Replace surround characters

64+| `mr<char_to_replace><new_char>` | Replace the closest surround characters |

40−- `md` - Delete surround characters

65+| `md<char_to_delete>` | Delete the closest surround characters |

42−`ms` acts on a selection, so select the text first and use `ms<char>`. `mr` and `md` work

43−on the closest pairs found and selections are not required; use counts to act in outer pairs.

67+You can use counts to act on outer pairs.

45−It can also act on multiple selections (yay!). For example, to change every occurrence of `(use)` to `[use]`:

69+Surround can also act on multiple selections. For example, to change every occurrence of `(use)` to `[use]`:

47−- `%` to select the whole file

71+1. `%` to select the whole file

48−- `s` to split the selections on a search term

72+2. `s` to split the selections on a search term

49−- Input `use` and hit Enter

73+3. Input `use` and hit Enter

50−- `mr([` to replace the parens with square brackets

74+4. `mr([` to replace the parentheses with square brackets

52−Multiple characters are currently not supported, but planned.

76+Multiple characters are currently not supported, but planned for future release.

54−## Syntax-tree Motions

78+## Selecting and manipulating text with textobjects

56−`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) move the primary

80+In Helix, textobjects are a way to select, manipulate and operate on a piece of

57−selection according to the selection's place in the syntax tree. Let's walk

81+text in a structured way. They allow you to refer to blocks of text based on

58−through an example to get familiar with them. Many languages have a syntax like

82+their structure or purpose, such as a word, sentence, paragraph, or even a

59−so for function calls:

83+function or block of code.

61−```

85+![Textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif)

86+![Textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif)

87+

88+- `ma` - Select around the object (`va` in Vim, `<alt-a>` in Kakoune)

89+- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` in Kakoune)

90+

91+| Key after `mi` or `ma` | Textobject selected |

92+| --- | --- |

93+| `w` | Word |

94+| `W` | WORD |

95+| `p` | Paragraph |

96+| `(`, `[`, `'`, etc. | Specified surround pairs |

97+| `m` | The closest surround pair |

98+| `f` | Function |

99+| `c` | Class |

100+| `a` | Argument/parameter |

101+| `o` | Comment |

102+| `t` | Test |

103+| `g` | Change |

104+

105+> 💡 `f`, `c`, etc. need a tree-sitter grammar active for the current

106+document and a special tree-sitter query file to work properly. [Only

107+some grammars][lang-support] currently have the query file implemented.

108+Contributions are welcome!

109+

110+## Navigating using tree-sitter textobjects

111+

112+Navigating between functions, classes, parameters, and other elements is

113+possible using tree-sitter and textobject queries. For

114+example to move to the next function use `]f`, to move to previous

115+class use `[c`, and so on.

116+

117+![Tree-sitter-nav-demo][tree-sitter-nav-demo]

118+

119+For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind

120+documentation.

121+

122+> 💡 This feature relies on tree-sitter textobjects

123+> and requires the corresponding query file to work properly.

124+

125+## Moving the selection with syntax-aware motions

126+

127+`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the

128+selection according to its location in the syntax tree. For example, many languages have the

129+following syntax for function calls:

130+

131+```js

62−func(arg1, arg2, arg3)

132+func(arg1, arg2, arg3);

63```

133```

134

65A function call might be parsed by tree-sitter into a tree like the following.

135A function call might be parsed by tree-sitter into a tree like the following.

@@ -93,77 +163,29 @@ a more intuitive tree format:

93 └──────────┘ └──────────┘ └──────────┘

163 └──────────┘ └──────────┘ └──────────┘

94```

164```

165

96−Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf

166+If you have a selection that wraps `arg1` (see the tree above), and you use

97−in the tree above.

167+`Alt-n`, it will select the next sibling in the syntax tree: `arg2`.

168

99−```

169+```js

170+// before

100func([arg1], arg2, arg3)

171func([arg1], arg2, arg3)

172+// after

173+func(arg1, [arg2], arg3);

101```

174```

102

175

103−Using `Alt-n` would select the next sibling in the syntax tree: `arg2`.

176+Similarly, `Alt-o` will expand the selection to the parent node, in this case, the

177+arguments node.

104

178

105−```

179+```js

106−func(arg1, [arg2], arg3)

107−```

108−

109−While `Alt-o` would expand the selection to the parent node. In the tree above we

110−can see that we would select the `arguments` node.

111−

112−```

113−func[(arg1, arg2, arg3)]

180+func[(arg1, arg2, arg3)];

114```

181```

115

182

116There is also some nuanced behavior that prevents you from getting stuck on a

183There is also some nuanced behavior that prevents you from getting stuck on a

117−node with no sibling. If we have a selection on `arg1`, `Alt-p` would bring us

184+node with no sibling. When using `Alt-p` with a selection on `arg1`, the previous

118−to the previous child node. Since `arg1` doesn't have a sibling to its left,

185+child node will be selected. In the event that `arg1` does not have a previous

119−though, we climb the syntax tree and then take the previous selection. So

186+sibling, the selection will move up the syntax tree and select the previous

187+element. As a result, using `Alt-p` with a selection on `arg1` will move the

120−`Alt-p` will move the selection over to the "func" `identifier`.

188+selection to the "func" `identifier`.

121−

122−```

123−[func](arg1, arg2, arg3)

124−```

125−

126−## Textobjects

127−

128−![textobject-demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif)

129−![textobject-treesitter-demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif)

130−

131−- `ma` - Select around the object (`va` in Vim, `<alt-a>` in Kakoune)

132−- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` in Kakoune)

133−

134−| Key after `mi` or `ma` | Textobject selected |

135−| --- | --- |

136−| `w` | Word |

137−| `W` | WORD |

138−| `p` | Paragraph |

139−| `(`, `[`, `'`, etc | Specified surround pairs |

140−| `m` | Closest surround pair |

141−| `f` | Function |

142−| `c` | Class |

143−| `a` | Argument/parameter |

144−| `o` | Comment |

145−| `t` | Test |

146−| `g` | Change |

147−

148−> NOTE: `f`, `c`, etc need a tree-sitter grammar active for the current

149−document and a special tree-sitter query file to work properly. [Only

150−some grammars][lang-support] currently have the query file implemented.

151−Contributions are welcome!

152−

153−## Tree-sitter Textobject Based Navigation

154−

155−Navigating between functions, classes, parameters, etc is made

156−possible by leveraging tree-sitter and textobjects queries. For

157−example to move to the next function use `]f`, to move to previous

158−class use `[c`, and so on.

159−

160−![tree-sitter-nav-demo][tree-sitter-nav-demo]

161−

162−See the [unimpaired][unimpaired-keybinds] section of the keybind

163−documentation for the full reference.

164−

165−> NOTE: This feature is dependent on tree-sitter based textobjects

166−and therefore requires the corresponding query file to work properly.

167

189

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

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

169[unimpaired-keybinds]: ./keymap.md#unimpaired

191[unimpaired-keybinds]: ./keymap.md#unimpaired