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] 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 d9a113866..b18ed1a5d 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 a35482e6e..31852aa42 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 bf0ff079c..7781429d9 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).
+
-[](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
+[](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 b38a1f44e..019073e3e 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` `