From 4b4c9595eab996805c4c1c644a18a7f8ad6cfc1d Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Sun, 15 Jan 2023 18:13:12 +0000 Subject: [PATCH] Format documentation --- book/src/.prettierrc | 3 + book/src/commands.md | 3 +- book/src/configuration.md | 187 ++++++------- book/src/from-vim.md | 5 +- book/src/guides/adding_languages.md | 35 +-- book/src/guides/indent.md | 114 ++++---- book/src/guides/textobject.md | 40 +-- book/src/install.md | 78 +++--- book/src/keymap.md | 398 ++++++++++++++-------------- book/src/lang-support.md | 3 +- book/src/languages.md | 100 +++---- book/src/remapping.md | 22 +- book/src/themes.md | 115 ++++---- book/src/title-page.md | 10 +- book/src/usage.md | 76 +++--- 15 files changed, 633 insertions(+), 556 deletions(-) create mode 100644 book/src/.prettierrc diff --git a/book/src/.prettierrc b/book/src/.prettierrc new file mode 100644 index 000000000000..5b5bd9933e32 --- /dev/null +++ b/book/src/.prettierrc @@ -0,0 +1,3 @@ +{ + "proseWrap": "always" +} diff --git a/book/src/commands.md b/book/src/commands.md index d9a113866b2f..94761b64f703 100644 --- a/book/src/commands.md +++ b/book/src/commands.md @@ -1,5 +1,6 @@ # Commands -Command mode can be activated by pressing `:`, similar to Vim. Built-in commands: +Command mode can be activated by pressing `:`, similar to Vim. Built-in +commands: {{#include ./generated/typable-cmd.md}} diff --git a/book/src/configuration.md b/book/src/configuration.md index a35482e6ecba..e2aecd8768f7 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -1,11 +1,13 @@ # Configuration -To override global configuration parameters, create a `config.toml` file located in your config directory: +To override global configuration parameters, create a `config.toml` file located +in your config directory: -* Linux and Mac: `~/.config/helix/config.toml` -* Windows: `%AppData%\helix\config.toml` +- Linux and Mac: `~/.config/helix/config.toml` +- Windows: `%AppData%\helix\config.toml` -> Hint: You can easily open the config file by typing `:config-open` within Helix normal mode. +> Hint: You can easily open the config file by typing `:config-open` within +> Helix normal mode. Example config: @@ -25,38 +27,38 @@ select = "underline" hidden = false ``` -You may also specify a file to use for configuration with the `-c` or -`--config` CLI argument: `hx -c path/to/custom-config.toml`. +You may also specify a file to use for configuration with the `-c` or `--config` +CLI argument: `hx -c path/to/custom-config.toml`. -It is also possible to trigger configuration file reloading by sending the `USR1` -signal to the helix process, e.g. via `pkill -USR1 hx`. This is only supported -on unix operating systems. +It is also possible to trigger configuration file reloading by sending the +`USR1` signal to the helix process, e.g. via `pkill -USR1 hx`. This is only +supported on unix operating systems. ## Editor ### `[editor]` Section -| Key | Description | Default | -|--|--|---------| -| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `5` | -| `mouse` | Enable mouse mode. | `true` | -| `middle-click-paste` | Middle click paste support. | `true` | -| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` | -| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`
Windows: `["cmd", "/C"]` | -| `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` | -| `cursorline` | Highlight all lines with a cursor. | `false` | -| `cursorcolumn` | Highlight all columns with a cursor. | `false` | -| `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"]` | -| `auto-completion` | Enable automatic pop up of auto-completion. | `true` | -| `auto-format` | Enable automatic formatting on save. | `true` | -| `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` | -| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` | -| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` | -| `auto-info` | Whether to display infoboxes | `true` | -| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` | -| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` | -| `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` | -| `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` | +| Key | Description | Default | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `5` | +| `mouse` | Enable mouse mode. | `true` | +| `middle-click-paste` | Middle click paste support. | `true` | +| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` | +| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`
Windows: `["cmd", "/C"]` | +| `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` | +| `cursorline` | Highlight all lines with a cursor. | `false` | +| `cursorcolumn` | Highlight all columns with a cursor. | `false` | +| `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"]` | +| `auto-completion` | Enable automatic pop up of auto-completion. | `true` | +| `auto-format` | Enable automatic formatting on save. | `true` | +| `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` | +| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` | +| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` | +| `auto-info` | Whether to display infoboxes | `true` | +| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` | +| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` | +| `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` | +| `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` | ### `[editor.statusline]` Section @@ -78,57 +80,60 @@ mode.normal = "NORMAL" mode.insert = "INSERT" mode.select = "SELECT" ``` + The `[editor.statusline]` key takes the following sub-keys: -| Key | Description | Default | -| --- | --- | --- | -| `left` | A list of elements aligned to the left of the statusline | `["mode", "spinner", "file-name"]` | -| `center` | A list of elements aligned to the middle of the statusline | `[]` | -| `right` | A list of elements aligned to the right of the statusline | `["diagnostics", "selections", "position", "file-encoding"]` | -| `separator` | The character used to separate elements in the statusline | `"│"` | -| `mode.normal` | The text shown in the `mode` element for normal mode | `"NOR"` | -| `mode.insert` | The text shown in the `mode` element for insert mode | `"INS"` | -| `mode.select` | The text shown in the `mode` element for select mode | `"SEL"` | +| Key | Description | Default | +| ------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | +| `left` | A list of elements aligned to the left of the statusline | `["mode", "spinner", "file-name"]` | +| `center` | A list of elements aligned to the middle of the statusline | `[]` | +| `right` | A list of elements aligned to the right of the statusline | `["diagnostics", "selections", "position", "file-encoding"]` | +| `separator` | The character used to separate elements in the statusline | `"│"` | +| `mode.normal` | The text shown in the `mode` element for normal mode | `"NOR"` | +| `mode.insert` | The text shown in the `mode` element for insert mode | `"INS"` | +| `mode.select` | The text shown in the `mode` element for select mode | `"SEL"` | The following statusline elements can be configured: -| Key | Description | -| ------ | ----------- | -| `mode` | The current editor mode (`mode.normal`/`mode.insert`/`mode.select`) | -| `spinner` | A progress spinner indicating LSP activity | -| `file-name` | The path/name of the opened file | -| `file-base-name` | The basename of the opened file | -| `file-encoding` | The encoding of the opened file if it differs from UTF-8 | -| `file-line-ending` | The file line endings (CRLF or LF) | -| `total-line-numbers` | The total line numbers of the opened file | -| `file-type` | The type of the opened file | -| `diagnostics` | The number of warnings and/or errors | -| `workspace-diagnostics` | The number of warnings and/or errors on workspace | -| `selections` | The number of active selections | -| `primary-selection-length` | The number of characters currently in primary selection | -| `position` | The cursor position | -| `position-percentage` | The cursor position as a percentage of the total number of lines | -| `separator` | The string defined in `editor.statusline.separator` (defaults to `"│"`) | -| `spacer` | Inserts a space between elements (multiple/contiguous spacers may be specified) | +| Key | Description | +| -------------------------- | ------------------------------------------------------------------------------- | +| `mode` | The current editor mode (`mode.normal`/`mode.insert`/`mode.select`) | +| `spinner` | A progress spinner indicating LSP activity | +| `file-name` | The path/name of the opened file | +| `file-base-name` | The basename of the opened file | +| `file-encoding` | The encoding of the opened file if it differs from UTF-8 | +| `file-line-ending` | The file line endings (CRLF or LF) | +| `total-line-numbers` | The total line numbers of the opened file | +| `file-type` | The type of the opened file | +| `diagnostics` | The number of warnings and/or errors | +| `workspace-diagnostics` | The number of warnings and/or errors on workspace | +| `selections` | The number of active selections | +| `primary-selection-length` | The number of characters currently in primary selection | +| `position` | The cursor position | +| `position-percentage` | The cursor position as a percentage of the total number of lines | +| `separator` | The string defined in `editor.statusline.separator` (defaults to `"│"`) | +| `spacer` | Inserts a space between elements (multiple/contiguous spacers may be specified) | ### `[editor.lsp]` Section -| Key | Description | Default | -| --- | ----------- | ------- | -| `display-messages` | Display LSP progress messages below statusline[^1] | `false` | -| `auto-signature-help` | Enable automatic popup of signature help (parameter hints) | `true` | -| `display-signature-help-docs` | Display docs under signature help popup | `true` | +| Key | Description | Default | +| ----------------------------- | ---------------------------------------------------------- | ------- | +| `display-messages` | Display LSP progress messages below statusline[^1] | `false` | +| `auto-signature-help` | Enable automatic popup of signature help (parameter hints) | `true` | +| `display-signature-help-docs` | Display docs under signature help popup | `true` | -[^1]: By default, a progress spinner is shown in the statusline beside the file path. +[^1]: + By default, a progress spinner is shown in the statusline beside the file + path. ### `[editor.cursor-shape]` Section -Defines the shape of cursor in each mode. Note that due to limitations -of the terminal environment, only the primary cursor can change shape. -Valid values for these options are `block`, `bar`, `underline`, or `hidden`. +Defines the shape of cursor in each mode. Note that due to limitations of the +terminal environment, only the primary cursor can change shape. Valid values for +these options are `block`, `bar`, `underline`, or `hidden`. | Key | Description | Default | -| --- | ----------- | ------- | +| -------- | ------------------------------------------ | ------- | | `normal` | Cursor shape in [normal mode][normal mode] | `block` | | `insert` | Cursor shape in [insert mode][insert mode] | `block` | | `select` | Cursor shape in [select mode][select mode] | `block` | @@ -147,15 +152,15 @@ available, which is not defined by default. All git related options are only enabled in a git repository. -| Key | Description | Default | -|--|--|---------| -|`hidden` | Enables ignoring hidden files. | true -|`parents` | Enables reading ignore files from parent directories. | true -|`ignore` | Enables reading `.ignore` files. | true -|`git-ignore` | Enables reading `.gitignore` files. | true -|`git-global` | Enables reading global .gitignore, whose path is specified in git's config: `core.excludefile` option. | true -|`git-exclude` | Enables reading `.git/info/exclude` files. | true -|`max-depth` | Set with an integer value for maximum depth to recurse. | Defaults to `None`. +| Key | Description | Default | +| ------------- | ------------------------------------------------------------------------------------------------------ | ------------------- | +| `hidden` | Enables ignoring hidden files. | true | +| `parents` | Enables reading ignore files from parent directories. | true | +| `ignore` | Enables reading `.ignore` files. | true | +| `git-ignore` | Enables reading `.gitignore` files. | true | +| `git-global` | Enables reading global .gitignore, whose path is specified in git's config: `core.excludefile` option. | true | +| `git-exclude` | Enables reading `.git/info/exclude` files. | true | +| `max-depth` | Set with an integer value for maximum depth to recurse. | Defaults to `None`. | ### `[editor.auto-pairs]` Section @@ -169,8 +174,9 @@ To disable auto-pairs altogether, set `auto-pairs` to `false`: auto-pairs = false # defaults to `true` ``` -The default pairs are (){}[]''""``, but these can be customized by -setting `auto-pairs` to a TOML table: +The default pairs are +(){}[]''""``, but these can be customized by setting `auto-pairs` +to a TOML table: ```toml [editor.auto-pairs] @@ -182,9 +188,9 @@ setting `auto-pairs` to a TOML table: '<' = '>' ``` -Additionally, this setting can be used in a language config. Unless -the editor setting is `false`, this will override the editor config in -documents with this language. +Additionally, this setting can be used in a language config. Unless the editor +setting is `false`, this will override the editor config in documents with this +language. Example `languages.toml` that adds <> and removes '' @@ -205,18 +211,19 @@ name = "rust" Search specific options. -| Key | Description | Default | -|--|--|---------| -| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` | -| `wrap-around`| Whether the search should wrap after depleting the matches | `true` | +| Key | Description | Default | +| ------------- | -------------------------------------------------------------------------------------------------- | ------- | +| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` | +| `wrap-around` | Whether the search should wrap after depleting the matches | `true` | ### `[editor.whitespace]` Section -Options for rendering whitespace with visible characters. Use `:set whitespace.render all` to temporarily enable visible whitespace. +Options for rendering whitespace with visible characters. Use +`:set whitespace.render all` to temporarily enable visible whitespace. -| Key | Description | Default | -|-----|-------------|---------| -| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `tab`, and `newline`. | `"none"` | +| Key | Description | Default | +| ------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `tab`, and `newline`. | `"none"` | | `characters` | Literal characters to use when rendering whitespace. Sub-keys may be any of `tab`, `space`, `nbsp`, `newline` or `tabpad` | See example below | Example @@ -243,7 +250,7 @@ tabpad = "·" # Tabs will look like "→···" (depending on tab width) Options for rendering vertical indent guides. | Key | Description | Default | -| --- | --- | --- | +| ------------- | ------------------------------------------------------- | ------- | | `render` | Whether to render indent guides. | `false` | | `character` | Literal character to use for rendering the indent guide | `│` | | `skip-levels` | Number of indent levels to skip | `0` | diff --git a/book/src/from-vim.md b/book/src/from-vim.md index 6ace9102746d..ef227ae85f81 100644 --- a/book/src/from-vim.md +++ b/book/src/from-vim.md @@ -7,6 +7,9 @@ going to act on (a word, a paragraph, a line, etc) is selected first and the action itself (delete, change, yank, etc) comes second. A cursor is simply a single width selection. -See also Kakoune's [Migrating from Vim](https://github.com/mawww/kakoune/wiki/Migrating-from-Vim) and Helix's [Migrating from Vim](https://github.com/helix-editor/helix/wiki/Migrating-from-Vim). +See also Kakoune's +[Migrating from Vim](https://github.com/mawww/kakoune/wiki/Migrating-from-Vim) +and Helix's +[Migrating from Vim](https://github.com/helix-editor/helix/wiki/Migrating-from-Vim). > TODO: Mention textobjects, surround, registers diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md index 6598b9bf7488..c4a23373c1c7 100644 --- a/book/src/guides/adding_languages.md +++ b/book/src/guides/adding_languages.md @@ -6,10 +6,10 @@ To add a new language, you need to add a `[[language]]` entry to the `languages.toml` (see the [language configuration section]). When adding a new language or Language Server configuration for an existing -language, run `cargo xtask docgen` to add the new configuration to the -[Language Support][lang-support] docs before creating a pull request. -When adding a Language Server configuration, be sure to update the -[Language Server Wiki][install-lsp-wiki] with installation notes. +language, run `cargo xtask docgen` to add the new configuration to the [Language +Support][lang-support] docs before creating a pull request. When adding a +Language Server configuration, be sure to update the [Language Server +Wiki][install-lsp-wiki] with installation notes. ## Grammar configuration @@ -22,24 +22,29 @@ submitting a pull request. ## 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//`. The tree-sitter +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//`. The tree-sitter [website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries) gives more info on how to write queries. -> NOTE: When evaluating queries, the first matching query takes -precedence, which is different from other editors like Neovim where -the last matching query supersedes the ones before it. See -[this issue][neovim-query-precedence] for an example. +> NOTE: When evaluating queries, the first matching query takes precedence, +> which is different from other editors like Neovim where the last matching +> query supersedes the ones before it. See [this issue][neovim-query-precedence] +> for an example. ## Common Issues -- 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. +- 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. -- If a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in `runtime/grammar/.so` +- If a parser is segfaulting or you want to remove the parser, make sure to + remove the compiled parser in `runtime/grammar/.so` [language configuration section]: ../languages.md -[neovim-query-precedence]: https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090 -[install-lsp-wiki]: https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers +[neovim-query-precedence]: + https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090 +[install-lsp-wiki]: + https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers [lang-support]: ../lang-support.md diff --git a/book/src/guides/indent.md b/book/src/guides/indent.md index 0e259289781e..c12f9fef6352 100644 --- a/book/src/guides/indent.md +++ b/book/src/guides/indent.md @@ -1,35 +1,33 @@ # Adding Indent Queries -Helix uses tree-sitter to correctly indent new lines. This requires -a tree-sitter grammar and an `indent.scm` query file placed in -`runtime/queries/{language}/indents.scm`. The indentation for a line -is calculated by traversing the syntax tree from the lowest node at the -beginning of the new line. Each of these nodes contributes to the total -indent when it is captured by the query (in what way depends on the name -of the capture). - -Note that it matters where these added indents begin. For example, -multiple indent level increases that start on the same line only increase -the total indent level by 1. +Helix uses tree-sitter to correctly indent new lines. This requires a +tree-sitter grammar and an `indent.scm` query file placed in +`runtime/queries/{language}/indents.scm`. The indentation for a line is +calculated by traversing the syntax tree from the lowest node at the beginning +of the new line. Each of these nodes contributes to the total indent when it is +captured by the query (in what way depends on the name of the capture). + +Note that it matters where these added indents begin. For example, multiple +indent level increases that start on the same line only increase the total +indent level by 1. ## Scopes -Added indents don't always apply to the whole node. For example, in most -cases when a node should be indented, we actually only want everything -except for its first line to be indented. For this, there are several -scopes (more scopes may be added in the future if required): +Added indents don't always apply to the whole node. For example, in most cases +when a node should be indented, we actually only want everything except for its +first line to be indented. For this, there are several scopes (more scopes may +be added in the future if required): + +- `all`: This scope applies to the whole captured node. This is only different + from `tail` when the captured node is the first node on its line. -- `all`: -This scope applies to the whole captured node. This is only different from -`tail` when the captured node is the first node on its line. +- `tail`: This scope applies to everything except for the first line of the + captured node. -- `tail`: -This scope applies to everything except for the first line of the -captured node. +Every capture type has a default scope which should do the right thing in most +situations. When a different scope is required, this can be changed by using a +`#set!` declaration anywhere in the pattern: -Every capture type has a default scope which should do the right thing -in most situations. When a different scope is required, this can be -changed by using a `#set!` declaration anywhere in the pattern: ```scm (assignment_expression right: (_) @indent @@ -38,56 +36,54 @@ changed by using a `#set!` declaration anywhere in the pattern: ## Capture Types -- `@indent` (default scope `tail`): -Increase the indent level by 1. Multiple occurrences in the same line -don't stack. If there is at least one `@indent` and one `@outdent` -capture on the same line, the indent level isn't changed at all. - -- `@outdent` (default scope `all`): -Decrease the indent level by 1. The same rules as for `@indent` apply. +- `@indent` (default scope `tail`): Increase the indent level by 1. Multiple + occurrences in the same line don't stack. If there is at least one `@indent` + and one `@outdent` capture on the same line, the indent level isn't changed at + all. -- `@extend`: -Extend the range of this node to the end of the line and to lines that -are indented more than the line that this node starts on. This is useful -for languages like Python, where for the purpose of indentation some nodes -(like functions or classes) should also contain indented lines that follow them. +- `@outdent` (default scope `all`): Decrease the indent level by 1. The same + rules as for `@indent` apply. -- `@extend.prevent-once`: -Prevents the first extension of an ancestor of this node. For example, in Python -a return expression always ends the block that it is in. Note that this only stops the -extension of the next `@extend` capture. If multiple ancestors are captured, -only the extension of the innermost one is prevented. All other ancestors are unaffected -(regardless of whether the innermost ancestor would actually have been extended). +- `@extend`: Extend the range of this node to the end of the line and to lines + that are indented more than the line that this node starts on. This is useful + for languages like Python, where for the purpose of indentation some nodes + (like functions or classes) should also contain indented lines that follow + them. +- `@extend.prevent-once`: Prevents the first extension of an ancestor of this + node. For example, in Python a return expression always ends the block that it + is in. Note that this only stops the extension of the next `@extend` capture. + If multiple ancestors are captured, only the extension of the innermost one is + prevented. All other ancestors are unaffected (regardless of whether the + innermost ancestor would actually have been extended). ## Predicates -In some cases, an S-expression cannot express exactly what pattern should be matched. -For that, tree-sitter allows for predicates to appear anywhere within a pattern, -similar to how `#set!` declarations work: +In some cases, an S-expression cannot express exactly what pattern should be +matched. For that, tree-sitter allows for predicates to appear anywhere within a +pattern, similar to how `#set!` declarations work: + ```scm (some_kind (child_kind) @indent (#predicate? arg1 arg2 ...) ) ``` -The number of arguments depends on the predicate that's used. -Each argument is either a capture (`@name`) or a string (`"some string"`). -The following predicates are supported by tree-sitter: -- `#eq?`/`#not-eq?`: -The first argument (a capture) must/must not be equal to the second argument -(a capture or a string). +The number of arguments depends on the predicate that's used. Each argument is +either a capture (`@name`) or a string (`"some string"`). The following +predicates are supported by tree-sitter: + +- `#eq?`/`#not-eq?`: The first argument (a capture) must/must not be equal to + the second argument (a capture or a string). -- `#match?`/`#not-match?`: -The first argument (a capture) must/must not match the regex given in the -second argument (a string). +- `#match?`/`#not-match?`: The first argument (a capture) must/must not match + the regex given in the second argument (a string). Additionally, we support some custom predicates for indent queries: -- `#not-kind-eq?`: -The kind of the first argument (a capture) must not be equal to the second -argument (a string). +- `#not-kind-eq?`: The kind of the first argument (a capture) must not be equal + to the second argument (a string). -- `#same-line?`/`#not-same-line?`: -The captures given by the 2 arguments must/must not start on the same line. +- `#same-line?`/`#not-same-line?`: The captures given by the 2 arguments + must/must not start on the same line. diff --git a/book/src/guides/textobject.md b/book/src/guides/textobject.md index 8a2173547541..e1446f93e2f0 100644 --- a/book/src/guides/textobject.md +++ b/book/src/guides/textobject.md @@ -1,21 +1,21 @@ # Adding Textobject Queries -Textobjects that are language specific ([like functions, classes, etc][textobjects]) -require an accompanying tree-sitter grammar and a `textobjects.scm` query file -to work properly. Tree-sitter allows us to query the source code syntax tree -and capture specific parts of it. The queries are written in a lisp dialect. -More information on how to write queries can be found in the [official tree-sitter -documentation][tree-sitter-queries]. +Textobjects that are language specific ([like functions, classes, +etc][textobjects]) require an accompanying tree-sitter grammar and a +`textobjects.scm` query file to work properly. Tree-sitter allows us to query +the source code syntax tree and capture specific parts of it. The queries are +written in a lisp dialect. More information on how to write queries can be found +in the [official tree-sitter documentation][tree-sitter-queries]. Query files should be placed in `runtime/queries/{language}/textobjects.scm` -when contributing. Note that to test the query files locally you should put -them under your local runtime directory (`~/.config/helix/runtime` on Linux -for example). +when contributing. Note that to test the query files locally you should put them +under your local runtime directory (`~/.config/helix/runtime` on Linux for +example). The following [captures][tree-sitter-captures] are recognized: | Capture Name | -| --- | +| ------------------ | | `function.inside` | | `function.around` | | `class.inside` | @@ -26,7 +26,8 @@ The following [captures][tree-sitter-captures] are recognized: | `comment.inside` | | `comment.around` | -[Example query files][textobject-examples] can be found in the helix GitHub repository. +[Example query files][textobject-examples] can be found in the helix GitHub +repository. ## Queries for Textobject Based Navigation @@ -37,13 +38,16 @@ following order: - `object.around` - `object.inside` -For example if a `function.around` capture has been already defined for a language -in it's `textobjects.scm` file, function navigation should also work automatically. -`function.movement` should be defined only if the node captured by `function.around` -doesn't make sense in a navigation context. +For example if a `function.around` capture has been already defined for a +language in it's `textobjects.scm` file, function navigation should also work +automatically. `function.movement` should be defined only if the node captured +by `function.around` doesn't make sense in a navigation context. [textobjects]: ../usage.md#textobjects [textobjects-nav]: ../usage.md#tree-sitter-textobject-based-navigation -[tree-sitter-queries]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax -[tree-sitter-captures]: https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes -[textobject-examples]: https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l= +[tree-sitter-queries]: + https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax +[tree-sitter-captures]: + https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes +[textobject-examples]: + https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l= diff --git a/book/src/install.md b/book/src/install.md index bf0ff079c40e..71aebee691e5 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -1,6 +1,7 @@ # Installation -We provide pre-built binaries on the [GitHub Releases page](https://github.com/helix-editor/helix/releases). +We provide pre-built binaries on the +[GitHub Releases page](https://github.com/helix-editor/helix/releases). [![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions) @@ -17,23 +18,23 @@ brew install helix ### NixOS A [flake](https://nixos.wiki/wiki/Flakes) containing the package is available in -the project root. The flake can also be used to spin up a reproducible development -shell for working on Helix with `nix develop`. +the project root. The flake can also be used to spin up a reproducible +development shell for working on Helix with `nix develop`. Flake outputs are cached for each push to master using -[Cachix](https://www.cachix.org/). The flake is configured to -automatically make use of this cache assuming the user accepts -the new settings on first use. +[Cachix](https://www.cachix.org/). The flake is configured to automatically make +use of this cache assuming the user accepts the new settings on first use. If you are using a version of Nix without flakes enabled you can -[install Cachix cli](https://docs.cachix.org/installation); `cachix use helix` will -configure Nix to use cached outputs when possible. +[install Cachix cli](https://docs.cachix.org/installation); `cachix use helix` +will configure Nix to use cached outputs when possible. ### Arch Linux Releases are available in the `community` repository. -A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also available on the AUR, which builds the master branch. +A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also +available on the AUR, which builds the master branch. ### Fedora Linux @@ -52,8 +53,8 @@ sudo xbps-install helix ## Windows -Helix can be installed using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/) -or [MSYS2](https://msys2.org/). +Helix can be installed using [Scoop](https://scoop.sh/), +[Chocolatey](https://chocolatey.org/) or [MSYS2](https://msys2.org/). **Scoop:** @@ -71,19 +72,19 @@ choco install helix Choose the proper command for your system from below: - - For 32 bit Windows 7 or above: +- For 32 bit Windows 7 or above: ``` pacman -S mingw-w64-i686-helix ``` - - For 64 bit Windows 7 or above: +- For 64 bit Windows 7 or above: ``` pacman -S mingw-w64-x86_64-helix ``` - - For 64 bit Windows 8.1 or above: +- For 64 bit Windows 8.1 or above: ``` pacman -S mingw-w64-ucrt-x86_64-helix @@ -97,11 +98,13 @@ cd helix cargo install --path helix-term --locked ``` -This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`. +This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter +grammars in `./runtime/grammars`. -Helix also needs its runtime files so make sure to copy/symlink the `runtime/` directory into the -config directory (for example `~/.config/helix/runtime` on Linux/macOS). This location can be overridden -via the `HELIX_RUNTIME` environment variable. +Helix also needs its runtime files so make sure to copy/symlink the `runtime/` +directory into the config directory (for example `~/.config/helix/runtime` on +Linux/macOS). This location can be overridden via the `HELIX_RUNTIME` +environment variable. | OS | Command | | -------------------- | ------------------------------------------------ | @@ -109,8 +112,9 @@ via the `HELIX_RUNTIME` environment variable. | Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` | | Linux / macOS | `ln -s $PWD/runtime ~/.config/helix/runtime` | -Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires -elevated privileges - i.e. PowerShell or Cmd must be run as administrator. +Starting with Windows Vista you can also create symbolic links on Windows. Note +that this requires elevated privileges - i.e. PowerShell or Cmd must be run as +administrator. **PowerShell:** @@ -125,22 +129,28 @@ cd %appdata%\helix mklink /D runtime "\runtime" ``` -The runtime location can be overridden via the `HELIX_RUNTIME` environment variable. +The runtime location can be overridden via the `HELIX_RUNTIME` environment +variable. -> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --path helix-term --locked`, -> tree-sitter grammars will be built in `$HELIX_RUNTIME/grammars`. +> NOTE: if `HELIX_RUNTIME` is set prior to calling +> `cargo install --path helix-term --locked`, tree-sitter grammars will be built +> in `$HELIX_RUNTIME/grammars`. If you plan on keeping the repo locally, an alternative to copying/symlinking runtime files is to set `HELIX_RUNTIME=/path/to/helix/runtime` (`HELIX_RUNTIME=$PWD/runtime` if you're in the helix repo directory). -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: +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: ```bash cp contrib/Helix.desktop ~/.local/share/applications ``` -To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`: +To use another terminal than the default, you will need to modify the `.desktop` +file. For example, to use `kitty`: ```bash sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop @@ -151,21 +161,25 @@ Please note: there is no icon for Helix yet, so the system default will be used. ## Finishing up the installation -To make sure everything is set up as expected you should finally run the helix healthcheck via +To make sure everything is set up as expected you should finally run the helix +healthcheck via ``` hx --health ``` -For more information on the information displayed in the health check results refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck). +For more information on the information displayed in the health check results +refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck). ### Building tree-sitter grammars -Tree-sitter grammars must be fetched and compiled if not pre-packaged. -Fetch grammars with `hx --grammar fetch` (requires `git`) and compile them -with `hx --grammar build` (requires a C++ compiler). +Tree-sitter grammars must be fetched and compiled if not pre-packaged. Fetch +grammars with `hx --grammar fetch` (requires `git`) and compile them with +`hx --grammar build` (requires a C++ compiler). ### Installing language servers -Language servers can optionally be installed if you want their features (auto-complete, diagnostics etc.). -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. +Language servers can optionally be installed if you want their features +(auto-complete, diagnostics etc.). 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. diff --git a/book/src/keymap.md b/book/src/keymap.md index b38a1f44ea95..f43e2a45d9e9 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -29,38 +29,38 @@ > NOTE: Unlike Vim, `f`, `F`, `t` and `T` are not confined to the current line. -| Key | Description | Command | -| ----- | ----------- | ------- | -| `h`, `Left` | Move left | `move_char_left` | -| `j`, `Down` | Move down | `move_line_down` | -| `k`, `Up` | Move up | `move_line_up` | -| `l`, `Right` | Move right | `move_char_right` | -| `w` | Move next word start | `move_next_word_start` | -| `b` | Move previous word start | `move_prev_word_start` | -| `e` | Move next word end | `move_next_word_end` | -| `W` | Move next WORD start | `move_next_long_word_start` | -| `B` | Move previous WORD start | `move_prev_long_word_start` | -| `E` | Move next WORD end | `move_next_long_word_end` | -| `t` | Find 'till next char | `find_till_char` | -| `f` | Find next char | `find_next_char` | -| `T` | Find 'till previous char | `till_prev_char` | -| `F` | Find previous char | `find_prev_char` | -| `G` | Go to line number `` | `goto_line` | -| `Alt-.` | Repeat last motion (`f`, `t` or `m`) | `repeat_last_motion` | -| `Home` | Move to the start of the line | `goto_line_start` | -| `End` | Move to the end of the line | `goto_line_end` | -| `Ctrl-b`, `PageUp` | Move page up | `page_up` | -| `Ctrl-f`, `PageDown` | Move page down | `page_down` | -| `Ctrl-u` | Move half page up | `half_page_up` | -| `Ctrl-d` | Move half page down | `half_page_down` | -| `Ctrl-i` | Jump forward on the jumplist | `jump_forward` | -| `Ctrl-o` | Jump backward on the jumplist | `jump_backward` | -| `Ctrl-s` | Save the current selection to the jumplist | `save_selection` | +| Key | Description | Command | +| -------------------- | ------------------------------------------ | --------------------------- | +| `h`, `Left` | Move left | `move_char_left` | +| `j`, `Down` | Move down | `move_line_down` | +| `k`, `Up` | Move up | `move_line_up` | +| `l`, `Right` | Move right | `move_char_right` | +| `w` | Move next word start | `move_next_word_start` | +| `b` | Move previous word start | `move_prev_word_start` | +| `e` | Move next word end | `move_next_word_end` | +| `W` | Move next WORD start | `move_next_long_word_start` | +| `B` | Move previous WORD start | `move_prev_long_word_start` | +| `E` | Move next WORD end | `move_next_long_word_end` | +| `t` | Find 'till next char | `find_till_char` | +| `f` | Find next char | `find_next_char` | +| `T` | Find 'till previous char | `till_prev_char` | +| `F` | Find previous char | `find_prev_char` | +| `G` | Go to line number `` | `goto_line` | +| `Alt-.` | Repeat last motion (`f`, `t` or `m`) | `repeat_last_motion` | +| `Home` | Move to the start of the line | `goto_line_start` | +| `End` | Move to the end of the line | `goto_line_end` | +| `Ctrl-b`, `PageUp` | Move page up | `page_up` | +| `Ctrl-f`, `PageDown` | Move page down | `page_down` | +| `Ctrl-u` | Move half page up | `half_page_up` | +| `Ctrl-d` | Move half page down | `half_page_down` | +| `Ctrl-i` | Jump forward on the jumplist | `jump_forward` | +| `Ctrl-o` | Jump backward on the jumplist | `jump_backward` | +| `Ctrl-s` | Save the current selection to the jumplist | `save_selection` | ### Changes | Key | Description | Command | -| ----- | ----------- | ------- | +| ----------- | -------------------------------------------------------------------- | ------------------------- | | `r` | Replace with a character | `replace` | | `R` | Replace with yanked text | `replace_with_yanked` | | `~` | Switch case of the selected text | `switch_case` | @@ -95,68 +95,69 @@ #### Shell -| Key | Description | Command | -| ------ | ----------- | ------- | +| Key | Description | Command | +| ----------------------- | -------------------------------------------------------------------------------- | --------------------- | | | | Pipe each selection through shell command, replacing with output | `shell_pipe` | | Alt-| | Pipe each selection into shell command, ignoring output | `shell_pipe_to` | -| `!` | Run shell command, inserting output before each selection | `shell_insert_output` | -| `Alt-!` | Run shell command, appending output after each selection | `shell_append_output` | -| `$` | Pipe each selection into shell command, keep selections where command returned 0 | `shell_keep_pipe` | - +| `!` | Run shell command, inserting output before each selection | `shell_insert_output` | +| `Alt-!` | Run shell command, appending output after each selection | `shell_append_output` | +| `$` | Pipe each selection into shell command, keep selections where command returned 0 | `shell_keep_pipe` | ### Selection manipulation -| Key | Description | Command | -| ----- | ----------- | ------- | -| `s` | Select all regex matches inside selections | `select_regex` | -| `S` | Split selection into subselections on regex matches | `split_selection` | -| `Alt-s` | Split selection on newlines | `split_selection_on_newline` | -| `Alt-_ ` | Merge consecutive selections | `merge_consecutive_selections` | -| `&` | Align selection in columns | `align_selections` | -| `_` | Trim whitespace from the selection | `trim_selections` | -| `;` | Collapse selection onto a single cursor | `collapse_selection` | -| `Alt-;` | Flip selection cursor and anchor | `flip_selections` | -| `Alt-:` | Ensures the selection is in forward direction | `ensure_selections_forward` | -| `,` | Keep only the primary selection | `keep_primary_selection` | -| `Alt-,` | Remove the primary selection | `remove_primary_selection` | -| `C` | Copy selection onto the next line (Add cursor below) | `copy_selection_on_next_line` | -| `Alt-C` | Copy selection onto the previous line (Add cursor above) | `copy_selection_on_prev_line` | -| `(` | Rotate main selection backward | `rotate_selections_backward` | -| `)` | Rotate main selection forward | `rotate_selections_forward` | -| `Alt-(` | Rotate selection contents backward | `rotate_selection_contents_backward` | -| `Alt-)` | Rotate selection contents forward | `rotate_selection_contents_forward` | -| `%` | Select entire file | `select_all` | -| `x` | Select current line, if already selected, extend to next line | `extend_line_below` | -| `X` | Extend selection to line bounds (line-wise selection) | `extend_to_line_bounds` | -| `Alt-x` | Shrink selection to line bounds (line-wise selection) | `shrink_to_line_bounds` | -| `J` | Join lines inside selection | `join_selections` | -| `Alt-J` | Join lines inside selection and select space | `join_selections_space` | -| `K` | Keep selections matching the regex | `keep_selections` | -| `Alt-K` | Remove selections matching the regex | `remove_selections` | -| `Ctrl-c` | Comment/uncomment the selections | `toggle_comments` | -| `Alt-o`, `Alt-up` | Expand selection to parent syntax node (**TS**) | `expand_selection` | -| `Alt-i`, `Alt-down` | Shrink syntax tree object selection (**TS**) | `shrink_selection` | -| `Alt-p`, `Alt-left` | Select previous sibling node in syntax tree (**TS**) | `select_prev_sibling` | -| `Alt-n`, `Alt-right` | Select next sibling node in syntax tree (**TS**) | `select_next_sibling` | +| Key | Description | Command | +| -------------------- | ------------------------------------------------------------- | ------------------------------------ | +| `s` | Select all regex matches inside selections | `select_regex` | +| `S` | Split selection into subselections on regex matches | `split_selection` | +| `Alt-s` | Split selection on newlines | `split_selection_on_newline` | +| `Alt-_ ` | Merge consecutive selections | `merge_consecutive_selections` | +| `&` | Align selection in columns | `align_selections` | +| `_` | Trim whitespace from the selection | `trim_selections` | +| `;` | Collapse selection onto a single cursor | `collapse_selection` | +| `Alt-;` | Flip selection cursor and anchor | `flip_selections` | +| `Alt-:` | Ensures the selection is in forward direction | `ensure_selections_forward` | +| `,` | Keep only the primary selection | `keep_primary_selection` | +| `Alt-,` | Remove the primary selection | `remove_primary_selection` | +| `C` | Copy selection onto the next line (Add cursor below) | `copy_selection_on_next_line` | +| `Alt-C` | Copy selection onto the previous line (Add cursor above) | `copy_selection_on_prev_line` | +| `(` | Rotate main selection backward | `rotate_selections_backward` | +| `)` | Rotate main selection forward | `rotate_selections_forward` | +| `Alt-(` | Rotate selection contents backward | `rotate_selection_contents_backward` | +| `Alt-)` | Rotate selection contents forward | `rotate_selection_contents_forward` | +| `%` | Select entire file | `select_all` | +| `x` | Select current line, if already selected, extend to next line | `extend_line_below` | +| `X` | Extend selection to line bounds (line-wise selection) | `extend_to_line_bounds` | +| `Alt-x` | Shrink selection to line bounds (line-wise selection) | `shrink_to_line_bounds` | +| `J` | Join lines inside selection | `join_selections` | +| `Alt-J` | Join lines inside selection and select space | `join_selections_space` | +| `K` | Keep selections matching the regex | `keep_selections` | +| `Alt-K` | Remove selections matching the regex | `remove_selections` | +| `Ctrl-c` | Comment/uncomment the selections | `toggle_comments` | +| `Alt-o`, `Alt-up` | Expand selection to parent syntax node (**TS**) | `expand_selection` | +| `Alt-i`, `Alt-down` | Shrink syntax tree object selection (**TS**) | `shrink_selection` | +| `Alt-p`, `Alt-left` | Select previous sibling node in syntax tree (**TS**) | `select_prev_sibling` | +| `Alt-n`, `Alt-right` | Select next sibling node in syntax tree (**TS**) | `select_next_sibling` | ### Search -Search commands all operate on the `/` register by default. Use `"` to operate on a different one. +Search commands all operate on the `/` register by default. Use `"` to +operate on a different one. -| Key | Description | Command | -| ----- | ----------- | ------- | -| `/` | Search for regex pattern | `search` | -| `?` | Search for previous pattern | `rsearch` | -| `n` | Select next search match | `search_next` | -| `N` | Select previous search match | `search_prev` | -| `*` | Use current selection as the search pattern | `search_selection` | +| Key | Description | Command | +| --- | ------------------------------------------- | ------------------ | +| `/` | Search for regex pattern | `search` | +| `?` | Search for previous pattern | `rsearch` | +| `n` | Select next search match | `search_next` | +| `N` | Select previous search match | `search_prev` | +| `*` | Use current selection as the search pattern | `search_selection` | ### Minor modes -These sub-modes are accessible from normal mode and typically switch back to normal mode after a command. +These sub-modes are accessible from normal mode and typically switch back to +normal mode after a command. | Key | Description | Command | -| ----- | ----------- | ------- | +| -------- | -------------------------------------------------- | -------------- | | `v` | Enter [select (extend) mode](#select--extend-mode) | `select_mode` | | `g` | Enter [goto mode](#goto-mode) | N/A | | `m` | Enter [match mode](#match-mode) | N/A | @@ -173,12 +174,10 @@ Accessed by typing `z` in [normal mode](#normal-mode). View mode is intended for scrolling and manipulating the view without changing the selection. The "sticky" variant of this mode (accessed by typing `Z` in normal mode) is persistent; use the Escape key to return to normal mode after -usage (useful when you're simply looking over text and not actively editing -it). - +usage (useful when you're simply looking over text and not actively editing it). | Key | Description | Command | -| ----- | ----------- | ------- | +| -------------------- | --------------------------------------------------------- | ------------------- | | `z`, `c` | Vertically center the line | `align_view_center` | | `t` | Align the line to the top of the screen | `align_view_top` | | `b` | Align the line to the bottom of the screen | `align_view_bottom` | @@ -196,26 +195,26 @@ Accessed by typing `g` in [normal mode](#normal-mode). Jumps to various locations. -| Key | Description | Command | -| ----- | ----------- | ------- | -| `g` | Go to line number `` else start of file | `goto_file_start` | -| `e` | Go to the end of the file | `goto_last_line` | -| `f` | Go to files in the selection | `goto_file` | -| `h` | Go to the start of the line | `goto_line_start` | -| `l` | Go to the end of the line | `goto_line_end` | -| `s` | Go to first non-whitespace character of the line | `goto_first_nonwhitespace` | -| `t` | Go to the top of the screen | `goto_window_top` | -| `c` | Go to the middle of the screen | `goto_window_center` | -| `b` | Go to the bottom of the screen | `goto_window_bottom` | -| `d` | Go to definition (**LSP**) | `goto_definition` | -| `y` | Go to type definition (**LSP**) | `goto_type_definition` | -| `r` | Go to references (**LSP**) | `goto_reference` | -| `i` | Go to implementation (**LSP**) | `goto_implementation` | -| `a` | Go to the last accessed/alternate file | `goto_last_accessed_file` | -| `m` | Go to the last modified/alternate file | `goto_last_modified_file` | -| `n` | Go to next buffer | `goto_next_buffer` | -| `p` | Go to previous buffer | `goto_previous_buffer` | -| `.` | Go to last modification in current file | `goto_last_modification` | +| Key | Description | Command | +| --- | ------------------------------------------------ | -------------------------- | +| `g` | Go to line number `` else start of file | `goto_file_start` | +| `e` | Go to the end of the file | `goto_last_line` | +| `f` | Go to files in the selection | `goto_file` | +| `h` | Go to the start of the line | `goto_line_start` | +| `l` | Go to the end of the line | `goto_line_end` | +| `s` | Go to first non-whitespace character of the line | `goto_first_nonwhitespace` | +| `t` | Go to the top of the screen | `goto_window_top` | +| `c` | Go to the middle of the screen | `goto_window_center` | +| `b` | Go to the bottom of the screen | `goto_window_bottom` | +| `d` | Go to definition (**LSP**) | `goto_definition` | +| `y` | Go to type definition (**LSP**) | `goto_type_definition` | +| `r` | Go to references (**LSP**) | `goto_reference` | +| `i` | Go to implementation (**LSP**) | `goto_implementation` | +| `a` | Go to the last accessed/alternate file | `goto_last_accessed_file` | +| `m` | Go to the last modified/alternate file | `goto_last_modified_file` | +| `n` | Go to next buffer | `goto_next_buffer` | +| `p` | Go to previous buffer | `goto_previous_buffer` | +| `.` | Go to last modification in current file | `goto_last_modification` | #### Match mode @@ -225,7 +224,7 @@ See the relevant section in [Usage](./usage.md) for an explanation about [surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. | Key | Description | Command | -| ----- | ----------- | ------- | +| ---------------- | ----------------------------------------------- | -------------------------- | | `m` | Goto matching bracket (**TS**) | `match_brackets` | | `s` `` | Surround current selection with `` | `surround_add` | | `r` `` | Replace surround character `` with `` | `surround_replace` | @@ -242,7 +241,7 @@ Accessed by typing `Ctrl-w` in [normal mode](#normal-mode). This layer is similar to Vim keybindings as Kakoune does not support window. | Key | Description | Command | -| ----- | ------------- | ------- | +| ---------------------- | ---------------------------------------------------- | ----------------- | | `w`, `Ctrl-w` | Switch to next window | `rotate_view` | | `v`, `Ctrl-v` | Vertical right split | `vsplit` | | `s`, `Ctrl-s` | Horizontal bottom split | `hsplit` | @@ -265,46 +264,48 @@ Accessed by typing `Space` in [normal mode](#normal-mode). This layer is a kludge of mappings, mostly pickers. -| Key | Description | Command | -| ----- | ----------- | ------- | -| `f` | Open file picker | `file_picker` | -| `F` | Open file picker at current working directory | `file_picker_in_current_directory` | -| `b` | Open buffer picker | `buffer_picker` | -| `j` | Open jumplist picker | `jumplist_picker` | -| `k` | Show documentation for item under cursor in a [popup](#popup) (**LSP**) | `hover` | -| `s` | Open document symbol picker (**LSP**) | `symbol_picker` | -| `S` | Open workspace symbol picker (**LSP**) | `workspace_symbol_picker` | -| `d` | Open document diagnostics picker (**LSP**) | `diagnostics_picker` | -| `D` | Open workspace diagnostics picker (**LSP**) | `workspace_diagnostics_picker` | -| `r` | Rename symbol (**LSP**) | `rename_symbol` | -| `a` | Apply code action (**LSP**) | `code_action` | -| `'` | Open last fuzzy picker | `last_picker` | -| `w` | Enter [window mode](#window-mode) | N/A | -| `p` | Paste system clipboard after selections | `paste_clipboard_after` | -| `P` | Paste system clipboard before selections | `paste_clipboard_before` | -| `y` | Join and yank selections to clipboard | `yank_joined_to_clipboard` | -| `Y` | Yank main selection to clipboard | `yank_main_selection_to_clipboard` | -| `R` | Replace selections by clipboard contents | `replace_selections_with_clipboard` | -| `/` | Global search in workspace folder | `global_search` | -| `?` | Open command palette | `command_palette` | - -> TIP: Global search displays results in a fuzzy picker, use `Space + '` to bring it back up after opening a file. +| Key | Description | Command | +| --- | ----------------------------------------------------------------------- | ----------------------------------- | +| `f` | Open file picker | `file_picker` | +| `F` | Open file picker at current working directory | `file_picker_in_current_directory` | +| `b` | Open buffer picker | `buffer_picker` | +| `j` | Open jumplist picker | `jumplist_picker` | +| `k` | Show documentation for item under cursor in a [popup](#popup) (**LSP**) | `hover` | +| `s` | Open document symbol picker (**LSP**) | `symbol_picker` | +| `S` | Open workspace symbol picker (**LSP**) | `workspace_symbol_picker` | +| `d` | Open document diagnostics picker (**LSP**) | `diagnostics_picker` | +| `D` | Open workspace diagnostics picker (**LSP**) | `workspace_diagnostics_picker` | +| `r` | Rename symbol (**LSP**) | `rename_symbol` | +| `a` | Apply code action (**LSP**) | `code_action` | +| `'` | Open last fuzzy picker | `last_picker` | +| `w` | Enter [window mode](#window-mode) | N/A | +| `p` | Paste system clipboard after selections | `paste_clipboard_after` | +| `P` | Paste system clipboard before selections | `paste_clipboard_before` | +| `y` | Join and yank selections to clipboard | `yank_joined_to_clipboard` | +| `Y` | Yank main selection to clipboard | `yank_main_selection_to_clipboard` | +| `R` | Replace selections by clipboard contents | `replace_selections_with_clipboard` | +| `/` | Global search in workspace folder | `global_search` | +| `?` | Open command palette | `command_palette` | + +> TIP: Global search displays results in a fuzzy picker, use `Space + '` to +> bring it back up after opening a file. ##### Popup Displays documentation for item under cursor. | Key | Description | -| ---- | ----------- | +| -------- | ----------- | | `Ctrl-u` | Scroll up | | `Ctrl-d` | Scroll down | #### Unimpaired -Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired). +Mappings in the style of +[vim-unimpaired](https://github.com/tpope/vim-unimpaired). | Key | Description | Command | -| ----- | ----------- | ------- | +| -------- | -------------------------------------------- | --------------------- | | `[d` | Go to previous diagnostic (**LSP**) | `goto_prev_diag` | | `]d` | Go to next diagnostic (**LSP**) | `goto_next_diag` | | `[D` | Go to first diagnostic in document (**LSP**) | `goto_first_diag` | @@ -330,43 +331,43 @@ Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaire ## Insert mode -Insert mode bindings are somewhat minimal by default. Helix is designed to -be a modal editor, and this is reflected in the user experience and internal +Insert mode bindings are somewhat minimal by default. Helix is designed to be a +modal editor, and this is reflected in the user experience and internal mechanics. For example, changes to the text are only saved for undos when escaping from insert mode to normal mode. For this reason, new users are strongly encouraged to learn the modal editing paradigm to get the smoothest experience. -| Key | Description | Command | -| ----- | ----------- | ------- | -| `Escape` | Switch to normal mode | `normal_mode` | -| `Ctrl-s` | Commit undo checkpoint | `commit_undo_checkpoint` | -| `Ctrl-x` | Autocomplete | `completion` | -| `Ctrl-r` | Insert a register content | `insert_register` | -| `Ctrl-w`, `Alt-Backspace` | Delete previous word | `delete_word_backward` | -| `Alt-d`, `Alt-Delete` | Delete next word | `delete_word_forward` | -| `Ctrl-u` | Delete to start of line | `kill_to_line_start` | -| `Ctrl-k` | Delete to end of line | `kill_to_line_end` | -| `Ctrl-h`, `Backspace` | Delete previous char | `delete_char_backward` | -| `Ctrl-d`, `Delete` | Delete next char | `delete_char_forward` | -| `Ctrl-j`, `Enter` | Insert new line | `insert_newline` | +| Key | Description | Command | +| ------------------------- | ------------------------- | ------------------------ | +| `Escape` | Switch to normal mode | `normal_mode` | +| `Ctrl-s` | Commit undo checkpoint | `commit_undo_checkpoint` | +| `Ctrl-x` | Autocomplete | `completion` | +| `Ctrl-r` | Insert a register content | `insert_register` | +| `Ctrl-w`, `Alt-Backspace` | Delete previous word | `delete_word_backward` | +| `Alt-d`, `Alt-Delete` | Delete next word | `delete_word_forward` | +| `Ctrl-u` | Delete to start of line | `kill_to_line_start` | +| `Ctrl-k` | Delete to end of line | `kill_to_line_end` | +| `Ctrl-h`, `Backspace` | Delete previous char | `delete_char_backward` | +| `Ctrl-d`, `Delete` | Delete next char | `delete_char_forward` | +| `Ctrl-j`, `Enter` | Insert new line | `insert_newline` | These keys are not recommended, but are included for new users less familiar with modal editors. -| Key | Description | Command | -| ----- | ----------- | ------- | -| `Up` | Move to previous line | `move_line_up` | -| `Down` | Move to next line | `move_line_down` | -| `Left` | Backward a char | `move_char_left` | -| `Right` | Forward a char | `move_char_right` | -| `PageUp` | Move one page up | `page_up` | -| `PageDown` | Move one page down | `page_down` | -| `Home` | Move to line start | `goto_line_start` | -| `End` | Move to line end | `goto_line_end_newline` | +| Key | Description | Command | +| ---------- | --------------------- | ----------------------- | +| `Up` | Move to previous line | `move_line_up` | +| `Down` | Move to next line | `move_line_down` | +| `Left` | Backward a char | `move_char_left` | +| `Right` | Forward a char | `move_char_right` | +| `PageUp` | Move one page up | `page_up` | +| `PageDown` | Move one page down | `page_down` | +| `Home` | Move to line start | `goto_line_start` | +| `End` | Move to line end | `goto_line_end_newline` | -If you want to disable them in insert mode as you become more comfortable with modal editing, you can use -the following in your `config.toml`: +If you want to disable them in insert mode as you become more comfortable with +modal editing, you can use the following in your `config.toml`: ```toml [keys.insert] @@ -382,58 +383,57 @@ end = "no_op" ## Select / extend mode -This mode echoes Normal mode, but changes any movements to extend -selections rather than replace them. Goto motions are also changed to -extend, so that `vgl` for example extends the selection to the end of -the line. +This mode echoes Normal mode, but changes any movements to extend selections +rather than replace them. Goto motions are also changed to extend, so that `vgl` +for example extends the selection to the end of the line. Search is also affected. By default, `n` and `N` will remove the current -selection and select the next instance of the search term. Toggling this -mode before pressing `n` or `N` makes it possible to keep the current -selection. Toggling it on and off during your iterative searching allows -you to selectively add search terms to your selections. +selection and select the next instance of the search term. Toggling this mode +before pressing `n` or `N` makes it possible to keep the current selection. +Toggling it on and off during your iterative searching allows you to selectively +add search terms to your selections. ## Picker Keys to use within picker. Remapping currently not supported. -| Key | Description | -| ----- | ------------- | -| `Shift-Tab`, `Up`, `Ctrl-p` | Previous entry | -| `Tab`, `Down`, `Ctrl-n` | Next entry | -| `PageUp`, `Ctrl-u` | Page up | -| `PageDown`, `Ctrl-d` | Page down | -| `Home` | Go to first entry | -| `End` | Go to last entry | -| `Enter` | Open selected | -| `Ctrl-s` | Open horizontally | -| `Ctrl-v` | Open vertically | -| `Ctrl-t` | Toggle preview | -| `Escape`, `Ctrl-c` | Close picker | +| Key | Description | +| --------------------------- | ----------------- | +| `Shift-Tab`, `Up`, `Ctrl-p` | Previous entry | +| `Tab`, `Down`, `Ctrl-n` | Next entry | +| `PageUp`, `Ctrl-u` | Page up | +| `PageDown`, `Ctrl-d` | Page down | +| `Home` | Go to first entry | +| `End` | Go to last entry | +| `Enter` | Open selected | +| `Ctrl-s` | Open horizontally | +| `Ctrl-v` | Open vertically | +| `Ctrl-t` | Toggle preview | +| `Escape`, `Ctrl-c` | Close picker | ## Prompt Keys to use within prompt, Remapping currently not supported. -| Key | Description | -| ----- | ------------- | -| `Escape`, `Ctrl-c` | Close prompt | -| `Alt-b`, `Ctrl-Left` | Backward a word | -| `Ctrl-b`, `Left` | Backward a char | -| `Alt-f`, `Ctrl-Right` | Forward a word | -| `Ctrl-f`, `Right` | Forward a char | -| `Ctrl-e`, `End` | Move prompt end | -| `Ctrl-a`, `Home` | Move prompt start | -| `Ctrl-w`, `Alt-Backspace`, `Ctrl-Backspace` | Delete previous word | -| `Alt-d`, `Alt-Delete`, `Ctrl-Delete` | Delete next word | -| `Ctrl-u` | Delete to start of line | -| `Ctrl-k` | Delete to end of line | -| `Backspace`, `Ctrl-h` | Delete previous char | -| `Delete`, `Ctrl-d` | Delete next char | -| `Ctrl-s` | Insert a word under doc cursor, may be changed to Ctrl-r Ctrl-w later | -| `Ctrl-p`, `Up` | Select previous history | -| `Ctrl-n`, `Down` | Select next history | -| `Ctrl-r` | Insert the content of the register selected by following input char | -| `Tab` | Select next completion item | -| `BackTab` | Select previous completion item | -| `Enter` | Open selected | +| Key | Description | +| ------------------------------------------- | --------------------------------------------------------------------- | +| `Escape`, `Ctrl-c` | Close prompt | +| `Alt-b`, `Ctrl-Left` | Backward a word | +| `Ctrl-b`, `Left` | Backward a char | +| `Alt-f`, `Ctrl-Right` | Forward a word | +| `Ctrl-f`, `Right` | Forward a char | +| `Ctrl-e`, `End` | Move prompt end | +| `Ctrl-a`, `Home` | Move prompt start | +| `Ctrl-w`, `Alt-Backspace`, `Ctrl-Backspace` | Delete previous word | +| `Alt-d`, `Alt-Delete`, `Ctrl-Delete` | Delete next word | +| `Ctrl-u` | Delete to start of line | +| `Ctrl-k` | Delete to end of line | +| `Backspace`, `Ctrl-h` | Delete previous char | +| `Delete`, `Ctrl-d` | Delete next char | +| `Ctrl-s` | Insert a word under doc cursor, may be changed to Ctrl-r Ctrl-w later | +| `Ctrl-p`, `Up` | Select previous history | +| `Ctrl-n`, `Down` | Select next history | +| `Ctrl-r` | Insert the content of the register selected by following input char | +| `Tab` | Select next completion item | +| `BackTab` | Select previous completion item | +| `Enter` | Open selected | diff --git a/book/src/lang-support.md b/book/src/lang-support.md index 6a08cd699813..1137fb673804 100644 --- a/book/src/lang-support.md +++ b/book/src/lang-support.md @@ -11,6 +11,7 @@ Languages][adding-languages] guide for more language configuration information. {{#include ./generated/lang-support.md}} -[lsp-install-wiki]: https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers +[lsp-install-wiki]: + https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers [lang-config]: ./languages.md [adding-languages]: ./guides/adding_languages.md diff --git a/book/src/languages.md b/book/src/languages.md index ff06dc00d425..e365225bdf11 100644 --- a/book/src/languages.md +++ b/book/src/languages.md @@ -1,17 +1,19 @@ # Languages -Language-specific settings and settings for language servers are configured -in `languages.toml` files. +Language-specific settings and settings for language servers are configured in +`languages.toml` files. ## `languages.toml` files There are three possible `languages.toml` files. The first is compiled into -Helix and lives in the [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml). +Helix and lives in the +[Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml). This provides the default configurations for languages and language servers. -You may define a `languages.toml` in your [configuration directory](./configuration.md) -which overrides values from the built-in language configuration. For example -to disable auto-LSP-formatting in Rust: +You may define a `languages.toml` in your +[configuration directory](./configuration.md) which overrides values from the +built-in language configuration. For example to disable auto-LSP-formatting in +Rust: ```toml # in /helix/languages.toml @@ -21,8 +23,8 @@ name = "rust" auto-format = false ``` -Language configuration may also be overridden local to a project by creating -a `languages.toml` file under a `.helix` directory. Its settings will be merged +Language configuration may also be overridden local to a project by creating a +`languages.toml` file under a `.helix` directory. Its settings will be merged with the language configuration in the configuration directory and the built-in configuration. @@ -45,23 +47,23 @@ formatter = { command = "mylang-formatter" , args = ["--stdin"] } These configuration keys are available: -| Key | Description | -| ---- | ----------- | -| `name` | The name of the language | +| 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.` or `text.` 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][treesitter-language-injection] site. | -| `file-types` | The filetypes of the language, for example `["yml", "yaml"]`. See the file-type detection section below. | -| `shebangs` | The interpreters from the shebang line, for example `["sh", "bash"]` | -| `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 | -| `diagnostic-severity` | Minimal severity of diagnostic for it to be displayed. (Allowed values: `Error`, `Warning`, `Info`, `Hint`) | -| `comment-token` | The token to use as a comment-token | -| `indent` | The indent to use. Has sub keys `tab-width` and `unit` | -| `language-server` | The Language Server to run. See the Language Server configuration section below. | -| `config` | Language Server configuration | -| `grammar` | The tree-sitter grammar to use (defaults to the value of `name`) | -| `formatter` | The formatter for the language, it will take precedence over the lsp when defined. The formatter must be able to take the original file as input from stdin and write the formatted file to stdout | -| `max-line-length` | Maximum line length. Used for the `:reflow` command | +| `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. | +| `file-types` | The filetypes of the language, for example `["yml", "yaml"]`. See the file-type detection section below. | +| `shebangs` | The interpreters from the shebang line, for example `["sh", "bash"]` | +| `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 | +| `diagnostic-severity` | Minimal severity of diagnostic for it to be displayed. (Allowed values: `Error`, `Warning`, `Info`, `Hint`) | +| `comment-token` | The token to use as a comment-token | +| `indent` | The indent to use. Has sub keys `tab-width` and `unit` | +| `language-server` | The Language Server to run. See the Language Server configuration section below. | +| `config` | Language Server configuration | +| `grammar` | The tree-sitter grammar to use (defaults to the value of `name`) | +| `formatter` | The formatter for the language, it will take precedence over the lsp when defined. The formatter must be able to take the original file as input from stdin and write the formatted file to stdout | +| `max-line-length` | Maximum line length. Used for the `:reflow` command | ### File-type detection and the `file-types` key @@ -82,27 +84,28 @@ with the following priorities: 2. Extension: if there are no exact matches, any `file-types` string that matches the file extension of a given file wins. In the example above, the `"toml"` matches files like `Cargo.toml` or `languages.toml`. -3. Suffix: if there are still no matches, any values in `suffix` tables - are checked against the full path of the given file. In the example above, - the `{ suffix = ".git/config" }` would match against any `config` files - in `.git` directories. Note: `/` is used as the directory separator but is - replaced at runtime with the appropriate path separator for the operating - system, so this rule would match against `.git\config` files on Windows. +3. Suffix: if there are still no matches, any values in `suffix` tables are + checked against the full path of the given file. In the example above, the + `{ suffix = ".git/config" }` would match against any `config` files in `.git` + directories. Note: `/` is used as the directory separator but is replaced at + runtime with the appropriate path separator for the operating system, so this + rule would match against `.git\config` files on Windows. ### Language Server configuration The `language-server` field takes the following keys: -| Key | Description | -| --- | ----------- | -| `command` | The name of the language server binary to execute. Binaries must be in `$PATH` | -| `args` | A list of arguments to pass to the language server binary | -| `timeout` | The maximum time a request to the language server may take, in seconds. Defaults to `20` | +| Key | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `command` | The name of the language server binary to execute. Binaries must be in `$PATH` | +| `args` | A list of arguments to pass to the language server binary | +| `timeout` | The maximum time a request to the language server may take, in seconds. Defaults to `20` | | `language-id` | The language name to pass to the language server. Some language servers support multiple languages and use this field to determine which one is being served in a buffer | -| `environment` | Any environment variables that will be used when starting the language server `{ "KEY1" = "Value1", "KEY2" = "Value2" }` | +| `environment` | Any environment variables that will be used when starting the language server `{ "KEY1" = "Value1", "KEY2" = "Value2" }` | -The top-level `config` field is used to configure the LSP initialization options. A `format` -sub-table within `config` can be used to pass extra formatting options to +The top-level `config` field is used to configure the LSP initialization +options. A `format` sub-table within `config` can be used to pass extra +formatting options to [Document Formatting Requests](https://github.com/microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-16.md#document-formatting-request--leftwards_arrow_with_hook). For example with typescript: @@ -128,23 +131,23 @@ source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767 Grammar configuration takes these keys: | Key | Description | -| --- | ----------- | +| -------- | ------------------------------------------------------------------------ | | `name` | The name of the tree-sitter grammar | | `source` | The method of fetching the grammar - a table with a schema defined below | -Where `source` is a table with either these keys when using a grammar from a -git repository: +Where `source` is a table with either these keys when using a grammar from a git +repository: -| Key | Description | -| --- | ----------- | -| `git` | A git remote URL from which the grammar should be cloned | -| `rev` | The revision (commit hash or tag) which should be fetched | +| Key | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `git` | A git remote URL from which the grammar should be cloned | +| `rev` | The revision (commit hash or tag) which should be fetched | | `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 | ### Choosing grammars -You may use a top-level `use-grammars` key to control which grammars are -fetched and built when using `hx --grammar fetch` and `hx --grammar build`. +You may use a top-level `use-grammars` key to control which grammars are fetched +and built when using `hx --grammar fetch` and `hx --grammar build`. ```toml # Note: this key must come **before** the [[language]] and [[grammar]] sections @@ -155,4 +158,5 @@ use-grammars = { except = [ "yaml", "json" ] } When omitted, all grammars are fetched and built. -[treesitter-language-injection]: https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection +[treesitter-language-injection]: + https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection diff --git a/book/src/remapping.md b/book/src/remapping.md index e89c66113d1b..bb773020a145 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -1,8 +1,8 @@ # Key Remapping One-way key remapping is temporarily supported via a simple TOML configuration -file. (More powerful solutions such as rebinding via commands will be -available in the future). +file. (More powerful solutions such as rebinding via commands will be available +in the future). To remap keys, write a `config.toml` file in your `helix` configuration directory (default `~/.config/helix` in Linux systems) with a structure like @@ -23,13 +23,15 @@ g = { a = "code_action" } # Maps `ga` to show possible code actions "A-x" = "normal_mode" # Maps Alt-X to enter normal mode j = { k = "normal_mode" } # Maps `jk` to exit insert mode ``` -> NOTE: Typable commands can also be remapped, remember to keep the `:` prefix to indicate it's a typable command. -Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes -`C-`, `S-` and `A-`. Special keys are encoded as follows: +> NOTE: Typable commands can also be remapped, remember to keep the `:` prefix +> to indicate it's a typable command. + +Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes `C-`, +`S-` and `A-`. Special keys are encoded as follows: | Key name | Representation | -| --- | --- | +| ------------ | -------------- | | Backspace | `"backspace"` | | Space | `"space"` | | Return/Enter | `"ret"` | @@ -50,5 +52,9 @@ Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes Keys can be disabled by binding them to the `no_op` command. -Commands can be found at [Keymap](https://docs.helix-editor.com/keymap.html) Commands. -> 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`. +Commands can be found at [Keymap](https://docs.helix-editor.com/keymap.html) +Commands. + +> 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`. diff --git a/book/src/themes.md b/book/src/themes.md index 015ec59b3f5e..4fdd8eb3d88e 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -1,14 +1,22 @@ # Themes -To use a theme add `theme = ""` to your [`config.toml`](./configuration.md) at the very top of the file before the first section or select it during runtime using `:theme `. +To use a theme add `theme = ""` to your +[`config.toml`](./configuration.md) at the very top of the file before the first +section or select it during runtime using `:theme `. ## Creating a theme -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. +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. -The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes. +The names "default" and "base16_default" are reserved for the builtin themes and +cannot be overridden by user defined themes. -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). +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). Each line in the theme file is specified as below: @@ -16,7 +24,10 @@ Each line in the theme file is specified as below: key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] } ``` -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. +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. To specify only the foreground color: @@ -24,7 +35,8 @@ To specify only the foreground color: key = "#ffffff" ``` -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). +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). ```toml "key.key" = "#ffffff" @@ -33,8 +45,8 @@ if the key contains a dot `'.'`, it must be quoted to prevent it being parsed as ### Color palettes It's recommended define a palette of named colors, and refer to them from the -configuration values in your theme. To do this, add a table called -`palette` to your theme file: +configuration values in your theme. To do this, add a table called `palette` to +your theme file: ```toml "ui.background" = "white" @@ -45,15 +57,15 @@ white = "#ffffff" black = "#000000" ``` -Remember that the `[palette]` table includes all keys after its header, -so you should define the palette after normal theme options. +Remember that the `[palette]` table includes all keys after its header, so you +should define the palette after normal theme options. The default palette uses the terminal's default 16 colors, and the colors names are listed below. The `[palette]` section in the config file takes precedence over it and is merged into the default palette. | Color Name | -| --- | +| --------------- | | `black` | | `red` | | `green` | @@ -73,43 +85,43 @@ over it and is merged into the default palette. ### Modifiers -The following values may be used as modifiers. +The following values may be used as modifiers. Less common modifiers might not be supported by your terminal emulator. -| Modifier | -| --- | -| `bold` | -| `dim` | -| `italic` | -| `underlined` | -| `slow_blink` | -| `rapid_blink` | -| `reversed` | -| `hidden` | -| `crossed_out` | - -> Note: The `underlined` modifier is deprecated and only available for backwards compatibility. -> Its behavior is equivalent to setting `underline.style="line"`. +| Modifier | +| ------------- | +| `bold` | +| `dim` | +| `italic` | +| `underlined` | +| `slow_blink` | +| `rapid_blink` | +| `reversed` | +| `hidden` | +| `crossed_out` | + +> Note: The `underlined` modifier is deprecated and only available for backwards +> compatibility. Its behavior is equivalent to setting `underline.style="line"`. ### Underline Style -One of the following values may be used as a value for `underline.style`. +One of the following values may be used as a value for `underline.style`. Some styles might not be supported by your terminal emulator. -| Modifier | -| --- | -| `line` | -| `curl` | -| `dashed` | -| `dotted` | -| `double_line` | - +| Modifier | +| ------------- | +| `line` | +| `curl` | +| `dashed` | +| `dotted` | +| `double_line` | ### Inheritance -Extend upon other themes by setting the `inherits` property to an existing theme. +Extend upon other themes by setting the `inherits` property to an existing +theme. ```toml inherits = "boo_berry" @@ -128,9 +140,12 @@ The following is a list of scopes available to use for styling. #### Syntax highlighting -These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme). +These keys match +[tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme). -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`. +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`. We use a similar set of scopes as [SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also @@ -145,7 +160,9 @@ We use a similar set of scopes as - `constructor` - `constant` (TODO: constant.other.placeholder for %v) - - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc) + + - `builtin` Special constants provided by the language (`true`, `false`, `nil` + etc) - `boolean` - `character` - `escape` @@ -154,6 +171,7 @@ We use a similar set of scopes as - `float` - `string` (TODO: string.quoted.{single, double}, string.raw/.unquoted)? + - `regexp` - Regular expressions - `special` - `path` @@ -161,11 +179,13 @@ We use a similar set of scopes as - `symbol` - Erlang/Elixir atoms, Ruby symbols, Clojure keywords - `comment` - Code comments + - `line` - Single line comments (`//`) - - `block` - Block comments (e.g. (`/* */`) + - `block` - Block comments (e.g. (`/* */`) - `documentation` - Documentation comments (e.g. `///` in Rust) - `variable` - Variables + - `builtin` - Reserved language variables (`self`, `this`, `super`, etc) - `parameter` - Function parameters - `other` @@ -174,11 +194,13 @@ We use a similar set of scopes as - `label` - `punctuation` + - `delimiter` - Commas, colons - `bracket` - Parentheses, angle brackets, etc. - `special` - String interpolation brackets. - `keyword` + - `control` - `conditional` - `if`, `else` - `repeat` - `for`, `while`, `loop` @@ -186,15 +208,16 @@ We use a similar set of scopes as - `return` - `exception` - `operator` - `or`, `in` - - `directive` - Preprocessor directives (`#if` in C) + - `directive` - Preprocessor directives (`#if` in C) - `function` - `fn`, `func` - `storage` - Keywords describing how things are stored - - `type` - The type of something, `class`, `function`, `var`, `let`, etc. + - `type` - The type of something, `class`, `function`, `var`, `let`, etc. - `modifier` - Storage modifiers like `static`, `mut`, `const`, `ref`, etc. - `operator` - `||`, `+=`, `>` - `function` + - `builtin` - `method` - `macro` @@ -207,6 +230,7 @@ We use a similar set of scopes as - `special` - `markup` + - `heading` - `marker` - `1`, `2`, `3`, `4`, `5`, `6` - heading text for h1 through h6 @@ -246,9 +270,8 @@ These scopes are used for theming the editor interface. - `completion` - for completion doc popup ui - `hover` - for hover popup ui - | Key | Notes | -| --- | --- | +| --------------------------- | ---------------------------------------------------------------------------------------------- | | `ui.background` | | | `ui.background.separator` | Picker separator below input line | | `ui.cursor` | | @@ -266,7 +289,7 @@ These scopes are used for theming the editor interface. | `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) | | `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) | | `ui.statusline.separator` | Separator character in statusline | -| `ui.popup` | Documentation popups (e.g Space + k) | +| `ui.popup` | Documentation popups (e.g Space + k) | | `ui.popup.info` | Prompt for multiple key options | | `ui.window` | Border lines separating splits | | `ui.help` | Description box for commands | @@ -275,7 +298,7 @@ These scopes are used for theming the editor interface. | `ui.text.inactive` | Same as `ui.text` but when the text is inactive (e.g. suggestions) | | `ui.text.info` | The key: command text in `ui.popup.info` boxes | | `ui.virtual.ruler` | Ruler columns (see the [`editor.rulers` config][editor-section]) | -| `ui.virtual.whitespace` | Visible whitespace characters | +| `ui.virtual.whitespace` | Visible whitespace characters | | `ui.virtual.indent-guide` | Vertical indent width guides | | `ui.menu` | Code and command completion menus | | `ui.menu.selected` | Selected autocomplete item | diff --git a/book/src/title-page.md b/book/src/title-page.md index f24d3d33f7e8..ec5756edb249 100644 --- a/book/src/title-page.md +++ b/book/src/title-page.md @@ -3,10 +3,10 @@ Docs for bleeding edge master can be found at [https://docs.helix-editor.com/master](https://docs.helix-editor.com/master). -See the [usage] section for a quick overview of the editor, [keymap] -section for all available keybindings and the [configuration] section -for defining custom keybindings, setting themes, etc. -For everything else (e.g., how to install supported language servers), see the [Helix Wiki]. +See the [usage] section for a quick overview of the editor, [keymap] section for +all available keybindings and the [configuration] section for defining custom +keybindings, setting themes, etc. For everything else (e.g., how to install +supported language servers), see the [Helix Wiki]. Refer the [FAQ] for common questions. @@ -14,4 +14,4 @@ Refer the [FAQ] for common questions. [usage]: ./usage.md [keymap]: ./keymap.md [configuration]: ./configuration.md -[Helix Wiki]: https://github.com/helix-editor/helix/wiki \ No newline at end of file +[Helix Wiki]: https://github.com/helix-editor/helix/wiki diff --git a/book/src/usage.md b/book/src/usage.md index a6eb9ec1d4f1..fca6fdc65492 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -1,37 +1,45 @@ # Usage -(Currently not fully documented, see the [keymappings](./keymap.md) list for more.) +(Currently not fully documented, see the [keymappings](./keymap.md) list for +more.) -See [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction. +See [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) +(accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction. ## Registers -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: +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: - `"ay` - Yank the current selection to register `a`. - `"op` - Paste the text in register `o` after the selection. -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: +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: -- `"hc` - Store the selection in register `h` and then change it (delete and enter insert mode). +- `"hc` - Store the selection in register `h` and then change it (delete and + enter insert mode). - `"md` - Store the selection in register `m` and delete it. ### Special Registers | Register character | Contains | -| --- | --- | +| ------------------ | --------------------- | | `/` | Last search | | `:` | Last executed command | | `"` | Last yanked text | | `_` | Black hole | -> 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. -> The black hole register works as a no-op register, meaning no data will be written to / read from it. +> 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. The black hole register works as a no-op register, meaning +> no data will be written to / read from it. ## Surround -Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) is built into -helix. The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich): +Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) +is built into helix. The keymappings have been inspired from +[vim-sandwich](https://github.com/machakann/vim-sandwich): ![surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif) @@ -39,10 +47,12 @@ helix. The keymappings have been inspired from [vim-sandwich](https://github.com - `mr` - Replace surround characters - `md` - Delete surround characters -`ms` acts on a selection, so select the text first and use `ms`. `mr` and `md` work -on the closest pairs found and selections are not required; use counts to act in outer pairs. +`ms` acts on a selection, so select the text first and use `ms`. `mr` and +`md` work on the closest pairs found and selections are not required; use counts +to act in outer pairs. -It can also act on multiple selections (yay!). For example, to change every occurrence of `(use)` to `[use]`: +It can also act on multiple selections (yay!). For example, to change every +occurrence of `(use)` to `[use]`: - `%` to select the whole file - `s` to split the selections on a search term @@ -53,10 +63,10 @@ Multiple characters are currently not supported, but planned. ## Syntax-tree Motions -`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) move the primary -selection according to the selection's place in the syntax tree. Let's walk -through an example to get familiar with them. Many languages have a syntax like -so for function calls: +`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) move the +primary selection according to the selection's place in the syntax tree. Let's +walk through an example to get familiar with them. Many languages have a syntax +like so for function calls: ``` func(arg1, arg2, arg3) @@ -106,8 +116,8 @@ Using `Alt-n` would select the next sibling in the syntax tree: `arg2`. func(arg1, [arg2], arg3) ``` -While `Alt-o` would expand the selection to the parent node. In the tree above we -can see that we would select the `arguments` node. +While `Alt-o` would expand the selection to the parent node. In the tree above +we can see that we would select the `arguments` node. ``` func[(arg1, arg2, arg3)] @@ -132,7 +142,7 @@ though, we climb the syntax tree and then take the previous selection. So - `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) | Key after `mi` or `ma` | Textobject selected | -| --- | --- | +| ---------------------- | ------------------------ | | `w` | Word | | `W` | WORD | | `p` | Paragraph | @@ -145,26 +155,26 @@ though, we climb the syntax tree and then take the previous selection. So | `t` | Test | | `g` | Change | -> NOTE: `f`, `c`, etc need a tree-sitter grammar active for the current -document and a special tree-sitter query file to work properly. [Only -some grammars][lang-support] currently have the query file implemented. -Contributions are welcome! +> NOTE: `f`, `c`, etc need a tree-sitter grammar active for the current document +> and a special tree-sitter query file to work properly. [Only some +> grammars][lang-support] currently have the query file implemented. +> Contributions are welcome! ## Tree-sitter Textobject Based Navigation -Navigating between functions, classes, parameters, etc is made -possible by leveraging tree-sitter and textobjects queries. For -example to move to the next function use `]f`, to move to previous -class use `[c`, and so on. +Navigating between functions, classes, parameters, etc is made possible by +leveraging tree-sitter and textobjects queries. For example to move to the next +function use `]f`, to move to previous class use `[c`, and so on. ![tree-sitter-nav-demo][tree-sitter-nav-demo] -See the [unimpaired][unimpaired-keybinds] section of the keybind -documentation for the full reference. +See the [unimpaired][unimpaired-keybinds] section of the keybind documentation +for the full reference. -> NOTE: This feature is dependent on tree-sitter based textobjects -and therefore requires the corresponding query file to work properly. +> NOTE: This feature is dependent on tree-sitter based textobjects and therefore +> requires the corresponding query file to work properly. [lang-support]: ./lang-support.md [unimpaired-keybinds]: ./keymap.md#unimpaired -[tree-sitter-nav-demo]: https://user-images.githubusercontent.com/23398472/152332550-7dfff043-36a2-4aec-b8f2-77c13eb56d6f.gif +[tree-sitter-nav-demo]: + https://user-images.githubusercontent.com/23398472/152332550-7dfff043-36a2-4aec-b8f2-77c13eb56d6f.gif