From 421b5ebace07faec6b4479ca67092cf151b2bc97 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Sat, 14 Jan 2023 14:58:14 +0000 Subject: [PATCH 01/33] Rewrite and refactor all documentation --- book/src/commands.md | 3 +- book/src/configuration.md | 197 +++++++++-------- book/src/install.md | 241 ++++++++++++-------- book/src/keymap.md | 451 +++++++++++++++++++------------------- book/src/lang-support.md | 12 +- book/src/languages.md | 112 +++++----- book/src/remapping.md | 42 ++-- book/src/themes.md | 270 +++++++++++++---------- book/src/usage.md | 172 +++++++++------ 9 files changed, 817 insertions(+), 683 deletions(-) diff --git a/book/src/commands.md b/book/src/commands.md index d9a113866b2f..b18ed1a5d7bb 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, similar to Vim, can be activated by pressing `:`. The built-in +commands are: {{#include ./generated/typable-cmd.md}} diff --git a/book/src/configuration.md b/book/src/configuration.md index a35482e6ecba..31852aa42b87 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. +> ๐Ÿ’ก You can easily open the config file by typing `:config-open` within Helix +> normal mode. Example config: @@ -25,38 +27,37 @@ 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`. - -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. +You can use a custom configuration file by specifying it with the `-c` or +`--config` command line argument, for example +`hx -c path/to/custom-config.toml`. Additionally, you can reload the +configuration file by sending the USR1 signal to the Helix process on Unix +operating systems, such as by using the command `pkill -USR1 hx`. ## 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 the 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 +79,62 @@ 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. Valid values for these options are +`block`, `bar`, `underline`,or `hidden`. + +> ๐Ÿ’กDue to limitations of the terminal environment, only the primary cursor can +> change shape. | 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` | @@ -139,23 +145,20 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`. ### `[editor.file-picker]` Section -Sets options for file picker and global search. All but the last key listed in -the default file-picker configuration below are IgnoreOptions: whether hidden -files and files listed within ignore files are ignored by (not visible in) the -helix file picker and global search. There is also one other key, `max-depth` -available, which is not defined by default. +Set options for file picker and global search. Ignoring a file means it is not +visible in the Helix file picker and global search. 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 +172,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 +186,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 +209,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 +248,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/install.md b/book/src/install.md index bf0ff079c40e..7781429d9f44 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -1,171 +1,222 @@ -# Installation +# Installing Helix -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) - -## OSX +- [Installing Helix](#installing-helix) + - [Using the Pre-built Binaries](#using-the-pre-built-binaries) + - [Installing Helix on Linux through the Official Package Manager](#installing-helix-on-linux-through-the-official-package-manager) + - [Installing Helix on Linux via Third-Party Repositories](#installing-helix-on-linux-via-third-party-repositories) + - [Installing Helix on macOS via Homebrew](#installing-helix-on-macos-via-homebrew) + - [Installing Helix on Windows](#installing-helix-on-windows) + - [Building from Source](#building-from-source) + - [Validating the Installation](#validating-the-installation) + -Helix is available in homebrew-core: +To install Helix, follow the instructions specific to your operating system. +Additionally: -``` -brew install helix -``` +- To get the latest pre-release version of Helix, you will need to + [build from source](#building-from-source). -## Linux +- To take full advantage of Helix, install the language servers for your + preferred programming languages. Refer to the + [Helix Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) + for detailed instructions. -### NixOS +## Using the Pre-built Binaries -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`. +Download pre-built binaries from the +[GitHub Releases page](https://github.com/helix-editor/helix/releases). You will +need to add the binary to your system's `$PATH` to access it from the command +line. -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. +## Installing Helix on Linux through the Official Package Manager -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. +If your Linux distribution has Helix available through its official package +manager, install it through that. The following list shows availability +throughout the Linux ecosystem: -### Arch Linux +[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions) -Releases are available in the `community` repository. +## Installing Helix on Linux via Third-Party Repositories -A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also available on the AUR, which builds the master branch. +If Helix is not available through your distribution's official repository, use a +third-party repository. -### Fedora Linux +- Ubuntu -You can install the COPR package for Helix via +Helix is available for 20.04 LTS (Focal Fossa) and 22.04 Ubuntu 22.04 LTS (Jammy +Jellyfish) via +[Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor): +```sh +sudo add-apt-repository ppa:maveonair/helix-editor +sudo apt update +sudo apt install helix ``` + +- Fedora/RHEL Linux + +Helix is available via `copr`: + +```sh sudo dnf copr enable varlad/helix sudo dnf install helix ``` -### Void Linux +- Arch Linux Community -``` -sudo xbps-install helix +Releases are available in the community repository. Additionally, a +[helix-git](https://aur.archlinux.org/packages/helix-git/) package is available +in the AUR, which builds the master branch. + +- NixOS + +Helix is available as a [flake](https://nixos.wiki/wiki/Flakes) in the project +root. Use `nix develop` to spin up a reproducible development shell. 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. + +If you are using a version of Nix without flakes enabled, +[install Cachix CLI](https://docs.cachix.org/installation) and use +`cachix use helix` to configure Nix to use cached outputs when possible. + +## Installing Helix on macOS via Homebrew + +Helix is available in Homebrew Core: + +```sh +brew install helix ``` -## Windows +## Installing Helix on Windows -Helix can be installed using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/) -or [MSYS2](https://msys2.org/). +Install on Windows using [Scoop](https://scoop.sh/), +[Chocolatey](https://chocolatey.org/) or [MSYS2](https://msys2.org/). **Scoop:** -``` +```sh scoop install helix ``` **Chocolatey:** -``` +```sh choco install helix ``` **MSYS2:** -Choose the proper command for your system from below: - - - For 32 bit Windows 7 or above: +For 64-bit Windows 8.1 or above: -``` -pacman -S mingw-w64-i686-helix +```sh +pacman -S mingw-w64-ucrt-x86_64-helix ``` - - For 64 bit Windows 7 or above: +## Building from Source -``` -pacman -S mingw-w64-x86_64-helix -``` - - - For 64 bit Windows 8.1 or above: +1. Clone the repository: -``` -pacman -S mingw-w64-ucrt-x86_64-helix +```sh +git clone https://github.com/helix-editor/helix +cd helix ``` -## Build from source +2. Compile Helix: -``` -git clone https://github.com/helix-editor/helix -cd helix +```sh 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 command will create the `hx` executable and construct the tree-sitter +grammars in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME` +(as described below). -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. +3. Configure Helix's runtime files -| OS | Command | -| -------------------- | ------------------------------------------------ | -| Windows (Cmd) | `xcopy /e /i runtime %AppData%\helix\runtime` | -| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` | -| Linux / macOS | `ln -s $PWD/runtime ~/.config/helix/runtime` | +**IMPORTANT**: The runtime files must be accessible to the newly created binary. +They are currently located in the source code `runtime` directory. To make them +accessible, you must follow the instructions for your operating system: -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. +> ๐Ÿ’ก Tree-sitter grammars can 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). -**PowerShell:** +- Linux and macOS -```powershell -New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime" -``` +Either, -**Cmd:** +1. Set the `HELIX_RUNTIME` environmental variable on your system to tell Helix + where to find the runtime files. -```cmd -cd %appdata%\helix -mklink /D runtime "\runtime" -``` + Use the `HELIX_RUNTIME=/path/to/helix/runtime` format, for example: + `HELIX_RUNTIME=/home/user-name/src/helix/runtime`. Add this variable to your + `~/.bashrc` file or equivalent to persist it. -The runtime location can be overridden via the `HELIX_RUNTIME` environment variable. +Or, -> 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`. +2. Create a symlink in `~/.config/helix/` that links to the source code + directory. -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). +`ln -s $PWD/runtime ~/.config/helix/runtime` -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: +And optionally: -```bash +3. Configure the Desktop Shortcut + +If your desktop environment supports the +[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), +you can configure Helix to show up in the application menu by copying the +provided `.desktop` and icon files to their correct folders: + +```sh cp contrib/Helix.desktop ~/.local/share/applications +cp contrib/helix.png ~/.local/share/icons ``` -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 system default, you can modify the `.desktop` +file. For example, to use `kitty`: -```bash +```sh sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop ``` -Please note: there is no icon for Helix yet, so the system default will be used. +- Windows -## Finishing up the installation +> TODO Add correct file paths after feedback -To make sure everything is set up as expected you should finally run the helix healthcheck via +Either, -``` -hx --health -``` +1. Set the `HELIX_RUNTIME` environmental variable on your system to tell Helix + where to find the runtime files. + + Use the `???` format, for example: `???`. Add this variable to your `???` + file or equivalent to persist it. -For more information on the information displayed in the health check results refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck). +Or, -### Building tree-sitter grammars +2. Create a symlink in `???` that links to the source code directory. -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). +| Method | Command | +| ---------- | -------------------------------------------------------------------------------------- | +| PowerShell | `New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"` | +| Cmd | `cd %appdata%\helix` | +| | `mklink /D runtime "\runtime"` | -### Installing language servers +> ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or Cmd +> as an administrator. + +## Validating the Installation + +To make sure everything is set up as expected you should run the Helix health +check: + +```sh +hx --health +``` -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. +For more information on the health check results refer to +[Health check](https://github.com/helix-editor/helix/wiki/Healthcheck). diff --git a/book/src/keymap.md b/book/src/keymap.md index b38a1f44ea95..019073e3ea0e 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -21,46 +21,46 @@ > ๐Ÿ’ก Mappings marked (**LSP**) require an active language server for the file. -> ๐Ÿ’ก Mappings marked (**TS**) require a tree-sitter grammar for the filetype. +> ๐Ÿ’ก Mappings marked (**TS**) require a tree-sitter grammar for the file type. ## Normal mode ### Movement -> 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` | +> ๐Ÿ’ก 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 jump list | `jump_forward` | +| `Ctrl-o` | Jump backward on the jump list | `jump_backward` | +| `Ctrl-s` | Save the current selection to the jump list | `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` | @@ -82,7 +82,7 @@ | `P` | Paste before selection | `paste_before` | | `"` `` | Select a register to yank to or paste from | `select_register` | | `>` | Indent selection | `indent` | -| `<` | Unindent selection | `unindent` | +| `<` | Remove indentation from the selection | `unindent` | | `=` | Format selection (currently nonfunctional/disabled) (**LSP**) | `format_selections` | | `d` | Delete selection | `delete_selection` | | `Alt-d` | Delete selection, without yanking | `delete_selection_noyank` | @@ -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 sub selections 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 operate on the `/` register by default. To use a different +register, use `".` -| 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. +Minor 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 | @@ -168,17 +169,14 @@ These sub-modes are accessible from normal mode and typically switch back to nor #### View mode -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). - +View mode is accessed by typing `z` in [normal mode](#normal-mode) and 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 and can be exited using the escape key. This is 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` | @@ -192,57 +190,55 @@ it). #### Goto mode -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` | +Goto mode is accessed by typing `g` in [normal mode](#normal-mode), it 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` | #### Match mode -Accessed by typing `m` in [normal mode](#normal-mode). +Match mode is accessed by typing `m` in [normal mode](#normal-mode). See the relevant section in [Usage](./usage.md) for an explanation about -[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. +[surround](./usage.md#surround) and [text object](./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` | | `d` `` | Delete surround character `` | `surround_delete` | -| `a` `` | Select around textobject | `select_textobject_around` | -| `i` `` | Select inside textobject | `select_textobject_inner` | +| `a` `` | Select around text object | `select_textobject_around` | +| `i` `` | Select inside text object | `select_textobject_inner` | TODO: Mappings for selecting syntax nodes (a superset of `[`). #### Window mode -Accessed by typing `Ctrl-w` in [normal mode](#normal-mode). - -This layer is similar to Vim keybindings as Kakoune does not support window. +Window mode is 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` | @@ -261,50 +257,53 @@ This layer is similar to Vim keybindings as Kakoune does not support window. #### Space mode -Accessed by typing `Space` in [normal mode](#normal-mode). +Space mode is 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 jump list 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` | + +> ๐Ÿ’ก 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. +Popups display documentation for items under the cursor. If there is more +content than fits on the screen, you can use scroll: | Key | Description | -| ---- | ----------- | +| -------- | ----------- | | `Ctrl-u` | Scroll up | | `Ctrl-d` | Scroll down | #### Unimpaired -Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired). +These mappings are 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 +329,44 @@ 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 -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` | +Insert mode bindings are minimal by default. Helix is designed to be a modal +editor, and this is reflected in the user experience and internal mechanics. +Changes to the text are only saved for undos when escaping from insert mode to +normal mode. + +> ๐Ÿ’ก 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` | 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`: +As you become more comfortable with modal editing, you may want to disable some +insert mode bindings. You can do this by editing your `config.toml` file. ```toml [keys.insert] @@ -382,58 +382,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. +Select 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..930c9a20057e 100644 --- a/book/src/lang-support.md +++ b/book/src/lang-support.md @@ -1,16 +1,18 @@ # Language Support -The following languages and Language Servers are supported. In order to use -Language Server features, you must first [install][lsp-install-wiki] the -appropriate Language Server. +The following languages and Language Servers are supported. To use Language +Server features, you must first [install][lsp-install-wiki] the appropriate +Language Server. -Check the language support in your installed helix version with `hx --health`. +You can check the language support in your installed Helix version with +`hx --health`. Also see the [Language Configuration][lang-config] docs and the [Adding 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..e2af50d0c2c8 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). -This provides the default configurations for languages and language servers. +There are three possible locations for a `languages.toml` file: -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: +1. In the Helix source code, this lives in the + [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml). + It provides the default configurations for languages and language servers. + +2. In your [configuration directory](./configuration.md). This overrides values + from the built-in language configuration. For example to disable + auto-LSP-formatting in Rust: ```toml # in /helix/languages.toml @@ -21,10 +23,10 @@ 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 -with the language configuration in the configuration directory and the built-in -configuration. +3. In a `.helix` folder in your project. Language configuration may also be + overridden local to a project by creating a `languages.toml` file in a + `.helix` folder. Its settings will be merged with the language configuration + in the configuration directory and the built-in configuration. ## Language configuration @@ -45,28 +47,28 @@ 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 -Helix determines which language configuration to use with the `file-types` key -from the above section. `file-types` is a list of strings or tables, for +Helix determines which language configuration to use based on the `file-types` +key from the above section. `file-types` is a list of strings or tables, for example: ```toml @@ -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..e4995770c58a 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -1,35 +1,43 @@ # 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). +Helix currently supports one-way key remapping through a simple TOML +configuration 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 +To remap keys, create a `config.toml` file in your `Helix` configuration +directory (default `~/.config/helix` on Linux systems) with a structure like this: ```toml + # At most one section each of 'keys.normal', 'keys.insert' and 'keys.select' + [keys.normal] -C-s = ":w" # Maps the Ctrl-s to the typable command :w which is an alias for :write (save file) -C-o = ":open ~/.config/helix/config.toml" # Maps the Ctrl-o to opening of the helix config file +C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file) +C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file a = "move_char_left" # Maps the 'a' key to the move_char_left command w = "move_line_up" # Maps the 'w' key move_line_up "C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line g = { a = "code_action" } # Maps `ga` to show possible code actions -"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode +"ret" = [ + "open_below", + "normal_mode", +] # Maps the enter key to open_below then re-enter normal mode [keys.insert] -"A-x" = "normal_mode" # Maps Alt-X to enter normal mode +"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 +58,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`. +You can find a list of available commands at +[Keymap](https://docs.helix-editor.com/keymap.html) + +> 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..33d319bd6bb2 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -1,22 +1,35 @@ # 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 the top of your +[`config.toml`](./configuration.md) file, or select it during runtime using +`:theme `. -## Creating a 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. +### Creating Your Theme File -The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes. +To create a theme file: -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). +1. Create a 'themes' folder in your user configuration folder (e.g. + `~/.config/helix/themes`) +2. Create a file with the name of your theme as the file name (e.g. + `mytheme.toml`) and place it in your `themes` folder. -Each line in the theme file is specified as below: +> ๐Ÿ’ก The names "default" and "base16_default" are reserved for built-in themes +> and cannot be overridden by user-defined themes. + +### An Overview of the Theme File Format + +Each line in the theme file is specified as follows: ```toml 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,17 +37,34 @@ 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" ``` +For inspiration, you can find the default `theme.toml` +[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). + +### Using the Linter + +If you plan to submit your theme for inclusion in Helix, it is recommended to +use the supplied linting tool to ensure compliance with the specifications: + +```sh +cargo xtask themelint onedark # replace onedark with +``` + +## The Details of Theme Creation + ### 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: +It's recommended to define a palette of named colors and refer to them in the +configuration values in your theme. To do this, add a table called `palette` to +your theme file: ```toml "ui.background" = "white" @@ -45,15 +75,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. +Keep in mind that the [palette] table includes all keys after its header, so it +should be defined after the 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 +103,40 @@ over it and is merged into the default palette. ### Modifiers -The following values may be used as modifiers. +The following values can be used as modifiers, providing they are supported by +your terminal emulator. -Less common modifiers might not be supported by your terminal emulator. +| Modifier | +| ------------- | +| `bold` | +| `dim` | +| `italic` | +| `underlined` | +| `slow_blink` | +| `rapid_blink` | +| `reversed` | +| `hidden` | +| `crossed_out` | -| 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"`. +> ๐Ÿ’ก 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`. - -Some styles might not be supported by your terminal emulator. - -| Modifier | -| --- | -| `line` | -| `curl` | -| `dashed` | -| `dotted` | -| `double_line` | +One of the following values can be used for `underline.style`, providing it is +supported by your terminal emulator. +| Modifier | +| ------------- | +| `line` | +| `curl` | +| `dashed` | +| `dotted` | +| `double_line` | ### Inheritance -Extend upon other themes by setting the `inherits` property to an existing theme. +Extends other themes by setting the `inherits` property to an existing theme. ```toml inherits = "boo_berry" @@ -124,19 +151,22 @@ berry = "#2A2A4D" ### Scopes -The following is a list of scopes available to use for styling. +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`. +When determining styling for a highlight, the longest matching theme key will be +used. For example, if the highlight is `function.builtin.static,` the key +`function.builtin` will be used instead of function. We use a similar set of scopes as -[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also +[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also [TextMate](https://macromates.com/manual/en/language_grammars) scopes. -- `attribute` - Class attributes, html tag attributes +- `attribute` - Class attributes, HTML tag attributes - `type` - Types - `builtin` - Primitive types provided by the language (`int`, `usize`) @@ -144,8 +174,10 @@ We use a similar set of scopes as - `variant` - `constructor` -- `constant` (TODO: constant.other.placeholder for %v) - - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc) +- `constant` (TODO: constant.other.placeholder for `%v)` + + - `builtin` Special constants provided by the language (`true`, `false`, `nil` + etc.) - `boolean` - `character` - `escape` @@ -154,6 +186,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,12 +194,14 @@ 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) + + - `builtin` - Reserved language variables (`self`, `this`, `super`, etc.) - `parameter` - Function parameters - `other` - `member` - Fields of composite data types (e.g. structs, unions) @@ -174,11 +209,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 +223,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 +245,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 @@ -216,9 +255,9 @@ We use a similar set of scopes as - `bold` - `italic` - `link` - - `url` - urls pointed to by links - - `label` - non-url link references - - `text` - url and image descriptions in links + - `url` - URLs pointed to by links + - `label` - non-URL link references + - `text` - URL and image descriptions in links - `quote` - `raw` - `inline` @@ -232,74 +271,67 @@ We use a similar set of scopes as #### Interface -These scopes are used for theming the editor interface. +These scopes are used for theming the editor interface: - `markup` - `normal` - - `completion` - for completion doc popup ui - - `hover` - for hover popup ui + - `completion` - for completion doc popup UI + - `hover` - for hover popup UI - `heading` - - `completion` - for completion doc popup ui - - `hover` - for hover popup ui + - `completion` - for completion doc popup UI + - `hover` - for hover popup UI - `raw` - `inline` - - `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` | | -| `ui.cursor.insert` | | -| `ui.cursor.select` | | -| `ui.cursor.match` | Matching bracket etc. | -| `ui.cursor.primary` | Cursor with primary selection | -| `ui.gutter` | Gutter | -| `ui.gutter.selected` | Gutter for the line the cursor is on | -| `ui.linenr` | Line numbers | -| `ui.linenr.selected` | Line number for the line the cursor is on | -| `ui.statusline` | Statusline | -| `ui.statusline.inactive` | Statusline (unfocused document) | -| `ui.statusline.normal` | Statusline mode during normal mode ([only if `editor.color-modes` is enabled][editor-section]) | -| `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.info` | Prompt for multiple key options | -| `ui.window` | Border lines separating splits | -| `ui.help` | Description box for commands | -| `ui.text` | Command prompts, popup text, etc. | -| `ui.text.focus` | | -| `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.indent-guide` | Vertical indent width guides | -| `ui.menu` | Code and command completion menus | -| `ui.menu.selected` | Selected autocomplete item | -| `ui.menu.scroll` | `fg` sets thumb color, `bg` sets track color of scrollbar | -| `ui.selection` | For selections in the editing area | -| `ui.selection.primary` | | -| `ui.cursorline.primary` | The line of the primary cursor ([if cursorline is enabled][editor-section]) | -| `ui.cursorline.secondary` | The lines of any other cursors ([if cursorline is enabled][editor-section]) | -| `ui.cursorcolumn.primary` | The column of the primary cursor ([if cursorcolumn is enabled][editor-section]) | -| `ui.cursorcolumn.secondary` | The columns of any other cursors ([if cursorcolumn is enabled][editor-section]) | -| `warning` | Diagnostics warning (gutter) | -| `error` | Diagnostics error (gutter) | -| `info` | Diagnostics info (gutter) | -| `hint` | Diagnostics hint (gutter) | -| `diagnostic` | Diagnostics fallback style (editing area) | -| `diagnostic.hint` | Diagnostics hint (editing area) | -| `diagnostic.info` | Diagnostics info (editing area) | -| `diagnostic.warning` | Diagnostics warning (editing area) | -| `diagnostic.error` | Diagnostics error (editing area) | - -You can check compliance to spec with - -```shell -cargo xtask themelint onedark # replace onedark with -``` + - `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` | | +| `ui.cursor.insert` | | +| `ui.cursor.select` | | +| `ui.cursor.match` | Matching bracket etc. | +| `ui.cursor.primary` | Cursor with primary selection | +| `ui.gutter` | Gutter | +| `ui.gutter.selected` | Gutter for the line the cursor is on | +| `ui.linenr` | Line numbers | +| `ui.linenr.selected` | Line number for the line the cursor is on | +| `ui.statusline` | `statusline` | +| `ui.statusline.inactive` | `statusline` (unfocused document) | +| `ui.statusline.normal` | `statusline` mode during normal mode ([only if `editor.color-modes` is enabled][editor-section]) | +| `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.info` | Prompt for multiple key options | +| `ui.window` | Borderlines separating splits | +| `ui.help` | Description box for commands | +| `ui.text` | Command prompts, popup text, etc. | +| `ui.text.focus` | | +| `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.indent-guide` | Vertical indent width guides | +| `ui.menu` | Code and command completion menus | +| `ui.menu.selected` | Selected autocomplete item | +| `ui.menu.scroll` | `fg` sets thumb color, `bg` sets track color of scrollbar | +| `ui.selection` | For selections in the editing area | +| `ui.selection.primary` | | +| `ui.cursorline.primary` | The line of the primary cursor ([if `cursorline` is enabled][editor-section]) | +| `ui.cursorline.secondary` | The lines of any other cursors ([if `cursorline` is enabled][editor-section]) | +| `ui.cursorcolumn.primary` | The column of the primary cursor ([if `cursorcolumn` is enabled][editor-section]) | +| `ui.cursorcolumn.secondary` | The columns of any other cursors ([if `cursorcolumn` is enabled][editor-section]) | +| `warning` | Diagnostics warning (gutter) | +| `error` | Diagnostics error (gutter) | +| `info` | Diagnostics info (gutter) | +| `hint` | Diagnostics hint (gutter) | +| `diagnostic` | Diagnostics fallback style (editing area) | +| `diagnostic.hint` | Diagnostics hint (editing area) | +| `diagnostic.info` | Diagnostics info (editing area) | +| `diagnostic.warning` | Diagnostics warning (editing area) | +| `diagnostic.error` | Diagnostics error (editing area) | [editor-section]: ./configuration.md#editor-section diff --git a/book/src/usage.md b/book/src/usage.md index a6eb9ec1d4f1..747c05d532d6 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -1,68 +1,100 @@ -# Usage +# Using Helix -(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. +- [Using Helix](#using-helix) + - [Registers](#registers) + - [User-defined Registers](#user-defined-registers) + - [Built-in Registers](#built-in-registers) + - [Surround](#surround) + - [Moving the Primary Selection with Syntax-tree Motions](#moving-the-primary-selection-with-syntax-tree-motions) + - [Selecting and Manipulating Text with Textobjects](#selecting-and-manipulating-text-with-textobjects) + - [Navigating Using Tree-sitter Textobjects](#navigating-using-tree-sitter-textobjects) + + +For a full interactive introduction to Helix, refer to the +[tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) which +can be accessed via the command `hx --tutor` or `:tutor`. + +> ๐Ÿ’ก Currently, not all functionality is fully documented, please refer to the +> [key mappings](./keymap.md) list. ## 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: +In Helix, registers are storage locations for text and other data, such as the +result of a search. Registers can be used to cut, copy, and paste text, similar +to the clipboard in other text editors. Usage is similar to Vim, with `"` being +used to select a register. + +### User-defined Registers + +Helix allows you to create your own named registers for storing text, for +example: - `"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 a register is selected before invoking a change or delete command, the +selection will be stored in the register and the action will be carried out: -- `"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 +### Built-in 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. +The system clipboard is not directly supported by a built-in register. Instead, +special commands and keybindings are provided. Refer to the +[key map](keymap.md#space-mode) for more details. + +The black hole register is a no-op register, meaning that no data will be read +or written to 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): +Helix includes built-in functionality similar to +[vim-surround](https://github.com/tpope/vim-surround). The key mappings for this +functionality have been inspired by +[vim-sandwich](https://github.com/machakann/vim-sandwich). -![surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif) +![Surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif) -- `ms` - Add surround characters -- `mr` - Replace surround characters -- `md` - Delete surround characters +| Key Sequence | Action | +| --------------------------------- | --------------------------------------- | +| `ms` (after selecting text) | Add surround characters to selection | +| `mr` | Replace the closest surround characters | +| `md` | Delete the closest 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. +You can use counts to act on outer pairs. -It can also act on multiple selections (yay!). For example, to change every occurrence of `(use)` to `[use]`: +Surround can also act on multiple selections. For example, to change every +occurrence of `(use)` to `[use]`: -- `%` to select the whole file -- `s` to split the selections on a search term -- Input `use` and hit Enter -- `mr([` to replace the parens with square brackets +1. `%` to select the whole file +2. `s` to split the selections on a search term +3. Input `use` and hit Enter +4. `mr([` to replace the parentheses with square brackets -Multiple characters are currently not supported, but planned. +Multiple characters are currently not supported, but planned for future release. -## Syntax-tree Motions +## Moving the Primary Selection with 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) allow you to +move the primary selection according to its location in the syntax tree. For +example, many languages have the following syntax for function calls: -``` -func(arg1, arg2, arg3) +```js +func(arg1, arg2, arg3); ``` -A function call might be parsed by tree-sitter into a tree like the following. +A function call parsed by tree-sitter might look like: ```tsq (call @@ -93,50 +125,46 @@ a more intuitive tree format: โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` -Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf -in the tree above. - -``` -func([arg1], arg2, arg3) -``` - -Using `Alt-n` would select the next sibling in the syntax tree: `arg2`. +If you have a selection that wraps `arg1` (see the tree above), and you use +Alt-n, it will select the next sibling in the syntax tree: `arg2`. -``` -func(arg1, [arg2], arg3) +```js +func([arg1], arg2, arg3) > 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. +Similarly, Alt-o will expand the selection to the parent node, in this case, the +arguments node. -``` -func[(arg1, arg2, arg3)] +```js +func[(arg1, arg2, arg3)]; ``` There is also some nuanced behavior that prevents you from getting stuck on a -node with no sibling. If we have a selection on `arg1`, `Alt-p` would bring us -to the previous child node. Since `arg1` doesn't have a sibling to its left, -though, we climb the syntax tree and then take the previous selection. So -`Alt-p` will move the selection over to the "func" `identifier`. +node with no sibling. When using Alt-p with a selection on `arg1`, the previous +child node will be selected. In the event that `arg1` does not have a previous +sibling, the selection will move up the syntax tree and select the previous +element. As a result, using Alt-p with a selection on `arg1` will move the +selection to the "func" `identifier`. -``` -[func](arg1, arg2, arg3) -``` +## Selecting and Manipulating Text with Textobjects -## Textobjects +In Helix, Textobjects are a way to select, manipulate and operate on a piece of +text in a structured way. They allow you to refer to blocks of text based on +their structure or purpose, such as a word, sentence, paragraph, or even a +function or block of code. -![textobject-demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) -![textobject-treesitter-demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) +![Textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) +![Textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) - `ma` - Select around the object (`va` in Vim, `` in Kakoune) - `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) | Key after `mi` or `ma` | Textobject selected | -| --- | --- | +| ---------------------- | ------------------------ | | `w` | Word | | `W` | WORD | | `p` | Paragraph | -| `(`, `[`, `'`, etc | Specified surround pairs | +| `(`, `[`, `'`, etc. | Specified surround pairs | | `m` | Closest surround pair | | `f` | Function | | `c` | Class | @@ -145,26 +173,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! +> ๐Ÿ’ก`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 Using Tree-sitter Textobjects -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, and other elements is +possible using tree-sitter and Textobject 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. +For the full reference see the [unimpaired][unimpaired-keybinds] section of the +key bind documentation. -> NOTE: This feature is dependent on tree-sitter based textobjects -and therefore requires the corresponding query file to work properly. +> ๐Ÿ’ก This feature relies on tree-sitter Textobjects and 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 From dc6a0e3064afefce39e102f886df439a5d99193d Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Sat, 14 Jan 2023 16:37:42 +0000 Subject: [PATCH 02/33] Rewrite and refactor the guides --- book/src/guides/README.md | 2 +- book/src/guides/adding_languages.md | 78 +++++++++++-------- book/src/guides/indent.md | 114 ++++++++++++++-------------- book/src/guides/textobject.md | 42 +++++----- 4 files changed, 125 insertions(+), 111 deletions(-) diff --git a/book/src/guides/README.md b/book/src/guides/README.md index e0c44ce7d1f1..c25768e68961 100644 --- a/book/src/guides/README.md +++ b/book/src/guides/README.md @@ -1,4 +1,4 @@ # Guides This section contains guides for adding new language server configurations, -tree-sitter grammars, textobject queries, etc. +tree-sitter grammars, textobject queries, and other similar items. diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md index 6598b9bf7488..3a59b5fdabf2 100644 --- a/book/src/guides/adding_languages.md +++ b/book/src/guides/adding_languages.md @@ -1,45 +1,59 @@ -# Adding languages +# Adding new languages to Helix + +In order to add a new language to Helix, you will need to follow the steps +below. ## Language configuration -To add a new language, you need to add a `[[language]]` entry to the -`languages.toml` (see the [language configuration section]). +1. Add a new `[[language]]` entry in the `languages.toml` file and provide the + necessary configuration for the new language. For more information on + language configuration, refer to the + [language configuration section](../languages.md) of the documentation. +2. If you are adding a new language or updating an existing language server + configuration, run the command `cargo xtask docgen` to update the + [Language Support](../lang-support.md) documentation. -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. +> ๐Ÿ’ก If you are adding a new Language Server configuration, make sure to update +> the +> [Language Server Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) +> with the installation instructions. ## Grammar configuration -If a tree-sitter grammar is available for the language, add a new `[[grammar]]` -entry to `languages.toml`. - -You may use the `source.path` key rather than `source.git` with an absolute path -to a locally available grammar for testing, but switch to `source.git` before -submitting a pull request. +1. If a tree-sitter grammar is available for the new language, add a new + `[[grammar]]` entry to the `languages.toml` file. +2. If you are testing the grammar locally, you can use the `source.path` key + with an absolute path to the grammar. However, before submitting a pull + request, make sure to switch to using `source.git`. ## 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 -[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. - -## 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 a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in `runtime/grammar/.so` +1. In order to provide syntax highlighting and indentation for the new language, + you will need to add queries. +2. Create a new directory for the language with the path + `runtime/queries//`. +3. Refer to the + [tree-sitter website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries) + for more information on writing queries. + +> ๐Ÿ’ก In Helix, the first matching query takes precedence when evaluating +> queries, which is different from other editors such as Neovim where the last +> matching query supersedes the ones before it. See +> [this issue](https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090) +> for an example. + +## Common issues + +- If you encounter errors when running Helix after switching branches, you may + need to update the tree-sitter grammars. Run the command `hx --grammar fetch` + to fetch the grammars and `hx --grammar build` to build any out-of-date + grammars. +- If a parser is causing a segfault or you want to remove it, make sure to + remove the compiled parser located at `runtime/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..be8d797a3612 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]. +Helix supports textobjects that are language specific, such as functions, +classes, etc. These 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 +when contributing to Helix. 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,24 +26,28 @@ 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 -[Tree-sitter based navigation][textobjects-nav] is done using captures in the -following order: +Tree-sitter based navigation in Helix is done using captures in the following +order: - `object.movement` - `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 its `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= From d3dfb291036c0e341e7273103f9d97491d756904 Mon Sep 17 00:00:00 2001 From: CptPotato <3957610+CptPotato@users.noreply.github.com> Date: Sat, 14 Jan 2023 19:42:52 +0100 Subject: [PATCH 03/33] update runtime directory instructions for windows --- book/src/install.md | 37 ++++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index 7781429d9f44..f81bd27c602a 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -148,7 +148,7 @@ accessible, you must follow the instructions for your operating system: Either, -1. Set the `HELIX_RUNTIME` environmental variable on your system to tell Helix +1. Set the `HELIX_RUNTIME` environment variable on your system to tell Helix where to find the runtime files. Use the `HELIX_RUNTIME=/path/to/helix/runtime` format, for example: @@ -160,7 +160,9 @@ Or, 2. Create a symlink in `~/.config/helix/` that links to the source code directory. -`ln -s $PWD/runtime ~/.config/helix/runtime` + ```sh + ln -s $PWD/runtime ~/.config/helix/runtime + ``` And optionally: @@ -186,28 +188,33 @@ sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desk - Windows -> TODO Add correct file paths after feedback - Either, -1. Set the `HELIX_RUNTIME` environmental variable on your system to tell Helix +1. Set the `HELIX_RUNTIME` environment variable on your system to tell Helix where to find the runtime files. - Use the `???` format, for example: `???`. Add this variable to your `???` - file or equivalent to persist it. + You can either do this using the Windows settings (search for `Edit + environment variables for your account`) or use the `setx` command in Cmd: + + ```sh + setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" + ``` + + > ๐Ÿ’ก `%userprofile%` resolves to your user directory like + > `C:\Users\Your-Name\` for example. Or, -2. Create a symlink in `???` that links to the source code directory. +2. Create a symlink in `%appdata%\helix\` that links to the source + code directory. -| Method | Command | -| ---------- | -------------------------------------------------------------------------------------- | -| PowerShell | `New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"` | -| Cmd | `cd %appdata%\helix` | -| | `mklink /D runtime "\runtime"` | + | Method | Command | + | ---------- | -------------------------------------------------------------------------------------- | + | PowerShell | `New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"` | + | Cmd | `cd %appdata%\helix`
`mklink /D runtime "%userprofile%\src\helix\runtime"` | -> ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or Cmd -> as an administrator. + > ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or Cmd + > as an administrator. ## Validating the Installation From a6894a1ba7d57e9265374d552ae9b2ebf3251fb0 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Mon, 16 Jan 2023 11:11:16 +0000 Subject: [PATCH 04/33] Update the Ubuntu 3rd party repo section with 22.10 --- book/src/install.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index f81bd27c602a..c7565fb252d0 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -43,10 +43,15 @@ throughout the Linux ecosystem: If Helix is not available through your distribution's official repository, use a third-party repository. -- Ubuntu +### Ubuntu -Helix is available for 20.04 LTS (Focal Fossa) and 22.04 Ubuntu 22.04 LTS (Jammy -Jellyfish) via +Helix is available for the following versions of Ubuntu: + +- 20.04 LTS (Focal Fossa) +- 22.04 LTS (Jammy Jellyfish) +- 22.10 (Kinetic Kudu) + +Via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor): ```sh @@ -55,7 +60,7 @@ sudo apt update sudo apt install helix ``` -- Fedora/RHEL Linux +### Fedora/RHEL Linux Helix is available via `copr`: @@ -64,13 +69,13 @@ sudo dnf copr enable varlad/helix sudo dnf install helix ``` -- Arch Linux Community +### Arch Linux Community Releases are available in the community repository. Additionally, a [helix-git](https://aur.archlinux.org/packages/helix-git/) package is available in the AUR, which builds the master branch. -- NixOS +### NixOS Helix is available as a [flake](https://nixos.wiki/wiki/Flakes) in the project root. Use `nix develop` to spin up a reproducible development shell. Outputs are @@ -193,8 +198,9 @@ Either, 1. Set the `HELIX_RUNTIME` environment variable on your system to tell Helix where to find the runtime files. - You can either do this using the Windows settings (search for `Edit - environment variables for your account`) or use the `setx` command in Cmd: + You can either do this using the Windows settings (search for + `Edit environment variables for your account`) or use the `setx` command in + Cmd: ```sh setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" @@ -205,16 +211,16 @@ Either, Or, -2. Create a symlink in `%appdata%\helix\` that links to the source - code directory. +2. Create a symlink in `%appdata%\helix\` that links to the source code + directory. | Method | Command | | ---------- | -------------------------------------------------------------------------------------- | | PowerShell | `New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"` | | Cmd | `cd %appdata%\helix`
`mklink /D runtime "%userprofile%\src\helix\runtime"` | - > ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or Cmd - > as an administrator. + > ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or + > Cmd as an administrator. ## Validating the Installation From 07cbc5475c1018ef1e4982650995d34bc335eea5 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Mon, 16 Jan 2023 19:44:24 +0000 Subject: [PATCH 05/33] Merge from upstream --- book/src/configuration.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/src/configuration.md b/book/src/configuration.md index 6499ee972b29..604bfdb3ff2a 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -219,11 +219,11 @@ Search specific options. 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`, `nbsp`, `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 | +| Key | Description | Default | |-----|-------------|---------| | `render` | +Whether to render whitespace. May either be `"all"` or `"none"`, or a table with +sub-keys `space`, `nbsp`, `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 From 3901d60911d9a5caef2718ce02f84dc7200a9c7a Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Sat, 28 Jan 2023 13:51:38 -0600 Subject: [PATCH 06/33] Rewrite and refactor all documentation --- book/src/commands.md | 2 +- book/src/configuration.md | 35 ++-- book/src/guides/README.md | 2 +- book/src/guides/adding_languages.md | 77 +++++---- book/src/guides/textobject.md | 12 +- book/src/install.md | 257 +++++++++++++++++----------- book/src/keymap.md | 65 ++++--- book/src/lang-support.md | 4 +- book/src/languages.md | 24 +-- book/src/remapping.md | 16 +- book/src/themes.md | 100 ++++++----- book/src/usage.md | 146 +++++++++------- 12 files changed, 419 insertions(+), 321 deletions(-) diff --git a/book/src/commands.md b/book/src/commands.md index d9a113866b2f..6ae4185048c1 100644 --- a/book/src/commands.md +++ b/book/src/commands.md @@ -1,5 +1,5 @@ # Commands -Command mode can be activated by pressing `:`, similar to Vim. Built-in commands: +Command mode, similar to Vim, can be activated by pressing `:`. The built-in commands are: {{#include ./generated/typable-cmd.md}} diff --git a/book/src/configuration.md b/book/src/configuration.md index ab229f772a1c..b262b231688d 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -2,10 +2,10 @@ 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. +> ๐Ÿ’ก You can easily open the config file by typing `:config-open` within Helix normal mode. Example config: @@ -25,12 +25,10 @@ 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`. - -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. +You can use a custom configuration file by specifying it with the `-c` or +`--config` command line argument, for example `hx -c path/to/custom-config.toml`. +Additionally, you can reload the configuration file by sending the USR1 +signal to the Helix process on Unix operating systems, such as by using the command `pkill -USR1 hx`. ## Editor @@ -49,7 +47,7 @@ on unix operating systems. | `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` | +| `auto-save` | Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal. | `false` | | `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` | @@ -123,10 +121,12 @@ The following statusline elements can be configured: ### `[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. +Defines the shape of cursor in each mode. Valid values for these options are `block`, `bar`, `underline`, or `hidden`. +> ๐Ÿ’กDue to limitations of the terminal environment, only the primary cursor can +> change shape. + | Key | Description | Default | | --- | ----------- | ------- | | `normal` | Cursor shape in [normal mode][normal mode] | `block` | @@ -139,11 +139,8 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`. ### `[editor.file-picker]` Section -Sets options for file picker and global search. All but the last key listed in -the default file-picker configuration below are IgnoreOptions: whether hidden -files and files listed within ignore files are ignored by (not visible in) the -helix file picker and global search. There is also one other key, `max-depth` -available, which is not defined by default. +Sets options for file picker and global search. Ignoring a file means it is +not visible in the Helix file picker and global search. All git related options are only enabled in a git repository. @@ -153,7 +150,7 @@ All git related options are only enabled in a git repository. |`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-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`. @@ -207,7 +204,7 @@ Search specific options. | Key | Description | Default | |--|--|---------| -| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` | +| `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 diff --git a/book/src/guides/README.md b/book/src/guides/README.md index e0c44ce7d1f1..c25768e68961 100644 --- a/book/src/guides/README.md +++ b/book/src/guides/README.md @@ -1,4 +1,4 @@ # Guides This section contains guides for adding new language server configurations, -tree-sitter grammars, textobject queries, etc. +tree-sitter grammars, textobject queries, and other similar items. diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md index 6598b9bf7488..816826cfc125 100644 --- a/book/src/guides/adding_languages.md +++ b/book/src/guides/adding_languages.md @@ -1,45 +1,52 @@ -# Adding languages +# Adding new languages to Helix + +In order to add a new language to Helix, you will need to follow the steps +below. ## Language configuration -To add a new language, you need to add a `[[language]]` entry to the -`languages.toml` (see the [language configuration section]). +1. Add a new `[[language]]` entry in the `languages.toml` file and provide the + necessary configuration for the new language. For more information on + language configuration, refer to the + [language configuration section](../languages.md) of the documentation. +2. If you are adding a new language or updating an existing language server + configuration, run the command `cargo xtask docgen` to update the + [Language Support](../lang-support.md) documentation. -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. +> ๐Ÿ’ก If you are adding a new Language Server configuration, make sure to update +> the +> [Language Server Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) +> with the installation instructions. ## Grammar configuration -If a tree-sitter grammar is available for the language, add a new `[[grammar]]` -entry to `languages.toml`. - -You may use the `source.path` key rather than `source.git` with an absolute path -to a locally available grammar for testing, but switch to `source.git` before -submitting a pull request. +1. If a tree-sitter grammar is available for the new language, add a new + `[[grammar]]` entry to the `languages.toml` file. +2. If you are testing the grammar locally, you can use the `source.path` key + with an absolute path to the grammar. However, before submitting a pull + request, make sure to switch to using `source.git`. ## 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 -[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. - -## 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 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 -[lang-support]: ../lang-support.md +1. In order to provide syntax highlighting and indentation for the new language, + you will need to add queries. +2. Create a new directory for the language with the path + `runtime/queries//`. +3. Refer to the + [tree-sitter website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries) + for more information on writing queries. + +> ๐Ÿ’ก In Helix, the first matching query takes precedence when evaluating +> queries, which is different from other editors such as Neovim where the last +> matching query supersedes the ones before it. See +> [this issue](https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090) +> for an example. + +## Common issues + +- If you encounter errors when running Helix after switching branches, you may + need to update the tree-sitter grammars. Run the command `hx --grammar fetch` + to fetch the grammars and `hx --grammar build` to build any out-of-date + grammars. +- If a parser is causing a segfault or you want to remove it, make sure to + remove the compiled parser located at `runtime/grammar/.so`. diff --git a/book/src/guides/textobject.md b/book/src/guides/textobject.md index 8a2173547541..71082f4be504 100644 --- a/book/src/guides/textobject.md +++ b/book/src/guides/textobject.md @@ -1,14 +1,14 @@ # 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 +Helix supports textobjects that are language specific, such as functions, classes, etc. +These 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 +when contributing to Helix. Note that to test the query files locally you should put them under your local runtime directory (`~/.config/helix/runtime` on Linux for example). @@ -30,7 +30,7 @@ The following [captures][tree-sitter-captures] are recognized: ## Queries for Textobject Based Navigation -[Tree-sitter based navigation][textobjects-nav] is done using captures in the +Tree-sitter based navigation in Helix is done using captures in the following order: - `object.movement` @@ -38,12 +38,10 @@ following order: - `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. +in its `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= diff --git a/book/src/install.md b/book/src/install.md index 792799d7a7f9..52a807c239cc 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -1,179 +1,240 @@ -# Installation +# Installing Helix -We provide pre-built binaries on the [GitHub Releases page](https://github.com/helix-editor/helix/releases). + +- [Installing Helix](#installing-helix) + - [Using the Pre-built Binaries](#using-the-pre-built-binaries) + - [Installing Helix on Linux through the Official Package Manager](#installing-helix-on-linux-through-the-official-package-manager) + - [Installing Helix on Linux via Third-Party Repositories](#installing-helix-on-linux-via-third-party-repositories) + - [Installing Helix on macOS via Homebrew](#installing-helix-on-macos-via-homebrew) + - [Installing Helix on Windows](#installing-helix-on-windows) + - [Building from Source](#building-from-source) + - [Validating the Installation](#validating-the-installation) + -[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions) +To install Helix, follow the instructions specific to your operating system. +Additionally: -## OSX +- To get the latest pre-release version of Helix, you will need to + [build from source](#building-from-source). -Helix is available in homebrew-core: +- To take full advantage of Helix, install the language servers for your + preferred programming languages. Refer to the + [Helix Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) + for detailed instructions. -``` -brew install helix -``` +## Using the Pre-built Binaries -## Linux +Download pre-built binaries from the +[GitHub Releases page](https://github.com/helix-editor/helix/releases). You will +need to add the binary to your system's `$PATH` to access it from the command +line. -### NixOS +## Installing Helix on Linux through the Official Package Manager -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`. +If your Linux distribution has Helix available through its official package +manager, install it through that. The following shows availability +throughout the Linux ecosystem: -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. +[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions) -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. +## Installing Helix on Linux via Third-Party Repositories -### Arch Linux +If Helix is not available through your distribution's official repository, use a +third-party repository. -Releases are available in the `community` repository. +### Ubuntu -A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also available on the AUR, which builds the master branch. +Helix is available for the following versions of Ubuntu: -### Fedora Linux +- 20.04 LTS (Focal Fossa) +- 22.04 LTS (Jammy Jellyfish) +- 22.10 (Kinetic Kudu) -You can install the COPR package for Helix via +Via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor) +```sh +sudo add-apt-repository ppa:maveonair/helix-editor +sudo apt update +sudo apt install helix ``` + +### Fedora/RHEL Linux + +Helix is available via `copr`: + +```sh sudo dnf copr enable varlad/helix sudo dnf install helix ``` -### Void Linux +### Arch Linux Community -``` -sudo xbps-install helix +Releases are available in the community repository. Additionally, a +[helix-git](https://aur.archlinux.org/packages/helix-git/) package is available +in the AUR, which builds the master branch. + +### NixOS + +Helix is available as a [flake](https://nixos.wiki/wiki/Flakes) in the project +root. Use `nix develop` to spin up a reproducible development shell. 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. + +If you are using a version of Nix without flakes enabled, +[install Cachix CLI](https://docs.cachix.org/installation) and use +`cachix use helix` to configure Nix to use cached outputs when possible. + +## Installing Helix on macOS via Homebrew + +Helix is available in Homebrew Core: + +```sh +brew install helix ``` -## Windows +## Installing Helix on Windows -Helix can be installed using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/) +Install on Windows using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/) or [MSYS2](https://msys2.org/). **Scoop:** -``` +```sh scoop install helix ``` **Chocolatey:** -``` +```sh choco install helix ``` **MSYS2:** -Choose the [proper command](https://www.msys2.org/docs/package-naming/) for your system from below: - - - For 32 bit Windows 7 or above: - -``` -pacman -S mingw-w64-i686-helix -``` - - - For 64 bit Windows 7 or above: +For 64-bit Windows 8.1 or above: -``` -pacman -S mingw-w64-x86_64-helix -``` - - - For 64 bit Windows 8.1 or above: - -``` +```sh pacman -S mingw-w64-ucrt-x86_64-helix ``` ## Build from source -``` +1. Clone the repository: + +```sh git clone https://github.com/helix-editor/helix cd helix +``` + +2. Compile Helix: + +```sh 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 command will create the `hx` executable and construct the tree-sitter +grammars in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME` +(as described below). -If you are using the musl-libc instead of glibc the following environment variable must be set during the build -to ensure tree sitter grammars can be loaded correctly: +> ๐Ÿ’ก If you are using the musl-libc instead of glibc the following environment variable must be set during the build +> to ensure tree sitter grammars can be loaded correctly: +> +> ```sh +> RUSTFLAGS="-C target-feature=-crt-static" +> ``` -``` -RUSTFLAGS="-C target-feature=-crt-static" -``` +3. Configure Helix's runtime files +**IMPORTANT**: The runtime files must be accessible to the newly created binary. +They are currently located in the source code `runtime` directory. To make them +accessible, you must follow the instructions for your operating system: -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. +> ๐Ÿ’ก Tree-sitter grammars can 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). -| OS | Command | -| -------------------- | ------------------------------------------------ | -| Windows (Cmd) | `xcopy /e /i runtime %AppData%\helix\runtime` | -| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` | -| Linux / macOS | `ln -s $PWD/runtime ~/.config/helix/runtime` | +- Linux and macOS -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. +Either, -**PowerShell:** +1. Set the `HELIX_RUNTIME` environment variable on your system to tell Helix + where to find the runtime files. -```powershell -New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime" -``` + Use the `HELIX_RUNTIME=/path/to/helix/runtime` format, for example: + `HELIX_RUNTIME=/home/user-name/src/helix/runtime`. Add this variable to your + `~/.bashrc` file or equivalent to persist it. -**Cmd:** +Or, -```cmd -cd %appdata%\helix -mklink /D runtime "\runtime" -``` +2. Create a symlink in `~/.config/helix` that links to the source code + directory. -The runtime location can be overridden via the `HELIX_RUNTIME` environment variable. + ```sh + ln -s $PWD/runtime ~/.config/helix/runtime + ``` -> 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`. +And optionally: -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). +3. Configure the Desktop Shortcut -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: +If your desktop environment supports the +[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html) +you can configure Helix to show up in the application menu by copying the +provided `.desktop` and icon files to their correct folders: -```bash +```sh cp contrib/Helix.desktop ~/.local/share/applications +cp contrib/helix.png ~/.local/share/icons ``` -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 system default, you can modify the `.desktop` +file. For example, to use `kitty`: -```bash +```sh sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop ``` -Please note: there is no icon for Helix yet, so the system default will be used. +- Windows -## Finishing up the installation +Either, -To make sure everything is set up as expected you should finally run the helix healthcheck via +1. Set the `HELIX_RUNTIME` environment variable on your system to tell Helix + where to find the runtime files. -``` -hx --health -``` + You can either do this using the Windows setting (search for + `Edit environment variables for your account`) or use the `setx` command in + Cmd: + + ```sh + setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" + ``` -For more information on the information displayed in the health check results refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck). + > ๐Ÿ’ก `%userprofile%` resolves to your user directory like + > `C:\Users\Your-Name\` for example. -### Building tree-sitter grammars +Or, -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). +2. Create a symlink in `%appdata%\helix\` that links to the source code + directory. -### Installing language servers + | Method | Command | + | ---------- | -------------------------------------------------------------------------------------- | + | PowerShell | `New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"` | + | Cmd | `cd %appdata%\helix`
`mklink /D runtime "%userprofile%\src\helix\runtime"` | + + > ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or + > Cmd as an administrator. + +## Validating the Installation + +To make sure everything is set up as expected you should run the Helix health +check: + +```sh +hx --health +``` -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. +For more information on the health check results refer to +[Health check](https://github.com/helix-editor/helix/wiki/Healthcheck). diff --git a/book/src/keymap.md b/book/src/keymap.md index 0550e57f3f3b..79e5decbed2c 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -21,7 +21,7 @@ > ๐Ÿ’ก Mappings marked (**LSP**) require an active language server for the file. -> ๐Ÿ’ก Mappings marked (**TS**) require a tree-sitter grammar for the filetype. +> ๐Ÿ’ก Mappings marked (**TS**) require a tree-sitter grammar for the file type. ## Normal mode @@ -53,9 +53,9 @@ | `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` | +| `Ctrl-i` | Jump forward on the jump list | `jump_forward` | +| `Ctrl-o` | Jump backward on the jump list | `jump_backward` | +| `Ctrl-s` | Save the current selection to the jump list | `save_selection` | ### Changes @@ -109,7 +109,7 @@ | Key | Description | Command | | ----- | ----------- | ------- | | `s` | Select all regex matches inside selections | `select_regex` | -| `S` | Split selection into subselections on regex matches | `split_selection` | +| `S` | Split selection into sub selections 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` | @@ -141,7 +141,7 @@ ### 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. To use a different register, use `"`. | Key | Description | Command | | ----- | ----------- | ------- | @@ -153,7 +153,7 @@ Search commands all operate on the `/` register by default. Use `"` to ope ### Minor modes -These sub-modes are accessible from normal mode and typically switch back to normal mode after a command. +Minor modes are accessible from normal mode and typically switch back to normal mode after a command. | Key | Description | Command | | ----- | ----------- | ------- | @@ -171,13 +171,11 @@ These modes (except command mode) can be configured by #### View mode -Accessed by typing `z` in [normal mode](#normal-mode). - -View mode is intended for scrolling and manipulating the view without changing +View mode is access by typing `z` in [normal mode](#normal-mode) +and 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). +normal mode) is persistent and can be exited using the escape key. This is +useful when you're simply looking over text and not actively editing it. | Key | Description | Command | @@ -195,9 +193,8 @@ it). #### Goto mode -Accessed by typing `g` in [normal mode](#normal-mode). - -Jumps to various locations. +Goto mode is accessed by typing `g` in [normal mode](#normal-mode), it jumps to +various locations. | Key | Description | Command | | ----- | ----------- | ------- | @@ -222,10 +219,10 @@ Jumps to various locations. #### Match mode -Accessed by typing `m` in [normal mode](#normal-mode). +Match mode is accessed by typing `m` in [normal mode](#normal-mode). See the relevant section in [Usage](./usage.md) for an explanation about -[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. +[surround](./usage.md#surround) and [text object](./usage.md#textobjects) usage. | Key | Description | Command | | ----- | ----------- | ------- | @@ -233,16 +230,15 @@ See the relevant section in [Usage](./usage.md) for an explanation about | `s` `` | Surround current selection with `` | `surround_add` | | `r` `` | Replace surround character `` with `` | `surround_replace` | | `d` `` | Delete surround character `` | `surround_delete` | -| `a` `` | Select around textobject | `select_textobject_around` | -| `i` `` | Select inside textobject | `select_textobject_inner` | +| `a` `` | Select around text object | `select_textobject_around` | +| `i` `` | Select inside text object | `select_textobject_inner` | TODO: Mappings for selecting syntax nodes (a superset of `[`). #### Window mode -Accessed by typing `Ctrl-w` in [normal mode](#normal-mode). - -This layer is similar to Vim keybindings as Kakoune does not support window. +Window mode is 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 | | ----- | ------------- | ------- | @@ -264,7 +260,7 @@ This layer is similar to Vim keybindings as Kakoune does not support window. #### Space mode -Accessed by typing `Space` in [normal mode](#normal-mode). +Space mode is accessed by typing `Space` in [normal mode](#normal-mode). This layer is a kludge of mappings, mostly pickers. @@ -273,7 +269,7 @@ This layer is a kludge of mappings, mostly pickers. | `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` | +| `j` | Open jump list picker | `jump list_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` | @@ -304,7 +300,7 @@ Displays documentation for item under cursor. #### Unimpaired -Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired). +These mappings are in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired). | Key | Description | Command | | ----- | ----------- | ------- | @@ -333,12 +329,13 @@ 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 +Insert mode bindings are 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. +mechanics. Changes to the text are only saved for undos when +escaping from insert mode to normal mode. + +> ๐Ÿ’ก New users are strongly encouraged to learn the modal editing paradigm +> to get the smoothest experience. | Key | Description | Command | | ----- | ----------- | ------- | @@ -368,8 +365,8 @@ with modal editors. | `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`: +As you become more comfortable with modal editing, you may want to disable some +insert mode bindings. You can do this by editing your `config.toml` file. ```toml [keys.insert] @@ -385,7 +382,7 @@ end = "no_op" ## Select / extend mode -This mode echoes Normal mode, but changes any movements to extend +Select 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. diff --git a/book/src/lang-support.md b/book/src/lang-support.md index 6a08cd699813..3f96673bc953 100644 --- a/book/src/lang-support.md +++ b/book/src/lang-support.md @@ -1,10 +1,10 @@ # Language Support -The following languages and Language Servers are supported. In order to use +The following languages and Language Servers are supported. To use Language Server features, you must first [install][lsp-install-wiki] the appropriate Language Server. -Check the language support in your installed helix version with `hx --health`. +You can check the language support in your installed helix version with `hx --health`. Also see the [Language Configuration][lang-config] docs and the [Adding Languages][adding-languages] guide for more language configuration information. diff --git a/book/src/languages.md b/book/src/languages.md index ff06dc00d425..c368b3e9e85d 100644 --- a/book/src/languages.md +++ b/book/src/languages.md @@ -5,13 +5,15 @@ 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). -This provides the default configurations for languages and language servers. +There are three possible locations for a `languages.toml` file: -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: +1. In the Helix source code, this lives in the + [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml) + It provides the default configurations for languages and language servers. + +2. In your [configuration directory](./configuration.md). This overrides values + from the built-in language configuration. For example to disable + auto-LSP-formatting in Rust: ```toml # in /helix/languages.toml @@ -21,10 +23,10 @@ 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 -with the language configuration in the configuration directory and the built-in -configuration. +3. In a `.helix` folder in your project. Language configuration may also be + overridden local to a project by creating a `languages.toml` file in a + `.helix` folder. Its settings will be merged with the language configuration + in the configuration directory and the built-in configuration. ## Language configuration @@ -65,7 +67,7 @@ These configuration keys are available: ### File-type detection and the `file-types` key -Helix determines which language configuration to use with the `file-types` key +Helix determines which language configuration to use based on the `file-types` key from the above section. `file-types` is a list of strings or tables, for example: diff --git a/book/src/remapping.md b/book/src/remapping.md index 8339e05fce8c..b7fb72a56298 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -1,18 +1,18 @@ # Key Remapping -One-way key remapping is temporarily supported via a simple TOML configuration +Helix currently supports one-way key remapping through a simple TOML configuration 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 +To remap keys, create a `config.toml` file in your `Helix` configuration +directory (default `~/.config/helix` on Linux systems) with a structure like this: ```toml # At most one section each of 'keys.normal', 'keys.insert' and 'keys.select' [keys.normal] -C-s = ":w" # Maps the Ctrl-s to the typable command :w which is an alias for :write (save file) -C-o = ":open ~/.config/helix/config.toml" # Maps the Ctrl-o to opening of the helix config file +C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file) +C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file a = "move_char_left" # Maps the 'a' key to the move_char_left command w = "move_line_up" # Maps the 'w' key move_line_up "C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line @@ -20,10 +20,9 @@ g = { a = "code_action" } # Maps `ga` to show possible code actions "ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode [keys.insert] -"A-x" = "normal_mode" # Maps Alt-X to enter normal mode +"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. ## Minor modes @@ -76,5 +75,6 @@ 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. +You can find a list of available commands at [Keymap](https://docs.helix-editor.com/keymap.html). + > 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 0d0827fd18e3..87ab5bb605f6 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 the top of your [`config.toml`](./configuration.md) file, or select it during runtime using `:theme `. -## Creating a 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. +### Creating Your Theme File -The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes. +To create a theme file: -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). +1. Create a 'themes' folder in your user configuration folder (e.g. + `~/.config/helix/themes`). +2. Create a file with the name of your theme as the file name (e.g. + `mytheme.toml`) and place it in your `themes` folder. + +> ๐Ÿ’ก The names "default" and "base16_default" are reserved for built-in themes +> and cannot be overridden by user-defined themes. + +### An overview of the Theme File Format Each line in the theme file is specified as below: @@ -16,7 +24,7 @@ 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,15 +32,31 @@ 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" ``` +For inspiration, you can find the default `theme.toml` +[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). + +### Using the Linter + +If you plan to submit your theme for inclusion in Helix, it is recommended to +use the supplied linting tool to ensure compliance with the specifications: + +```sh +cargo xtask themelint onedark # replace onedark with +``` + +## The Details of Theme Creation + ### Color palettes -It's recommended define a palette of named colors, and refer to them from the +It's recommended to define a palette of named colors, and refer to them in the configuration values in your theme. To do this, add a table called `palette` to your theme file: @@ -45,8 +69,8 @@ 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. +Keep in mind that the `[palette]` table includes all keys after its header, +so it should be defined after the 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 @@ -73,9 +97,8 @@ over it and is merged into the default palette. ### Modifiers -The following values may be used as modifiers. - -Less common modifiers might not be supported by your terminal emulator. +The following values may be used as modifier, provided they are supported by +your terminal emulator. | Modifier | | --- | @@ -89,14 +112,13 @@ Less common modifiers might not be supported by your terminal emulator. | `hidden` | | `crossed_out` | -> Note: The `underlined` modifier is deprecated and only available for backwards compatibility. +> ๐Ÿ’ก 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`. - -Some styles might not be supported by your terminal emulator. +One of the following values may be used as a value for `underline.style`, providing it is +supported by your terminal emulator. | Modifier | | --- | @@ -109,7 +131,7 @@ Some styles might not be supported by your terminal emulator. ### Inheritance -Extend upon other themes by setting the `inherits` property to an existing theme. +Extends other themes by setting the `inherits` property to an existing theme. ```toml inherits = "boo_berry" @@ -124,19 +146,19 @@ berry = "#2A2A4D" ### Scopes -The following is a list of scopes available to use for styling. +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). -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`. +When determining styling for a highlight, the longest matching theme key will be used. For example, if the highlight is `function.builtin.static`, the key `function.builtin` will be used instead of `function`. We use a similar set of scopes as -[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also +[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also [TextMate](https://macromates.com/manual/en/language_grammars) scopes. -- `attribute` - Class attributes, html tag attributes +- `attribute` - Class attributes, HTML tag attributes - `type` - Types - `builtin` - Primitive types provided by the language (`int`, `usize`) @@ -144,7 +166,7 @@ We use a similar set of scopes as - `variant` - `constructor` -- `constant` (TODO: constant.other.placeholder for %v) +- `constant` (TODO: constant.other.placeholder for `%v`) - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc) - `boolean` - `character` @@ -162,7 +184,7 @@ We use a similar set of scopes as - `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 @@ -186,10 +208,10 @@ 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` - `||`, `+=`, `>` @@ -216,9 +238,9 @@ We use a similar set of scopes as - `bold` - `italic` - `link` - - `url` - urls pointed to by links - - `label` - non-url link references - - `text` - url and image descriptions in links + - `url` - URLs pointed to by links + - `label` - non-URL link references + - `text` - URL and image descriptions in links - `quote` - `raw` - `inline` @@ -232,19 +254,19 @@ We use a similar set of scopes as #### Interface -These scopes are used for theming the editor interface. +These scopes are used for theming the editor interface: - `markup` - `normal` - - `completion` - for completion doc popup ui - - `hover` - for hover popup ui + - `completion` - for completion doc popup UI + - `hover` - for hover popup UI - `heading` - - `completion` - for completion doc popup ui - - `hover` - for hover popup ui + - `completion` - for completion doc popup UI + - `hover` - for hover popup UI - `raw` - `inline` - - `completion` - for completion doc popup ui - - `hover` - for hover popup ui + - `completion` - for completion doc popup UI + - `hover` - for hover popup UI | Key | Notes | @@ -300,10 +322,4 @@ These scopes are used for theming the editor interface. | `diagnostic.warning` | Diagnostics warning (editing area) | | `diagnostic.error` | Diagnostics error (editing area) | -You can check compliance to spec with - -```shell -cargo xtask themelint onedark # replace onedark with -``` - [editor-section]: ./configuration.md#editor-section diff --git a/book/src/usage.md b/book/src/usage.md index a6eb9ec1d4f1..60ddfbc3f305 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -1,22 +1,44 @@ -# Usage +# Using Helix + + +- [Using Helix](#using-helix) + - [Registers](#registers) + - [User-defined Registers](#user-defined-registers) + - [Built-in Registers](#built-in-registers) + - [Surround](#surround) + - [Moving the Primary Selection with Syntax-tree Motions](#moving-the-primary-selection-with-syntax-tree-motions) + - [Selecting and Manipulating Text with Textobjects](#selecting-and-manipulating-text-with-textobjects) + - [Navigating Using Tree-sitter Textobjects](#navigating-using-tree-sitter-textobjects) + + +For a full interactive introduction to Helix, refer to the +[tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) which +can be accessed via the command `hx --tutor` or `:tutor`. + +> ๐Ÿ’ก Currently, not all functionality is fully documented, please refer to the +> [key mappings](./keymap.md) list. -(Currently not fully documented, see the [keymappings](./keymap.md) list for more.) +## Registers -See [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction. +In Helix, registers are storage locations for text and other data, such as the +result of a search. Registers can be used to cut, copy, and paste text, similar +to the clipboard in other text editors. Usage is similar to Vim, with `"` being +used to select a register. -## Registers +### User-defined 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: +Helix allows you to create your own named registers for storing text, for +example: - `"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 a register is selected before invoking a change or delete command, the selection will be stored in the register and the action will be carried out: - `"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 +### Built-in Registers | Register character | Contains | | --- | --- | @@ -25,41 +47,43 @@ If there is a selected register before invoking a change or delete command, the | `"` | 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. +The system clipboard is not directly supported by a built-in register. Instead, special commands and keybindings are provided. Refer to the +[key map](keymap.md#space-mode) for more details. + +The black hole register is a no-op register, meaning that no data will be read or written to 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): +Helix includes built-in functionality similar to [vim-surround](https://github.com/tpope/vim-surround). +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) +![Surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif) -- `ms` - Add surround characters -- `mr` - Replace surround characters -- `md` - Delete surround characters +| Key Sequence | Action | +| --------------------------------- | --------------------------------------- | +| `ms` (after selecting text) | Add surround characters to selection | +| `mr` | Replace the closest surround characters | +| `md` | Delete the closest 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. +You can use counts to act on outer pairs. -It can also act on multiple selections (yay!). For example, to change every occurrence of `(use)` to `[use]`: +Surround can also act on multiple selections. For example, to change every occurrence of `(use)` to `[use]`: -- `%` to select the whole file -- `s` to split the selections on a search term -- Input `use` and hit Enter -- `mr([` to replace the parens with square brackets +1. `%` to select the whole file +2. `s` to split the selections on a search term +3. Input `use` and hit Enter +4. `mr([` to replace the parentheses with square brackets -Multiple characters are currently not supported, but planned. +Multiple characters are currently not supported, but planned for future release. -## Syntax-tree Motions +## Moving the Primary Selection with 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) allow you to move the primary +selection according to its location in the syntax tree. For example, many languages have the +following syntax for function calls: -``` -func(arg1, arg2, arg3) +```js +func(arg1, arg2, arg3); ``` A function call might be parsed by tree-sitter into a tree like the following. @@ -93,40 +117,36 @@ a more intuitive tree format: โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` -Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf -in the tree above. - -``` -func([arg1], arg2, arg3) -``` - -Using `Alt-n` would select the next sibling in the syntax tree: `arg2`. +If you have a selection that wraps `arg1` (see the tree above), and you use +Alt-n, it will select the next sibling in the syntax tree: `arg2`. -``` -func(arg1, [arg2], arg3) +```js +func([arg1], arg2, arg3) > 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. +Similarly, Alt-o will expand the selection to the parent node, in this case, the +arguments node. -``` -func[(arg1, arg2, arg3)] +```js +func[(arg1, arg2, arg3)]; ``` There is also some nuanced behavior that prevents you from getting stuck on a -node with no sibling. If we have a selection on `arg1`, `Alt-p` would bring us -to the previous child node. Since `arg1` doesn't have a sibling to its left, -though, we climb the syntax tree and then take the previous selection. So -`Alt-p` will move the selection over to the "func" `identifier`. +node with no sibling. When using Alt-p with a selection on `arg1`, the previous +child node will be selected. In the event that `arg1` does not have a previous +sibling, the selection will move up the syntax tree and select the previous +element. As a result, using Alt-p with a selection on `arg1` will move the +selection to the "func" `identifier`. -``` -[func](arg1, arg2, arg3) -``` +## Selecting and Manipulating Text with Textobjects -## Textobjects +In Helix, Textobjects are a way to select, manipulate and operate on a piece of +text in a structured way. They allow you to refer to blocks of text based on +their structure or purpose, such as a word, sentence, paragraph, or even a +function or block of code. -![textobject-demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) -![textobject-treesitter-demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) +![Textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) +![Textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) - `ma` - Select around the object (`va` in Vim, `` in Kakoune) - `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) @@ -136,7 +156,7 @@ though, we climb the syntax tree and then take the previous selection. So | `w` | Word | | `W` | WORD | | `p` | Paragraph | -| `(`, `[`, `'`, etc | Specified surround pairs | +| `(`, `[`, `'`, etc. | Specified surround pairs | | `m` | Closest surround pair | | `f` | Function | | `c` | Class | @@ -145,25 +165,25 @@ 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 +> ๐Ÿ’ก `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 Using Tree-sitter Textobject -Navigating between functions, classes, parameters, etc is made -possible by leveraging tree-sitter and textobjects queries. For +Navigating between functions, classes, parameters, and other elements is +possible using tree-sitter and Textobject 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. +For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind +documentation. -> NOTE: This feature is dependent on tree-sitter based textobjects -and therefore requires the corresponding query file to work properly. +> ๐Ÿ’ก This feature relies on tree-sitter Textobjects +> and requires the corresponding query file to work properly. [lang-support]: ./lang-support.md [unimpaired-keybinds]: ./keymap.md#unimpaired From d932969cfc9fadda12a74cc01665919dee7152fb Mon Sep 17 00:00:00 2001 From: David Else <12832280+David-Else@users.noreply.github.com> Date: Sun, 29 Jan 2023 14:57:17 +0000 Subject: [PATCH 07/33] Apply suggestions from code review Apply the suggestions that can be committed from the GitHub web interface. Co-authored-by: Michael Davis --- book/src/configuration.md | 2 +- book/src/keymap.md | 2 +- book/src/remapping.md | 4 ++-- book/src/themes.md | 2 +- book/src/usage.md | 5 ++++- 5 files changed, 9 insertions(+), 6 deletions(-) diff --git a/book/src/configuration.md b/book/src/configuration.md index b262b231688d..c209ecbccba4 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -124,7 +124,7 @@ The following statusline elements can be configured: Defines the shape of cursor in each mode. Valid values for these options are `block`, `bar`, `underline`, or `hidden`. -> ๐Ÿ’กDue to limitations of the terminal environment, only the primary cursor can +> ๐Ÿ’ก Due to limitations of the terminal environment, only the primary cursor can > change shape. | Key | Description | Default | diff --git a/book/src/keymap.md b/book/src/keymap.md index 79e5decbed2c..608b34cf584a 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -238,7 +238,7 @@ TODO: Mappings for selecting syntax nodes (a superset of `[`). #### Window mode Window mode is accessed by typing `Ctrl-w` in [normal mode](#normal-mode), -this layer is similar to Vim keybindings as Kakoune does not support window. +this layer is similar to Vim keybindings as Kakoune does not support windows. | Key | Description | Command | | ----- | ------------- | ------- | diff --git a/book/src/remapping.md b/book/src/remapping.md index b7fb72a56298..59553e9acaa3 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -4,7 +4,7 @@ Helix currently supports one-way key remapping through a simple TOML configurati file. (More powerful solutions such as rebinding via commands will be available in the future). -To remap keys, create a `config.toml` file in your `Helix` configuration +To remap keys, create a `config.toml` file in your `helix` configuration directory (default `~/.config/helix` on Linux systems) with a structure like this: @@ -75,6 +75,6 @@ Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes Keys can be disabled by binding them to the `no_op` command. -You can find a list of available commands at [Keymap](https://docs.helix-editor.com/keymap.html). +You can find a list of available commands in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation. > 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 87ab5bb605f6..f8b91e197bee 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -131,7 +131,7 @@ supported by your terminal emulator. ### Inheritance -Extends other themes by setting the `inherits` property to an existing theme. +Extend other themes by setting the `inherits` property to an existing theme. ```toml inherits = "boo_berry" diff --git a/book/src/usage.md b/book/src/usage.md index 60ddfbc3f305..cb71e2518b84 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -121,7 +121,10 @@ If you have a selection that wraps `arg1` (see the tree above), and you use Alt-n, it will select the next sibling in the syntax tree: `arg2`. ```js -func([arg1], arg2, arg3) > func(arg1, [arg2], arg3); +// before +func([arg1], arg2, arg3) +// after +func(arg1, [arg2], arg3); ``` Similarly, Alt-o will expand the selection to the parent node, in this case, the From 550273c7c2b6770e8212b354b8b3d77ac6541546 Mon Sep 17 00:00:00 2001 From: David Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 1 Feb 2023 15:23:36 +0000 Subject: [PATCH 08/33] Add Windows themes folder Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com> --- book/src/themes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/themes.md b/book/src/themes.md index f8b91e197bee..d3625deab84f 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -9,7 +9,7 @@ To use a theme add `theme = ""` to the top of your [`config.toml`](./confi To create a theme file: 1. Create a 'themes' folder in your user configuration folder (e.g. - `~/.config/helix/themes`). + `~/.config/helix/themes`, or `%AppData%\helix\themes` on Windows). 2. Create a file with the name of your theme as the file name (e.g. `mytheme.toml`) and place it in your `themes` folder. From 498be1b7a1aec3ff567b95130148628beeef9b77 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Thu, 2 Feb 2023 12:23:32 +0000 Subject: [PATCH 09/33] Apply the rest of the suggestions from the code review --- book/src/keymap.md | 14 +++++++------- book/src/usage.md | 20 ++++++++++---------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index 72a8d54c5520..1e4e56a1cbfd 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -53,9 +53,9 @@ | `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 jump list | `jump_forward` | -| `Ctrl-o` | Jump backward on the jump list | `jump_backward` | -| `Ctrl-s` | Save the current selection to the jump list | `save_selection` | +| `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 @@ -221,7 +221,7 @@ various locations. Match mode is accessed by typing `m` in [normal mode](#normal-mode). See the relevant section in [Usage](./usage.md) for an explanation about -[surround](./usage.md#surround) and [text object](./usage.md#textobjects) usage. +[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. | Key | Description | Command | | ---------------- | ----------------------------------------------- | -------------------------- | @@ -229,8 +229,8 @@ See the relevant section in [Usage](./usage.md) for an explanation about | `s` `` | Surround current selection with `` | `surround_add` | | `r` `` | Replace surround character `` with `` | `surround_replace` | | `d` `` | Delete surround character `` | `surround_delete` | -| `a` `` | Select around text object | `select_textobject_around` | -| `i` `` | Select inside text object | `select_textobject_inner` | +| `a` `` | Select around textobject | `select_textobject_around` | +| `i` `` | Select inside textobject | `select_textobject_inner` | TODO: Mappings for selecting syntax nodes (a superset of `[`). @@ -268,7 +268,7 @@ This layer is a kludge of mappings, mostly pickers. | `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 jump list picker | `jump list_picker` | +| `j` | Open jumplist picker | `jump list_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` | diff --git a/book/src/usage.md b/book/src/usage.md index 8cac7149fe50..e2a44ae71f5e 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -6,7 +6,7 @@ - [User-defined Registers](#user-defined-registers) - [Built-in Registers](#built-in-registers) - [Surround](#surround) - - [Moving the Primary Selection with Syntax-tree Motions](#moving-the-primary-selection-with-syntax-tree-motions) + - [Moving the Selection with Syntax-tree Motions](#moving-the-selection-with-syntax-tree-motions) - [Selecting and Manipulating Text with Textobjects](#selecting-and-manipulating-text-with-textobjects) - [Navigating Using Tree-sitter Textobjects](#navigating-using-tree-sitter-textobjects) @@ -77,9 +77,9 @@ Surround can also act on multiple selections. For example, to change every occur Multiple characters are currently not supported, but planned for future release. -## Moving the Primary Selection with Syntax-tree Motions +## Moving the Selection with Syntax-tree Motions -`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the primary +`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the selection according to its location in the syntax tree. For example, many languages have the following syntax for function calls: @@ -119,7 +119,7 @@ a more intuitive tree format: ``` If you have a selection that wraps `arg1` (see the tree above), and you use -Alt-n, it will select the next sibling in the syntax tree: `arg2`. +`Alt-n`, it will select the next sibling in the syntax tree: `arg2`. ```js // before @@ -128,7 +128,7 @@ func([arg1], arg2, arg3) func(arg1, [arg2], arg3); ``` -Similarly, Alt-o will expand the selection to the parent node, in this case, the +Similarly, `Alt-o` will expand the selection to the parent node, in this case, the arguments node. ```js @@ -136,15 +136,15 @@ func[(arg1, arg2, arg3)]; ``` There is also some nuanced behavior that prevents you from getting stuck on a -node with no sibling. When using Alt-p with a selection on `arg1`, the previous +node with no sibling. When using `Alt-p` with a selection on `arg1`, the previous child node will be selected. In the event that `arg1` does not have a previous sibling, the selection will move up the syntax tree and select the previous -element. As a result, using Alt-p with a selection on `arg1` will move the +element. As a result, using `Alt-p` with a selection on `arg1` will move the selection to the "func" `identifier`. ## Selecting and Manipulating Text with Textobjects -In Helix, Textobjects are a way to select, manipulate and operate on a piece of +In Helix, textobjects are a way to select, manipulate and operate on a piece of text in a structured way. They allow you to refer to blocks of text based on their structure or purpose, such as a word, sentence, paragraph, or even a function or block of code. @@ -177,7 +177,7 @@ Contributions are welcome! ## Navigating Using Tree-sitter Textobject Navigating between functions, classes, parameters, and other elements is -possible using tree-sitter and Textobject queries. For +possible using tree-sitter and textobject queries. For example to move to the next function use `]f`, to move to previous class use `[c`, and so on. @@ -186,7 +186,7 @@ class use `[c`, and so on. For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind documentation. -> ๐Ÿ’ก This feature relies on tree-sitter Textobjects +> ๐Ÿ’ก This feature relies on tree-sitter textobjects > and requires the corresponding query file to work properly. [lang-support]: ./lang-support.md From 7cfdd9c1bcf6b583e7291de4512d2a176c6d6db6 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Thu, 2 Feb 2023 12:43:27 +0000 Subject: [PATCH 10/33] Revert "Apply the rest of the suggestions from the code review" This reverts commit 498be1b7a1aec3ff567b95130148628beeef9b77. --- book/src/keymap.md | 14 +++++++------- book/src/usage.md | 20 ++++++++++---------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index 1e4e56a1cbfd..72a8d54c5520 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -53,9 +53,9 @@ | `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` | +| `Ctrl-i` | Jump forward on the jump list | `jump_forward` | +| `Ctrl-o` | Jump backward on the jump list | `jump_backward` | +| `Ctrl-s` | Save the current selection to the jump list | `save_selection` | ### Changes @@ -221,7 +221,7 @@ various locations. Match mode is accessed by typing `m` in [normal mode](#normal-mode). See the relevant section in [Usage](./usage.md) for an explanation about -[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. +[surround](./usage.md#surround) and [text object](./usage.md#textobjects) usage. | Key | Description | Command | | ---------------- | ----------------------------------------------- | -------------------------- | @@ -229,8 +229,8 @@ See the relevant section in [Usage](./usage.md) for an explanation about | `s` `` | Surround current selection with `` | `surround_add` | | `r` `` | Replace surround character `` with `` | `surround_replace` | | `d` `` | Delete surround character `` | `surround_delete` | -| `a` `` | Select around textobject | `select_textobject_around` | -| `i` `` | Select inside textobject | `select_textobject_inner` | +| `a` `` | Select around text object | `select_textobject_around` | +| `i` `` | Select inside text object | `select_textobject_inner` | TODO: Mappings for selecting syntax nodes (a superset of `[`). @@ -268,7 +268,7 @@ This layer is a kludge of mappings, mostly pickers. | `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 | `jump list_picker` | +| `j` | Open jump list picker | `jump list_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` | diff --git a/book/src/usage.md b/book/src/usage.md index e2a44ae71f5e..8cac7149fe50 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -6,7 +6,7 @@ - [User-defined Registers](#user-defined-registers) - [Built-in Registers](#built-in-registers) - [Surround](#surround) - - [Moving the Selection with Syntax-tree Motions](#moving-the-selection-with-syntax-tree-motions) + - [Moving the Primary Selection with Syntax-tree Motions](#moving-the-primary-selection-with-syntax-tree-motions) - [Selecting and Manipulating Text with Textobjects](#selecting-and-manipulating-text-with-textobjects) - [Navigating Using Tree-sitter Textobjects](#navigating-using-tree-sitter-textobjects) @@ -77,9 +77,9 @@ Surround can also act on multiple selections. For example, to change every occur Multiple characters are currently not supported, but planned for future release. -## Moving the Selection with Syntax-tree Motions +## Moving the Primary Selection with Syntax-tree Motions -`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the +`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the primary selection according to its location in the syntax tree. For example, many languages have the following syntax for function calls: @@ -119,7 +119,7 @@ a more intuitive tree format: ``` If you have a selection that wraps `arg1` (see the tree above), and you use -`Alt-n`, it will select the next sibling in the syntax tree: `arg2`. +Alt-n, it will select the next sibling in the syntax tree: `arg2`. ```js // before @@ -128,7 +128,7 @@ func([arg1], arg2, arg3) func(arg1, [arg2], arg3); ``` -Similarly, `Alt-o` will expand the selection to the parent node, in this case, the +Similarly, Alt-o will expand the selection to the parent node, in this case, the arguments node. ```js @@ -136,15 +136,15 @@ func[(arg1, arg2, arg3)]; ``` There is also some nuanced behavior that prevents you from getting stuck on a -node with no sibling. When using `Alt-p` with a selection on `arg1`, the previous +node with no sibling. When using Alt-p with a selection on `arg1`, the previous child node will be selected. In the event that `arg1` does not have a previous sibling, the selection will move up the syntax tree and select the previous -element. As a result, using `Alt-p` with a selection on `arg1` will move the +element. As a result, using Alt-p with a selection on `arg1` will move the selection to the "func" `identifier`. ## Selecting and Manipulating Text with Textobjects -In Helix, textobjects are a way to select, manipulate and operate on a piece of +In Helix, Textobjects are a way to select, manipulate and operate on a piece of text in a structured way. They allow you to refer to blocks of text based on their structure or purpose, such as a word, sentence, paragraph, or even a function or block of code. @@ -177,7 +177,7 @@ Contributions are welcome! ## Navigating Using Tree-sitter Textobject Navigating between functions, classes, parameters, and other elements is -possible using tree-sitter and textobject queries. For +possible using tree-sitter and Textobject queries. For example to move to the next function use `]f`, to move to previous class use `[c`, and so on. @@ -186,7 +186,7 @@ class use `[c`, and so on. For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind documentation. -> ๐Ÿ’ก This feature relies on tree-sitter textobjects +> ๐Ÿ’ก This feature relies on tree-sitter Textobjects > and requires the corresponding query file to work properly. [lang-support]: ./lang-support.md From 1480e19c15a6ff212657d0b68c4c42f865676881 Mon Sep 17 00:00:00 2001 From: Michael Davis Date: Thu, 2 Feb 2023 10:06:39 -0600 Subject: [PATCH 11/33] Revert "Merge branch 'rewrite-and-refactor-all-documentation' of github.com:David-Else/helix into rewrite-and-refactor-all-documentation" This reverts commit 7c8404248ffef73b80b9051d5a4359c5bcfa5d1a, reversing changes made to d932969cfc9fadda12a74cc01665919dee7152fb. --- book/src/configuration.md | 100 ++++++++++++------------ book/src/guides/indent.md | 114 ++++++++++++++------------- book/src/guides/textobject.md | 5 +- book/src/install.md | 2 +- book/src/keymap.md | 140 +++++++++++++++++----------------- book/src/lang-support.md | 3 +- book/src/languages.md | 86 ++++++++++----------- book/src/remapping.md | 14 +--- book/src/themes.md | 28 +------ book/src/usage.md | 12 ++- 10 files changed, 235 insertions(+), 269 deletions(-) diff --git a/book/src/configuration.md b/book/src/configuration.md index a3d017e13dc8..c209ecbccba4 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -1,7 +1,6 @@ # 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` @@ -77,51 +76,48 @@ 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 @@ -132,7 +128,7 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`. > change shape. | 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` | @@ -170,9 +166,8 @@ 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] @@ -184,9 +179,9 @@ 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 '' @@ -214,14 +209,12 @@ Search specific options. ### `[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`, `nbsp`, `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 | +| Key | Description | Default | +|-----|-------------|---------| +| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `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 @@ -247,7 +240,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` | @@ -311,3 +304,4 @@ Currently unused #### `[editor.gutters.spacer]` Section +Currently unused \ No newline at end of file diff --git a/book/src/guides/indent.md b/book/src/guides/indent.md index c12f9fef6352..0e259289781e 100644 --- a/book/src/guides/indent.md +++ b/book/src/guides/indent.md @@ -1,33 +1,35 @@ # 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): - -- `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. +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): -- `tail`: This scope applies to everything except for the first line of the - captured node. +- `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. -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: +- `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: ```scm (assignment_expression right: (_) @indent @@ -36,54 +38,56 @@ situations. When a different scope is required, this can be changed by using a ## 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. +- `@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. +- `@outdent` (default scope `all`): +Decrease the indent level by 1. The same rules as for `@indent` apply. -- `@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`: +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). +- `@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: +## 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: ```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: -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). +- `#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 be4b140d57f0..71082f4be504 100644 --- a/book/src/guides/textobject.md +++ b/book/src/guides/textobject.md @@ -15,7 +15,7 @@ for example). The following [captures][tree-sitter-captures] are recognized: | Capture Name | -| ------------------ | +| --- | | `function.inside` | | `function.around` | | `class.inside` | @@ -26,8 +26,7 @@ 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 diff --git a/book/src/install.md b/book/src/install.md index cbf405cf0749..52a807c239cc 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -118,7 +118,7 @@ For 64-bit Windows 8.1 or above: pacman -S mingw-w64-ucrt-x86_64-helix ``` -2. Compile Helix: +## Build from source 1. Clone the repository: diff --git a/book/src/keymap.md b/book/src/keymap.md index 72a8d54c5520..608b34cf584a 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -60,7 +60,7 @@ ### 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` | @@ -82,7 +82,7 @@ | `P` | Paste before selection | `paste_before` | | `"` `` | Select a register to yank to or paste from | `select_register` | | `>` | Indent selection | `indent` | -| `<` | Remove indentation from the selection | `unindent` | +| `<` | Unindent selection | `unindent` | | `=` | Format selection (currently nonfunctional/disabled) (**LSP**) | `format_selections` | | `d` | Delete selection | `delete_selection` | | `Alt-d` | Delete selection, without yanking | `delete_selection_noyank` | @@ -95,13 +95,14 @@ #### 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 @@ -142,20 +143,20 @@ Search commands all operate on the `/` register by default. To use a different register, use `"`. -| 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 Minor 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 | @@ -178,7 +179,7 @@ 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` | @@ -224,7 +225,7 @@ See the relevant section in [Usage](./usage.md) for an explanation about [surround](./usage.md#surround) and [text object](./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` | @@ -240,7 +241,7 @@ Window mode is accessed by typing `Ctrl-w` in [normal mode](#normal-mode), this layer is similar to Vim keybindings as Kakoune does not support windows. | 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` | @@ -290,11 +291,10 @@ This layer is a kludge of mappings, mostly pickers. ##### Popup -Popups display documentation for items under the cursor. If there is more -content than fits on the screen, you can use scroll: +Displays documentation for item under cursor. | Key | Description | -| -------- | ----------- | +| ---- | ----------- | | `Ctrl-u` | Scroll up | | `Ctrl-d` | Scroll down | @@ -354,16 +354,16 @@ escaping from insert mode to normal mode. 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` | As you become more comfortable with modal editing, you may want to disable some insert mode bindings. You can do this by editing your `config.toml` file. @@ -388,52 +388,52 @@ 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 add64a0a9571..3f96673bc953 100644 --- a/book/src/lang-support.md +++ b/book/src/lang-support.md @@ -11,7 +11,6 @@ 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 963827a2d4ba..c368b3e9e85d 100644 --- a/book/src/languages.md +++ b/book/src/languages.md @@ -1,7 +1,7 @@ # 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 @@ -47,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 @@ -84,28 +84,27 @@ 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: @@ -131,23 +130,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 @@ -158,5 +157,4 @@ 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 5b081cf16308..59553e9acaa3 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -9,9 +9,7 @@ directory (default `~/.config/helix` on Linux systems) with a structure like this: ```toml - # At most one section each of 'keys.normal', 'keys.insert' and 'keys.select' - [keys.normal] C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file) C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file @@ -19,15 +17,11 @@ a = "move_char_left" # Maps the 'a' key to the move_char_left command w = "move_line_up" # Maps the 'w' key move_line_up "C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line g = { a = "code_action" } # Maps `ga` to show possible code actions -"ret" = [ - "open_below", - "normal_mode", -] # Maps the enter key to open_below then re-enter normal mode +"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode [keys.insert] "A-x" = "normal_mode" # Maps Alt-X to enter normal mode j = { k = "normal_mode" } # Maps `jk` to exit insert mode - ``` ## Minor modes @@ -56,11 +50,11 @@ t = ":run-shell-command cargo test" ## Special keys and modifiers -Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes `C-`, -`S-` and `A-`. Special keys are encoded as follows: +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"` | diff --git a/book/src/themes.md b/book/src/themes.md index 9d06216c365e..d3625deab84f 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -18,12 +18,7 @@ To create a theme file: ### An overview of the Theme File Format -> ๐Ÿ’ก The names "default" and "base16_default" are reserved for built-in themes -> and cannot be overridden by user-defined themes. - -### An Overview of the Theme File Format - -Each line in the theme file is specified as follows: +Each line in the theme file is specified as below: ```toml key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] } @@ -82,7 +77,7 @@ 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` | @@ -133,13 +128,6 @@ supported by your terminal emulator. | `dotted` | | `double_line` | -| Modifier | -| ------------- | -| `line` | -| `curl` | -| `dashed` | -| `dotted` | -| `double_line` | ### Inheritance @@ -162,8 +150,7 @@ 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). When determining styling for a highlight, the longest matching theme key will be used. For example, if the highlight is `function.builtin.static`, the key `function.builtin` will be used instead of `function`. @@ -189,7 +176,6 @@ We use a similar set of scopes as - `float` - `string` (TODO: string.quoted.{single, double}, string.raw/.unquoted)? - - `regexp` - Regular expressions - `special` - `path` @@ -197,14 +183,12 @@ 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. (`/* */`) - `documentation` - Documentation comments (e.g. `///` in Rust) - `variable` - Variables - - - `builtin` - Reserved language variables (`self`, `this`, `super`, etc.) + - `builtin` - Reserved language variables (`self`, `this`, `super`, etc) - `parameter` - Function parameters - `other` - `member` - Fields of composite data types (e.g. structs, unions) @@ -212,13 +196,11 @@ 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` @@ -235,7 +217,6 @@ We use a similar set of scopes as - `operator` - `||`, `+=`, `>` - `function` - - `builtin` - `method` - `macro` @@ -248,7 +229,6 @@ We use a similar set of scopes as - `special` - `markup` - - `heading` - `marker` - `1`, `2`, `3`, `4`, `5`, `6` - heading text for h1 through h6 diff --git a/book/src/usage.md b/book/src/usage.md index 8cac7149fe50..cb71e2518b84 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -35,14 +35,13 @@ example: If a register is selected before invoking a change or delete command, the selection will be stored in the register and the action will be carried out: -- `"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. ### Built-in Registers | Register character | Contains | -| ------------------ | --------------------- | +| --- | --- | | `/` | Last search | | `:` | Last executed command | | `"` | Last yanked text | @@ -87,7 +86,7 @@ following syntax for function calls: func(arg1, arg2, arg3); ``` -A function call parsed by tree-sitter might look like: +A function call might be parsed by tree-sitter into a tree like the following. ```tsq (call @@ -156,7 +155,7 @@ function or block of code. - `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) | Key after `mi` or `ma` | Textobject selected | -| ---------------------- | ------------------------ | +| --- | --- | | `w` | Word | | `W` | WORD | | `p` | Paragraph | @@ -191,5 +190,4 @@ documentation. [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 From f92d5804743c17fe9dc6e1cc1d7e055ab63328ed Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Fri, 3 Feb 2023 14:50:01 +0000 Subject: [PATCH 12/33] Apply code review suggestions --- book/src/keymap.md | 14 +++++++------- book/src/usage.md | 24 ++++++++++++------------ 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index 608b34cf584a..3979a8413c41 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -53,9 +53,9 @@ | `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 jump list | `jump_forward` | -| `Ctrl-o` | Jump backward on the jump list | `jump_backward` | -| `Ctrl-s` | Save the current selection to the jump list | `save_selection` | +| `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 @@ -222,7 +222,7 @@ various locations. Match mode is accessed by typing `m` in [normal mode](#normal-mode). See the relevant section in [Usage](./usage.md) for an explanation about -[surround](./usage.md#surround) and [text object](./usage.md#textobjects) usage. +[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. | Key | Description | Command | | ----- | ----------- | ------- | @@ -230,8 +230,8 @@ See the relevant section in [Usage](./usage.md) for an explanation about | `s` `` | Surround current selection with `` | `surround_add` | | `r` `` | Replace surround character `` with `` | `surround_replace` | | `d` `` | Delete surround character `` | `surround_delete` | -| `a` `` | Select around text object | `select_textobject_around` | -| `i` `` | Select inside text object | `select_textobject_inner` | +| `a` `` | Select around textobject | `select_textobject_around` | +| `i` `` | Select inside textobject | `select_textobject_inner` | TODO: Mappings for selecting syntax nodes (a superset of `[`). @@ -269,7 +269,7 @@ This layer is a kludge of mappings, mostly pickers. | `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 jump list picker | `jump list_picker` | +| `j` | Open jumplist picker | `jump list_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` | diff --git a/book/src/usage.md b/book/src/usage.md index cb71e2518b84..9d929470520b 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -6,7 +6,7 @@ - [User-defined Registers](#user-defined-registers) - [Built-in Registers](#built-in-registers) - [Surround](#surround) - - [Moving the Primary Selection with Syntax-tree Motions](#moving-the-primary-selection-with-syntax-tree-motions) + - [Moving the Selection with Syntax-tree Motions](#moving-the-selection-with-syntax-tree-motions) - [Selecting and Manipulating Text with Textobjects](#selecting-and-manipulating-text-with-textobjects) - [Navigating Using Tree-sitter Textobjects](#navigating-using-tree-sitter-textobjects) @@ -76,9 +76,9 @@ Surround can also act on multiple selections. For example, to change every occur Multiple characters are currently not supported, but planned for future release. -## Moving the Primary Selection with Syntax-tree Motions +## Moving the Selection with Syntax-tree Motions -`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the primary +`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the selection according to its location in the syntax tree. For example, many languages have the following syntax for function calls: @@ -118,7 +118,7 @@ a more intuitive tree format: ``` If you have a selection that wraps `arg1` (see the tree above), and you use -Alt-n, it will select the next sibling in the syntax tree: `arg2`. +`Alt-n`, it will select the next sibling in the syntax tree: `arg2`. ```js // before @@ -127,7 +127,7 @@ func([arg1], arg2, arg3) func(arg1, [arg2], arg3); ``` -Similarly, Alt-o will expand the selection to the parent node, in this case, the +Similarly, `Alt-o` will expand the selection to the parent node, in this case, the arguments node. ```js @@ -135,21 +135,21 @@ func[(arg1, arg2, arg3)]; ``` There is also some nuanced behavior that prevents you from getting stuck on a -node with no sibling. When using Alt-p with a selection on `arg1`, the previous +node with no sibling. When using `Alt-p` with a selection on `arg1`, the previous child node will be selected. In the event that `arg1` does not have a previous sibling, the selection will move up the syntax tree and select the previous -element. As a result, using Alt-p with a selection on `arg1` will move the +element. As a result, using `Alt-p` with a selection on `arg1` will move the selection to the "func" `identifier`. ## Selecting and Manipulating Text with Textobjects -In Helix, Textobjects are a way to select, manipulate and operate on a piece of +In Helix, textobjects are a way to select, manipulate and operate on a piece of text in a structured way. They allow you to refer to blocks of text based on their structure or purpose, such as a word, sentence, paragraph, or even a function or block of code. -![Textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) -![Textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) +![textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) +![textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) - `ma` - Select around the object (`va` in Vim, `` in Kakoune) - `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) @@ -176,7 +176,7 @@ Contributions are welcome! ## Navigating Using Tree-sitter Textobject Navigating between functions, classes, parameters, and other elements is -possible using tree-sitter and Textobject queries. For +possible using tree-sitter and textobject queries. For example to move to the next function use `]f`, to move to previous class use `[c`, and so on. @@ -185,7 +185,7 @@ class use `[c`, and so on. For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind documentation. -> ๐Ÿ’ก This feature relies on tree-sitter Textobjects +> ๐Ÿ’ก This feature relies on tree-sitter textobjects > and requires the corresponding query file to work properly. [lang-support]: ./lang-support.md From f7ed274e39b986245cf23522d7a431e8e680075b Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Fri, 3 Feb 2023 16:16:50 +0000 Subject: [PATCH 13/33] Changes after re-reading all documents --- book/src/configuration.md | 58 ++++++++++++++--------------- book/src/guides/adding_languages.md | 2 +- book/src/install.md | 4 +- book/src/keymap.md | 4 +- book/src/languages.md | 2 +- book/src/remapping.md | 5 +-- book/src/themes.md | 10 ++--- book/src/usage.md | 12 +++--- 8 files changed, 48 insertions(+), 49 deletions(-) diff --git a/book/src/configuration.md b/book/src/configuration.md index d736ddbc493d..1698840bbc4c 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -36,23 +36,23 @@ signal to the Helix process on Unix operating systems, such as by using the comm | 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"]` | +| `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` | +| `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 the 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` | +| `auto-completion` | Enable automatic pop up of auto-completion | `true` | +| `auto-format` | Enable automatic formatting on save | `true` | +| `auto-save` | Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal | `false` | +| `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. | `[]` | +| `auto-info` | Whether to display info boxes | `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` | @@ -139,22 +139,22 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`. ### `[editor.file-picker]` Section -Sets options for file picker and global search. Ignoring a file means it is +Set options for file picker and global search. Ignoring a file means it is not visible in the Helix file picker and global search. All git related options are only enabled in a git repository. | Key | Description | Default | |--|--|---------| -|`hidden` | Enables ignoring hidden files. | true +|`hidden` | Enables ignoring hidden files | true |`follow-links` | Follow symlinks instead of ignoring them | true |`deduplicate-links` | Ignore symlinks that point at files already shown in the picker | 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`. +|`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 @@ -215,7 +215,7 @@ Options for rendering whitespace with visible characters. Use `:set whitespace.r | Key | Description | Default | |-----|-------------|---------| -| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline`. | `"none"` | +| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `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 +243,7 @@ Options for rendering vertical indent guides. | Key | Description | Default | | --- | --- | --- | -| `render` | Whether to render indent guides. | `false` | +| `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` | @@ -268,7 +268,7 @@ gutters = ["diff", "diagnostics", "line-numbers", "spacer"] To customize the behavior of gutters, the `[editor.gutters]` section must be used. This section contains top level settings, as well as settings for -specific gutter components as sub-sections. +specific gutter components as subsections. | Key | Description | Default | | --- | --- | --- | @@ -310,13 +310,13 @@ Currently unused ### `[editor.soft-wrap]` Section -Options for soft wrapping lines that exceed the view width +Options for soft wrapping lines that exceed the view width: | Key | Description | Default | | --- | --- | --- | -| `enable` | Whether soft wrapping is enabled. | `false` | -| `max-wrap` | Maximum free space left at the end of the line. | `20` | -| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line. | `40` | +| `enable` | Whether soft wrapping is enabled | `false` | +| `max-wrap` | Maximum free space left at the end of the line | `20` | +| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line | `40` | | `wrap-indicator` | Text inserted before soft wrapped lines, highlighted with `ui.virtual.wrap` | `โ†ช ` | Example: diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md index 816826cfc125..5a3fe3ec817b 100644 --- a/book/src/guides/adding_languages.md +++ b/book/src/guides/adding_languages.md @@ -48,5 +48,5 @@ below. need to update the tree-sitter grammars. Run the command `hx --grammar fetch` to fetch the grammars and `hx --grammar build` to build any out-of-date grammars. -- If a parser is causing a segfault or you want to remove it, make sure to +- If a parser is causing a segfault, or you want to remove it, make sure to remove the compiled parser located at `runtime/grammar/.so`. diff --git a/book/src/install.md b/book/src/install.md index 52a807c239cc..f576e14a1909 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -118,7 +118,7 @@ For 64-bit Windows 8.1 or above: pacman -S mingw-w64-ucrt-x86_64-helix ``` -## Build from source +## Building from source 1. Clone the repository: @@ -185,7 +185,7 @@ provided `.desktop` and icon files to their correct folders: ```sh cp contrib/Helix.desktop ~/.local/share/applications -cp contrib/helix.png ~/.local/share/icons +cp contrib/helix.png ~/.icons # or ~/.local/share/icons ``` To use another terminal than the system default, you can modify the `.desktop` diff --git a/book/src/keymap.md b/book/src/keymap.md index 3979a8413c41..bbf982f4dec3 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -15,7 +15,7 @@ - [Popup](#popup) - [Unimpaired](#unimpaired) - [Insert Mode](#insert-mode) -- [Select / extend mode](#select--extend-mode) +- [Select / extend mode](#select-extend-mode) - [Picker](#picker) - [Prompt](#prompt) @@ -287,7 +287,7 @@ This layer is a kludge of mappings, mostly pickers. | `/` | 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. +> ๐Ÿ’ก Global search displays results in a fuzzy picker, use `Space + '` to bring it back up after opening a file. ##### Popup diff --git a/book/src/languages.md b/book/src/languages.md index e225748383e3..269e04f3e0e5 100644 --- a/book/src/languages.md +++ b/book/src/languages.md @@ -8,7 +8,7 @@ in `languages.toml` files. There are three possible locations for a `languages.toml` file: 1. In the Helix source code, this lives in the - [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml) + [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml). It provides the default configurations for languages and language servers. 2. In your [configuration directory](./configuration.md). This overrides values diff --git a/book/src/remapping.md b/book/src/remapping.md index 59553e9acaa3..241f56b44e49 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -75,6 +75,5 @@ Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes Keys can be disabled by binding them to the `no_op` command. -You can find a list of available commands in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation. - -> 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`. +You can find a list of available commands in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation + and in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`. diff --git a/book/src/themes.md b/book/src/themes.md index d3625deab84f..68755628cf0b 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -16,7 +16,7 @@ To create a theme file: > ๐Ÿ’ก The names "default" and "base16_default" are reserved for built-in themes > and cannot be overridden by user-defined themes. -### An overview of the Theme File Format +### An Overview of the Theme File Format Each line in the theme file is specified as below: @@ -188,7 +188,7 @@ We use a similar set of scopes as - `documentation` - Documentation comments (e.g. `///` in Rust) - `variable` - Variables - - `builtin` - Reserved language variables (`self`, `this`, `super`, etc) + - `builtin` - Reserved language variables (`self`, `this`, `super`, etc.) - `parameter` - Function parameters - `other` - `member` - Fields of composite data types (e.g. structs, unions) @@ -292,16 +292,16 @@ 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.window` | Borderlines separating splits | | `ui.help` | Description box for commands | | `ui.text` | Command prompts, popup text, etc. | | `ui.text.focus` | | | `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/usage.md b/book/src/usage.md index 9d929470520b..43bdac1c2526 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -148,8 +148,8 @@ text in a structured way. They allow you to refer to blocks of text based on their structure or purpose, such as a word, sentence, paragraph, or even a function or block of code. -![textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) -![textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) +![Textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) +![Textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) - `ma` - Select around the object (`va` in Vim, `` in Kakoune) - `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) @@ -160,7 +160,7 @@ function or block of code. | `W` | WORD | | `p` | Paragraph | | `(`, `[`, `'`, etc. | Specified surround pairs | -| `m` | Closest surround pair | +| `m` | The closest surround pair | | `f` | Function | | `c` | Class | | `a` | Argument/parameter | @@ -168,19 +168,19 @@ function or block of code. | `t` | Test | | `g` | Change | -> ๐Ÿ’ก `f`, `c`, etc need a tree-sitter grammar active for the current +> ๐Ÿ’ก `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! -## Navigating Using Tree-sitter Textobject +## Navigating Using Tree-sitter Textobjects Navigating between functions, classes, parameters, and other elements is possible using tree-sitter and textobject 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] +![Tree-sitter-nav-demo][tree-sitter-nav-demo] For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind documentation. From a5567a990e0d778e10c514c2634f7c76abc8871d Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Fri, 3 Feb 2023 16:20:23 +0000 Subject: [PATCH 14/33] Missed a full stop --- book/src/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/configuration.md b/book/src/configuration.md index 1698840bbc4c..5427afa0f6a1 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -41,7 +41,7 @@ signal to the Helix process on Unix operating systems, such as by using the comm | `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` | +| `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"]` | From 192e89126fe53625156bb512e70ed1ca91beb79c Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Tue, 7 Feb 2023 14:50:52 +0000 Subject: [PATCH 15/33] Code review suggestions and remove macOS and Windows specific sections --- book/src/install.md | 83 +++++++++++++-------------------------------- 1 file changed, 23 insertions(+), 60 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index f576e14a1909..f4a5e41f6235 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -1,15 +1,17 @@ -# Installing Helix +# Installation -- [Installing Helix](#installing-helix) - - [Using the Pre-built Binaries](#using-the-pre-built-binaries) - - [Installing Helix on Linux through the Official Package Manager](#installing-helix-on-linux-through-the-official-package-manager) - - [Installing Helix on Linux via Third-Party Repositories](#installing-helix-on-linux-via-third-party-repositories) - - [Installing Helix on macOS via Homebrew](#installing-helix-on-macos-via-homebrew) - - [Installing Helix on Windows](#installing-helix-on-windows) - - [Building from Source](#building-from-source) +- [Installation](#installation) + - [Pre-built binaries](#pre-built-binaries) + - [Official repositories for Linux, macOS and Windows](#official-repositories-for-linux-macos-and-windows) + - [Third party repositories for Linux](#third-party-repositories-for-linux) + - [Ubuntu](#ubuntu) + - [Fedora/RHEL](#fedorarhel) + - [Arch Linux community](#arch-linux-community) + - [NixOS](#nixos) + - [Building from source](#building-from-source) - [Validating the Installation](#validating-the-installation) - + To install Helix, follow the instructions specific to your operating system. Additionally: @@ -22,35 +24,29 @@ Additionally: [Helix Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) for detailed instructions. -## Using the Pre-built Binaries +## Pre-built binaries Download pre-built binaries from the [GitHub Releases page](https://github.com/helix-editor/helix/releases). You will need to add the binary to your system's `$PATH` to access it from the command line. -## Installing Helix on Linux through the Official Package Manager +## Official repositories for Linux, macOS and Windows -If your Linux distribution has Helix available through its official package -manager, install it through that. The following shows availability -throughout the Linux ecosystem: +Helix is available for Linux, macOS and Windows via the official repositories listed below. For installation instructions consult the documentation. [![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions) -## Installing Helix on Linux via Third-Party Repositories +If Helix is not available through the above list, you will need to use a +third-party repository or build from source. -If Helix is not available through your distribution's official repository, use a -third-party repository. +## Third party repositories for Linux -### Ubuntu - -Helix is available for the following versions of Ubuntu: +The following third party repositories are available: -- 20.04 LTS (Focal Fossa) -- 22.04 LTS (Jammy Jellyfish) -- 22.10 (Kinetic Kudu) +### Ubuntu -Via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor) +Helix is available via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor): ```sh sudo add-apt-repository ppa:maveonair/helix-editor @@ -58,7 +54,7 @@ sudo apt update sudo apt install helix ``` -### Fedora/RHEL Linux +### Fedora/RHEL Helix is available via `copr`: @@ -67,9 +63,9 @@ sudo dnf copr enable varlad/helix sudo dnf install helix ``` -### Arch Linux Community +### Arch Linux community -Releases are available in the community repository. Additionally, a +Releases are available in the `community` repository. Additionally, a [helix-git](https://aur.archlinux.org/packages/helix-git/) package is available in the AUR, which builds the master branch. @@ -85,39 +81,6 @@ If you are using a version of Nix without flakes enabled, [install Cachix CLI](https://docs.cachix.org/installation) and use `cachix use helix` to configure Nix to use cached outputs when possible. -## Installing Helix on macOS via Homebrew - -Helix is available in Homebrew Core: - -```sh -brew install helix -``` - -## Installing Helix on Windows - -Install on Windows using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/) -or [MSYS2](https://msys2.org/). - -**Scoop:** - -```sh -scoop install helix -``` - -**Chocolatey:** - -```sh -choco install helix -``` - -**MSYS2:** - -For 64-bit Windows 8.1 or above: - -```sh -pacman -S mingw-w64-ucrt-x86_64-helix -``` - ## Building from source 1. Clone the repository: From e01032e113e5bb67f13aaa59b5773306fe688d66 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Tue, 7 Feb 2023 15:42:19 +0000 Subject: [PATCH 16/33] Add OpenBSD to heading --- book/src/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/install.md b/book/src/install.md index f4a5e41f6235..a364db6458d9 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -31,7 +31,7 @@ Download pre-built binaries from the need to add the binary to your system's `$PATH` to access it from the command line. -## Official repositories for Linux, macOS and Windows +## Official repositories for Linux, macOS, Windows and OpenBSD Helix is available for Linux, macOS and Windows via the official repositories listed below. For installation instructions consult the documentation. From 445314c5cf5bce9ae4bc4e7a25a8cf497acc2b1d Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 8 Feb 2023 15:23:42 +0000 Subject: [PATCH 17/33] Add back macOS and Windows sections and further simplify and improve --- book/src/install.md | 61 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 10 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index a364db6458d9..8a28c4126e76 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -3,13 +3,21 @@ - [Installation](#installation) - [Pre-built binaries](#pre-built-binaries) - - [Official repositories for Linux, macOS and Windows](#official-repositories-for-linux-macos-and-windows) - - [Third party repositories for Linux](#third-party-repositories-for-linux) + - [Linux, macOS, Windows and OpenBSD via official repositories](#linux-macos-windows-and-openbsd-via-official-repositories) + - [Linux](#linux) - [Ubuntu](#ubuntu) - [Fedora/RHEL](#fedorarhel) - [Arch Linux community](#arch-linux-community) - [NixOS](#nixos) + - [macOS](#macos) + - [Homebrew Core](#homebrew-core) + - [Windows](#windows) + - [Scoop](#scoop) + - [Chocolatey](#chocolatey) + - [MSYS2](#msys2) - [Building from source](#building-from-source) + - [Additional steps for Linux and macOS](#additional-steps-for-linux-and-macos) + - [Additional steps for Windows](#additional-steps-for-windows) - [Validating the Installation](#validating-the-installation) @@ -31,16 +39,13 @@ Download pre-built binaries from the need to add the binary to your system's `$PATH` to access it from the command line. -## Official repositories for Linux, macOS, Windows and OpenBSD +## Linux, macOS, Windows and OpenBSD via official repositories -Helix is available for Linux, macOS and Windows via the official repositories listed below. For installation instructions consult the documentation. +Helix is available for Linux, macOS and Windows via the official repositories listed below. [![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions) -If Helix is not available through the above list, you will need to use a -third-party repository or build from source. - -## Third party repositories for Linux +## Linux The following third party repositories are available: @@ -80,6 +85,42 @@ accepts the new settings on first use. If you are using a version of Nix without flakes enabled, [install Cachix CLI](https://docs.cachix.org/installation) and use `cachix use helix` to configure Nix to use cached outputs when possible. +@@ -85,39 +81,6 @@ ### NixOS + [install Cachix CLI](https://docs.cachix.org/installation) and use + `cachix use helix` to configure Nix to use cached outputs when possible. + +## macOS + +### Homebrew Core + +```sh +brew install helix +``` + +## Windows + +Install on Windows using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/) +or [MSYS2](https://msys2.org/). + +### Scoop + +```sh +scoop install helix +``` + +### Chocolatey + +```sh +choco install helix +``` + +### MSYS2 + +For 64-bit Windows 8.1 or above: + +```sh +pacman -S mingw-w64-ucrt-x86_64-helix +``` ## Building from source @@ -117,7 +158,7 @@ accessible, you must follow the instructions for your operating system: > grammars with `hx --grammar fetch` (requires `git`) and compile them with > `hx --grammar build` (requires a C++ compiler). -- Linux and macOS +### Additional steps for Linux and macOS Either, @@ -159,7 +200,7 @@ sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.deskt sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop ``` -- Windows +### Additional steps for Windows Either, From 47fca795163c71021f0c4fc7ee24a30aa6e379ab Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 8 Feb 2023 15:28:49 +0000 Subject: [PATCH 18/33] Change wording to nightly --- book/src/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/install.md b/book/src/install.md index 8a28c4126e76..3b9d39b3c3ad 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -24,7 +24,7 @@ To install Helix, follow the instructions specific to your operating system. Additionally: -- To get the latest pre-release version of Helix, you will need to +- To get the latest nightly version of Helix, you will need to [build from source](#building-from-source). - To take full advantage of Helix, install the language servers for your From 6674a081b9bbd11e71163fe9d45564ef7fe8c3d6 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 8 Feb 2023 16:00:55 +0000 Subject: [PATCH 19/33] Remove README installation section and turn into a link --- README.md | 83 +------------------------------------------------------ 1 file changed, 1 insertion(+), 82 deletions(-) diff --git a/README.md b/README.md index 60125e11800b..cba52a7a1e86 100644 --- a/README.md +++ b/README.md @@ -45,91 +45,10 @@ Note: Only certain languages have indentation definitions at the moment. Check # Installation -Packages are available for various distributions (see [Installation docs](https://docs.helix-editor.com/install.html)). - -If you would like to build from source: - -```shell -git clone https://github.com/helix-editor/helix -cd helix -cargo install --locked --path helix-term -``` - -This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`. - -Helix 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, or `%AppData%/helix/runtime` on Windows). - -| OS | Command | -| -------------------- | ------------------------------------------------ | -| Windows (Cmd) | `xcopy /e /i runtime %AppData%\helix\runtime` | -| 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. - -**PowerShell:** - -```powershell -New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime" -``` - -**Cmd:** - -```cmd -cd %appdata%\helix -mklink /D runtime "\runtime" -``` - -The runtime location can be overridden via the `HELIX_RUNTIME` environment variable. - -> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --locked --path helix-term`, -> 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). - -Packages already solve this for you by wrapping the `hx` binary with a wrapper -that sets the variable to the install dir. - -> NOTE: running via cargo also doesn't require setting explicit `HELIX_RUNTIME` path, it will automatically -> detect the `runtime` directory in the project root. - -If you want to customize your `languages.toml` config, -tree-sitter grammars may be manually fetched and built with `hx --grammar fetch` and `hx --grammar build`. - -In order to use LSP features like auto-complete, you will need to -[install the appropriate Language Server](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) -for a language. +[Installation documentation](https://docs.helix-editor.com/install.html). [![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions) -## Adding Helix to your desktop environment - -If installing from source, to use Helix in desktop environments that supports [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder: - -```bash -cp contrib/Helix.desktop ~/.local/share/applications -cp contrib/helix.png ~/.local/share/icons -``` - -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 -sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop -``` - -## macOS - -Helix can be installed on macOS through homebrew: - -``` -brew install helix -``` - # Contributing Contributing guidelines can be found [here](./docs/CONTRIBUTING.md). From 3bd1b232518c493d5c3588a879cd7227dc9f954b Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 8 Feb 2023 18:02:57 +0000 Subject: [PATCH 20/33] Simplify building from source and follow code review suggestions --- book/src/install.md | 126 +++++++++++++++++++------------------------- 1 file changed, 53 insertions(+), 73 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index 3b9d39b3c3ad..6e95f73cfb1f 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -1,9 +1,9 @@ -# Installation +# Installing Helix -- [Installation](#installation) +- [Installing Helix](#installing-helix) - [Pre-built binaries](#pre-built-binaries) - - [Linux, macOS, Windows and OpenBSD via official repositories](#linux-macos-windows-and-openbsd-via-official-repositories) + - [Linux, macOS, Windows and OpenBSD packaging status](#linux-macos-windows-and-openbsd-packaging-status) - [Linux](#linux) - [Ubuntu](#ubuntu) - [Fedora/RHEL](#fedorarhel) @@ -16,30 +16,30 @@ - [Chocolatey](#chocolatey) - [MSYS2](#msys2) - [Building from source](#building-from-source) - - [Additional steps for Linux and macOS](#additional-steps-for-linux-and-macos) - - [Additional steps for Windows](#additional-steps-for-windows) + - [Configuring Helix's runtime files for Linux and macOS](#configuring-helixs-runtime-files-for-linux-and-macos) + - [Configuring Helix's runtime files for Windows](#configuring-helixs-runtime-files-for-windows) - [Validating the Installation](#validating-the-installation) + - [Configure the Desktop Shortcut](#configure-the-desktop-shortcut) To install Helix, follow the instructions specific to your operating system. -Additionally: +Note that: -- To get the latest nightly version of Helix, you will need to +- To get the latest nightly version of Helix, you need to [build from source](#building-from-source). - To take full advantage of Helix, install the language servers for your - preferred programming languages. Refer to the - [Helix Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) - for detailed instructions. + preferred programming languages. See the + [wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) + for instructions. ## Pre-built binaries Download pre-built binaries from the -[GitHub Releases page](https://github.com/helix-editor/helix/releases). You will -need to add the binary to your system's `$PATH` to access it from the command +[GitHub Releases page](https://github.com/helix-editor/helix/releases). Add the binary to your system's `$PATH` to use it from the command line. -## Linux, macOS, Windows and OpenBSD via official repositories +## Linux, macOS, Windows and OpenBSD packaging status Helix is available for Linux, macOS and Windows via the official repositories listed below. @@ -124,21 +124,21 @@ pacman -S mingw-w64-ucrt-x86_64-helix ## Building from source -1. Clone the repository: +Clone the repository: ```sh git clone https://github.com/helix-editor/helix cd helix ``` -2. Compile Helix: +Compile Helix: ```sh cargo install --path helix-term --locked ``` This command will create the `hx` executable and construct the tree-sitter -grammars in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME` +grammars either in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME` (as described below). > ๐Ÿ’ก If you are using the musl-libc instead of glibc the following environment variable must be set during the build @@ -148,80 +148,40 @@ grammars in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME` > RUSTFLAGS="-C target-feature=-crt-static" > ``` -3. Configure Helix's runtime files - -**IMPORTANT**: The runtime files must be accessible to the newly created binary. -They are currently located in the source code `runtime` directory. To make them -accessible, you must follow the instructions for your operating system: - > ๐Ÿ’ก Tree-sitter grammars can 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). -### Additional steps for Linux and macOS - -Either, - -1. Set the `HELIX_RUNTIME` environment variable on your system to tell Helix - where to find the runtime files. - - Use the `HELIX_RUNTIME=/path/to/helix/runtime` format, for example: - `HELIX_RUNTIME=/home/user-name/src/helix/runtime`. Add this variable to your - `~/.bashrc` file or equivalent to persist it. - -Or, +### Configuring Helix's runtime files for Linux and macOS -2. Create a symlink in `~/.config/helix` that links to the source code - directory. - - ```sh - ln -s $PWD/runtime ~/.config/helix/runtime - ``` - -And optionally: - -3. Configure the Desktop Shortcut - -If your desktop environment supports the -[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html) -you can configure Helix to show up in the application menu by copying the -provided `.desktop` and icon files to their correct folders: +Either set the `HELIX_RUNTIME` environment variable to point to the runtime files and add it to your `~/.bashrc` or equivalent: ```sh -cp contrib/Helix.desktop ~/.local/share/applications -cp contrib/helix.png ~/.icons # or ~/.local/share/icons +HELIX_RUNTIME=/home/user-name/src/helix/runtime ``` -To use another terminal than the system default, you can modify the `.desktop` -file. For example, to use `kitty`: +Or, create a symlink in `~/.config/helix` that links to the source code + directory. ```sh -sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop -sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop +ln -s $PWD/runtime ~/.config/helix/runtime ``` -### Additional steps for Windows - -Either, - -1. Set the `HELIX_RUNTIME` environment variable on your system to tell Helix - where to find the runtime files. +### Configuring Helix's runtime files for Windows - You can either do this using the Windows setting (search for - `Edit environment variables for your account`) or use the `setx` command in - Cmd: +Either set the `HELIX_RUNTIME` environment variable to point to the runtime files using the Windows setting (search for +`Edit environment variables for your account`) or use the `setx` command in +Cmd: - ```sh - setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" - ``` - - > ๐Ÿ’ก `%userprofile%` resolves to your user directory like - > `C:\Users\Your-Name\` for example. +```sh +setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" +``` -Or, +> ๐Ÿ’ก `%userprofile%` resolves to your user directory like +> `C:\Users\Your-Name\` for example. -2. Create a symlink in `%appdata%\helix\` that links to the source code - directory. +Or, create a symlink in `%appdata%\helix\` that links to the source code + directory: | Method | Command | | ---------- | -------------------------------------------------------------------------------------- | @@ -242,3 +202,23 @@ hx --health For more information on the health check results refer to [Health check](https://github.com/helix-editor/helix/wiki/Healthcheck). + +## Configure the Desktop Shortcut + +If your desktop environment supports the +[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html) +you can configure Helix to show up in the application menu by copying the +provided `.desktop` and icon files to their correct folders: + +```sh +cp contrib/Helix.desktop ~/.local/share/applications +cp contrib/helix.png ~/.icons # or ~/.local/share/icons +``` + +To use another terminal than the system default, you can modify the `.desktop` +file. For example, to use `kitty`: + +```sh +sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop +sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop +``` From 99eec65608e5ade89c2e8ef4b3006e11f56444fc Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 8 Feb 2023 18:44:55 +0000 Subject: [PATCH 21/33] Code review revisions --- book/src/keymap.md | 2 +- book/src/remapping.md | 2 +- book/src/themes.md | 7 +-- book/src/usage.md | 106 +++++++++++++++++++++--------------------- 4 files changed, 57 insertions(+), 60 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index bbf982f4dec3..e38913e2cb56 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -269,7 +269,7 @@ This layer is a kludge of mappings, mostly pickers. | `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 | `jump list_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` | diff --git a/book/src/remapping.md b/book/src/remapping.md index 241f56b44e49..38afc4203489 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -75,5 +75,5 @@ Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes Keys can be disabled by binding them to the `no_op` command. -You can find a list of available commands in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation +A list of commands is available in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation and in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`. diff --git a/book/src/themes.md b/book/src/themes.md index 68755628cf0b..d17accf17bcf 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -4,8 +4,6 @@ To use a theme add `theme = ""` to the top of your [`config.toml`](./confi ## Creating a Theme -### Creating Your Theme File - To create a theme file: 1. Create a 'themes' folder in your user configuration folder (e.g. @@ -16,7 +14,7 @@ To create a theme file: > ๐Ÿ’ก The names "default" and "base16_default" are reserved for built-in themes > and cannot be overridden by user-defined themes. -### An Overview of the Theme File Format +### Overview Each line in the theme file is specified as below: @@ -45,8 +43,7 @@ user-submitted themes ### Using the Linter -If you plan to submit your theme for inclusion in Helix, it is recommended to -use the supplied linting tool to ensure compliance with the specifications: +Use the supplied linting tool to check for errors and missing scopes: ```sh cargo xtask themelint onedark # replace onedark with diff --git a/book/src/usage.md b/book/src/usage.md index 43bdac1c2526..d5e7e7883650 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -4,12 +4,12 @@ - [Using Helix](#using-helix) - [Registers](#registers) - [User-defined Registers](#user-defined-registers) - - [Built-in Registers](#built-in-registers) + - [Special Registers](#special-registers) - [Surround](#surround) - - [Moving the Selection with Syntax-tree Motions](#moving-the-selection-with-syntax-tree-motions) - [Selecting and Manipulating Text with Textobjects](#selecting-and-manipulating-text-with-textobjects) - [Navigating Using Tree-sitter Textobjects](#navigating-using-tree-sitter-textobjects) - + - [Moving the Selection with Syntax-aware Motions](#moving-the-selection-with-syntax-aware-motions) + For a full interactive introduction to Helix, refer to the [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) which @@ -38,7 +38,7 @@ If a register is selected before invoking a change or delete command, the select - `"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. -### Built-in Registers +### Special Registers | Register character | Contains | | --- | --- | @@ -47,7 +47,7 @@ If a register is selected before invoking a change or delete command, the select | `"` | Last yanked text | | `_` | Black hole | -The system clipboard is not directly supported by a built-in register. Instead, special commands and keybindings are provided. Refer to the +The system clipboard is not directly supported by a special register. Instead, special commands and keybindings are provided. Refer to the [key map](keymap.md#space-mode) for more details. The black hole register is a no-op register, meaning that no data will be read or written to it. @@ -76,7 +76,54 @@ Surround can also act on multiple selections. For example, to change every occur Multiple characters are currently not supported, but planned for future release. -## Moving the Selection with Syntax-tree Motions +## Selecting and Manipulating Text with Textobjects + +In Helix, textobjects are a way to select, manipulate and operate on a piece of +text in a structured way. They allow you to refer to blocks of text based on +their structure or purpose, such as a word, sentence, paragraph, or even a +function or block of code. + +![Textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) +![Textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) + +- `ma` - Select around the object (`va` in Vim, `` in Kakoune) +- `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) + +| Key after `mi` or `ma` | Textobject selected | +| --- | --- | +| `w` | Word | +| `W` | WORD | +| `p` | Paragraph | +| `(`, `[`, `'`, etc. | Specified surround pairs | +| `m` | The closest surround pair | +| `f` | Function | +| `c` | Class | +| `a` | Argument/parameter | +| `o` | Comment | +| `t` | Test | +| `g` | Change | + +> ๐Ÿ’ก `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! + +## Navigating Using Tree-sitter Textobjects + +Navigating between functions, classes, parameters, and other elements is +possible using tree-sitter and textobject 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] + +For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind +documentation. + +> ๐Ÿ’ก This feature relies on tree-sitter textobjects +> and requires the corresponding query file to work properly. + +## Moving the Selection with Syntax-aware Motions `Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the selection according to its location in the syntax tree. For example, many languages have the @@ -141,53 +188,6 @@ sibling, the selection will move up the syntax tree and select the previous element. As a result, using `Alt-p` with a selection on `arg1` will move the selection to the "func" `identifier`. -## Selecting and Manipulating Text with Textobjects - -In Helix, textobjects are a way to select, manipulate and operate on a piece of -text in a structured way. They allow you to refer to blocks of text based on -their structure or purpose, such as a word, sentence, paragraph, or even a -function or block of code. - -![Textobject demo](https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif) -![Textobject tree-sitter demo](https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif) - -- `ma` - Select around the object (`va` in Vim, `` in Kakoune) -- `mi` - Select inside the object (`vi` in Vim, `` in Kakoune) - -| Key after `mi` or `ma` | Textobject selected | -| --- | --- | -| `w` | Word | -| `W` | WORD | -| `p` | Paragraph | -| `(`, `[`, `'`, etc. | Specified surround pairs | -| `m` | The closest surround pair | -| `f` | Function | -| `c` | Class | -| `a` | Argument/parameter | -| `o` | Comment | -| `t` | Test | -| `g` | Change | - -> ๐Ÿ’ก `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! - -## Navigating Using Tree-sitter Textobjects - -Navigating between functions, classes, parameters, and other elements is -possible using tree-sitter and textobject 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] - -For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind -documentation. - -> ๐Ÿ’ก This feature relies on tree-sitter textobjects -> and 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 From 6b30103a6e6e7dd31da2ff0ed485a7beb14593ac Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 8 Feb 2023 18:54:38 +0000 Subject: [PATCH 22/33] Fix copy paste mistake --- book/src/install.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index 6e95f73cfb1f..f1d892fac52a 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -85,9 +85,6 @@ accepts the new settings on first use. If you are using a version of Nix without flakes enabled, [install Cachix CLI](https://docs.cachix.org/installation) and use `cachix use helix` to configure Nix to use cached outputs when possible. -@@ -85,39 +81,6 @@ ### NixOS - [install Cachix CLI](https://docs.cachix.org/installation) and use - `cachix use helix` to configure Nix to use cached outputs when possible. ## macOS From 24fc54afcdbfa67b351913923cb16408e98e8bab Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Thu, 9 Feb 2023 11:32:39 +0000 Subject: [PATCH 23/33] Apply the latest code review suggestions --- book/src/install.md | 23 +++++++++++------------ book/src/keymap.md | 2 +- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index f1d892fac52a..4a5efc098e03 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -16,10 +16,9 @@ - [Chocolatey](#chocolatey) - [MSYS2](#msys2) - [Building from source](#building-from-source) - - [Configuring Helix's runtime files for Linux and macOS](#configuring-helixs-runtime-files-for-linux-and-macos) - - [Configuring Helix's runtime files for Windows](#configuring-helixs-runtime-files-for-windows) - - [Validating the Installation](#validating-the-installation) - - [Configure the Desktop Shortcut](#configure-the-desktop-shortcut) + - [Configuring Helix's runtime files](#configuring-helixs-runtime-files) + - [Validating the Installation](#validating-the-installation) + - [Configure the Desktop Shortcut](#configure-the-desktop-shortcut) To install Helix, follow the instructions specific to your operating system. @@ -149,7 +148,9 @@ grammars either in the `runtime` folder, or in the folder specified in `HELIX_RU > grammars with `hx --grammar fetch` (requires `git`) and compile them with > `hx --grammar build` (requires a C++ compiler). -### Configuring Helix's runtime files for Linux and macOS +### Configuring Helix's runtime files + +- **Linux and macOS** Either set the `HELIX_RUNTIME` environment variable to point to the runtime files and add it to your `~/.bashrc` or equivalent: @@ -157,14 +158,13 @@ Either set the `HELIX_RUNTIME` environment variable to point to the runtime file HELIX_RUNTIME=/home/user-name/src/helix/runtime ``` -Or, create a symlink in `~/.config/helix` that links to the source code - directory. +Or, create a symlink in `~/.config/helix` that links to the source code directory: ```sh ln -s $PWD/runtime ~/.config/helix/runtime ``` -### Configuring Helix's runtime files for Windows +- **Windows** Either set the `HELIX_RUNTIME` environment variable to point to the runtime files using the Windows setting (search for `Edit environment variables for your account`) or use the `setx` command in @@ -177,8 +177,7 @@ setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" > ๐Ÿ’ก `%userprofile%` resolves to your user directory like > `C:\Users\Your-Name\` for example. -Or, create a symlink in `%appdata%\helix\` that links to the source code - directory: +Or, create a symlink in `%appdata%\helix\` that links to the source code directory: | Method | Command | | ---------- | -------------------------------------------------------------------------------------- | @@ -188,7 +187,7 @@ Or, create a symlink in `%appdata%\helix\` that links to the source code > ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or > Cmd as an administrator. -## Validating the Installation +### Validating the Installation To make sure everything is set up as expected you should run the Helix health check: @@ -200,7 +199,7 @@ hx --health For more information on the health check results refer to [Health check](https://github.com/helix-editor/helix/wiki/Healthcheck). -## Configure the Desktop Shortcut +### Configure the Desktop Shortcut If your desktop environment supports the [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html) diff --git a/book/src/keymap.md b/book/src/keymap.md index e38913e2cb56..b33c11d95a3c 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -171,7 +171,7 @@ These modes (except command mode) can be configured by #### View mode -View mode is access by typing `z` in [normal mode](#normal-mode) +View mode is accessed by typing `z` in [normal mode](#normal-mode) and 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 and can be exited using the escape key. This is From b3c551eab8f2b5c3f53d4d495d272324beeb7a96 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Thu, 9 Feb 2023 11:44:50 +0000 Subject: [PATCH 24/33] More small code review items --- book/src/commands.md | 2 +- book/src/install.md | 2 +- book/src/themes.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/book/src/commands.md b/book/src/commands.md index 6ae4185048c1..047a30a91c83 100644 --- a/book/src/commands.md +++ b/book/src/commands.md @@ -1,5 +1,5 @@ # Commands -Command mode, similar to Vim, can be activated by pressing `:`. The built-in commands are: +Command mode can be activated by pressing `:`. The built-in commands are: {{#include ./generated/typable-cmd.md}} diff --git a/book/src/install.md b/book/src/install.md index 4a5efc098e03..20b6ac7d5fb5 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -127,7 +127,7 @@ git clone https://github.com/helix-editor/helix cd helix ``` -Compile Helix: +Compile from source: ```sh cargo install --path helix-term --locked diff --git a/book/src/themes.md b/book/src/themes.md index d17accf17bcf..f079fb77fa94 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -2,7 +2,7 @@ To use a theme add `theme = ""` to the top of your [`config.toml`](./configuration.md) file, or select it during runtime using `:theme `. -## Creating a Theme +## Creating a theme To create a theme file: From 81a95f853897b6c2cf8695d4c77bb0d45c4f4ed3 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Thu, 9 Feb 2023 12:14:49 +0000 Subject: [PATCH 25/33] Change minor modes for code review --- book/src/keymap.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index b33c11d95a3c..4ab672676a86 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -153,7 +153,7 @@ Search commands all operate on the `/` register by default. To use a different r ### Minor modes -Minor 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 | | ----- | ----------- | ------- | @@ -171,8 +171,9 @@ These modes (except command mode) can be configured by #### View mode -View mode is accessed by typing `z` in [normal mode](#normal-mode) -and is intended for scrolling and manipulating the view without changing +Accessed by typing `z` in [normal mode](#normal-mode). + +View mode is 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 and can be exited using the escape key. This is useful when you're simply looking over text and not actively editing it. @@ -193,8 +194,9 @@ useful when you're simply looking over text and not actively editing it. #### Goto mode -Goto mode is accessed by typing `g` in [normal mode](#normal-mode), it jumps to -various locations. +Accessed by typing `g` in [normal mode](#normal-mode). + +Jumps to various locations. | Key | Description | Command | | ----- | ----------- | ------- | @@ -219,7 +221,7 @@ various locations. #### Match mode -Match mode is accessed by typing `m` in [normal mode](#normal-mode). +Accessed by typing `m` in [normal mode](#normal-mode). See the relevant section in [Usage](./usage.md) for an explanation about [surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. @@ -237,8 +239,9 @@ TODO: Mappings for selecting syntax nodes (a superset of `[`). #### Window mode -Window mode is accessed by typing `Ctrl-w` in [normal mode](#normal-mode), -this layer is similar to Vim keybindings as Kakoune does not support windows. +Accessed by typing `Ctrl-w` in [normal mode](#normal-mode). + +This layer is similar to Vim keybindings as Kakoune does not support windows. | Key | Description | Command | | ----- | ------------- | ------- | @@ -260,7 +263,7 @@ this layer is similar to Vim keybindings as Kakoune does not support windows. #### Space mode -Space mode is accessed by typing `Space` in [normal mode](#normal-mode). +Accessed by typing `Space` in [normal mode](#normal-mode). This layer is a kludge of mappings, mostly pickers. From 81f9e1b0ea671aa7a02d0bf79767714dfd2f7571 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Thu, 9 Feb 2023 12:22:01 +0000 Subject: [PATCH 26/33] Fix link and typos --- book/src/keymap.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index 4ab672676a86..ee9a644adc89 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -173,7 +173,7 @@ These modes (except command mode) can be configured by Accessed by typing `z` in [normal mode](#normal-mode). -View mode is is intended for scrolling and manipulating the view without changing +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 and can be exited using the escape key. This is useful when you're simply looking over text and not actively editing it. @@ -224,7 +224,7 @@ Jumps to various locations. Accessed by typing `m` in [normal mode](#normal-mode). See the relevant section in [Usage](./usage.md) for an explanation about -[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage. +[surround](./usage.md#surround) and [textobject](./usage.md#navigating-using-tree-sitter-textobjects) usage. | Key | Description | Command | | ----- | ----------- | ------- | @@ -279,7 +279,7 @@ This layer is a kludge of mappings, mostly pickers. | `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` | +| `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` | From b5bd5597267db843054787068e4fd4864206e261 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Sat, 11 Feb 2023 16:08:52 +0000 Subject: [PATCH 27/33] Add note that you need a c++ compiler to install the tree-sitter grammars --- book/src/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/install.md b/book/src/install.md index 20b6ac7d5fb5..2f54c45ea240 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -135,7 +135,7 @@ cargo install --path helix-term --locked This command will create the `hx` executable and construct the tree-sitter grammars either in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME` -(as described below). +(as described below). To build the tree-sitter grammars requires a c++ compiler to be installed, for example `gcc-c++`. > ๐Ÿ’ก If you are using the musl-libc instead of glibc the following environment variable must be set during the build > to ensure tree sitter grammars can be loaded correctly: From b1372a7bbd0b1618555737c5fed9a9a2a78080a5 Mon Sep 17 00:00:00 2001 From: David-Else <12832280+David-Else@users.noreply.github.com> Date: Sun, 12 Feb 2023 10:21:16 +0000 Subject: [PATCH 28/33] Add pacman example --- book/src/install.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index 2f54c45ea240..be93db3a4656 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -69,8 +69,12 @@ sudo dnf install helix ### Arch Linux community -Releases are available in the `community` repository. Additionally, a -[helix-git](https://aur.archlinux.org/packages/helix-git/) package is available +Releases are available in the `community` repository: + +```sh +sudo pacman -S helix +``` +Additionally, a [helix-git](https://aur.archlinux.org/packages/helix-git/) package is available in the AUR, which builds the master branch. ### NixOS From fbaa5d5adc0ac6c47d77aacbad2021fa5c86251c Mon Sep 17 00:00:00 2001 From: David <12832280+David-Else@users.noreply.github.com> Date: Fri, 17 Feb 2023 12:15:26 +0000 Subject: [PATCH 29/33] Make sure all headings are lower case --- book/src/SUMMARY.md | 10 +++++----- book/src/guides/indent.md | 4 ++-- book/src/guides/textobject.md | 4 ++-- book/src/install.md | 8 ++++---- book/src/keymap.md | 2 +- book/src/remapping.md | 2 +- book/src/themes.md | 6 +++--- book/src/usage.md | 20 ++++++++++---------- 8 files changed, 28 insertions(+), 28 deletions(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index eaf0c4f483f1..6e780b87fc19 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -6,13 +6,13 @@ - [Usage](./usage.md) - [Keymap](./keymap.md) - [Commands](./commands.md) - - [Language Support](./lang-support.md) + - [Language support](./lang-support.md) - [Migrating from Vim](./from-vim.md) - [Configuration](./configuration.md) - [Themes](./themes.md) - - [Key Remapping](./remapping.md) + - [Key remapping](./remapping.md) - [Languages](./languages.md) - [Guides](./guides/README.md) - - [Adding Languages](./guides/adding_languages.md) - - [Adding Textobject Queries](./guides/textobject.md) - - [Adding Indent Queries](./guides/indent.md) + - [Adding languages](./guides/adding_languages.md) + - [Adding textobject queries](./guides/textobject.md) + - [Adding indent queries](./guides/indent.md) diff --git a/book/src/guides/indent.md b/book/src/guides/indent.md index 0e259289781e..b660d785734e 100644 --- a/book/src/guides/indent.md +++ b/book/src/guides/indent.md @@ -1,4 +1,4 @@ -# Adding Indent Queries +# 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 @@ -36,7 +36,7 @@ changed by using a `#set!` declaration anywhere in the pattern: (#set! "scope" "all")) ``` -## Capture Types +## Capture types - `@indent` (default scope `tail`): Increase the indent level by 1. Multiple occurrences in the same line diff --git a/book/src/guides/textobject.md b/book/src/guides/textobject.md index 71082f4be504..405f11c1b00a 100644 --- a/book/src/guides/textobject.md +++ b/book/src/guides/textobject.md @@ -1,4 +1,4 @@ -# Adding Textobject Queries +# Adding textobject queries Helix supports textobjects that are language specific, such as functions, classes, etc. These textobjects require an accompanying tree-sitter grammar and a `textobjects.scm` query file @@ -28,7 +28,7 @@ The following [captures][tree-sitter-captures] are recognized: [Example query files][textobject-examples] can be found in the helix GitHub repository. -## Queries for Textobject Based Navigation +## Queries for textobject based navigation Tree-sitter based navigation in Helix is done using captures in the following order: diff --git a/book/src/install.md b/book/src/install.md index be93db3a4656..e65f35e7ab08 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -17,8 +17,8 @@ - [MSYS2](#msys2) - [Building from source](#building-from-source) - [Configuring Helix's runtime files](#configuring-helixs-runtime-files) - - [Validating the Installation](#validating-the-installation) - - [Configure the Desktop Shortcut](#configure-the-desktop-shortcut) + - [Validating the installation](#validating-the-installation) + - [Configure the desktop shortcut](#configure-the-desktop-shortcut) To install Helix, follow the instructions specific to your operating system. @@ -191,7 +191,7 @@ Or, create a symlink in `%appdata%\helix\` that links to the source code directo > ๐Ÿ’ก On Windows, creating a symbolic link may require running PowerShell or > Cmd as an administrator. -### Validating the Installation +### Validating the installation To make sure everything is set up as expected you should run the Helix health check: @@ -203,7 +203,7 @@ hx --health For more information on the health check results refer to [Health check](https://github.com/helix-editor/helix/wiki/Healthcheck). -### Configure the Desktop Shortcut +### Configure the desktop shortcut If your desktop environment supports the [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html) diff --git a/book/src/keymap.md b/book/src/keymap.md index ee9a644adc89..379c8ac65978 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -14,7 +14,7 @@ - [Space mode](#space-mode) - [Popup](#popup) - [Unimpaired](#unimpaired) -- [Insert Mode](#insert-mode) +- [Insert mode](#insert-mode) - [Select / extend mode](#select-extend-mode) - [Picker](#picker) - [Prompt](#prompt) diff --git a/book/src/remapping.md b/book/src/remapping.md index 38afc4203489..d762c6add4fc 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -1,4 +1,4 @@ -# Key Remapping +# Key remapping Helix currently supports one-way key remapping through a simple TOML configuration file. (More powerful solutions such as rebinding via commands will be diff --git a/book/src/themes.md b/book/src/themes.md index f079fb77fa94..a6ffb4b29c49 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -41,7 +41,7 @@ For inspiration, you can find the default `theme.toml` user-submitted themes [here](https://github.com/helix-editor/helix/blob/master/runtime/themes). -### Using the Linter +### Using the linter Use the supplied linting tool to check for errors and missing scopes: @@ -49,7 +49,7 @@ Use the supplied linting tool to check for errors and missing scopes: cargo xtask themelint onedark # replace onedark with ``` -## The Details of Theme Creation +## The details of theme creation ### Color palettes @@ -112,7 +112,7 @@ your terminal emulator. > ๐Ÿ’ก The `underlined` modifier is deprecated and only available for backwards compatibility. > Its behavior is equivalent to setting `underline.style="line"`. -### Underline Style +### Underline style One of the following values may be used as a value for `underline.style`, providing it is supported by your terminal emulator. diff --git a/book/src/usage.md b/book/src/usage.md index d5e7e7883650..13946e840654 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -3,12 +3,12 @@ - [Using Helix](#using-helix) - [Registers](#registers) - - [User-defined Registers](#user-defined-registers) - - [Special Registers](#special-registers) + - [User-defined registers](#user-defined-registers) + - [Special registers](#special-registers) - [Surround](#surround) - - [Selecting and Manipulating Text with Textobjects](#selecting-and-manipulating-text-with-textobjects) - - [Navigating Using Tree-sitter Textobjects](#navigating-using-tree-sitter-textobjects) - - [Moving the Selection with Syntax-aware Motions](#moving-the-selection-with-syntax-aware-motions) + - [Selecting and manipulating text with textobjects](#selecting-and-manipulating-text-with-textobjects) + - [Navigating using tree-sitter textobjects](#navigating-using-tree-sitter-textobjects) + - [Moving the selection with syntax-aware motions](#moving-the-selection-with-syntax-aware-motions) For a full interactive introduction to Helix, refer to the @@ -25,7 +25,7 @@ result of a search. Registers can be used to cut, copy, and paste text, similar to the clipboard in other text editors. Usage is similar to Vim, with `"` being used to select a register. -### User-defined Registers +### User-defined registers Helix allows you to create your own named registers for storing text, for example: @@ -38,7 +38,7 @@ If a register is selected before invoking a change or delete command, the select - `"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 +### Special registers | Register character | Contains | | --- | --- | @@ -76,7 +76,7 @@ Surround can also act on multiple selections. For example, to change every occur Multiple characters are currently not supported, but planned for future release. -## Selecting and Manipulating Text with Textobjects +## Selecting and manipulating text with textobjects In Helix, textobjects are a way to select, manipulate and operate on a piece of text in a structured way. They allow you to refer to blocks of text based on @@ -108,7 +108,7 @@ 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! -## Navigating Using Tree-sitter Textobjects +## Navigating using tree-sitter textobjects Navigating between functions, classes, parameters, and other elements is possible using tree-sitter and textobject queries. For @@ -123,7 +123,7 @@ documentation. > ๐Ÿ’ก This feature relies on tree-sitter textobjects > and requires the corresponding query file to work properly. -## Moving the Selection with Syntax-aware Motions +## Moving the selection with syntax-aware motions `Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) allow you to move the selection according to its location in the syntax tree. For example, many languages have the From aa45dc74c9cc0430bff9f02aea1d8ee6a7c8e613 Mon Sep 17 00:00:00 2001 From: David <12832280+David-Else@users.noreply.github.com> Date: Fri, 17 Feb 2023 12:37:12 +0000 Subject: [PATCH 30/33] Revert to the original passage adding a reference to Windows that was missing --- book/src/themes.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/book/src/themes.md b/book/src/themes.md index a6ffb4b29c49..7463843c99ea 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -4,12 +4,7 @@ To use a theme add `theme = ""` to the top of your [`config.toml`](./confi ## Creating a theme -To create a theme file: - -1. Create a 'themes' folder in your user configuration folder (e.g. - `~/.config/helix/themes`, or `%AppData%\helix\themes` on Windows). -2. Create a file with the name of your theme as the file name (e.g. - `mytheme.toml`) and place it in your `themes` folder. +Create a file with the name of your theme as the file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes` or `%AppData%\helix\themes` on Windows). The directory might have to be created beforehand. > ๐Ÿ’ก The names "default" and "base16_default" are reserved for built-in themes > and cannot be overridden by user-defined themes. From b1d63ea66b4e9c31b7cdfb04c669ebc4e6c63f82 Mon Sep 17 00:00:00 2001 From: David Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 1 Mar 2023 13:48:32 +0000 Subject: [PATCH 31/33] Update book/src/guides/adding_languages.md Fix grammar typo Co-authored-by: Michael Davis --- book/src/guides/adding_languages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md index 5a3fe3ec817b..b92af4028e9a 100644 --- a/book/src/guides/adding_languages.md +++ b/book/src/guides/adding_languages.md @@ -49,4 +49,4 @@ below. to fetch the grammars and `hx --grammar build` to build any out-of-date grammars. - If a parser is causing a segfault, or you want to remove it, make sure to - remove the compiled parser located at `runtime/grammar/.so`. + remove the compiled parser located at `runtime/grammars/.so`. From 07be576ad4b8365c175353f798bff447bb551985 Mon Sep 17 00:00:00 2001 From: David Else <12832280+David-Else@users.noreply.github.com> Date: Wed, 1 Mar 2023 13:49:20 +0000 Subject: [PATCH 32/33] Update book/src/install.md Fix tree sitter typo Co-authored-by: Michael Davis --- book/src/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/install.md b/book/src/install.md index fb4fc689fb74..3fe1868ea95e 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -142,7 +142,7 @@ grammars either in the `runtime` folder, or in the folder specified in `HELIX_RU (as described below). To build the tree-sitter grammars requires a c++ compiler to be installed, for example `gcc-c++`. > ๐Ÿ’ก If you are using the musl-libc instead of glibc the following environment variable must be set during the build -> to ensure tree sitter grammars can be loaded correctly: +> to ensure tree-sitter grammars can be loaded correctly: > > ```sh > RUSTFLAGS="-C target-feature=-crt-static" From 826f4703a8fab13921d4efd7e048d7cfe5f3059e Mon Sep 17 00:00:00 2001 From: David <12832280+David-Else@users.noreply.github.com> Date: Wed, 1 Mar 2023 14:14:49 +0000 Subject: [PATCH 33/33] Remove TOC links to main heading --- book/src/install.md | 35 +++++++++++++++++------------------ book/src/usage.md | 15 +++++++-------- 2 files changed, 24 insertions(+), 26 deletions(-) diff --git a/book/src/install.md b/book/src/install.md index 3fe1868ea95e..f9cf9a3ba782 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -1,24 +1,23 @@ # Installing Helix -- [Installing Helix](#installing-helix) - - [Pre-built binaries](#pre-built-binaries) - - [Linux, macOS, Windows and OpenBSD packaging status](#linux-macos-windows-and-openbsd-packaging-status) - - [Linux](#linux) - - [Ubuntu](#ubuntu) - - [Fedora/RHEL](#fedorarhel) - - [Arch Linux community](#arch-linux-community) - - [NixOS](#nixos) - - [macOS](#macos) - - [Homebrew Core](#homebrew-core) - - [Windows](#windows) - - [Scoop](#scoop) - - [Chocolatey](#chocolatey) - - [MSYS2](#msys2) - - [Building from source](#building-from-source) - - [Configuring Helix's runtime files](#configuring-helixs-runtime-files) - - [Validating the installation](#validating-the-installation) - - [Configure the desktop shortcut](#configure-the-desktop-shortcut) +- [Pre-built binaries](#pre-built-binaries) +- [Linux, macOS, Windows and OpenBSD packaging status](#linux-macos-windows-and-openbsd-packaging-status) +- [Linux](#linux) + - [Ubuntu](#ubuntu) + - [Fedora/RHEL](#fedorarhel) + - [Arch Linux community](#arch-linux-community) + - [NixOS](#nixos) +- [macOS](#macos) + - [Homebrew Core](#homebrew-core) +- [Windows](#windows) + - [Scoop](#scoop) + - [Chocolatey](#chocolatey) + - [MSYS2](#msys2) +- [Building from source](#building-from-source) + - [Configuring Helix's runtime files](#configuring-helixs-runtime-files) + - [Validating the installation](#validating-the-installation) + - [Configure the desktop shortcut](#configure-the-desktop-shortcut) To install Helix, follow the instructions specific to your operating system. diff --git a/book/src/usage.md b/book/src/usage.md index 13946e840654..81cf83725609 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -1,14 +1,13 @@ # Using Helix -- [Using Helix](#using-helix) - - [Registers](#registers) - - [User-defined registers](#user-defined-registers) - - [Special registers](#special-registers) - - [Surround](#surround) - - [Selecting and manipulating text with textobjects](#selecting-and-manipulating-text-with-textobjects) - - [Navigating using tree-sitter textobjects](#navigating-using-tree-sitter-textobjects) - - [Moving the selection with syntax-aware motions](#moving-the-selection-with-syntax-aware-motions) +- [Registers](#registers) + - [User-defined registers](#user-defined-registers) + - [Special registers](#special-registers) +- [Surround](#surround) +- [Selecting and manipulating text with textobjects](#selecting-and-manipulating-text-with-textobjects) +- [Navigating using tree-sitter textobjects](#navigating-using-tree-sitter-textobjects) +- [Moving the selection with syntax-aware motions](#moving-the-selection-with-syntax-aware-motions) For a full interactive introduction to Helix, refer to the