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:
| Name | Description | |
|---|---|---|
:quit, :q | Close the current view. | |
:quit!, :q! | Force close the current view, ignoring unsaved changes. |
| 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 |
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 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 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 |
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. +
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 | block |
insert | Cursor shape in insert mode | block |
[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
@@ -321,14 +320,14 @@ name = "rust"
[editor.search] Section
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
Options for rendering whitespace with visible characters. Use :set whitespace.render all to temporarily enable visible whitespace.
| Key | Description | Default |
|---|---|---|
render | Whether to render whitespace. May either be "all" or "none", or a table with sub-keys space, nbsp, tab, and newline. | "none" |
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 |
[editor.indent-guides] Section
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 |
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.
| Key | Description | Default |
|---|---|---|
layout | A vector of gutters to display | ["diagnostics", "spacer", "line-numbers", "spacer", "diff"] |
[editor.gutters.spacer] Section
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 | โช |
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).
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 docs before creating a pull request.
-When adding a Language Server configuration, be sure to update the
-Language Server Wiki with installation notes.
-
+
- Add a new
[[language]]entry in thelanguages.tomlfile and provide the +necessary configuration for the new language. For more information on +language configuration, refer to the +language configuration section of the documentation.
+ - If you are adding a new language or updating an existing language server
+configuration, run the command
cargo xtask docgento update the +Language Support documentation.
+
+๐ก If you are adding a new Language Server configuration, make sure to update +the +Language Server Wiki +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.
-
+
- If a tree-sitter grammar is available for the new language, add a new
+
[[grammar]]entry to thelanguages.tomlfile.
+ - If you are testing the grammar locally, you can use the
source.pathkey +with an absolute path to the grammar. However, before submitting a pull +request, make sure to switch to usingsource.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
-gives more info on how to write queries.
-
+
- In order to provide syntax highlighting and indentation for the new language, +you will need to add queries. +
- Create a new directory for the language with the path
+
runtime/queries/<name>/.
+ - Refer to the +tree-sitter website +for more information on writing 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 for an example.
+๐ก 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 +for an example.
Common Issues
+Common issues
-
-
-
-
If you get errors when running after switching branches, you may have to update the tree-sitter grammars. Run
-hx --grammar fetchto fetch the grammars andhx --grammar buildto 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
+ - 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 andhx --grammar buildto 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.
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
runtime/queries/{language}/indents.scm. The indentation for a line
@@ -182,7 +182,7 @@ changed by using a #set! declaration anywhere in the pattern:
Capture Types
+Capture types
-
@indent(default scopetail): diff --git a/master/guides/index.html b/master/guides/index.html index f5078f5e5..8a8bd8334 100644 --- a/master/guides/index.html +++ b/master/guides/index.html @@ -83,7 +83,7 @@ @@ -149,7 +149,7 @@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.
Adding Textobject Queries
-Textobjects that are language specific (like functions, classes, etc)
-require an accompanying tree-sitter grammar and a textobjects.scm query file
+
Adding textobject queries
+Helix supports textobjects that are language specific, such as functions, classes, etc.
+These textobjects require an accompanying tree-sitter grammar and a textobjects.scm query file
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.
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).
The following captures are recognized:
@@ -172,8 +172,8 @@ for example).Example query files can be found in the helix GitHub repository.
-Queries for Textobject Based Navigation
-Tree-sitter based navigation is done using captures in the +
Queries for textobject based navigation
+Tree-sitter based navigation in Helix is done using captures in the following order:
object.movement
@@ -181,7 +181,7 @@ 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.
Installation
-We provide pre-built binaries on the GitHub Releases page.
+Installing Helix
+ +-
+
- Pre-built binaries +
- Linux, macOS, Windows and OpenBSD packaging status +
- Linux + + +
- macOS + + +
- Windows
+
-
+
- Scoop +
- Chocolatey +
- MSYS2 +
+ - Building from source + + +
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.
+
+ -
+
To take full advantage of Helix, install the language servers for your +preferred programming languages. See the +wiki +for instructions.
+
+
Pre-built binaries
+Download pre-built binaries from the
+GitHub Releases page. 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.
OSX
-Helix is available in homebrew-core:
-brew install helix
-Linux
-NixOS
-A flake 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.
Flake outputs are cached for each push to master using -Cachix. The flake is configured to -automatically make use of this cache assuming the user accepts -the new settings on first use.
-If you are using a version of Nix without flakes enabled you can
-install Cachix cli; cachix use helix will
-configure Nix to use cached outputs when possible.
Arch Linux
-Releases are available in the community repository.
A helix-git package is also available on the AUR, which builds the master branch.
-Fedora Linux
-You can install the COPR package for Helix via
-sudo dnf copr enable varlad/helix
+The following third party repositories are available:
+Ubuntu
+Helix is available via Maveonair's PPA:
+sudo add-apt-repository ppa:maveonair/helix-editor
+sudo apt update
+sudo apt install helix
+
+Fedora/RHEL
+Helix is available via copr:
+sudo dnf copr enable varlad/helix
sudo dnf install helix
-Void Linux
-sudo xbps-install helix
+Arch Linux community
+Releases are available in the community repository:
+sudo pacman -S helix
+
+Additionally, a helix-git package is available
+in the AUR, which builds the master branch.
+NixOS
+Helix is available as a flake in the project
+root. Use nix develop to spin up a reproducible development shell. Outputs are
+cached for each push to master using Cachix. 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 and use
+cachix use helix to configure Nix to use cached outputs when possible.
+macOS
+Homebrew Core
+brew install helix
Windows
-Helix can be installed using Scoop, Chocolatey
+
Install on Windows using Scoop, Chocolatey
or MSYS2.
-Scoop:
-scoop install helix
+Scoop
+scoop install helix
-Chocolatey:
-choco install helix
+Chocolatey
+choco install helix
-MSYS2:
-Choose the proper command for your system from below:
-
-- For 32 bit Windows 7 or above:
-
-pacman -S mingw-w64-i686-helix
+MSYS2
+For 64-bit Windows 8.1 or above:
+pacman -S mingw-w64-ucrt-x86_64-helix
-
-- For 64 bit Windows 7 or above:
-
-pacman -S mingw-w64-x86_64-helix
+Building from source
+Clone the repository:
+git clone https://github.com/helix-editor/helix
+cd helix
-
-- For 64 bit Windows 8.1 or above:
-
-pacman -S mingw-w64-ucrt-x86_64-helix
+Compile from source:
+cargo install --path helix-term --locked
-Build from source
-git clone https://github.com/helix-editor/helix
-cd helix
-cargo install --path helix-term --locked
+This command will create the hx executable and construct the tree-sitter
+grammars either in the runtime folder, or in the folder specified in HELIX_RUNTIME
+(as described below). To build the tree-sitter grammars requires a c++ compiler to be installed, for example gcc-c++.
+
+๐ก If you are using the musl-libc instead of glibc the following environment variable must be set during the build
+to ensure tree-sitter grammars can be loaded correctly:
+RUSTFLAGS="-C target-feature=-crt-static"
-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:
-RUSTFLAGS="-C target-feature=-crt-static"
+
+
+๐ก 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).
+
+Configuring Helix's runtime files
+
+- Linux and macOS
+
+Either set the HELIX_RUNTIME environment variable to point to the runtime files and add it to your ~/.bashrc or equivalent:
+HELIX_RUNTIME=/home/user-name/src/helix/runtime
-Helix also needs its runtime files so make sure to copy/symlink the runtime/ directory into the
-config directory (for example ~/.config/helix/runtime on Linux/macOS). This location can be overridden
-via the HELIX_RUNTIME environment variable.
-OS Command Windows (Cmd) xcopy /e /i runtime %AppData%\helix\runtimeWindows (PowerShell) xcopy /e /i runtime $Env:AppData\helix\runtimeLinux / 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:
-New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
+Or, create a symlink in ~/.config/helix that links to the source code directory:
+ln -s $PWD/runtime ~/.config/helix/runtime
-Note: "runtime" must be the absolute path to the runtime directory.
-Cmd:
-cd %appdata%\helix
-mklink /D runtime "<helix-repo>\runtime"
+
+- Windows
+
+Either set the HELIX_RUNTIME environment variable to point to the runtime files using the Windows setting (search for
+Edit environment variables for your account) or use the setx command in
+Cmd:
+setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
-The runtime location can be overridden via the HELIX_RUNTIME environment variable.
-NOTE: if HELIX_RUNTIME is set prior to calling cargo install --path helix-term --locked,
-tree-sitter grammars will be built in $HELIX_RUNTIME/grammars.
+๐ก %userprofile% resolves to your user directory like
+C:\Users\Your-Name\ for example.
-If you plan on keeping the repo locally, an alternative to copying/symlinking
-runtime files is to set HELIX_RUNTIME=/path/to/helix/runtime
-(HELIX_RUNTIME=$PWD/runtime if you're in the helix repo directory).
-To use Helix in desktop environments that supports XDG desktop menu, including Gnome and KDE, copy the provided .desktop file to the correct folder:
-cp contrib/Helix.desktop ~/.local/share/applications
+Or, create a symlink in %appdata%\helix\ that links to the source code directory:
+| Method | Command |
+| ---------- | -------------------------------------------------------------------------------------- |
+| PowerShell | New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime" |
+| Cmd | cd %appdata%\helix
mklink /D runtime "%userprofile%\src\helix\runtime" |
+
+๐ก On Windows, creating a symbolic link may require running PowerShell or
+Cmd as an administrator.
+
+Validating the installation
+To make sure everything is set up as expected you should run the Helix health
+check:
+hx --health
-To use another terminal than the default, you will need to modify the .desktop file. For example, to use kitty:
-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
+For more information on the health check results refer to
+Health check.
+Configure the desktop shortcut
+If your desktop environment supports the
+XDG desktop menu
+you can configure Helix to show up in the application menu by copying the
+provided .desktop and icon files to their correct folders:
+cp contrib/Helix.desktop ~/.local/share/applications
+cp contrib/helix.png ~/.icons # or ~/.local/share/icons
-Please note: there is no icon for Helix yet, so the system default will be used.
-Finishing up the installation
-To make sure everything is set up as expected you should finally run the helix healthcheck via
-hx --health
+To use another terminal than the system default, you can modify the .desktop
+file. For example, to use kitty:
+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
-For more information on the information displayed in the health check results refer to Healthcheck.
-Building tree-sitter grammars
-Tree-sitter grammars must be fetched and compiled if not pre-packaged.
-Fetch grammars with hx --grammar fetch (requires git) and compile them
-with hx --grammar build (requires a C++ compiler).
-Installing language servers
-Language servers can optionally be installed if you want their features (auto-complete, diagnostics etc.).
-Follow the instructions on the wiki page to add your language servers of choice.
๐ก 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
@@ -266,7 +266,7 @@Selection manipulation
| 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 |
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 | ||
|---|---|---|---|---|
/ | Search for regex pattern | search | ||
? | Search for previous pattern | rsearch |
| 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 |
| Key | Description | Command |
|---|---|---|
m | Goto matching bracket (TS) | match_brackets |
s <char> | Surround current selection with <char> | surround_add |
| Key | Description | Command |
|---|---|---|
w, Ctrl-w | Switch to next window | rotate_view |
v, Ctrl-v | Vertical right split | vsplit |
-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
Displays documentation for item under cursor.
@@ -440,7 +439,7 @@ it).Unimpaired
-Mappings in the style of vim-unimpaired.
+These mappings are in the style of vim-unimpaired.
| Key | Description | Command |
|---|---|---|
]d | Go to next diagnostic (LSP) | goto_next_diag |
[d | Go to previous diagnostic (LSP) | goto_prev_diag |
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 |
|---|---|---|
Escape | Switch to normal mode | normal_mode |
Ctrl-s | Commit undo checkpoint | commit_undo_checkpoint |
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.
[keys.insert]
up = "no_op"
down = "no_op"
@@ -513,7 +514,7 @@ home = "no_op"
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.
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 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 docs and the Adding Languages guide for more language configuration information.
| Language | Syntax Highlighting | Treesitter Textobjects | Auto Indent | Default LSP |
|---|
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:
file-types = ["Makefile", "toml", { suffix = ".git/config" }]
diff --git a/master/print.html b/master/print.html
index bfe90054d..1d78ed56a 100644
--- a/master/print.html
+++ b/master/print.html
@@ -84,7 +84,7 @@
@@ -156,134 +156,219 @@ section for all available keybindings and the con
for defining custom keybindings, setting themes, etc.
For everything else (e.g., how to install supported language servers), see the Helix Wiki.
Refer the FAQ for common questions.
-Installation
-We provide pre-built binaries on the GitHub Releases page.
+Installing Helix
+
+
+- Pre-built binaries
+- Linux, macOS, Windows and OpenBSD packaging status
+- Linux
+
+
+- macOS
+
+
+- Windows
+
+- Scoop
+- Chocolatey
+- MSYS2
+
+
+- Building from source
+
+
+
+
+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.
+
+-
+
To take full advantage of Helix, install the language servers for your
+preferred programming languages. See the
+wiki
+for instructions.
+
+
+Pre-built binaries
+Download pre-built binaries from the
+GitHub Releases page. 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.
-OSX
-Helix is available in homebrew-core:
-brew install helix
-
Linux
-NixOS
-A flake 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.
-Flake outputs are cached for each push to master using
-Cachix. The flake is configured to
-automatically make use of this cache assuming the user accepts
-the new settings on first use.
-If you are using a version of Nix without flakes enabled you can
-install Cachix cli; cachix use helix will
-configure Nix to use cached outputs when possible.
-Arch Linux
-Releases are available in the community repository.
-A helix-git package is also available on the AUR, which builds the master branch.
-Fedora Linux
-You can install the COPR package for Helix via
-sudo dnf copr enable varlad/helix
+The following third party repositories are available:
+Ubuntu
+Helix is available via Maveonair's PPA:
+sudo add-apt-repository ppa:maveonair/helix-editor
+sudo apt update
+sudo apt install helix
+
+Fedora/RHEL
+Helix is available via copr:
+sudo dnf copr enable varlad/helix
sudo dnf install helix
-Void Linux
-sudo xbps-install helix
+Arch Linux community
+Releases are available in the community repository:
+sudo pacman -S helix
+
+Additionally, a helix-git package is available
+in the AUR, which builds the master branch.
+NixOS
+Helix is available as a flake in the project
+root. Use nix develop to spin up a reproducible development shell. Outputs are
+cached for each push to master using Cachix. 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 and use
+cachix use helix to configure Nix to use cached outputs when possible.
+macOS
+Homebrew Core
+brew install helix
Windows
-Helix can be installed using Scoop, Chocolatey
+
Install on Windows using Scoop, Chocolatey
or MSYS2.
-Scoop:
-scoop install helix
+Scoop
+scoop install helix
-Chocolatey:
-choco install helix
+Chocolatey
+choco install helix
-MSYS2:
-Choose the proper command for your system from below:
-
-- For 32 bit Windows 7 or above:
-
-pacman -S mingw-w64-i686-helix
+MSYS2
+For 64-bit Windows 8.1 or above:
+pacman -S mingw-w64-ucrt-x86_64-helix
-
-- For 64 bit Windows 7 or above:
-
-pacman -S mingw-w64-x86_64-helix
+Building from source
+Clone the repository:
+git clone https://github.com/helix-editor/helix
+cd helix
-
-- For 64 bit Windows 8.1 or above:
-
-pacman -S mingw-w64-ucrt-x86_64-helix
+Compile from source:
+cargo install --path helix-term --locked
-Build from source
-git clone https://github.com/helix-editor/helix
-cd helix
-cargo install --path helix-term --locked
+This command will create the hx executable and construct the tree-sitter
+grammars either in the runtime folder, or in the folder specified in HELIX_RUNTIME
+(as described below). To build the tree-sitter grammars requires a c++ compiler to be installed, for example gcc-c++.
+
+๐ก If you are using the musl-libc instead of glibc the following environment variable must be set during the build
+to ensure tree-sitter grammars can be loaded correctly:
+RUSTFLAGS="-C target-feature=-crt-static"
-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:
-RUSTFLAGS="-C target-feature=-crt-static"
+
+
+๐ก 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).
+
+Configuring Helix's runtime files
+
+- Linux and macOS
+
+Either set the HELIX_RUNTIME environment variable to point to the runtime files and add it to your ~/.bashrc or equivalent:
+HELIX_RUNTIME=/home/user-name/src/helix/runtime
-Helix also needs its runtime files so make sure to copy/symlink the runtime/ directory into the
-config directory (for example ~/.config/helix/runtime on Linux/macOS). This location can be overridden
-via the HELIX_RUNTIME environment variable.
-OS Command Windows (Cmd) xcopy /e /i runtime %AppData%\helix\runtimeWindows (PowerShell) xcopy /e /i runtime $Env:AppData\helix\runtimeLinux / 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:
-New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
+Or, create a symlink in ~/.config/helix that links to the source code directory:
+ln -s $PWD/runtime ~/.config/helix/runtime
-Note: "runtime" must be the absolute path to the runtime directory.
-Cmd:
-cd %appdata%\helix
-mklink /D runtime "<helix-repo>\runtime"
+
+- Windows
+
+Either set the HELIX_RUNTIME environment variable to point to the runtime files using the Windows setting (search for
+Edit environment variables for your account) or use the setx command in
+Cmd:
+setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
-The runtime location can be overridden via the HELIX_RUNTIME environment variable.
-NOTE: if HELIX_RUNTIME is set prior to calling cargo install --path helix-term --locked,
-tree-sitter grammars will be built in $HELIX_RUNTIME/grammars.
+๐ก %userprofile% resolves to your user directory like
+C:\Users\Your-Name\ for example.
+
+Or, create a symlink in %appdata%\helix\ that links to the source code directory:
+| Method | Command |
+| ---------- | -------------------------------------------------------------------------------------- |
+| PowerShell | New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime" |
+| Cmd | cd %appdata%\helix
mklink /D runtime "%userprofile%\src\helix\runtime" |
+
+๐ก On Windows, creating a symbolic link may require running PowerShell or
+Cmd as an administrator.
-If you plan on keeping the repo locally, an alternative to copying/symlinking
-runtime files is to set HELIX_RUNTIME=/path/to/helix/runtime
-(HELIX_RUNTIME=$PWD/runtime if you're in the helix repo directory).
-To use Helix in desktop environments that supports XDG desktop menu, including Gnome and KDE, copy the provided .desktop file to the correct folder:
-cp contrib/Helix.desktop ~/.local/share/applications
+Validating the installation
+To make sure everything is set up as expected you should run the Helix health
+check:
+hx --health
-To use another terminal than the default, you will need to modify the .desktop file. For example, to use kitty:
-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
+For more information on the health check results refer to
+Health check.
+Configure the desktop shortcut
+If your desktop environment supports the
+XDG desktop menu
+you can configure Helix to show up in the application menu by copying the
+provided .desktop and icon files to their correct folders:
+cp contrib/Helix.desktop ~/.local/share/applications
+cp contrib/helix.png ~/.icons # or ~/.local/share/icons
-Please note: there is no icon for Helix yet, so the system default will be used.
-Finishing up the installation
-To make sure everything is set up as expected you should finally run the helix healthcheck via
-hx --health
+To use another terminal than the system default, you can modify the .desktop
+file. For example, to use kitty:
+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
-For more information on the information displayed in the health check results refer to Healthcheck.
-Building tree-sitter grammars
-Tree-sitter grammars must be fetched and compiled if not pre-packaged.
-Fetch grammars with hx --grammar fetch (requires git) and compile them
-with hx --grammar build (requires a C++ compiler).
-Installing language servers
-Language servers can optionally be installed if you want their features (auto-complete, diagnostics etc.).
-Follow the instructions on the wiki page to add your language servers of choice.
-Usage
-(Currently not fully documented, see the keymappings list for more.)
-See tutor (accessible via hx --tutor or :tutor) for a vimtutor-like introduction.
+Using Helix
+
+
+- Registers
+
+
+- Surround
+- Selecting and manipulating text with textobjects
+- Navigating using tree-sitter textobjects
+- Moving the selection with syntax-aware motions
+
+
+For a full interactive introduction to Helix, refer to the
+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 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 /Last search :Last executed command The system clipboard is not directly supported by a special register. Instead, special commands and keybindings are provided. Refer to the
+key map 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 is built into
-helix. The keymappings have been inspired from vim-sandwich:
-
-
-ms - Add surround charactersmr - Replace surround charactersmd - Delete 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.
-It can also act on multiple selections (yay!). For example, to change every occurrence of (use) to [use]:
-
+Helix includes built-in functionality similar to vim-surround.
+The keymappings have been inspired from vim-sandwich:
+
+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
+
+You can use counts to act on outer pairs.
+Surround can also act on multiple selections. For example, to change every occurrence of (use) to [use]:
+
% to select the whole files to split the selections on a search term- Input
use and hit Enter
-mr([ to replace the parens with square bracketsmr([ to replace the parentheses with square brackets
+Multiple characters are currently not supported, but planned for future release.
+Selecting and manipulating text with textobjects
+In Helix, textobjects are a way to select, manipulate and operate on a piece of
+text in a structured way. They allow you to refer to blocks of text based on
+their structure or purpose, such as a word, sentence, paragraph, or even a
+function or block of code.
+
+
+
+ma - Select around the object (va in Vim, <alt-a> in Kakoune)mi - Select inside the object (vi in Vim, <alt-i> in Kakoune)
-Multiple characters are currently not supported, but planned.
-Syntax-tree Motions
-Alt-p, Alt-o, Alt-i, and Alt-n (or Alt and arrow keys) move the primary
-selection according to the selection's place in the syntax tree. Let's walk
-through an example to get familiar with them. Many languages have a syntax like
-so for function calls:
-
func(arg1, arg2, arg3)
+Key after mi or ma Textobject selected wWord WWORD pParagraph (, [, ', etc.Specified surround pairs mThe closest surround pair fFunction cClass aArgument/parameter oComment tTest gChange
+
+
+๐ก 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 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.
+
+For the full reference see the unimpaired 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:
+func(arg1, arg2, arg3);
A function call might be parsed by tree-sitter into a tree like the following.
(call
@@ -346,63 +472,23 @@ a more intuitive tree format:
โ "arg1" โ โ "arg2" โ โ "arg3" โ
โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ
-Say we have a selection that wraps arg1. The selection is on the arg1 leaf
-in the tree above.
-func([arg1], arg2, arg3)
-
-Using Alt-n would select the next sibling in the syntax tree: arg2.
-func(arg1, [arg2], arg3)
+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.
+// before
+func([arg1], arg2, arg3)
+// after
+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)]
+Similarly, Alt-o will expand the selection to the parent node, in this case, the
+arguments node.
+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
-
-
-
-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 wWord WWORD pParagraph (, [, ', etcSpecified surround pairs mClosest surround pair fFunction cClass aArgument/parameter oComment tTest gChange
-
-
-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 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.
-
-See the unimpaired 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.
Keymap
- Normal mode
@@ -431,8 +517,8 @@ and therefore requires the corresponding query file to work properly.
-Insert Mode
-Select / extend mode
+Insert mode
+Select / extend mode
Picker
Prompt
@@ -440,7 +526,7 @@ and therefore requires the corresponding query file to work properly.
๐ก 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
@@ -522,7 +608,7 @@ and therefore requires the corresponding query file to work properly.
Selection manipulation
Key Description Command sSelect all regex matches inside selections select_regexSSplit selection into subselections on regex matches split_selectionSSplit selection into sub selections on regex matches split_selectionAlt-sSplit selection on newlines split_selection_on_newlineAlt-_ Merge consecutive selections merge_consecutive_selections&Align selection in columns align_selections
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 /Search for regex pattern search?Search for previous pattern rsearchAccessed by typing z in 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 z, cVertically center the line align_view_centertAlign the line to the top of the screen align_view_topMatch mode
Accessed by typing m in normal mode.
See the relevant section in Usage for an explanation about
-surround and textobject usage.
+surround and textobject usage.
Key Description Command mGoto matching bracket (TS) match_bracketss <char>Surround current selection with <char> surround_addTODO: Mappings for selecting syntax nodes (a superset of [).
Window mode
Accessed by typing Ctrl-w in 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 w, Ctrl-wSwitch to next window rotate_viewv, Ctrl-vVertical right split vsplit
-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
Displays documentation for item under cursor.
@@ -696,7 +781,7 @@ it).
Unimpaired
-Mappings in the style of vim-unimpaired.
+These mappings are in the style of vim-unimpaired.
Key Description Command ]dGo to next diagnostic (LSP) goto_next_diag[dGo to previous diagnostic (LSP) goto_prev_diag
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 EscapeSwitch to normal mode normal_modeCtrl-sCommit undo checkpoint commit_undo_checkpointEndMove 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.
[keys.insert]
up = "no_op"
down = "no_op"
@@ -769,7 +856,7 @@ home = "no_op"
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.
@@ -819,7 +906,7 @@ you to selectively add search terms to your selections.
EnterOpen selected
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:
Name Description :quit, :qClose the current view. :quit!, :q!Force close the current view, ignoring unsaved changes. :run-shell-command, :shRun a shell command
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 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 docs and the Adding
Languages guide for more language configuration information.
Language Syntax Highlighting Treesitter Textobjects Auto Indent Default LSP 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:
theme = "onedark"
@@ -1095,31 +1182,30 @@ select = "underline"
[editor.file-picker]
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 scrolloffNumber of lines of padding around the edge of the screen when scrolling. 5mouseEnable mouse mode. truemiddle-click-pasteMiddle click paste support. truescroll-linesNumber of lines to scroll per scroll wheel step. 3shellShell to use when running external commands. Unix: ["sh", "-c"]
Windows: ["cmd", "/C"] line-numberLine 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. absolutecursorlineHighlight all lines with a cursor. falsecursorcolumnHighlight all columns with a cursor. falsescrolloffNumber of lines of padding around the edge of the screen when scrolling 5mouseEnable mouse mode truemiddle-click-pasteMiddle click paste support truescroll-linesNumber of lines to scroll per scroll wheel step 3shellShell to use when running external commands Unix: ["sh", "-c"]
Windows: ["cmd", "/C"] line-numberLine 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 absolutecursorlineHighlight all lines with a cursor falsecursorcolumnHighlight all columns with a cursor falseguttersGutters 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-completionEnable automatic pop up of auto-completion. trueauto-formatEnable automatic formatting on save. trueauto-saveEnable automatic saving on focus moving away from Helix. Requires focus event support from your terminal. falseidle-timeoutTime in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. 400auto-completionEnable automatic pop up of auto-completion trueauto-formatEnable automatic formatting on save trueauto-saveEnable automatic saving on the focus moving away from Helix. Requires focus event support from your terminal falseidle-timeoutTime in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant 400completion-trigger-lenThe min-length of word under cursor to trigger autocompletion 2auto-infoWhether to display infoboxes truetrue-colorSet to true to override automatic detection of terminal truecolor support in the event of a false negative. falserulersList of column positions at which to display the rulers. Can be overridden by language specific rulers in languages.toml file. []auto-infoWhether to display info boxes truetrue-colorSet to true to override automatic detection of terminal truecolor support in the event of a false negative falserulersList of column positions at which to display the rulers. Can be overridden by language specific rulers in languages.toml file []bufferlineRenders 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) nevercolor-modesWhether to color the mode indicator with different colors depending on the mode itself false
@@ -1182,9 +1268,12 @@ mode.select = "SELECT"
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.
+
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 normalCursor shape in normal mode blockinsertCursor shape in insert mode blockblock, bar, u
[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 hiddenEnables ignoring hidden files. true hiddenEnables ignoring hidden files true follow-linksFollow symlinks instead of ignoring them true deduplicate-linksIgnore symlinks that point at files already shown in the picker true parentsEnables reading ignore files from parent directories. true ignoreEnables reading .ignore files. true git-ignoreEnables reading .gitignore files. true git-globalEnables reading global .gitignore, whose path is specified in git's config: core.excludefile option. true git-excludeEnables reading .git/info/exclude files. true max-depthSet with an integer value for maximum depth to recurse. Defaults to None. parentsEnables reading ignore files from parent directories true ignoreEnables reading .ignore files true git-ignoreEnables reading .gitignore files true git-globalEnables reading global .gitignore, whose path is specified in git's config: core.excludefile option true git-excludeEnables reading .git/info/exclude files true max-depthSet with an integer value for maximum depth to recurse Defaults to None.
[editor.auto-pairs] Section
@@ -1245,14 +1331,14 @@ name = "rust"
[editor.search] Section
Search specific options.
Key Description Default smart-caseEnable smart case regex searching (case insensitive unless pattern contains upper case characters) truesmart-caseEnable smart case regex searching (case-insensitive unless pattern contains upper case characters) truewrap-aroundWhether 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.
Key Description Default renderWhether to render whitespace. May either be "all" or "none", or a table with sub-keys space, nbsp, tab, and newline. "none"renderWhether to render whitespace. May either be "all" or "none", or a table with sub-keys space, nbsp, tab, and newline "none"charactersLiteral characters to use when rendering whitespace. Sub-keys may be any of tab, space, nbsp, newline or tabpad See example below
@@ -1275,7 +1361,7 @@ tabpad = "ยท" # Tabs will look like "โยทยทยท" (depending o
[editor.indent-guides] Section
Options for rendering vertical indent guides.
Key Description Default renderWhether to render indent guides. falserenderWhether to render indent guides falsecharacterLiteral character to use for rendering the indent guide โskip-levelsNumber of indent levels to skip 0
@@ -1294,7 +1380,7 @@ gutters = ["diff", "diagnostics", "line-numbers",
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 layoutA vector of gutters to display ["diagnostics", "spacer", "line-numbers", "spacer", "diff"]
@@ -1320,11 +1406,11 @@ min-width = 1
[editor.gutters.spacer] Section
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 enableWhether soft wrapping is enabled. falsemax-wrapMaximum free space left at the end of the line. 20max-indent-retainMaximum indentation to carry over when soft wrapping a line. 40enableWhether soft wrapping is enabled falsemax-wrapMaximum free space left at the end of the line 20max-indent-retainMaximum indentation to carry over when soft wrapping a line 40wrap-indicatorText inserted before soft wrapped lines, highlighted with ui.virtual.wrap โช
@@ -1336,23 +1422,35 @@ max-indent-retain = 0
wrap-indicator = "" # set wrap-indicator to "" to hide it
Themes
-To use a theme add theme = "<name>" to your config.toml 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 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.
-The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes.
-The default theme.toml can be found here, and user submitted themes here.
+Create a file with the name of your theme as the file name (i.e mytheme.toml) and place it in your themes directory (i.e ~/.config/helix/themes or %AppData%\helix\themes on Windows). The directory might have to be created beforehand.
+
+๐ก The names "default" and "base16_default" are reserved for built-in themes
+and cannot be overridden by user-defined themes.
+
+Overview
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:
key = "#ffffff"
-if the key contains a dot '.', it must be quoted to prevent it being parsed as a dotted key.
+If the key contains a dot '.', it must be quoted to prevent it being parsed as a dotted key.
"key.key" = "#ffffff"
+For inspiration, you can find the default theme.toml
+here and
+user-submitted themes
+here.
+Using the linter
+Use the supplied linting tool to check for errors and missing scopes:
+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:
"ui.background" = "white"
@@ -1362,8 +1460,8 @@ configuration values in your theme. To do this, add a table called
white = "#ffffff"
black = "#000000"
-Remember that the [palette] table includes all keys after its header,
-so you should define the palette after normal theme options.
+Keep in mind that the [palette] table includes all keys after its header,
+so it should be defined after the normal theme options.
The default palette uses the terminal's default 16 colors, and the colors names
are listed below. The [palette] section in the config file takes precedence
over it and is merged into the default palette.
@@ -1387,8 +1485,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 bolddim
-Note: The underlined modifier is deprecated and only available for backwards compatibility.
+
๐ก The underlined modifier is deprecated and only available for backwards compatibility.
Its behavior is equivalent to setting underline.style="line".
-Underline Style
-One of the following values may be used as a value for underline.style.
-Some styles might not be supported by your terminal emulator.
+Underline style
+One of the following values may be used as a value for underline.style, providing it is
+supported by your terminal emulator.
Modifier linecurlunderline.style="line"
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.
inherits = "boo_berry"
# Override the theming for "keyword"s:
@@ -1428,16 +1526,16 @@ Its behavior is equivalent to setting underline.style="line"
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.
-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. See also
+Sublime Text. See also
TextMate scopes.
-
-
attribute - Class attributes, html tag attributes
+attribute - Class attributes, HTML tag attributes
-
type - Types
@@ -1454,7 +1552,7 @@ berry = "#2A2A4D"
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)
@@ -1491,7 +1589,7 @@ berry = "#2A2A4D"
comment - Code comments
line - Single line comments (//)block - Block comments (e.g. (/* */)
+block - Block comments (e.g. (/* */)
documentation - Documentation comments (e.g. /// in Rust)
@@ -1501,7 +1599,7 @@ berry = "#2A2A4D"
-
variable - Variables
-builtin - Reserved language variables (self, this, super, etc)builtin - Reserved language variables (self, this, super, etc.)parameter - Function parametersother
@@ -1534,11 +1632,11 @@ berry = "#2A2A4D"
operator - or, indirective - Preprocessor directives (#if in C) directive - Preprocessor directives (#if in C)function - fn, funcstorage - 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.
italiclink
-url - urls pointed to by linkslabel - non-url link referencestext - url and image descriptions in linksurl - URLs pointed to by linkslabel - non-URL link referencestext - URL and image descriptions in links
quote
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 uihover - for hover popup uicompletion - for completion doc popup UIhover - for hover popup UI
heading
-completion - for completion doc popup uihover - for hover popup uicompletion - for completion doc popup UIhover - for hover popup UI
raw
inline
-completion - for completion doc popup uihover - for hover popup uicompletion - for completion doc popup UIhover - for hover popup UI
@@ -1663,9 +1761,9 @@ berry = "#2A2A4D"
ui.statusline.insertStatusline mode during insert mode (only if editor.color-modes is enabled) ui.statusline.selectStatusline mode during select mode (only if editor.color-modes is enabled) ui.statusline.separatorSeparator character in statusline ui.popupDocumentation popups (e.g Space + k) ui.popupDocumentation popups (e.g. Space + k) ui.popup.infoPrompt for multiple key options ui.windowBorder lines separating splits ui.windowBorderlines separating splits ui.helpDescription box for commands ui.textCommand prompts, popup text, etc. ui.text.focusdiagnostic.warningDiagnostics warning (editing area) diagnostic.errorDiagnostics error (editing area)
-
-You can check compliance to spec with
-cargo xtask themelint onedark # replace onedark with <name>
-
-Key Remapping
-One-way key remapping is temporarily supported via a simple TOML configuration
+
Key remapping
+Helix currently supports one-way key remapping through a simple TOML configuration
file. (More powerful solutions such as rebinding via commands will be
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:
# 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
@@ -1716,12 +1810,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
Minor modes are accessed by pressing a key (usually from normal mode), giving access to dedicated bindings. Bindings
can be modified or added by nesting definitions.
@@ -1766,30 +1857,37 @@ t = ":run-shell-command cargo test"
Keys can be disabled by binding them to the no_op command.
-Commands can be found at Keymap Commands.
-
-Commands can also be found in the source code at helix-term/src/commands.rs at the invocation of static_commands! macro and the TypableCommandList.
-
+A list of commands is available in the Keymap documentation
+and in the source code at helix-term/src/commands.rs at the invocation of static_commands! macro and the TypableCommandList.
Languages
Language-specific settings and settings for language servers are configured
in languages.toml files.
languages.toml files
-There are three possible languages.toml files. The first is compiled into
-Helix and lives in the Helix repository.
-This provides the default configurations for languages and language servers.
-You may define a languages.toml in your configuration directory
-which overrides values from the built-in language configuration. For example
-to disable auto-LSP-formatting in Rust:
+There are three possible locations for a languages.toml file:
+
+-
+
In the Helix source code, this lives in the
+Helix repository.
+It provides the default configurations for languages and language servers.
+
+-
+
In your configuration directory. This overrides values
+from the built-in language configuration. For example to disable
+auto-LSP-formatting in Rust:
+
+
# in <config_dir>/helix/languages.toml
[[language]]
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.
+
+- 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
Each language is configured by adding a [[language]] section to a
languages.toml file. For example:
@@ -1823,7 +1921,7 @@ formatter = { command = "mylang-formatter" , args = ["--stdin&quo
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:
file-types = ["Makefile", "toml", { suffix = ".git/config" }]
@@ -1896,52 +1994,69 @@ use-grammars = { except = [ "yaml", "json" ] }
When omitted, all grammars are fetched and built.
Guides
This section contains guides for adding new language server configurations,
-tree-sitter grammars, textobject queries, etc.
-Adding languages
+tree-sitter grammars, textobject queries, and other similar items.
+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).
-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 docs before creating a pull request.
-When adding a Language Server configuration, be sure to update the
-Language Server Wiki with installation notes.
+
+- 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 of the documentation.
+- 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 documentation.
+
+
+๐ก If you are adding a new Language Server configuration, make sure to update
+the
+Language Server Wiki
+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.
+
+- If a tree-sitter grammar is available for the new language, add a new
+
[[grammar]] entry to the languages.toml file.
+- 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
-gives more info on how to write queries.
+
+- In order to provide syntax highlighting and indentation for the new language,
+you will need to add queries.
+- Create a new directory for the language with the path
+
runtime/queries/<name>/.
+- Refer to the
+tree-sitter website
+for more information on writing 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 for an example.
+๐ก 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
+for an example.
-Common Issues
+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
-
+- 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.
-Adding Textobject Queries
-Textobjects that are language specific (like functions, classes, etc)
-require an accompanying tree-sitter grammar and a textobjects.scm query file
+
Adding textobject queries
+Helix supports textobjects that are language specific, such as functions, classes, etc.
+These textobjects require an accompanying tree-sitter grammar and a textobjects.scm query file
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.
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).
The following captures are recognized:
@@ -1958,8 +2073,8 @@ for example).
Example query files can be found in the helix GitHub repository.
-Queries for Textobject Based Navigation
-Tree-sitter based navigation is done using captures in the +
Queries for textobject based navigation
+Tree-sitter based navigation in Helix is done using captures in the following order:
object.movement
@@ -1967,10 +2082,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.
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
runtime/queries/{language}/indents.scm. The indentation for a line
@@ -2005,7 +2120,7 @@ changed by using a #set! declaration anywhere in the pattern:
Capture Types
+Capture types
-
-@indent(default scopetail): diff --git a/master/remapping.html b/master/remapping.html index c3702d281..75e347b05 100644 --- a/master/remapping.html +++ b/master/remapping.html @@ -3,7 +3,7 @@Key Remapping +Key remapping @@ -83,7 +83,7 @@ @@ -147,17 +147,17 @@- Key Remapping
-One-way key remapping is temporarily supported via a simple TOML configuration +
Key remapping
+Helix currently supports one-way key remapping through a simple TOML configuration file. (More powerful solutions such as rebinding via commands will be available in the future).
-To remap keys, write a
config.tomlfile in yourhelixconfiguration -directory (default~/.config/helixin Linux systems) with a structure like +To remap keys, create a
config.tomlfile in yourhelixconfiguration +directory (default~/.config/helixon Linux systems) with a structure like this:
-# 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 @@ -165,12 +165,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
Minor modes are accessed by pressing a key (usually from normal mode), giving access to dedicated bindings. Bindings can be modified or added by nesting definitions.
@@ -215,10 +212,8 @@ t = ":run-shell-command cargo test"Keys can be disabled by binding them to the
-no_opcommand.Commands can be found at Keymap Commands.
--
+Commands can also be found in the source code at
-helix-term/src/commands.rsat the invocation ofstatic_commands!macro and theTypableCommandList.A list of commands is available in the Keymap documentation +and in the source code at
diff --git a/master/searchindex.js b/master/searchindex.js index 1a7d3892c..da6c6cbce 100644 --- a/master/searchindex.js +++ b/master/searchindex.js @@ -1 +1 @@ -Object.assign(window.search, {"doc_urls":["title-page.html#helix","install.html#installation","install.html#osx","install.html#linux","install.html#nixos","install.html#arch-linux","install.html#fedora-linux","install.html#void-linux","install.html#windows","install.html#build-from-source","install.html#finishing-up-the-installation","install.html#building-tree-sitter-grammars","install.html#installing-language-servers","usage.html#usage","usage.html#registers","usage.html#special-registers","usage.html#surround","usage.html#syntax-tree-motions","usage.html#textobjects","usage.html#tree-sitter-textobject-based-navigation","keymap.html#keymap","keymap.html#normal-mode","keymap.html#movement","keymap.html#changes","keymap.html#selection-manipulation","keymap.html#search","keymap.html#minor-modes","keymap.html#insert-mode","keymap.html#select--extend-mode","keymap.html#picker","keymap.html#prompt","commands.html#commands","lang-support.html#language-support","from-vim.html#migrating-from-vim","configuration.html#configuration","configuration.html#editor","configuration.html#editor-section","configuration.html#editorstatusline-section","configuration.html#editorlsp-section","configuration.html#editorcursor-shape-section","configuration.html#editorfile-picker-section","configuration.html#editorauto-pairs-section","configuration.html#editorsearch-section","configuration.html#editorwhitespace-section","configuration.html#editorindent-guides-section","configuration.html#editorgutters-section","configuration.html#editorsoft-wrap-section","themes.html#themes","themes.html#creating-a-theme","themes.html#color-palettes","themes.html#modifiers","themes.html#underline-style","themes.html#inheritance","themes.html#scopes","remapping.html#key-remapping","remapping.html#minor-modes","remapping.html#special-keys-and-modifiers","languages.html#languages","languages.html#languagestoml-files","languages.html#language-configuration","languages.html#file-type-detection-and-the-file-types-key","languages.html#language-server-configuration","languages.html#tree-sitter-grammar-configuration","languages.html#choosing-grammars","guides/index.html#guides","guides/adding_languages.html#adding-languages","guides/adding_languages.html#language-configuration","guides/adding_languages.html#grammar-configuration","guides/adding_languages.html#queries","guides/adding_languages.html#common-issues","guides/textobject.html#adding-textobject-queries","guides/textobject.html#queries-for-textobject-based-navigation","guides/indent.html#adding-indent-queries","guides/indent.html#scopes","guides/indent.html#capture-types","guides/indent.html#predicates"],"index":{"documentStore":{"docInfo":{"0":{"body":38,"breadcrumbs":2,"title":1},"1":{"body":9,"breadcrumbs":2,"title":1},"10":{"body":22,"breadcrumbs":4,"title":3},"11":{"body":21,"breadcrumbs":5,"title":4},"12":{"body":18,"breadcrumbs":4,"title":3},"13":{"body":16,"breadcrumbs":2,"title":1},"14":{"body":54,"breadcrumbs":2,"title":1},"15":{"body":37,"breadcrumbs":3,"title":2},"16":{"body":76,"breadcrumbs":2,"title":1},"17":{"body":150,"breadcrumbs":4,"title":3},"18":{"body":76,"breadcrumbs":2,"title":1},"19":{"body":49,"breadcrumbs":6,"title":5},"2":{"body":7,"breadcrumbs":2,"title":1},"20":{"body":45,"breadcrumbs":3,"title":1},"21":{"body":0,"breadcrumbs":4,"title":2},"22":{"body":161,"breadcrumbs":3,"title":1},"23":{"body":228,"breadcrumbs":3,"title":1},"24":{"body":220,"breadcrumbs":4,"title":2},"25":{"body":39,"breadcrumbs":3,"title":1},"26":{"body":772,"breadcrumbs":4,"title":2},"27":{"body":192,"breadcrumbs":4,"title":2},"28":{"body":53,"breadcrumbs":5,"title":3},"29":{"body":60,"breadcrumbs":3,"title":1},"3":{"body":0,"breadcrumbs":2,"title":1},"30":{"body":136,"breadcrumbs":3,"title":1},"31":{"body":688,"breadcrumbs":3,"title":1},"32":{"body":356,"breadcrumbs":5,"title":2},"33":{"body":53,"breadcrumbs":4,"title":2},"34":{"body":80,"breadcrumbs":2,"title":1},"35":{"body":0,"breadcrumbs":2,"title":1},"36":{"body":228,"breadcrumbs":3,"title":2},"37":{"body":225,"breadcrumbs":3,"title":2},"38":{"body":57,"breadcrumbs":3,"title":2},"39":{"body":42,"breadcrumbs":4,"title":3},"4":{"body":56,"breadcrumbs":2,"title":1},"40":{"body":121,"breadcrumbs":4,"title":3},"41":{"body":62,"breadcrumbs":4,"title":3},"42":{"body":30,"breadcrumbs":3,"title":2},"43":{"body":66,"breadcrumbs":3,"title":2},"44":{"body":40,"breadcrumbs":4,"title":3},"45":{"body":92,"breadcrumbs":3,"title":2},"46":{"body":71,"breadcrumbs":4,"title":3},"47":{"body":18,"breadcrumbs":3,"title":1},"48":{"body":93,"breadcrumbs":4,"title":2},"49":{"body":82,"breadcrumbs":4,"title":2},"5":{"body":12,"breadcrumbs":3,"title":2},"50":{"body":31,"breadcrumbs":3,"title":1},"51":{"body":16,"breadcrumbs":4,"title":2},"52":{"body":22,"breadcrumbs":3,"title":1},"53":{"body":524,"breadcrumbs":3,"title":1},"54":{"body":131,"breadcrumbs":5,"title":2},"55":{"body":66,"breadcrumbs":5,"title":2},"56":{"body":70,"breadcrumbs":6,"title":3},"57":{"body":9,"breadcrumbs":3,"title":1},"58":{"body":57,"breadcrumbs":4,"title":2},"59":{"body":223,"breadcrumbs":4,"title":2},"6":{"body":14,"breadcrumbs":3,"title":2},"60":{"body":109,"breadcrumbs":8,"title":6},"61":{"body":111,"breadcrumbs":5,"title":3},"62":{"body":90,"breadcrumbs":6,"title":4},"63":{"body":38,"breadcrumbs":4,"title":2},"64":{"body":14,"breadcrumbs":2,"title":1},"65":{"body":0,"breadcrumbs":5,"title":2},"66":{"body":45,"breadcrumbs":5,"title":2},"67":{"body":26,"breadcrumbs":5,"title":2},"68":{"body":40,"breadcrumbs":4,"title":1},"69":{"body":32,"breadcrumbs":5,"title":2},"7":{"body":4,"breadcrumbs":3,"title":2},"70":{"body":79,"breadcrumbs":7,"title":3},"71":{"body":35,"breadcrumbs":8,"title":4},"72":{"body":57,"breadcrumbs":7,"title":3},"73":{"body":68,"breadcrumbs":5,"title":1},"74":{"body":95,"breadcrumbs":6,"title":2},"75":{"body":93,"breadcrumbs":5,"title":1},"8":{"body":54,"breadcrumbs":2,"title":1},"9":{"body":208,"breadcrumbs":3,"title":2}},"docs":{"0":{"body":"Docs for bleeding edge master can be found at https://docs.helix-editor.com/master . See the usage section for a quick overview of the editor, keymap section for all available keybindings and the configuration section for defining custom keybindings, setting themes, etc. For everything else (e.g., how to install supported language servers), see the Helix Wiki . Refer the FAQ for common questions.","breadcrumbs":"Helix ยป Helix","id":"0","title":"Helix"},"1":{"body":"We provide pre-built binaries on the GitHub Releases page . Packaging status","breadcrumbs":"Installation ยป Installation","id":"1","title":"Installation"},"10":{"body":"To make sure everything is set up as expected you should finally run the helix healthcheck via hx --health For more information on the information displayed in the health check results refer to Healthcheck .","breadcrumbs":"Installation ยป Finishing up the installation","id":"10","title":"Finishing up the installation"},"11":{"body":"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).","breadcrumbs":"Installation ยป Building tree-sitter grammars","id":"11","title":"Building tree-sitter grammars"},"12":{"body":"Language servers can optionally be installed if you want their features (auto-complete, diagnostics etc.). Follow the instructions on the wiki page to add your language servers of choice.","breadcrumbs":"Installation ยป Installing language servers","id":"12","title":"Installing language servers"},"13":{"body":"(Currently not fully documented, see the keymappings list for more.) See tutor (accessible via hx --tutor or :tutor) for a vimtutor-like introduction.","breadcrumbs":"Usage ยป Usage","id":"13","title":"Usage"},"14":{"body":"Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with \" being used to select a register: \"ay - Yank the current selection to register a. \"op - Paste the text in register o after the selection. If there is a selected register before invoking a change or delete command, the selection will be stored in the register and the action will be carried out: \"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.","breadcrumbs":"Usage ยป Registers","id":"14","title":"Registers"},"15":{"body":"Register character Contains / Last search : Last executed command \" Last yanked text _ Black hole There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the keymap for the specifics. The black hole register works as a no-op register, meaning no data will be written to / read from it.","breadcrumbs":"Usage ยป Special Registers","id":"15","title":"Special Registers"},"16":{"body":"Functionality similar to vim-surround is built into helix. The keymappings have been inspired from vim-sandwich : surround demo ms - Add surround characters mr - Replace surround characters md - Delete surround characters ms acts on a selection, so select the text first and use mshelix-term/src/commands.rsat the invocation ofstatic_commands!macro and theTypableCommandList.. mr and md work on the closest pairs found and selections are not required; use counts to act in outer pairs. It can also act on multiple selections (yay!). For example, to change every occurrence of (use) to [use]: % 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 Multiple characters are currently not supported, but planned.","breadcrumbs":"Usage ยป Surround","id":"16","title":"Surround"},"17":{"body":"Alt-p, Alt-o, Alt-i, and Alt-n (or Alt and arrow keys) move the primary selection according to the selection's place in the syntax tree. Let's walk through an example to get familiar with them. Many languages have a syntax like so for function calls: func(arg1, arg2, arg3) A function call might be parsed by tree-sitter into a tree like the following. (call function: (identifier) ; func arguments: (arguments ; (arg1, arg2, arg3) (identifier) ; arg1 (identifier) ; arg2 (identifier))) ; arg3 Use :tree-sitter-subtree to view the syntax tree of the primary selection. In a more intuitive tree format: โโโโโโ โcallโ โโโโโโโดโโโโโดโโโโโโ โ โ\nโโโโโโโผโโโโโ โโโโโโผโโโโโ\nโidentifierโ โargumentsโ\nโ \"func\" โ โโโโโโดโโโโฌโโโโโโดโโโโ\nโโโโโโโโโโโโ โ โ โ โ โ โ โโโโโโโโโโโผโ โโโโโโผโโโโโโ โโผโโโโโโโโโโ โidentifierโ โidentifierโ โidentifierโ โ \"arg1\" โ โ \"arg2\" โ โ \"arg3\" โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ Say we have a selection that wraps arg1. The selection is on the arg1 leaf in the tree above. func([arg1], arg2, arg3) Using Alt-n would select the next sibling in the syntax tree: arg2. 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)] 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)","breadcrumbs":"Usage ยป Syntax-tree Motions","id":"17","title":"Syntax-tree Motions"},"18":{"body":"textobject-demo textobject-treesitter-demo ma - Select around the object (va in Vim, in Kakoune) mi - Select inside the object (vi in Vim, in Kakoune) Key after mi or ma Textobject selected w Word W WORD p Paragraph (, [, ', etc Specified surround pairs m 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 currently have the query file implemented. Contributions are welcome!","breadcrumbs":"Usage ยป Textobjects","id":"18","title":"Textobjects"},"19":{"body":"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 See the unimpaired 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.","breadcrumbs":"Usage ยป Tree-sitter Textobject Based Navigation","id":"19","title":"Tree-sitter Textobject Based Navigation"},"2":{"body":"Helix is available in homebrew-core: brew install helix","breadcrumbs":"Installation ยป OSX","id":"2","title":"OSX"},"20":{"body":"Normal mode Movement Changes Shell Selection manipulation Search Minor modes View mode Goto mode Match mode Window mode Space mode Popup Unimpaired Insert Mode Select / extend mode Picker Prompt ๐ก Mappings marked ( LSP ) require an active language server for the file. ๐ก Mappings marked ( TS ) require a tree-sitter grammar for the filetype.","breadcrumbs":"Usage ยป Keymap ยป Keymap","id":"20","title":"Keymap"},"21":{"body":"","breadcrumbs":"Usage ยป Keymap ยป Normal mode","id":"21","title":"Normal mode"},"22":{"body":"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","breadcrumbs":"Usage ยป Keymap ยป Movement","id":"22","title":"Movement"},"23":{"body":"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 ` Set the selected text to lower case switch_to_lowercase Alt-` Set the selected text to upper case switch_to_uppercase i Insert before selection insert_mode a Insert after selection (append) append_mode I Insert at the start of the line insert_at_line_start A Insert at the end of the line insert_at_line_end o Open new line below selection open_below O Open new line above selection open_above . Repeat last insert N/A u Undo change undo U Redo change redo Alt-u Move backward in history earlier Alt-U Move forward in history later y Yank selection yank p Paste after selection paste_after P Paste before selection paste_before \" Select a register to yank to or paste from select_register > Indent selection indent < Unindent selection unindent = Format selection (currently nonfunctional/disabled) ( LSP ) format_selections d Delete selection delete_selection Alt-d Delete selection, without yanking delete_selection_noyank c Change selection (delete and enter insert mode) change_selection Alt-c Change selection (delete and enter insert mode, without yanking) change_selection_noyank Ctrl-a Increment object (number) under cursor increment Ctrl-x Decrement object (number) under cursor decrement Q Start/stop macro recording to the selected register (experimental) record_macro q Play back a recorded macro from the selected register (experimental) replay_macro Shell 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","breadcrumbs":"Usage ยป Keymap ยป Changes","id":"23","title":"Changes"},"24":{"body":"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 the inserted 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","breadcrumbs":"Usage ยป Keymap ยป Selection manipulation","id":"24","title":"Selection manipulation"},"25":{"body":"Search commands all operate on the / register by default. Use \" to operate on a different one. Key Description Command / Search for regex pattern search ? Search for previous pattern rsearch n Select next search match search_next N Select previous search match search_prev * Use current selection as the search pattern search_selection","breadcrumbs":"Usage ยป Keymap ยป Search","id":"25","title":"Search"},"26":{"body":"These sub-modes are accessible from normal mode and typically switch back to normal mode after a command. Key Description Command v Enter select (extend) mode select_mode g Enter goto mode N/A m Enter match mode N/A : Enter command mode command_mode z Enter view mode N/A Z Enter sticky view mode N/A Ctrl-w Enter window mode N/A Space Enter space mode N/A These modes (except command mode) can be configured by remapping keys . View mode Accessed by typing z in 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). 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 m Align the line to the middle of the screen (horizontally) align_view_middle j, down Scroll the view downwards scroll_down k, up Scroll the view upwards scroll_up Ctrl-f, PageDown Move page down page_down Ctrl-b, PageUp Move page up page_up Ctrl-d Move half page down half_page_down Ctrl-u Move half page up half_page_up Goto mode Accessed by typing g in 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 Match mode Accessed by typing m in normal mode . See the relevant section in Usage for an explanation about surround and textobject 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
You can check compliance to spec with
-cargo xtask themelint onedark # replace onedark with <name>
-