aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--README.md84
-rw-r--r--book/src/SUMMARY.md10
-rw-r--r--book/src/commands.md2
-rw-r--r--book/src/configuration.md89
-rw-r--r--book/src/guides/README.md2
-rw-r--r--book/src/guides/adding_languages.md77
-rw-r--r--book/src/guides/indent.md4
-rw-r--r--book/src/guides/textobject.md16
-rw-r--r--book/src/install.md261
-rw-r--r--book/src/keymap.md40
-rw-r--r--book/src/lang-support.md4
-rw-r--r--book/src/languages.md24
-rw-r--r--book/src/remapping.md19
-rw-r--r--book/src/themes.md98
-rw-r--r--book/src/usage.md206
15 files changed, 465 insertions, 471 deletions
diff --git a/README.md b/README.md
index a2667321..cba52a7a 100644
--- a/README.md
+++ b/README.md
@@ -45,92 +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 Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
-```
-Note: "runtime" must be absolute path to the runtime directory.
-
-**Cmd:**
-
-```cmd
-cd %appdata%\helix
-mklink /D runtime "<helix-repo>\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).
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index eaf0c4f4..6e780b87 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/commands.md b/book/src/commands.md
index d9a11386..047a30a9 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 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 0b9ebe96..5410024b 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
@@ -38,23 +36,23 @@ on unix operating systems.
| 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"]`<br/>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` |
+| `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"]`<br/>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` |
+| `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` |
@@ -125,10 +123,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` |
@@ -141,25 +141,22 @@ 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
+|`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
@@ -211,7 +208,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
@@ -220,7 +217,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
@@ -248,7 +245,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` |
@@ -273,7 +270,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 |
| --- | --- | --- |
@@ -315,13 +312,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/README.md b/book/src/guides/README.md
index e0c44ce7..c25768e6 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 6598b9bf..b92af402 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/<name>/`. 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/<name>.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/<name>/`.
+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/grammars/<name>.so`.
diff --git a/book/src/guides/indent.md b/book/src/guides/indent.md
index 0e259289..b660d785 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 8a217354..405f11c1 100644
--- a/book/src/guides/textobject.md
+++ b/book/src/guides/textobject.md
@@ -1,14 +1,14 @@
-# Adding Textobject Queries
+# 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).
@@ -28,9 +28,9 @@ 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][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 7df9e6c7..f9cf9a3b 100644
--- a/book/src/install.md
+++ b/book/src/install.md
@@ -1,180 +1,223 @@
-# Installation
-
-We provide pre-built binaries on the [GitHub Releases page](https://github.com/helix-editor/helix/releases).
+# Installing Helix
+
+<!--toc:start-->
+- [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)
+<!--toc:end-->
+
+To install Helix, follow the instructions specific to your operating system.
+Note that:
+
+- 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. 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). Add the binary to your system's `$PATH` to use it from the command
+line.
+
+## Linux, macOS, Windows and OpenBSD packaging status
+
+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)
-## OSX
+## Linux
-Helix is available in homebrew-core:
+The following third party repositories are available:
-```
-brew install helix
-```
+### Ubuntu
-## Linux
+Helix is available via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor):
-### NixOS
+```sh
+sudo add-apt-repository ppa:maveonair/helix-editor
+sudo apt update
+sudo apt install helix
+```
-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`.
+### Fedora/RHEL
-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.
+Helix is available via `copr`:
-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.
+```sh
+sudo dnf copr enable varlad/helix
+sudo dnf install helix
+```
-### Arch Linux
+### Arch Linux community
-Releases are available in the `community` repository.
+Releases are available in the `community` repository:
-A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also available on the AUR, which builds the master branch.
+```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.
-### Fedora Linux
+### NixOS
-You can install the COPR package for Helix via
+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.
-```
-sudo dnf copr enable varlad/helix
-sudo dnf install helix
-```
+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.
+
+## macOS
-### Void Linux
+### Homebrew Core
-```
-sudo xbps-install helix
+```sh
+brew install helix
```
## 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:**
+### Scoop
-```
+```sh
scoop install helix
```
-**Chocolatey:**
+### 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:
-
-```
-pacman -S mingw-w64-x86_64-helix
-```
+### MSYS2
- - For 64 bit Windows 8.1 or above:
+For 64-bit Windows 8.1 or above:
-```
+```sh
pacman -S mingw-w64-ucrt-x86_64-helix
```
-## Build from source
+## Building from source
-```
+Clone the repository:
+
+```sh
git clone https://github.com/helix-editor/helix
cd helix
-cargo install --path helix-term --locked
```
-This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`.
-
-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:
+Compile from source:
+```sh
+cargo install --path helix-term --locked
```
-RUSTFLAGS="-C target-feature=-crt-static"
-```
-
-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.
+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). To build the tree-sitter grammars requires a c++ compiler to be installed, for example `gcc-c++`.
-| 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` |
+> 💡 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"
+> ```
-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:**
+### Configuring Helix's runtime files
-```powershell
-New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
-```
-Note: "runtime" must be the absolute path to the runtime directory.
+- **Linux and macOS**
-**Cmd:**
+Either set the `HELIX_RUNTIME` environment variable to point to the runtime files and add it to your `~/.bashrc` or equivalent:
-```cmd
-cd %appdata%\helix
-mklink /D runtime "<helix-repo>\runtime"
+```sh
+HELIX_RUNTIME=/home/user-name/src/helix/runtime
```
-The runtime location can be overridden via the `HELIX_RUNTIME` environment variable.
+Or, create a symlink in `~/.config/helix` that links to the source code directory:
-> 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`.
+```sh
+ln -s $PWD/runtime ~/.config/helix/runtime
+```
-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).
+- **Windows**
-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:
+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:
-```bash
-cp contrib/Helix.desktop ~/.local/share/applications
+```sh
+setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
```
-To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`:
+> 💡 `%userprofile%` resolves to your user directory like
+> `C:\Users\Your-Name\` for example.
-```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
-```
+Or, create a symlink in `%appdata%\helix\` that links to the source code directory:
-Please note: there is no icon for Helix yet, so the system default will be used.
+ | Method | Command |
+ | ---------- | -------------------------------------------------------------------------------------- |
+ | PowerShell | `New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"` |
+ | Cmd | `cd %appdata%\helix` <br/> `mklink /D runtime "%userprofile%\src\helix\runtime"` |
-## Finishing up the installation
+ > 💡 On Windows, creating a symbolic link may require running PowerShell or
+ > Cmd as an administrator.
-To make sure everything is set up as expected you should finally run the helix healthcheck via
+### Validating the installation
-```
+To make sure everything is set up as expected you should run the Helix health
+check:
+
+```sh
hx --health
```
-For more information on the information displayed in the health check results refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck).
+For more information on the health check results refer to
+[Health check](https://github.com/helix-editor/helix/wiki/Healthcheck).
-### Building tree-sitter grammars
+### Configure the desktop shortcut
-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).
+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:
-### Installing language servers
+```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`:
-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.
+```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
+```
diff --git a/book/src/keymap.md b/book/src/keymap.md
index bc16aa1a..173728f2 100644
--- a/book/src/keymap.md
+++ b/book/src/keymap.md
@@ -14,14 +14,14 @@
- [Space mode](#space-mode)
- [Popup](#popup)
- [Unimpaired](#unimpaired)
-- [Insert Mode](#insert-mode)
-- [Select / extend mode](#select--extend-mode)
+- [Insert mode](#insert-mode)
+- [Select / extend mode](#select-extend-mode)
- [Picker](#picker)
- [Prompt](#prompt)
> 💡 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
@@ -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 `"<char>` to operate on a different one.
+Search commands all operate on the `/` register by default. To use a different register, use `"<char>`.
| Key | Description | Command |
| ----- | ----------- | ------- |
@@ -175,9 +175,8 @@ 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).
+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 |
@@ -225,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 |
| ----- | ----------- | ------- |
@@ -242,7 +241,7 @@ TODO: Mappings for selecting syntax nodes (a superset of `[`).
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 |
| ----- | ------------- | ------- |
@@ -293,7 +292,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
@@ -306,7 +305,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 |
| ----- | ----------- | ------- |
@@ -335,12 +334,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 |
| ----- | ----------- | ------- |
@@ -370,8 +370,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]
@@ -387,7 +387,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 6a08cd69..3f96673b 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 74d090eb..8a8f3bb6 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 <config_dir>/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 8339e05f..d762c6ad 100644
--- a/book/src/remapping.md
+++ b/book/src/remapping.md
@@ -1,18 +1,18 @@
-# Key Remapping
+# 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,5 @@ 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`.
+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 9b7e97a1..af238e94 100644
--- a/book/src/themes.md
+++ b/book/src/themes.md
@@ -1,14 +1,15 @@
# Themes
-To use a theme add `theme = "<name>"` to your [`config.toml`](./configuration.md) at the very top of the file before the first section or select it during runtime using `:theme <name>`.
+To use a theme add `theme = "<name>"` to the top of your [`config.toml`](./configuration.md) file, or select it during runtime using `:theme <name>`.
## Creating a theme
-Create a file with the name of your theme as file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes`). The directory might have to be created beforehand.
+Create a file with the name of your theme as 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 the builtin themes and cannot be overridden by user defined themes.
+> 💡 The names "default" and "base16_default" are reserved for built-in themes
+> and cannot be overridden by user-defined themes.
-The default theme.toml can be found [here](https://github.com/helix-editor/helix/blob/master/theme.toml), and user submitted themes [here](https://github.com/helix-editor/helix/blob/master/runtime/themes).
+### Overview
Each line in the theme file is specified as below:
@@ -16,7 +17,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 +25,30 @@ 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
+
+Use the supplied linting tool to check for errors and missing scopes:
+
+```sh
+cargo xtask themelint onedark # replace onedark with <name>
+```
+
+## 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 +61,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 +89,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 +104,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`.
+### 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 +123,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.
+Extend other themes by setting the `inherits` property to an existing theme.
```toml
inherits = "boo_berry"
@@ -124,19 +138,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 +158,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,11 +176,11 @@ 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
- - `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)
@@ -186,10 +200,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 +230,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 +246,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 |
@@ -270,9 +284,9 @@ 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` | |
@@ -301,10 +315,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 <name>
-```
-
[editor-section]: ./configuration.md#editor-section
diff --git a/book/src/usage.md b/book/src/usage.md
index a6eb9ec1..81cf8372 100644
--- a/book/src/usage.md
+++ b/book/src/usage.md
@@ -1,22 +1,43 @@
-# Usage
+# Using Helix
-(Currently not fully documented, see the [keymappings](./keymap.md) list for more.)
+<!--toc:start-->
+- [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)
+<!--toc:end-->
-See [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction.
+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).
- `"md` - Store the selection in register `m` and delete it.
-### Special Registers
+### Special registers
| Register character | Contains |
| --- | --- |
@@ -25,41 +46,90 @@ 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 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.
## 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<char>` (after selecting text) | Add surround characters to selection |
+| `mr<char_to_replace><new_char>` | Replace the closest surround characters |
+| `md<char_to_delete>` | Delete the closest surround characters |
-`ms` acts on a selection, so select the text first and use `ms<char>`. `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
+## Selecting and manipulating text with textobjects
-`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:
+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.
-```
-func(arg1, arg2, arg3)
+![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, `<alt-a>` in Kakoune)
+- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` 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
+following syntax for function calls:
+
+```js
+func(arg1, arg2, arg3);
```
A function call might be parsed by tree-sitter into a tree like the following.
@@ -93,77 +163,29 @@ a more intuitive tree format:
└──────────┘ └──────────┘ └──────────┘
```
-Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf
-in the tree above.
+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
+// before
func([arg1], arg2, arg3)
+// after
+func(arg1, [arg2], arg3);
```
-Using `Alt-n` would select the next sibling in the syntax tree: `arg2`.
+Similarly, `Alt-o` will expand the selection to the parent node, in this case, the
+arguments node.
-```
-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.
-
-```
-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`.
-
-```
-[func](arg1, arg2, arg3)
-```
-
-## Textobjects
-
-![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)
-
-- `ma` - Select around the object (`va` in Vim, `<alt-a>` in Kakoune)
-- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` in Kakoune)
-
-| Key after `mi` or `ma` | Textobject selected |
-| --- | --- |
-| `w` | Word |
-| `W` | WORD |
-| `p` | Paragraph |
-| `(`, `[`, `'`, etc | Specified surround pairs |
-| `m` | Closest surround pair |
-| `f` | Function |
-| `c` | Class |
-| `a` | Argument/parameter |
-| `o` | Comment |
-| `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!
-
-## Tree-sitter Textobject Based Navigation
-
-Navigating between functions, classes, parameters, etc is made
-possible by leveraging tree-sitter and textobjects queries. For
-example to move to the next function use `]f`, to move to previous
-class use `[c`, and so on.
-
-![tree-sitter-nav-demo][tree-sitter-nav-demo]
-
-See the [unimpaired][unimpaired-keybinds] section of the keybind
-documentation for the full reference.
-
-> NOTE: This feature is dependent on tree-sitter based textobjects
-and therefore requires the corresponding query file to work properly.
+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`.
[lang-support]: ./lang-support.md
[unimpaired-keybinds]: ./keymap.md#unimpaired
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-11-05 15:36:41 +0000