FAQ

Table of Contents

• How to…​
  • Collapse to single cursor after using multiple cursors / Keep only primary cursor
  • Change cursor shape on mode change (bar cursor on insert mode, block on normal mode, etc)
  • Map jk or jj to exit insert mode
  • Map unicode characters like ö to keybinding
  • Use my terminal’s 16 color palette as a theme
  • Perform find-and-replace
  • Strip whitespace or format the buffer
  • Access the Helix config directory
  • Access the log file
  • Add a language
  • Change grammars at project level
  • Close the LSP documentation popup
• General Questions
  • How to write plugins / Is there a plugin system in place yet ?
  • When will the next release be?
  • Is a Vi/Vim keymap planned?
  • Can the j/k bindings be changed to ignore soft wrapping when using a count like 3j
  • How do I build or run code from within Helix?
• Installation
  • Error when building tree-sitter language grammars in Fedora
• Common Issues
  • Alt-* key combinations do not work on MacOS iTerm2

How to…​

Collapse to single cursor after using multiple cursors / Keep only primary cursor

• Use the default keybind , bound to the keep_primary_selection command.

Change cursor shape on mode change (bar cursor on insert mode, block on normal mode, etc)

• Add this to your config.toml:

  [editor.cursor-shape]
  insert = "bar"
  normal = "block"
  select = "underline"

Map jk or jj to exit insert mode

• Add this to your config.toml:

  [keys.insert]
  j = { k = "normal_mode" }

Map unicode characters like ö to keybinding

• The TOML standard requires that these characters are quoted:

  [keys.normal]
  ö = "extend_line_up" # This line is invalid TOML
  "ö" = "extend_line_up" # This line is valid TOML

Use my terminal’s 16 color palette as a theme

• You can use color names like red, light-blue, etc to refer to the terminal’s colors in a theme file; refer the theme color palette documentation.

Perform find-and-replace

• Type % to select the entire file, then s to bring up a select: prompt. Enter your search, and press enter. All matches in the file will be selected; you can now use c to change them all simultaneously.

To make search fully case sensitive add the following to config.toml:

[editor.search]
smart-case = false

Strip whitespace or format the buffer

If the LSP for the language is active and supports autoformat, and the auto-format option is on (check your and the repo’s languages.toml), then this will happen on save. If there is an alternative command you can run in the terminal to format, you can pipe the whole buffer to it manually with %|<formatter><enter>.

Access the Helix config directory

You can use :config-open to open the config in Helix.

Platform	Location
Mac OS/Linux	~/.config/helix
Windows	C:\Users\____\AppData\Roaming\helix

Access the log file

Enable logging via the -v flag, with each use (up to -vvv) increasing the verbosity.

You can use :log-open to open the log in Helix.

Platform	Location
Mac OS/Linux	~/.cache/helix/helix.log
Windows	C:\Users\____\AppData\Local\helix\helix.log

Add a language

Check https://docs.helix-editor.com/guides/adding_languages.html

Change grammars at project level

You can specify custom grammars per-project/per-directory by placing the languages.toml in .helix/languages.toml at the root of your project. See https://docs.helix-editor.com/languages.html

Close the LSP documentation popup

Ctrl-c closes popups like LSP signature-help, hover, and auto-completion.

General Questions

How to write plugins / Is there a plugin system in place yet ?

• Current status as of December 2022:

There’s two prototypes we’re exploring that could potentially exist side by side: a typed list/ML-like implementation for scripting and a Rust based interface for things that require performance. Could potentially run both in wasm but I’m personally a bit unhappy with how big wasm implementations are, easily several orders of magnitude compared to the editor

Originally posted in https://github.com/helix-editor/helix/discussions/3806#discussioncomment-4438007

• Past discussions:

  • Initial discussion

  • Pre-RFC discussion

  • Plugin system MVP

When will the next release be?

We shoot to cut a release around every two to three months. We use CalVer versioning, so if the current release is v22.08, it was released in August of 2022.

Is a Vi/Vim keymap planned?

We are not interested in supporting alternative paradigms. The core of Helix’s editing is based on Selection → Action, and it would require extensive changes to create a true Vi/Vim keymap. However, there is a third-party keymap: https://github.com/LGUG2Z/helix-vim

Can the j/k bindings be changed to ignore soft wrapping when using a count like 3j

j and k are intentionally mapped to visual vertical movement. This is a more intuitive default that makes working with heavily soft-wrapped text (like this Markdown document) much easier. Textual vertical movement is bound to gk and gj. So you can use 3gj and 3gk instead of 3j and 3k to jump to a relative line number.

These commands are intentionally separate (with no special casing for count != 0) as they represent the fundamental vertical movement primitives. All other vertical movement behavior can be created by combining these commands using conditions. For example:

(if (!= count 0) (move_line_up count) (move_vertical_line_up 0))

If these fundamental primitives had such special handling built in, that would limit what could be implemented. Furthermore, helix is slightly opinionated towards unsurprising and consistent behavior.

How do I build or run code from within Helix?

This is not currently supported. You should build and run code in a separate terminal pane or split.

Installation

Error when building tree-sitter language grammars in Fedora

Ensure that you have a C compiler installed:

sudo dnf group install "C Development Tools and Libraries"

Common Issues

Alt-* key combinations do not work on MacOS iTerm2

Ensure that you have mapped the Option key to ESC+ in the iTerm2 preferences via Preferences > Profiles > Keys

Previous issues: https://github.com/helix-editor/helix/issues/773, https://github.com/helix-editor/helix/issues/1223, https://github.com/helix-editor/helix/issues/1915.