diff options
Diffstat (limited to 'print.html')
| -rw-r--r-- | print.html | 599 |
1 files changed, 357 insertions, 242 deletions
@@ -204,6 +204,7 @@ For everything else (e.g., how to install supported language servers), see the < <li><a href="install.html#macos">macOS</a> <ul> <li><a href="install.html#homebrew-core">Homebrew Core</a></li> +<li><a href="install.html#macports">MacPorts</a></li> </ul> </li> <li><a href="install.html#windows">Windows</a> @@ -258,14 +259,19 @@ sudo apt update sudo apt install helix </code></pre> <h3 id="fedorarhel"><a class="header" href="#fedorarhel">Fedora/RHEL</a></h3> -<p>Enable the <code>COPR</code> repository for Helix:</p> -<pre><code class="language-sh">sudo dnf copr enable varlad/helix -sudo dnf install helix +<pre><code class="language-sh">sudo dnf install helix </code></pre> <h3 id="arch-linux-extra"><a class="header" href="#arch-linux-extra">Arch Linux extra</a></h3> <p>Releases are available in the <code>extra</code> repository:</p> <pre><code class="language-sh">sudo pacman -S helix </code></pre> +<blockquote> +<p>๐ก When installed from the <code>extra</code> repository, run Helix with <code>helix</code> instead of <code>hx</code>.</p> +<p>For example:</p> +<pre><code class="language-sh">helix --health +</code></pre> +<p>to check health</p> +</blockquote> <p>Additionally, a <a href="https://aur.archlinux.org/packages/helix-git/">helix-git</a> package is available in the AUR, which builds the master branch.</p> <h3 id="nixos"><a class="header" href="#nixos">NixOS</a></h3> @@ -299,6 +305,9 @@ Download the official Helix AppImage from the <a href="https://github.com/helix- <h3 id="homebrew-core"><a class="header" href="#homebrew-core">Homebrew Core</a></h3> <pre><code class="language-sh">brew install helix </code></pre> +<h3 id="macports"><a class="header" href="#macports">MacPorts</a></h3> +<pre><code class="language-sh">port install helix +</code></pre> <h2 id="windows"><a class="header" href="#windows">Windows</a></h2> <p>Install on Windows using <a href="https://learn.microsoft.com/en-us/windows/package-manager/winget/">Winget</a>, <a href="https://scoop.sh/">Scoop</a>, <a href="https://chocolatey.org/">Chocolatey</a> or <a href="https://msys2.org/">MSYS2</a>.</p> @@ -328,7 +337,7 @@ Linux and macOS, or <code>%userprofile%\src\</code> on Windows.</p> <li>A C++14 compatible compiler to build the tree-sitter grammars, for example GCC or Clang</li> </ul> <p>If you are using the <code>musl-libc</code> standard library instead of <code>glibc</code> the following environment variable must be set during the build to ensure tree-sitter grammars can be loaded correctly:</p> -<pre><code class="language-sh">RUSTFLAGS="-C target-feature=-crt-static" +<pre><code class="language-sh">RUSTFLAGS="-C target-feature=-crt-static" </code></pre> <ol> <li> @@ -346,6 +355,9 @@ grammars in the local <code>runtime</code> folder.</p> </li> </ol> <blockquote> +<p>๐ก If you do not want to fetch or build grammars, set an environment variable <code>HELIX_DISABLE_AUTO_GRAMMAR_BUILD</code></p> +</blockquote> +<blockquote> <p>๐ก Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch grammars with <code>hx --grammar fetch</code> and compile them with <code>hx --grammar build</code>. This will install them in @@ -354,10 +366,10 @@ the <code>runtime</code> directory within the user's helix config directory (mor </blockquote> <h3 id="configuring-helixs-runtime-files"><a class="header" href="#configuring-helixs-runtime-files">Configuring Helix's runtime files</a></h3> <h4 id="linux-and-macos"><a class="header" href="#linux-and-macos">Linux and macOS</a></h4> -<p>The <strong>runtime</strong> directory is one below the Helix source, so either set a +<p>The <strong>runtime</strong> directory is one below the Helix source, so either export a <code>HELIX_RUNTIME</code> environment variable to point to that directory and add it to your <code>~/.bashrc</code> or equivalent:</p> -<pre><code class="language-sh">HELIX_RUNTIME=~/src/helix/runtime +<pre><code class="language-sh">export HELIX_RUNTIME=~/src/helix/runtime </code></pre> <p>Or, create a symbolic link:</p> <pre><code class="language-sh">ln -Ts $PWD/runtime ~/.config/helix/runtime @@ -367,7 +379,7 @@ your <code>~/.bashrc</code> or equivalent:</p> <p>Either set the <code>HELIX_RUNTIME</code> environment variable to point to the runtime files using the Windows setting (search for <code>Edit environment variables for your account</code>) or use the <code>setx</code> command in Cmd:</p> -<pre><code class="language-sh">setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" +<pre><code class="language-sh">setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime" </code></pre> <blockquote> <p>๐ก <code>%userprofile%</code> resolves to your user directory like @@ -375,8 +387,8 @@ Cmd:</p> </blockquote> <p>Or, create a symlink in <code>%appdata%\helix\</code> that links to the source code directory:</p> <div class="table-wrapper"><table><thead><tr><th>Method</th><th>Command</th></tr></thead><tbody> -<tr><td>PowerShell</td><td><code>New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"</code></td></tr> -<tr><td>Cmd</td><td><code>cd %appdata%\helix</code> <br/> <code>mklink /D runtime "%userprofile%\src\helix\runtime"</code></td></tr> +<tr><td>PowerShell</td><td><code>New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"</code></td></tr> +<tr><td>Cmd</td><td><code>cd %appdata%\helix</code> <br/> <code>mklink /D runtime "%userprofile%\src\helix\runtime"</code></td></tr> </tbody></table> </div> <blockquote> @@ -430,8 +442,8 @@ cp contrib/helix.png ~/.icons # or ~/.local/share/icons </code></pre> <p>To use another terminal than the system default, you can modify the <code>.desktop</code> file. For example, to use <code>kitty</code>:</p> -<pre><code class="language-sh">sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop -sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop +<pre><code class="language-sh">sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop +sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop </code></pre> <div style="break-before: page; page-break-before: always;"></div><h1 id="using-helix"><a class="header" href="#using-helix">Using Helix</a></h1> <!--toc:start--> @@ -458,19 +470,19 @@ can be accessed via the command <code>hx --tutor</code> or <code>:tutor</code>.< <h2 id="registers"><a class="header" href="#registers">Registers</a></h2> <p>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 <code>"</code> being +to the clipboard in other text editors. Usage is similar to Vim, with <code>"</code> being used to select a register.</p> <h3 id="user-defined-registers"><a class="header" href="#user-defined-registers">User-defined registers</a></h3> <p>Helix allows you to create your own named registers for storing text, for example:</p> <ul> -<li><code>"ay</code> - Yank the current selection to register <code>a</code>.</li> -<li><code>"op</code> - Paste the text in register <code>o</code> after the selection.</li> +<li><code>"ay</code> - Yank the current selection to register <code>a</code>.</li> +<li><code>"op</code> - Paste the text in register <code>o</code> after the selection.</li> </ul> <p>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:</p> <ul> -<li><code>"hc</code> - Store the selection in register <code>h</code> and then change it (delete and enter insert mode).</li> -<li><code>"md</code> - Store the selection in register <code>m</code> and delete it.</li> +<li><code>"hc</code> - Store the selection in register <code>h</code> and then change it (delete and enter insert mode).</li> +<li><code>"md</code> - Store the selection in register <code>m</code> and delete it.</li> </ul> <h3 id="default-registers"><a class="header" href="#default-registers">Default registers</a></h3> <p>Commands that use registers, like yank (<code>y</code>), use a default register if none is specified. @@ -478,7 +490,7 @@ These registers are used as defaults:</p> <div class="table-wrapper"><table><thead><tr><th>Register character</th><th>Contains</th></tr></thead><tbody> <tr><td><code>/</code></td><td>Last search</td></tr> <tr><td><code>:</code></td><td>Last executed command</td></tr> -<tr><td><code>"</code></td><td>Last yanked text</td></tr> +<tr><td><code>"</code></td><td>Last yanked text</td></tr> <tr><td><code>@</code></td><td>Last recorded macro</td></tr> </tbody></table> </div> @@ -489,8 +501,8 @@ These registers are used as defaults:</p> <tr><td><code>#</code></td><td>Selection indices (first selection is <code>1</code>, second is <code>2</code>, etc.)</td><td>This register is not writable</td></tr> <tr><td><code>.</code></td><td>Contents of the current selections</td><td>This register is not writable</td></tr> <tr><td><code>%</code></td><td>Name of the current file</td><td>This register is not writable</td></tr> -<tr><td><code>*</code></td><td>Reads from the system clipboard</td><td>Joins and yanks to the system clipboard</td></tr> -<tr><td><code>+</code></td><td>Reads from the primary clipboard</td><td>Joins and yanks to the primary clipboard</td></tr> +<tr><td><code>+</code></td><td>Reads from the system clipboard</td><td>Joins and yanks to the system clipboard</td></tr> +<tr><td><code>*</code></td><td>Reads from the primary clipboard</td><td>Joins and yanks to the primary clipboard</td></tr> </tbody></table> </div> <p>When yanking multiple selections to the clipboard registers, the selections @@ -560,7 +572,7 @@ documentation.</p> and requires the corresponding query file to work properly.</p> </blockquote> <h2 id="moving-the-selection-with-syntax-aware-motions"><a class="header" href="#moving-the-selection-with-syntax-aware-motions">Moving the selection with syntax-aware motions</a></h2> -<p><code>Alt-p</code>, <code>Alt-o</code>, <code>Alt-i</code>, and <code>Alt-n</code> (or <code>Alt</code> and arrow keys) allow you to move the +<p><code>Alt-p</code>, <code>Alt-o</code>, <code>Alt-i</code>, and <code>Alt-n</code> (or <code>Alt</code> 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:</p> <pre><code class="language-js">func(arg1, arg2, arg3); @@ -582,12 +594,12 @@ a more intuitive tree format:</p> โ โ โโโโโโโผโโโโโ โโโโโโผโโโโโ โidentifierโ โargumentsโ -โ "func" โ โโโโโโดโโโโฌโโโโโโดโโโโ +โ "func" โ โโโโโโดโโโโฌโโโโโโดโโโโ โโโโโโโโโโโโ โ โ โ โ โ โ โโโโโโโโโโโผโ โโโโโโผโโโโโโ โโผโโโโโโโโโโ โidentifierโ โidentifierโ โidentifierโ - โ "arg1" โ โ "arg2" โ โ "arg3" โ + โ "arg1" โ โ "arg2" โ โ "arg3" โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ </code></pre> <p>If you have a selection that wraps <code>arg1</code> (see the tree above), and you use @@ -606,7 +618,7 @@ node with no sibling. When using <code>Alt-p</code> with a selection on <code>ar child node will be selected. In the event that <code>arg1</code> does not have a previous sibling, the selection will move up the syntax tree and select the previous element. As a result, using <code>Alt-p</code> with a selection on <code>arg1</code> will move the -selection to the "func" <code>identifier</code>.</p> +selection to the "func" <code>identifier</code>.</p> <div style="break-before: page; page-break-before: always;"></div><h1 id="keymap"><a class="header" href="#keymap">Keymap</a></h1> <ul> <li><a href="keymap.html#normal-mode">Normal mode</a> @@ -627,6 +639,7 @@ selection to the "func" <code>identifier</code>.</p> <li><a href="keymap.html#window-mode">Window mode</a></li> <li><a href="keymap.html#space-mode">Space mode</a> <ul> +<li><a href="keymap.html#comment-mode">Comment mode</a></li> <li><a href="keymap.html#popup">Popup</a></li> </ul> </li> @@ -647,7 +660,7 @@ selection to the "func" <code>identifier</code>.</p> <p>๐ก Mappings marked (<strong>TS</strong>) require a tree-sitter grammar for the file type.</p> </blockquote> <h2 id="normal-mode"><a class="header" href="#normal-mode">Normal mode</a></h2> -<p>Normal mode is the default mode when you launch helix. Return to it from other modes by typing <code>Escape</code>.</p> +<p>Normal mode is the default mode when you launch helix. You can return to it from other modes by pressing the <code>Escape</code> key.</p> <h3 id="movement"><a class="header" href="#movement">Movement</a></h3> <blockquote> <p>NOTE: Unlike Vim, <code>f</code>, <code>F</code>, <code>t</code> and <code>T</code> are not confined to the current line.</p> @@ -668,13 +681,13 @@ selection to the "func" <code>identifier</code>.</p> <tr><td><code>T</code></td><td>Find 'till previous char</td><td><code>till_prev_char</code></td></tr> <tr><td><code>F</code></td><td>Find previous char</td><td><code>find_prev_char</code></td></tr> <tr><td><code>G</code></td><td>Go to line number <code><n></code></td><td><code>goto_line</code></td></tr> -<tr><td><code>Alt-.</code></td><td>Repeat last motion (<code>f</code>, <code>t</code> or <code>m</code>)</td><td><code>repeat_last_motion</code></td></tr> +<tr><td><code>Alt-.</code></td><td>Repeat last motion (<code>f</code>, <code>t</code>, <code>m</code>, <code>[</code> or <code>]</code>)</td><td><code>repeat_last_motion</code></td></tr> <tr><td><code>Home</code></td><td>Move to the start of the line</td><td><code>goto_line_start</code></td></tr> <tr><td><code>End</code></td><td>Move to the end of the line</td><td><code>goto_line_end</code></td></tr> <tr><td><code>Ctrl-b</code>, <code>PageUp</code></td><td>Move page up</td><td><code>page_up</code></td></tr> <tr><td><code>Ctrl-f</code>, <code>PageDown</code></td><td>Move page down</td><td><code>page_down</code></td></tr> -<tr><td><code>Ctrl-u</code></td><td>Move half page up</td><td><code>half_page_up</code></td></tr> -<tr><td><code>Ctrl-d</code></td><td>Move half page down</td><td><code>half_page_down</code></td></tr> +<tr><td><code>Ctrl-u</code></td><td>Move cursor and page half page up</td><td><code>page_cursor_half_up</code></td></tr> +<tr><td><code>Ctrl-d</code></td><td>Move cursor and page half page down</td><td><code>page_cursor_half_down</code></td></tr> <tr><td><code>Ctrl-i</code></td><td>Jump forward on the jumplist</td><td><code>jump_forward</code></td></tr> <tr><td><code>Ctrl-o</code></td><td>Jump backward on the jumplist</td><td><code>jump_backward</code></td></tr> <tr><td><code>Ctrl-s</code></td><td>Save the current selection to the jumplist</td><td><code>save_selection</code></td></tr> @@ -702,7 +715,7 @@ selection to the "func" <code>identifier</code>.</p> <tr><td><code>y</code></td><td>Yank selection</td><td><code>yank</code></td></tr> <tr><td><code>p</code></td><td>Paste after selection</td><td><code>paste_after</code></td></tr> <tr><td><code>P</code></td><td>Paste before selection</td><td><code>paste_before</code></td></tr> -<tr><td><code>"</code> <code><reg></code></td><td>Select a register to yank to or paste from</td><td><code>select_register</code></td></tr> +<tr><td><code>"</code> <code><reg></code></td><td>Select a register to yank to or paste from</td><td><code>select_register</code></td></tr> <tr><td><code>></code></td><td>Indent selection</td><td><code>indent</code></td></tr> <tr><td><code><</code></td><td>Unindent selection</td><td><code>unindent</code></td></tr> <tr><td><code>=</code></td><td>Format selection (currently nonfunctional/disabled) (<strong>LSP</strong>)</td><td><code>format_selections</code></td></tr> @@ -761,7 +774,7 @@ selection to the "func" <code>identifier</code>.</p> </tbody></table> </div> <h3 id="search"><a class="header" href="#search">Search</a></h3> -<p>Search commands all operate on the <code>/</code> register by default. To use a different register, use <code>"<char></code>.</p> +<p>Search commands all operate on the <code>/</code> register by default. To use a different register, use <code>"<char></code>.</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody> <tr><td><code>/</code></td><td>Search for regex pattern</td><td><code>search</code></td></tr> <tr><td><code>?</code></td><td>Search for previous pattern</td><td><code>rsearch</code></td></tr> @@ -788,7 +801,7 @@ selection to the "func" <code>identifier</code>.</p> <h4 id="view-mode"><a class="header" href="#view-mode">View mode</a></h4> <p>Accessed by typing <code>z</code> in <a href="keymap.html#normal-mode">normal mode</a>.</p> <p>View mode is intended for scrolling and manipulating the view without changing -the selection. The "sticky" variant of this mode (accessed by typing <code>Z</code> in +the selection. The "sticky" variant of this mode (accessed by typing <code>Z</code> in normal mode) is persistent and can be exited using the escape key. This is useful when you're simply looking over text and not actively editing it.</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody> @@ -800,8 +813,8 @@ useful when you're simply looking over text and not actively editing it.</p> <tr><td><code>k</code>, <code>up</code></td><td>Scroll the view upwards</td><td><code>scroll_up</code></td></tr> <tr><td><code>Ctrl-f</code>, <code>PageDown</code></td><td>Move page down</td><td><code>page_down</code></td></tr> <tr><td><code>Ctrl-b</code>, <code>PageUp</code></td><td>Move page up</td><td><code>page_up</code></td></tr> -<tr><td><code>Ctrl-d</code></td><td>Move half page down</td><td><code>half_page_down</code></td></tr> -<tr><td><code>Ctrl-u</code></td><td>Move half page up</td><td><code>half_page_up</code></td></tr> +<tr><td><code>Ctrl-u</code></td><td>Move cursor and page half page up</td><td><code>page_cursor_half_up</code></td></tr> +<tr><td><code>Ctrl-d</code></td><td>Move cursor and page half page down</td><td><code>page_cursor_half_down</code></td></tr> </tbody></table> </div> <h4 id="goto-mode"><a class="header" href="#goto-mode">Goto mode</a></h4> @@ -810,7 +823,7 @@ useful when you're simply looking over text and not actively editing it.</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody> <tr><td><code>g</code></td><td>Go to line number <code><n></code> else start of file</td><td><code>goto_file_start</code></td></tr> <tr><td><code>e</code></td><td>Go to the end of the file</td><td><code>goto_last_line</code></td></tr> -<tr><td><code>f</code></td><td>Go to files in the selection</td><td><code>goto_file</code></td></tr> +<tr><td><code>f</code></td><td>Go to files in the selections</td><td><code>goto_file</code></td></tr> <tr><td><code>h</code></td><td>Go to the start of the line</td><td><code>goto_line_start</code></td></tr> <tr><td><code>l</code></td><td>Go to the end of the line</td><td><code>goto_line_end</code></td></tr> <tr><td><code>s</code></td><td>Go to first non-whitespace character of the line</td><td><code>goto_first_nonwhitespace</code></td></tr> @@ -828,6 +841,7 @@ useful when you're simply looking over text and not actively editing it.</p> <tr><td><code>.</code></td><td>Go to last modification in current file</td><td><code>goto_last_modification</code></td></tr> <tr><td><code>j</code></td><td>Move down textual (instead of visual) line</td><td><code>move_line_down</code></td></tr> <tr><td><code>k</code></td><td>Move up textual (instead of visual) line</td><td><code>move_line_up</code></td></tr> +<tr><td><code>w</code></td><td>Show labels at each word and select the word that belongs to the entered labels</td><td><code>goto_word</code></td></tr> </tbody></table> </div> <h4 id="match-mode"><a class="header" href="#match-mode">Match mode</a></h4> @@ -851,8 +865,8 @@ useful when you're simply looking over text and not actively editing it.</p> <tr><td><code>w</code>, <code>Ctrl-w</code></td><td>Switch to next window</td><td><code>rotate_view</code></td></tr> <tr><td><code>v</code>, <code>Ctrl-v</code></td><td>Vertical right split</td><td><code>vsplit</code></td></tr> <tr><td><code>s</code>, <code>Ctrl-s</code></td><td>Horizontal bottom split</td><td><code>hsplit</code></td></tr> -<tr><td><code>f</code></td><td>Go to files in the selection in horizontal splits</td><td><code>goto_file</code></td></tr> -<tr><td><code>F</code></td><td>Go to files in the selection in vertical splits</td><td><code>goto_file</code></td></tr> +<tr><td><code>f</code></td><td>Go to files in the selections in horizontal splits</td><td><code>goto_file</code></td></tr> +<tr><td><code>F</code></td><td>Go to files in the selections in vertical splits</td><td><code>goto_file</code></td></tr> <tr><td><code>h</code>, <code>Ctrl-h</code>, <code>Left</code></td><td>Move to left split</td><td><code>jump_view_left</code></td></tr> <tr><td><code>j</code>, <code>Ctrl-j</code>, <code>Down</code></td><td>Move to split below</td><td><code>jump_view_down</code></td></tr> <tr><td><code>k</code>, <code>Ctrl-k</code>, <code>Up</code></td><td>Move to split above</td><td><code>jump_view_up</code></td></tr> @@ -884,6 +898,9 @@ useful when you're simply looking over text and not actively editing it.</p> <tr><td><code>h</code></td><td>Select symbol references (<strong>LSP</strong>)</td><td><code>select_references_to_symbol_under_cursor</code></td></tr> <tr><td><code>'</code></td><td>Open last fuzzy picker</td><td><code>last_picker</code></td></tr> <tr><td><code>w</code></td><td>Enter <a href="keymap.html#window-mode">window mode</a></td><td>N/A</td></tr> +<tr><td><code>c</code></td><td>Comment/uncomment selections</td><td><code>toggle_comments</code></td></tr> +<tr><td><code>C</code></td><td>Block comment/uncomment selections</td><td><code>toggle_block_comments</code></td></tr> +<tr><td><code>Alt-c</code></td><td>Line comment/uncomment selections</td><td><code>toggle_line_comments</code></td></tr> <tr><td><code>p</code></td><td>Paste system clipboard after selections</td><td><code>paste_clipboard_after</code></td></tr> <tr><td><code>P</code></td><td>Paste system clipboard before selections</td><td><code>paste_clipboard_before</code></td></tr> <tr><td><code>y</code></td><td>Yank selections to clipboard</td><td><code>yank_to_clipboard</code></td></tr> @@ -971,14 +988,14 @@ with modal editors.</p> <p>As you become more comfortable with modal editing, you may want to disable some insert mode bindings. You can do this by editing your <code>config.toml</code> file.</p> <pre><code class="language-toml">[keys.insert] -up = "no_op" -down = "no_op" -left = "no_op" -right = "no_op" -pageup = "no_op" -pagedown = "no_op" -home = "no_op" -end = "no_op" +up = "no_op" +down = "no_op" +left = "no_op" +right = "no_op" +pageup = "no_op" +pagedown = "no_op" +home = "no_op" +end = "no_op" </code></pre> <h2 id="select--extend-mode"><a class="header" href="#select--extend-mode">Select / extend mode</a></h2> <p>Accessed by typing <code>v</code> in <a href="keymap.html#normal-mode">normal mode</a>.</p> @@ -1055,7 +1072,7 @@ you to selectively add search terms to your selections.</p> <tr><td><code>:write-buffer-close!</code>, <code>:wbc!</code></td><td>Force write changes to disk creating necessary subdirectories and closes the buffer. Accepts an optional path (:write-buffer-close! some/path.txt)</td></tr> <tr><td><code>:new</code>, <code>:n</code></td><td>Create a new scratch buffer.</td></tr> <tr><td><code>:format</code>, <code>:fmt</code></td><td>Format the file using the LSP formatter.</td></tr> -<tr><td><code>:indent-style</code></td><td>Set the indentation style for editing. ('t' for tabs or 1-8 for number of spaces.)</td></tr> +<tr><td><code>:indent-style</code></td><td>Set the indentation style for editing. ('t' for tabs or 1-16 for number of spaces.)</td></tr> <tr><td><code>:line-ending</code></td><td>Set the document's default line ending. Options: crlf, lf.</td></tr> <tr><td><code>:earlier</code>, <code>:ear</code></td><td>Jump back to an earlier point in edit history. Accepts a number of steps or a time span.</td></tr> <tr><td><code>:later</code>, <code>:lat</code></td><td>Jump to a later point in edit history. Accepts a number of steps or a time span.</td></tr> @@ -1123,6 +1140,8 @@ you to selectively add search terms to your selections.</p> <tr><td><code>:reset-diff-change</code>, <code>:diffget</code>, <code>:diffg</code></td><td>Reset the diff change at the cursor position.</td></tr> <tr><td><code>:clear-register</code></td><td>Clear given register. If no argument is provided, clear all registers.</td></tr> <tr><td><code>:redraw</code></td><td>Clear and re-render the whole UI</td></tr> +<tr><td><code>:move</code></td><td>Move the current buffer and its corresponding file to a different path</td></tr> +<tr><td><code>:yank-diagnostic</code></td><td>Yank diagnostic(s) under primary cursor to register, or clipboard by default</td></tr> </tbody></table> </div><div style="break-before: page; page-break-before: always;"></div><h1 id="language-support"><a class="header" href="#language-support">Language Support</a></h1> <p>The following languages and Language Servers are supported. To use @@ -1132,6 +1151,8 @@ appropriate Language Server.</p> <p>Also see the <a href="./languages.html">Language Configuration</a> docs and the <a href="./guides/adding_languages.html">Adding Languages</a> guide for more language configuration information.</p> <div class="table-wrapper"><table><thead><tr><th>Language</th><th>Syntax Highlighting</th><th>Treesitter Textobjects</th><th>Auto Indent</th><th>Rainbow Brackets</th><th>Default LSP</th></tr></thead><tbody> +<tr><td>ada</td><td>โ</td><td>โ</td><td></td><td></td><td><code>ada_language_server</code>, <code>ada_language_server</code></td></tr> +<tr><td>agda</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>astro</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>awk</td><td>โ</td><td>โ</td><td></td><td></td><td><code>awk-language-server</code></td></tr> <tr><td>bash</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>bash-language-server</code></td></tr> @@ -1139,26 +1160,30 @@ Languages</a> guide for more language configuration information.</p> <tr><td>beancount</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>bibtex</td><td>โ</td><td></td><td></td><td></td><td><code>texlab</code></td></tr> <tr><td>bicep</td><td>โ</td><td></td><td></td><td></td><td><code>bicep-langserver</code></td></tr> +<tr><td>blade</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>blueprint</td><td>โ</td><td></td><td></td><td></td><td><code>blueprint-compiler</code></td></tr> <tr><td>c</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>clangd</code></td></tr> <tr><td>c-sharp</td><td>โ</td><td>โ</td><td></td><td></td><td><code>OmniSharp</code></td></tr> -<tr><td>cabal</td><td></td><td></td><td></td><td></td><td></td></tr> +<tr><td>cabal</td><td></td><td></td><td></td><td></td><td><code>haskell-language-server-wrapper</code></td></tr> <tr><td>cairo</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>cairo-language-server</code></td></tr> <tr><td>capnp</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> +<tr><td>cel</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>clojure</td><td>โ</td><td></td><td></td><td>โ</td><td><code>clojure-lsp</code></td></tr> <tr><td>cmake</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>cmake-language-server</code></td></tr> <tr><td>comment</td><td>โ</td><td></td><td></td><td></td><td></td></tr> -<tr><td>common-lisp</td><td>โ</td><td></td><td></td><td>โ</td><td><code>cl-lsp</code></td></tr> +<tr><td>common-lisp</td><td>โ</td><td></td><td>โ</td><td>โ</td><td><code>cl-lsp</code></td></tr> <tr><td>cpon</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> <tr><td>cpp</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>clangd</code></td></tr> <tr><td>crystal</td><td>โ</td><td>โ</td><td></td><td></td><td><code>crystalline</code></td></tr> -<tr><td>css</td><td>โ</td><td></td><td></td><td>โ</td><td><code>vscode-css-language-server</code></td></tr> +<tr><td>css</td><td>โ</td><td></td><td>โ</td><td>โ</td><td><code>vscode-css-language-server</code></td></tr> <tr><td>cue</td><td>โ</td><td></td><td></td><td></td><td><code>cuelsp</code></td></tr> <tr><td>d</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>serve-d</code></td></tr> -<tr><td>dart</td><td>โ</td><td></td><td>โ</td><td></td><td><code>dart</code></td></tr> +<tr><td>dart</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>dart</code></td></tr> +<tr><td>dbml</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>devicetree</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>dhall</td><td>โ</td><td>โ</td><td></td><td></td><td><code>dhall-lsp-server</code></td></tr> <tr><td>diff</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>docker-compose</td><td>โ</td><td></td><td>โ</td><td></td><td><code>docker-compose-langserver</code>, <code>yaml-language-server</code></td></tr> <tr><td>dockerfile</td><td>โ</td><td></td><td></td><td></td><td><code>docker-langserver</code></td></tr> <tr><td>dot</td><td>โ</td><td></td><td></td><td></td><td><code>dot-language-server</code></td></tr> <tr><td>dtd</td><td>โ</td><td></td><td></td><td></td><td></td></tr> @@ -1172,6 +1197,7 @@ Languages</a> guide for more language configuration information.</p> <tr><td>erb</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>erlang</td><td>โ</td><td>โ</td><td></td><td>โ</td><td><code>erlang_ls</code></td></tr> <tr><td>esdl</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>fidl</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>fish</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> <tr><td>forth</td><td>โ</td><td></td><td></td><td></td><td><code>forth-lsp</code></td></tr> <tr><td>fortran</td><td>โ</td><td></td><td>โ</td><td></td><td><code>fortls</code></td></tr> @@ -1184,47 +1210,60 @@ Languages</a> guide for more language configuration information.</p> <tr><td>git-config</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>git-ignore</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>git-rebase</td><td>โ</td><td></td><td></td><td></td><td></td></tr> -<tr><td>gleam</td><td>โ</td><td>โ</td><td></td><td></td><td><code>gleam</code></td></tr> +<tr><td>gleam</td><td>โ</td><td>โ</td><td></td><td>โ</td><td><code>gleam</code></td></tr> +<tr><td>glimmer</td><td>โ</td><td></td><td></td><td></td><td><code>ember-language-server</code></td></tr> <tr><td>glsl</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> -<tr><td>go</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>gopls</code></td></tr> +<tr><td>gn</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>go</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>gopls</code>, <code>golangci-lint-langserver</code></td></tr> <tr><td>godot-resource</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>gomod</td><td>โ</td><td></td><td></td><td></td><td><code>gopls</code></td></tr> <tr><td>gotmpl</td><td>โ</td><td></td><td></td><td></td><td><code>gopls</code></td></tr> <tr><td>gowork</td><td>โ</td><td></td><td></td><td></td><td><code>gopls</code></td></tr> <tr><td>graphql</td><td>โ</td><td></td><td></td><td></td><td><code>graphql-lsp</code></td></tr> +<tr><td>groovy</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>hare</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>haskell</td><td>โ</td><td>โ</td><td></td><td></td><td><code>haskell-language-server-wrapper</code></td></tr> <tr><td>haskell-persistent</td><td>โ</td><td></td><td></td><td></td><td></td></tr> -<tr><td>hcl</td><td>โ</td><td></td><td>โ</td><td></td><td><code>terraform-ls</code></td></tr> +<tr><td>hcl</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>terraform-ls</code></td></tr> <tr><td>heex</td><td>โ</td><td>โ</td><td></td><td></td><td><code>elixir-ls</code></td></tr> +<tr><td>helm</td><td>โ</td><td></td><td></td><td></td><td><code>helm_ls</code></td></tr> +<tr><td>hocon</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> +<tr><td>hoon</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>hosts</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>html</td><td>โ</td><td></td><td></td><td>โ</td><td><code>vscode-html-language-server</code></td></tr> <tr><td>hurl</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> +<tr><td>hyprlang</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> <tr><td>idris</td><td></td><td></td><td></td><td></td><td><code>idris2-lsp</code></td></tr> <tr><td>iex</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>ini</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>janet</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>java</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>jdtls</code></td></tr> <tr><td>javascript</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>typescript-language-server</code></td></tr> <tr><td>jinja</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>jsdoc</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>json</td><td>โ</td><td></td><td>โ</td><td>โ</td><td><code>vscode-json-language-server</code></td></tr> <tr><td>json5</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>jsonc</td><td>โ</td><td></td><td>โ</td><td></td><td><code>vscode-json-language-server</code></td></tr> <tr><td>jsonnet</td><td>โ</td><td></td><td></td><td></td><td><code>jsonnet-language-server</code></td></tr> <tr><td>jsx</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>typescript-language-server</code></td></tr> <tr><td>julia</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>julia</code></td></tr> <tr><td>just</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> -<tr><td>kdl</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>kdl</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> +<tr><td>koka</td><td>โ</td><td></td><td>โ</td><td></td><td><code>koka</code></td></tr> <tr><td>kotlin</td><td>โ</td><td></td><td></td><td></td><td><code>kotlin-language-server</code></td></tr> <tr><td>latex</td><td>โ</td><td>โ</td><td></td><td></td><td><code>texlab</code></td></tr> +<tr><td>ld</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> <tr><td>lean</td><td>โ</td><td></td><td></td><td></td><td><code>lean</code></td></tr> <tr><td>ledger</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>llvm</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> <tr><td>llvm-mir</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> <tr><td>llvm-mir-yaml</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> +<tr><td>log</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>lpf</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>lua</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>lua-language-server</code></td></tr> -<tr><td>make</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>make</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> <tr><td>markdoc</td><td>โ</td><td></td><td></td><td></td><td><code>markdoc-ls</code></td></tr> -<tr><td>markdown</td><td>โ</td><td></td><td></td><td></td><td><code>marksman</code></td></tr> +<tr><td>markdown</td><td>โ</td><td></td><td></td><td></td><td><code>marksman</code>, <code>markdown-oxide</code></td></tr> <tr><td>markdown.inline</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>matlab</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> <tr><td>mermaid</td><td>โ</td><td></td><td></td><td></td><td></td></tr> @@ -1234,12 +1273,13 @@ Languages</a> guide for more language configuration information.</p> <tr><td>nasm</td><td>โ</td><td>โ</td><td></td><td></td><td></td></tr> <tr><td>nickel</td><td>โ</td><td></td><td>โ</td><td></td><td><code>nls</code></td></tr> <tr><td>nim</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>nimlangserver</code></td></tr> -<tr><td>nix</td><td>โ</td><td></td><td></td><td>โ</td><td><code>nil</code></td></tr> -<tr><td>nu</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>nix</td><td>โ</td><td>โ</td><td></td><td>โ</td><td><code>nil</code></td></tr> +<tr><td>nu</td><td>โ</td><td></td><td></td><td></td><td><code>nu</code></td></tr> <tr><td>nunjucks</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>ocaml</td><td>โ</td><td></td><td>โ</td><td></td><td><code>ocamllsp</code></td></tr> <tr><td>ocaml-interface</td><td>โ</td><td></td><td></td><td></td><td><code>ocamllsp</code></td></tr> <tr><td>odin</td><td>โ</td><td></td><td>โ</td><td></td><td><code>ols</code></td></tr> +<tr><td>ohm</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> <tr><td>opencl</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>clangd</code></td></tr> <tr><td>openscad</td><td>โ</td><td></td><td></td><td></td><td><code>openscad-lsp</code></td></tr> <tr><td>org</td><td>โ</td><td></td><td></td><td></td><td></td></tr> @@ -1248,18 +1288,22 @@ Languages</a> guide for more language configuration information.</p> <tr><td>pem</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>perl</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>perlnavigator</code></td></tr> <tr><td>php</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>intelephense</code></td></tr> +<tr><td>php-only</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>pkgbuild</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>pkgbuild-language-server</code>, <code>bash-language-server</code></td></tr> +<tr><td>pkl</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> <tr><td>po</td><td>โ</td><td>โ</td><td></td><td></td><td></td></tr> <tr><td>pod</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>ponylang</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> +<tr><td>powershell</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>prisma</td><td>โ</td><td></td><td></td><td></td><td><code>prisma-language-server</code></td></tr> <tr><td>prolog</td><td></td><td></td><td></td><td></td><td><code>swipl</code></td></tr> -<tr><td>protobuf</td><td>โ</td><td></td><td>โ</td><td></td><td><code>bufls</code>, <code>pb</code></td></tr> +<tr><td>protobuf</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>bufls</code>, <code>pb</code></td></tr> <tr><td>prql</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>purescript</td><td>โ</td><td>โ</td><td></td><td></td><td><code>purescript-language-server</code></td></tr> <tr><td>python</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>pylsp</code></td></tr> <tr><td>qml</td><td>โ</td><td></td><td>โ</td><td></td><td><code>qmlls</code></td></tr> <tr><td>r</td><td>โ</td><td></td><td></td><td></td><td><code>R</code></td></tr> -<tr><td>racket</td><td>โ</td><td></td><td></td><td>โ</td><td><code>racket</code></td></tr> +<tr><td>racket</td><td>โ</td><td></td><td>โ</td><td>โ</td><td><code>racket</code></td></tr> <tr><td>regex</td><td>โ</td><td></td><td></td><td>โ</td><td></td></tr> <tr><td>rego</td><td>โ</td><td></td><td></td><td></td><td><code>regols</code></td></tr> <tr><td>rescript</td><td>โ</td><td>โ</td><td></td><td></td><td><code>rescript-language-server</code></td></tr> @@ -1270,22 +1314,26 @@ Languages</a> guide for more language configuration information.</p> <tr><td>ruby</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>solargraph</code></td></tr> <tr><td>rust</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>rust-analyzer</code></td></tr> <tr><td>sage</td><td>โ</td><td>โ</td><td></td><td></td><td></td></tr> -<tr><td>scala</td><td>โ</td><td></td><td>โ</td><td></td><td><code>metals</code></td></tr> -<tr><td>scheme</td><td>โ</td><td></td><td></td><td>โ</td><td></td></tr> +<tr><td>scala</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>metals</code></td></tr> +<tr><td>scheme</td><td>โ</td><td></td><td>โ</td><td>โ</td><td></td></tr> <tr><td>scss</td><td>โ</td><td></td><td></td><td>โ</td><td><code>vscode-css-language-server</code></td></tr> -<tr><td>slint</td><td>โ</td><td></td><td>โ</td><td></td><td><code>slint-lsp</code></td></tr> +<tr><td>slint</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>slint-lsp</code></td></tr> +<tr><td>smali</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> <tr><td>smithy</td><td>โ</td><td></td><td></td><td></td><td><code>cs</code></td></tr> <tr><td>sml</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>solidity</td><td>โ</td><td></td><td></td><td></td><td><code>solc</code></td></tr> +<tr><td>spicedb</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>sql</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>sshclientconfig</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>starlark</td><td>โ</td><td>โ</td><td></td><td>โ</td><td></td></tr> <tr><td>strace</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>supercollider</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>svelte</td><td>โ</td><td></td><td>โ</td><td></td><td><code>svelteserver</code></td></tr> <tr><td>sway</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>forc</code></td></tr> <tr><td>swift</td><td>โ</td><td></td><td></td><td></td><td><code>sourcekit-lsp</code></td></tr> <tr><td>t32</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>tablegen</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> +<tr><td>tact</td><td>โ</td><td>โ</td><td>โ</td><td></td><td></td></tr> <tr><td>task</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>templ</td><td>โ</td><td></td><td></td><td></td><td><code>templ</code></td></tr> <tr><td>tfvars</td><td>โ</td><td></td><td>โ</td><td></td><td><code>terraform-ls</code></td></tr> @@ -1295,11 +1343,12 @@ Languages</a> guide for more language configuration information.</p> <tr><td>tsx</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>typescript-language-server</code></td></tr> <tr><td>twig</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>typescript</td><td>โ</td><td>โ</td><td>โ</td><td>โ</td><td><code>typescript-language-server</code></td></tr> +<tr><td>typst</td><td>โ</td><td></td><td></td><td></td><td><code>typst-lsp</code></td></tr> <tr><td>ungrammar</td><td>โ</td><td></td><td></td><td></td><td></td></tr> -<tr><td>unison</td><td>โ</td><td></td><td></td><td></td><td></td></tr> +<tr><td>unison</td><td>โ</td><td></td><td>โ</td><td></td><td></td></tr> <tr><td>uxntal</td><td>โ</td><td></td><td></td><td></td><td></td></tr> <tr><td>v</td><td>โ</td><td>โ</td><td>โ</td><td></td><td><code>v-analyzer</code></td></tr> -<tr><td>vala</td><td>โ</td><td></td><td></td><td></td><td><code>vala-language-server</code></td></tr> +<tr><td>vala</td><td>โ</td><td>โ</td><td></td><td></td><td><code>vala-language-server</code></td></tr> <tr><td>verilog</td><td>โ</td><td>โ</td><td></td><td></td><td><code>svlangserver</code></td></tr> <tr><td>vhdl</td><td>โ</td><td></td><td></td><td></td><td><code>vhdl_ls</code></td></tr> <tr><td>vhs</td><td>โ</td><td></td><td></td><td></td><td></td></tr> @@ -1337,16 +1386,16 @@ single width selection.</p> <p>๐ก You can easily open the config file by typing <code>:config-open</code> within Helix normal mode.</p> </blockquote> <p>Example config:</p> -<pre><code class="language-toml">theme = "onedark" +<pre><code class="language-toml">theme = "onedark" [editor] -line-number = "relative" +line-number = "relative" mouse = false [editor.cursor-shape] -insert = "bar" -normal = "block" -select = "underline" +insert = "bar" +normal = "block" +select = "underline" [editor.file-picker] hidden = false @@ -1364,15 +1413,16 @@ Its settings will be merged with the configuration directory <code>config.toml</ <tr><td><code>mouse</code></td><td>Enable mouse mode</td><td><code>true</code></td></tr> <tr><td><code>middle-click-paste</code></td><td>Middle click paste support</td><td><code>true</code></td></tr> <tr><td><code>scroll-lines</code></td><td>Number of lines to scroll per scroll wheel step</td><td><code>3</code></td></tr> -<tr><td><code>shell</code></td><td>Shell to use when running external commands</td><td>Unix: <code>["sh", "-c"]</code><br/>Windows: <code>["cmd", "/C"]</code></td></tr> +<tr><td><code>shell</code></td><td>Shell to use when running external commands</td><td>Unix: <code>["sh", "-c"]</code><br/>Windows: <code>["cmd", "/C"]</code></td></tr> <tr><td><code>line-number</code></td><td>Line number display: <code>absolute</code> simply shows each line's number, while <code>relative</code> shows the distance from the current line. When unfocused or in insert mode, <code>relative</code> will still show absolute line numbers</td><td><code>absolute</code></td></tr> <tr><td><code>cursorline</code></td><td>Highlight all lines with a cursor</td><td><code>false</code></td></tr> <tr><td><code>cursorcolumn</code></td><td>Highlight all columns with a cursor</td><td><code>false</code></td></tr> -<tr><td><code>gutters</code></td><td>Gutters to display: Available are <code>diagnostics</code> and <code>diff</code> and <code>line-numbers</code> and <code>spacer</code>, note that <code>diagnostics</code> also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty</td><td><code>["diagnostics", "spacer", "line-numbers", "spacer", "diff"]</code></td></tr> +<tr><td><code>gutters</code></td><td>Gutters to display: Available are <code>diagnostics</code> and <code>diff</code> and <code>line-numbers</code> and <code>spacer</code>, note that <code>diagnostics</code> also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty</td><td><code>["diagnostics", "spacer", "line-numbers", "spacer", "diff"]</code></td></tr> <tr><td><code>auto-completion</code></td><td>Enable automatic pop up of auto-completion</td><td><code>true</code></td></tr> <tr><td><code>auto-format</code></td><td>Enable automatic formatting on save</td><td><code>true</code></td></tr> <tr><td><code>auto-save</code></td><td>Enable automatic saving on the focus moving away from Helix. Requires <a href="https://github.com/helix-editor/helix/wiki/Terminal-Support">focus event support</a> from your terminal</td><td><code>false</code></td></tr> -<tr><td><code>idle-timeout</code></td><td>Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant</td><td><code>400</code></td></tr> +<tr><td><code>idle-timeout</code></td><td>Time in milliseconds since last keypress before idle timers trigger.</td><td><code>250</code></td></tr> +<tr><td><code>completion-timeout</code></td><td>Time in milliseconds after typing a word character before completions are shown, set to 5 for instant.</td><td><code>250</code></td></tr> <tr><td><code>preview-completion-insert</code></td><td>Whether to apply completion item instantly when selected</td><td><code>true</code></td></tr> <tr><td><code>completion-trigger-len</code></td><td>The min-length of word under cursor to trigger autocompletion</td><td><code>2</code></td></tr> <tr><td><code>completion-replace</code></td><td>Set to <code>true</code> to make completions always replace the entire word and not just the part before the cursor</td><td><code>false</code></td></tr> @@ -1381,38 +1431,41 @@ Its settings will be merged with the configuration directory <code>config.toml</ <tr><td><code>undercurl</code></td><td>Set to <code>true</code> to override automatic detection of terminal undercurl support in the event of a false negative</td><td><code>false</code></td></tr> <tr><td><code>rulers</code></td><td>List of column positions at which to display the rulers. Can be overridden by language specific <code>rulers</code> in <code>languages.toml</code> file</td><td><code>[]</code></td></tr> <tr><td><code>bufferline</code></td><td>Renders a line at the top of the editor displaying open buffers. Can be <code>always</code>, <code>never</code> or <code>multiple</code> (only shown if more than one buffer is in use)</td><td><code>never</code></td></tr> -<tr><td><code>initial-mode</code></td><td>The initial mode for newly opened editors.</td><td><code>"normal"</code></td></tr> <tr><td><code>color-modes</code></td><td>Whether to color the mode indicator with different colors depending on the mode itself</td><td><code>false</code></td></tr> <tr><td><code>text-width</code></td><td>Maximum line length. Used for the <code>:reflow</code> command and soft-wrapping if <code>soft-wrap.wrap-at-text-width</code> is set</td><td><code>80</code></td></tr> <tr><td><code>workspace-lsp-roots</code></td><td>Directories relative to the workspace root that are treated as LSP roots. Should only be set in <code>.helix/config.toml</code></td><td><code>[]</code></td></tr> <tr><td><code>default-line-ending</code></td><td>The line ending to use for new documents. Can be <code>native</code>, <code>lf</code>, <code>crlf</code>, <code>ff</code>, <code>cr</code> or <code>nel</code>. <code>native</code> uses the platform's native line ending (<code>crlf</code> on Windows, otherwise <code>lf</code>).</td><td><code>native</code></td></tr> <tr><td><code>insert-final-newline</code></td><td>Whether to automatically insert a trailing line-ending on write if missing</td><td><code>true</code></td></tr> +<tr><td><code>popup-border</code></td><td>Draw border around <code>popup</code>, <code>menu</code>, <code>all</code>, or <code>none</code></td><td><code>none</code></td></tr> +<tr><td><code>indent-heuristic</code></td><td>How the indentation for a newly inserted line is computed: <code>simple</code> just copies the indentation level from the previous line, <code>tree-sitter</code> computes the indentation based on the syntax tree and <code>hybrid</code> combines both approaches. If the chosen heuristic is not available, a different one will be used as a fallback (the fallback order being <code>hybrid</code> -> <code>tree-sitter</code> -> <code>simple</code>).</td><td><code>hybrid</code></td></tr> +<tr><td><code>jump-label-alphabet</code></td><td>The characters that are used to generate two character jump labels. Characters at the start of the alphabet are used first.</td><td><code>"abcdefghijklmnopqrstuvwxyz"</code></td></tr> +<tr><td><code>initial-mode</code></td><td>The initial mode for newly opened editors.</td><td><code>"normal"</code></td></tr> <tr><td><code>rainbow-brackets</code></td><td>Whether to render rainbow colors for matching brackets. Requires tree-sitter <code>rainbows.scm</code> queries for the language.</td><td><code>false</code></td></tr> </tbody></table> </div> <h3 id="editorstatusline-section"><a class="header" href="#editorstatusline-section"><code>[editor.statusline]</code> Section</a></h3> <p>Allows configuring the statusline at the bottom of the editor.</p> <p>The configuration distinguishes between three areas of the status line:</p> -<p><code>[ ... ... LEFT ... ... | ... ... ... ... CENTER ... ... ... ... | ... ... RIGHT ... ... ]</code></p> +<p><code>[ ... ... LEFT ... ... | ... ... ... CENTER ... ... ... | ... ... RIGHT ... ... ]</code></p> <p>Statusline elements can be defined as follows:</p> <pre><code class="language-toml">[editor.statusline] -left = ["mode", "spinner"] -center = ["file-name"] -right = ["diagnostics", "selections", "position", "file-encoding", "file-line-ending", "file-type"] -separator = "โ" -mode.normal = "NORMAL" -mode.insert = "INSERT" -mode.select = "SELECT" +left = ["mode", "spinner"] +center = ["file-name"] +right = ["diagnostics", "selections", "position", "file-encoding", "file-line-ending", "file-type"] +separator = "โ" +mode.normal = "NORMAL" +mode.insert = "INSERT" +mode.select = "SELECT" </code></pre> <p>The <code>[editor.statusline]</code> key takes the following sub-keys:</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Default</th></tr></thead><tbody> -<tr><td><code>left</code></td><td>A list of elements aligned to the left of the statusline</td><td><code>["mode", "spinner", "file-name", "read-only-indicator", "file-modification-indicator"]</code></td></tr> +<tr><td><code>left</code></td><td>A list of elements aligned to the left of the statusline</td><td><code>["mode", "spinner", "file-name", "read-only-indicator", "file-modification-indicator"]</code></td></tr> <tr><td><code>center</code></td><td>A list of elements aligned to the middle of the statusline</td><td><code>[]</code></td></tr> -<tr><td><code>right</code></td><td>A list of elements aligned to the right of the statusline</td><td><code>["diagnostics", "selections", "register", "position", "file-encoding"]</code></td></tr> -<tr><td><code>separator</code></td><td>The character used to separate elements in the statusline</td><td><code>"โ"</code></td></tr> -<tr><td><code>mode.normal</code></td><td>The text shown in the <code>mode</code> element for normal mode</td><td><code>"NOR"</code></td></tr> -<tr><td><code>mode.insert</code></td><td>The text shown in the <code>mode</code> element for insert mode</td><td><code>"INS"</code></td></tr> -<tr><td><code>mode.select</code></td><td>The text shown in the <code>mode</code> element for select mode</td><td><code>"SEL"</code></td></tr> +<tr><td><code>right</code></td><td>A list of elements aligned to the right of the statusline</td><td><code>["diagnostics", "selections", "register", "position", "file-encoding"]</code></td></tr> +<tr><td><code>separator</code></td><td>The character used to separate elements in the statusline</td><td><code>"โ"</code></td></tr> +<tr><td><code>mode.normal</code></td><td>The text shown in the <code>mode</code> element for normal mode</td><td><code>"NOR"</code></td></tr> +<tr><td><code>mode.insert</code></td><td>The text shown in the <code>mode</code> element for insert mode</td><td><code>"INS"</code></td></tr> +<tr><td><code>mode.select</code></td><td>The text shown in the <code>mode</code> element for select mode</td><td><code>"SEL"</code></td></tr> </tbody></table> </div> <p>The following statusline elements can be configured:</p> @@ -1420,6 +1473,7 @@ mode.select = "SELECT" <tr><td><code>mode</code></td><td>The current editor mode (<code>mode.normal</code>/<code>mode.insert</code>/<code>mode.select</code>)</td></tr> <tr><td><code>spinner</code></td><td>A progress spinner indicating LSP activity</td></tr> <tr><td><code>file-name</code></td><td>The path/name of the opened file</td></tr> +<tr><td><code>file-absolute-path</code></td><td>The absolute path/name of the opened file</td></tr> <tr><td><code>file-base-name</code></td><td>The basename of the opened file</td></tr> <tr><td><code>file-modification-indicator</code></td><td>The indicator to show whether the file is modified (a <code>[+]</code> appears when there are unsaved changes)</td></tr> <tr><td><code>file-encoding</code></td><td>The encoding of the opened file if it differs from UTF-8</td></tr> @@ -1433,7 +1487,7 @@ mode.select = "SELECT" <tr><td><code>primary-selection-length</code></td><td>The number of characters currently in primary selection</td></tr> <tr><td><code>position</code></td><td>The cursor position</td></tr> <tr><td><code>position-percentage</code></td><td>The cursor position as a percentage of the total number of lines</td></tr> -<tr><td><code>separator</code></td><td>The string defined in <code>editor.statusline.separator</code> (defaults to <code>"โ"</code>)</td></tr> +<tr><td><code>separator</code></td><td>The string defined in <code>editor.statusline.separator</code> (defaults to <code>"โ"</code>)</td></tr> <tr><td><code>spacer</code></td><td>Inserts a space between elements (multiple/contiguous spacers may be specified)</td></tr> <tr><td><code>version-control</code></td><td>The current branch name or detached commit hash of the opened workspace</td></tr> <tr><td><code>register</code></td><td>The current selected register</td></tr> @@ -1474,17 +1528,29 @@ change shape.</p> not visible in the Helix file picker and global search.</p> <p>All git related options are only enabled in a git repository.</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Default</th></tr></thead><tbody> -<tr><td><code>hidden</code></td><td>Enables ignoring hidden files</td><td>true</td></tr> -<tr><td><code>follow-symlinks</code></td><td>Follow symlinks instead of ignoring them</td><td>true</td></tr> -<tr><td><code>deduplicate-links</code></td><td>Ignore symlinks that point at files already shown in the picker</td><td>true</td></tr> -<tr><td><code>parents</code></td><td>Enables reading ignore files from parent directories</td><td>true</td></tr> -<tr><td><code>ignore</code></td><td>Enables reading <code>.ignore</code> files</td><td>true</td></tr> -<tr><td><code>git-ignore</code></td><td>Enables reading <code>.gitignore</code> files</td><td>true</td></tr> -<tr><td><code>git-global</code></td><td>Enables reading global <code>.gitignore</code>, whose path is specified in git's config: <code>core.excludefile</code> option</td><td>true</td></tr> -<tr><td><code>git-exclude</code></td><td>Enables reading <code>.git/info/exclude</code> files</td><td>true</td></tr> -<tr><td><code>max-depth</code></td><td>Set with an integer value for maximum depth to recurse</td><td>Defaults to <code>None</code>.</td></tr> +<tr><td><code>hidden</code></td><td>Enables ignoring hidden files</td><td><code>true</code></td></tr> +<tr><td><code>follow-symlinks</code></td><td>Follow symlinks instead of ignoring them</td><td><code>true</code></td></tr> +<tr><td><code>deduplicate-links</code></td><td>Ignore symlinks that point at files already shown in the picker</td><td><code>true</code></td></tr> +<tr><td><code>parents</code></td><td>Enables reading ignore files from parent directories</td><td><code>true</code></td></tr> +<tr><td><code>ignore</code></td><td>Enables reading <code>.ignore</code> files</td><td><code>true</code></td></tr> +<tr><td><code>git-ignore</code></td><td>Enables reading <code>.gitignore</code> files</td><td><code>true</code></td></tr> +<tr><td><code>git-global</code></td><td>Enables reading global <code>.gitignore</code>, whose path is specified in git's config: <code>core.excludesfile</code> option</td><td><code>true</code></td></tr> +<tr><td><code>git-exclude</code></td><td>Enables reading <code>.git/info/exclude</code> files</td><td><code>true</code></td></tr> +<tr><td><code>max-depth</code></td><td>Set with an integer value for maximum depth to recurse</td><td>Unset by default</td></tr> </tbody></table> </div> +<p>Ignore files can be placed locally as <code>.ignore</code> or put in your home directory as <code>~/.ignore</code>. They support the usual ignore and negative ignore (unignore) rules used in <code>.gitignore</code> files.</p> +<p>Additionally, you can use Helix-specific ignore files by creating a local <code>.helix/ignore</code> file in the current workspace or a global <code>ignore</code> file located in your Helix config directory:</p> +<ul> +<li>Linux and Mac: <code>~/.config/helix/ignore</code></li> +<li>Windows: <code>%AppData%\helix\ignore</code></li> +</ul> +<p>Example:</p> +<pre><code class="language-ini"># unignore in file picker and global search +!.github/ +!.gitignore +!.gitattributes +</code></pre> <h3 id="editorauto-pairs-section"><a class="header" href="#editorauto-pairs-section"><code>[editor.auto-pairs]</code> Section</a></h3> <p>Enables automatic insertion of pairs to parentheses, brackets, etc. Can be a simple boolean value, or a specific mapping of pairs of single characters.</p> @@ -1492,28 +1558,28 @@ simple boolean value, or a specific mapping of pairs of single characters.</p> <pre><code class="language-toml">[editor] auto-pairs = false # defaults to `true` </code></pre> -<p>The default pairs are <code>(){}[]''""``</code>, but these can be customized by +<p>The default pairs are <code>(){}[]''""``</code>, but these can be customized by setting <code>auto-pairs</code> to a TOML table:</p> <pre><code class="language-toml">[editor.auto-pairs] '(' = ')' '{' = '}' '[' = ']' -'"' = '"' +'"' = '"' '`' = '`' '<' = '>' </code></pre> <p>Additionally, this setting can be used in a language config. Unless the editor setting is <code>false</code>, this will override the editor config in documents with this language.</p> -<p>Example <code>languages.toml</code> that adds <> and removes ''</p> +<p>Example <code>languages.toml</code> that adds <code><></code> and removes <code>''</code></p> <pre><code class="language-toml">[[language]] -name = "rust" +name = "rust" [language.auto-pairs] '(' = ')' '{' = '}' '[' = ']' -'"' = '"' +'"' = '"' '`' = '`' '<' = '>' </code></pre> @@ -1527,25 +1593,28 @@ name = "rust" <h3 id="editorwhitespace-section"><a class="header" href="#editorwhitespace-section"><code>[editor.whitespace]</code> Section</a></h3> <p>Options for rendering whitespace with visible characters. Use <code>:set whitespace.render all</code> to temporarily enable visible whitespace.</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Default</th></tr></thead><tbody> -<tr><td><code>render</code></td><td>Whether to render whitespace. May either be <code>"all"</code> or <code>"none"</code>, or a table with sub-keys <code>space</code>, <code>nbsp</code>, <code>tab</code>, and <code>newline</code></td><td><code>"none"</code></td></tr> -<tr><td><code>characters</code></td><td>Literal characters to use when rendering whitespace. Sub-keys may be any of <code>tab</code>, <code>space</code>, <code>nbsp</code>, <code>newline</code> or <code>tabpad</code></td><td>See example below</td></tr> +<tr><td><code>render</code></td><td>Whether to render whitespace. May either be <code>all</code> or <code>none</code>, or a table with sub-keys <code>space</code>, <code>nbsp</code>, <code>nnbsp</code>, <code>tab</code>, and <code>newline</code></td><td><code>none</code></td></tr> +<tr><td><code>characters</code></td><td>Literal characters to use when rendering whitespace. Sub-keys may be any of <code>tab</code>, <code>space</code>, <code>nbsp</code>, <code>nnbsp</code>, <code>newline</code> or <code>tabpad</code></td><td>See example below</td></tr> </tbody></table> </div> <p>Example</p> <pre><code class="language-toml">[editor.whitespace] -render = "all" +render = "all" # or control each character [editor.whitespace.render] -space = "all" -tab = "all" -newline = "none" +space = "all" +tab = "all" +nbsp = "none" +nnbsp = "none" +newline = "none" [editor.whitespace.characters] -space = "ยท" -nbsp = "โฝ" -tab = "โ" -newline = "โ" -tabpad = "ยท" # Tabs will look like "โยทยทยท" (depending on tab width) +space = "ยท" +nbsp = "โฝ" +nnbsp = "โฃ" +tab = "โ" +newline = "โ" +tabpad = "ยท" # Tabs will look like "โยทยทยท" (depending on tab width) </code></pre> <h3 id="editorindent-guides-section"><a class="header" href="#editorindent-guides-section"><code>[editor.indent-guides]</code> Section</a></h3> <p>Options for rendering vertical indent guides.</p> @@ -1559,26 +1628,26 @@ tabpad = "ยท" # Tabs will look like "โยทยทยท" (depending o <p>Example:</p> <pre><code class="language-toml">[editor.indent-guides] render = true -character = "โ" # Some characters that work well: "โ", "โ", "โ", "โธฝ" +character = "โ" # Some characters that work well: "โ", "โ", "โ", "โธฝ" skip-levels = 1 -rainbow-option = "normal" +rainbow-option = "normal" </code></pre> <h3 id="editorgutters-section"><a class="header" href="#editorgutters-section"><code>[editor.gutters]</code> Section</a></h3> <p>For simplicity, <code>editor.gutters</code> accepts an array of gutter types, which will use default settings for all gutter components.</p> <pre><code class="language-toml">[editor] -gutters = ["diff", "diagnostics", "line-numbers", "spacer"] +gutters = ["diff", "diagnostics", "line-numbers", "spacer"] </code></pre> <p>To customize the behavior of gutters, the <code>[editor.gutters]</code> section must be used. This section contains top level settings, as well as settings for specific gutter components as subsections.</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Default</th></tr></thead><tbody> -<tr><td><code>layout</code></td><td>A vector of gutters to display</td><td><code>["diagnostics", "spacer", "line-numbers", "spacer", "diff"]</code></td></tr> +<tr><td><code>layout</code></td><td>A vector of gutters to display</td><td><code>["diagnostics", "spacer", "line-numbers", "spacer", "diff"]</code></td></tr> </tbody></table> </div> <p>Example:</p> <pre><code class="language-toml">[editor.gutters] -layout = ["diff", "diagnostics", "line-numbers", "spacer"] +layout = ["diff", "diagnostics", "line-numbers", "spacer"] </code></pre> <h4 id="editorguttersline-numbers-section"><a class="header" href="#editorguttersline-numbers-section"><code>[editor.gutters.line-numbers]</code> Section</a></h4> <p>Options for the line number gutter</p> @@ -1593,7 +1662,10 @@ min-width = 1 <h4 id="editorguttersdiagnostics-section"><a class="header" href="#editorguttersdiagnostics-section"><code>[editor.gutters.diagnostics]</code> Section</a></h4> <p>Currently unused</p> <h4 id="editorguttersdiff-section"><a class="header" href="#editorguttersdiff-section"><code>[editor.gutters.diff]</code> Section</a></h4> -<p>Currently unused</p> +<p>The <code>diff</code> gutter option displays colored bars indicating whether a <code>git</code> diff represents that a line was added, removed or changed. +These colors are controlled by the theme attributes <code>diff.plus</code>, <code>diff.minus</code> and <code>diff.delta</code>.</p> +<p>Other diff providers will eventually be supported by a future plugin system.</p> +<p>There are currently no options for this section.</p> <h4 id="editorguttersspacer-section"><a class="header" href="#editorguttersspacer-section"><code>[editor.gutters.spacer]</code> Section</a></h4> <p>Currently unused</p> <h3 id="editorsoft-wrap-section"><a class="header" href="#editorsoft-wrap-section"><code>[editor.soft-wrap]</code> Section</a></h3> @@ -1611,7 +1683,26 @@ min-width = 1 enable = true max-wrap = 25 # increase value to reduce forced mid-word wrapping max-indent-retain = 0 -wrap-indicator = "" # set wrap-indicator to "" to hide it +wrap-indicator = "" # set wrap-indicator to "" to hide it +</code></pre> +<h3 id="editorsmart-tab-section"><a class="header" href="#editorsmart-tab-section"><code>[editor.smart-tab]</code> Section</a></h3> +<p>Options for navigating and editing using tab key.</p> +<div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Default</th></tr></thead><tbody> +<tr><td><code>enable</code></td><td>If set to true, then when the cursor is in a position with non-whitespace to its left, instead of inserting a tab, it will run <code>move_parent_node_end</code>. If there is only whitespace to the left, then it inserts a tab as normal. With the default bindings, to explicitly insert a tab character, press Shift-tab.</td><td><code>true</code></td></tr> +<tr><td><code>supersede-menu</code></td><td>Normally, when a menu is on screen, such as when auto complete is triggered, the tab key is bound to cycling through the items. This means when menus are on screen, one cannot use the tab key to trigger the <code>smart-tab</code> command. If this option is set to true, the <code>smart-tab</code> command always takes precedence, which means one cannot use the tab key to cycle through menu items. One of the other bindings must be used instead, such as arrow keys or <code>C-n</code>/<code>C-p</code>.</td><td><code>false</code></td></tr> +</tbody></table> +</div> +<p>Due to lack of support for S-tab in some terminals, the default keybindings don't fully embrace smart-tab editing experience. If you enjoy smart-tab navigation and a terminal that supports the <a href="https://github.com/helix-editor/helix/wiki/Terminal-Support#enhanced-keyboard-protocol">Enhanced Keyboard protocol</a>, consider setting extra keybindings:</p> +<pre><code>[keys.normal] +tab = "move_parent_node_end" +S-tab = "move_parent_node_start" + +[keys.insert] +S-tab = "move_parent_node_start" + +[keys.select] +tab = "extend_parent_node_end" +S-tab = "extend_parent_node_start" </code></pre> <h3 id="editorexplorer-section"><a class="header" href="#editorexplorer-section"><code>[editor.explorer]</code> Section</a></h3> <p>Sets explorer side width and style.</p> @@ -1620,38 +1711,32 @@ wrap-indicator = "" # set wrap-indicator to "" to hide it <tr><td><code>position</code></td><td>explorer widget position, <code>left</code> or <code>right</code></td><td><code>left</code></td></tr> </tbody></table> </div> -<h3 id="editorsmart-tab-section"><a class="header" href="#editorsmart-tab-section"><code>[editor.smart-tab]</code> Section</a></h3> -<div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th><th>Default</th></tr></thead><tbody> -<tr><td><code>enable</code></td><td>If set to true, then when the cursor is in a position with non-whitespace to its left, instead of inserting a tab, it will run <code>move_parent_node_end</code>. If there is only whitespace to the left, then it inserts a tab as normal. With the default bindings, to explicitly insert a tab character, press Shift-tab.</td><td><code>true</code></td></tr> -<tr><td><code>supersede-menu</code></td><td>Normally, when a menu is on screen, such as when auto complete is triggered, the tab key is bound to cycling through the items. This means when menus are on screen, one cannot use the tab key to trigger the <code>smart-tab</code> command. If this option is set to true, the <code>smart-tab</code> command always takes precedence, which means one cannot use the tab key to cycle through menu items. One of the other bindings must be used instead, such as arrow keys or <code>C-n</code>/<code>C-p</code>.</td><td><code>false</code></td></tr> -</tbody></table> -</div> <h3 id="editordigraphs-section"><a class="header" href="#editordigraphs-section"><code>[editor.digraphs]</code> Section</a></h3> <p>By default, special characters can be input using the <code>insert_digraphs</code> command, bound to <code>\</code> in normal mode. Custom digraphs can be added to the <code>editor.digraphs</code> section of the config.</p> <pre><code class="language-toml">[editor.digraphs] -ka = "ใ" -ku = { symbols = "ใ", description = "The japanese character Ku" } -shrug = "ยฏ\\_(ใ)_/ยฏ" +ka = "ใ" +ku = { symbols = "ใ", description = "The japanese character Ku" } +shrug = "ยฏ\\_(ใ)_/ยฏ" </code></pre> <div style="break-before: page; page-break-before: always;"></div><h1 id="themes"><a class="header" href="#themes">Themes</a></h1> -<p>To use a theme add <code>theme = "<name>"</code> to the top of your <a href="./configuration.html"><code>config.toml</code></a> file, or select it during runtime using <code>:theme <name></code>.</p> +<p>To use a theme add <code>theme = "<name>"</code> to the top of your <a href="./configuration.html"><code>config.toml</code></a> file, or select it during runtime using <code>:theme <name></code>.</p> <h2 id="creating-a-theme"><a class="header" href="#creating-a-theme">Creating a theme</a></h2> <p>Create a file with the name of your theme as the file name (i.e <code>mytheme.toml</code>) and place it in your <code>themes</code> directory (i.e <code>~/.config/helix/themes</code> or <code>%AppData%\helix\themes</code> on Windows). The directory might have to be created beforehand.</p> <blockquote> -<p>๐ก The names "default" and "base16_default" are reserved for built-in themes +<p>๐ก The names "default" and "base16_default" are reserved for built-in themes and cannot be overridden by user-defined themes.</p> </blockquote> <h3 id="overview"><a class="header" href="#overview">Overview</a></h3> <p>Each line in the theme file is specified as below:</p> -<pre><code class="language-toml">key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] } +<pre><code class="language-toml">key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] } </code></pre> <p>Where <code>key</code> represents what you want to style, <code>fg</code> specifies the foreground color, <code>bg</code> the background color, <code>underline</code> the underline <code>style</code>/<code>color</code>, and <code>modifiers</code> is a list of style modifiers. <code>bg</code>, <code>underline</code> and <code>modifiers</code> can be omitted to defer to the defaults.</p> <p>To specify only the foreground color:</p> -<pre><code class="language-toml">key = "#ffffff" +<pre><code class="language-toml">key = "#ffffff" </code></pre> <p>If the key contains a dot <code>'.'</code>, it must be quoted to prevent it being parsed as a <a href="https://toml.io/en/v1.0.0#keys">dotted key</a>.</p> -<pre><code class="language-toml">"key.key" = "#ffffff" +<pre><code class="language-toml">"key.key" = "#ffffff" </code></pre> <p>For inspiration, you can find the default <code>theme.toml</code> <a href="https://github.com/helix-editor/helix/blob/master/theme.toml">here</a> and @@ -1666,12 +1751,12 @@ user-submitted themes <p>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 <code>palette</code> to your theme file:</p> -<pre><code class="language-toml">"ui.background" = "white" -"ui.text" = "black" +<pre><code class="language-toml">"ui.background" = "white" +"ui.text" = "black" [palette] -white = "#ffffff" -black = "#000000" +white = "#ffffff" +black = "#000000" </code></pre> <p>Keep in mind that the <code>[palette]</code> table includes all keys after its header, so it should be defined after the normal theme options.</p> @@ -1715,7 +1800,7 @@ your terminal emulator.</p> </div> <blockquote> <p>๐ก The <code>underlined</code> modifier is deprecated and only available for backwards compatibility. -Its behavior is equivalent to setting <code>underline.style="line"</code>.</p> +Its behavior is equivalent to setting <code>underline.style="line"</code>.</p> </blockquote> <h3 id="underline-style"><a class="header" href="#underline-style">Underline style</a></h3> <p>One of the following values may be used as a value for <code>underline.style</code>, providing it is @@ -1730,19 +1815,19 @@ supported by your terminal emulator.</p> </div> <h3 id="inheritance"><a class="header" href="#inheritance">Inheritance</a></h3> <p>Extend other themes by setting the <code>inherits</code> property to an existing theme.</p> -<pre><code class="language-toml">inherits = "boo_berry" +<pre><code class="language-toml">inherits = "boo_berry" -# Override the theming for "keyword"s: -"keyword" = { fg = "gold" } +# Override the theming for "keyword"s: +"keyword" = { fg = "gold" } # Override colors in the palette: [palette] -berry = "#2A2A4D" +berry = "#2A2A4D" </code></pre> <h3 id="rainbow"><a class="header" href="#rainbow">Rainbow</a></h3> <p>The <code>rainbow</code> key is used for rainbow highlight for matching brackets. The key is a list of styles.</p> -<pre><code class="language-toml">rainbow = ["#ff0000", "#ffa500", "#fff000", { fg = "#00ff00", modifiers = ["bold"] }] +<pre><code class="language-toml">rainbow = ["#ff0000", "#ffa500", "#fff000", { fg = "#00ff00", modifiers = ["bold"] }] </code></pre> <p>Colors from the palette and modifiers may be used.</p> <h3 id="scopes"><a class="header" href="#scopes">Scopes</a></h3> @@ -1761,6 +1846,7 @@ The key is a list of styles.</p> <p><code>type</code> - Types</p> <ul> <li><code>builtin</code> - Primitive types provided by the language (<code>int</code>, <code>usize</code>)</li> +<li><code>parameter</code> - Generic type parameters (<code>T</code>)</li> <li><code>enum</code> <ul> <li><code>variant</code></li> @@ -1999,11 +2085,14 @@ The key is a list of styles.</p> <tr><td><code>ui.statusline.insert</code></td><td>Statusline mode during insert mode (<a href="./configuration.html#editor-section">only if <code>editor.color-modes</code> is enabled</a>)</td></tr> <tr><td><code>ui.statusline.select</code></td><td>Statusline mode during select mode (<a href="./configuration.html#editor-section">only if <code>editor.color-modes</code> is enabled</a>)</td></tr> <tr><td><code>ui.statusline.separator</code></td><td>Separator character in statusline</td></tr> +<tr><td><code>ui.bufferline</code></td><td>Style for the buffer line</td></tr> +<tr><td><code>ui.bufferline.active</code></td><td>Style for the active buffer in buffer line</td></tr> +<tr><td><code>ui.bufferline.background</code></td><td>Style for bufferline background</td></tr> <tr><td><code>ui.popup</code></td><td>Documentation popups (e.g. Space + k)</td></tr> <tr><td><code>ui.popup.info</code></td><td>Prompt for multiple key options</td></tr> <tr><td><code>ui.window</code></td><td>Borderlines separating splits</td></tr> <tr><td><code>ui.help</code></td><td>Description box for commands</td></tr> -<tr><td><code>ui.text</code></td><td>Command prompts, popup text, etc.</td></tr> +<tr><td><code>ui.text</code></td><td>Default text style, command prompts, popup text, etc.</td></tr> <tr><td><code>ui.text.focus</code></td><td>The currently selected line in the picker</td></tr> <tr><td><code>ui.text.inactive</code></td><td>Same as <code>ui.text</code> but when the text is inactive (e.g. suggestions)</td></tr> <tr><td><code>ui.text.info</code></td><td>The key: command text in <code>ui.popup.info</code> boxes</td></tr> @@ -2014,6 +2103,7 @@ The key is a list of styles.</p> <tr><td><code>ui.virtual.inlay-hint.parameter</code></td><td>Style for inlay hints of kind <code>parameter</code> (LSPs are not required to set a kind)</td></tr> <tr><td><code>ui.virtual.inlay-hint.type</code></td><td>Style for inlay hints of kind <code>type</code> (LSPs are not required to set a kind)</td></tr> <tr><td><code>ui.virtual.wrap</code></td><td>Soft-wrap indicator (see the <a href="./configuration.html#editor-section"><code>editor.soft-wrap</code> config</a>)</td></tr> +<tr><td><code>ui.virtual.jump-label</code></td><td>Style for virtual jump labels</td></tr> <tr><td><code>ui.menu</code></td><td>Code and command completion menus</td></tr> <tr><td><code>ui.menu.selected</code></td><td>Selected autocomplete item</td></tr> <tr><td><code>ui.menu.scroll</code></td><td><code>fg</code> sets thumb color, <code>bg</code> sets track color of scrollbar</td></tr> @@ -2033,6 +2123,8 @@ The key is a list of styles.</p> <tr><td><code>diagnostic.info</code></td><td>Diagnostics info (editing area)</td></tr> <tr><td><code>diagnostic.warning</code></td><td>Diagnostics warning (editing area)</td></tr> <tr><td><code>diagnostic.error</code></td><td>Diagnostics error (editing area)</td></tr> +<tr><td><code>diagnostic.unnecessary</code></td><td>Diagnostics with unnecessary tag (editing area)</td></tr> +<tr><td><code>diagnostic.deprecated</code></td><td>Diagnostics with deprecated tag (editing area)</td></tr> </tbody></table> </div><div style="break-before: page; page-break-before: always;"></div><h1 id="key-remapping"><a class="header" href="#key-remapping">Key remapping</a></h1> <p>Helix currently supports one-way key remapping through a simple TOML configuration @@ -2043,59 +2135,59 @@ directory (default <code>~/.config/helix</code> on Linux systems) with a structu this:</p> <pre><code class="language-toml"># At most one section each of 'keys.normal', 'keys.insert' and 'keys.select' [keys.normal] -C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file) -C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file -a = "move_char_left" # Maps the 'a' key to the move_char_left command -w = "move_line_up" # Maps the 'w' key move_line_up -"C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line -g = { a = "code_action" } # Maps `ga` to show possible code actions -"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode +C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file) +C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file +a = "move_char_left" # Maps the 'a' key to the move_char_left command +w = "move_line_up" # Maps the 'w' key move_line_up +"C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line +g = { a = "code_action" } # Maps `ga` to show possible code actions +"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode [keys.insert] -"A-x" = "normal_mode" # Maps Alt-X to enter normal mode -j = { k = "normal_mode" } # Maps `jk` to exit insert mode +"A-x" = "normal_mode" # Maps Alt-X to enter normal mode +j = { k = "normal_mode" } # Maps `jk` to exit insert mode </code></pre> <h2 id="minor-modes-1"><a class="header" href="#minor-modes-1">Minor modes</a></h2> <p>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.</p> <pre><code class="language-toml">[keys.insert.j] -k = "normal_mode" # Maps `jk` to exit insert mode +k = "normal_mode" # Maps `jk` to exit insert mode [keys.normal.g] -a = "code_action" # Maps `ga` to show possible code actions +a = "code_action" # Maps `ga` to show possible code actions # invert `j` and `k` in view mode [keys.normal.z] -j = "scroll_up" -k = "scroll_down" +j = "scroll_up" +k = "scroll_down" # create a new minor mode bound to `+` -[keys.normal."+"] -m = ":run-shell-command make" -c = ":run-shell-command cargo build" -t = ":run-shell-command cargo test" +[keys.normal."+"] +m = ":run-shell-command make" +c = ":run-shell-command cargo build" +t = ":run-shell-command cargo test" </code></pre> <h2 id="special-keys-and-modifiers"><a class="header" href="#special-keys-and-modifiers">Special keys and modifiers</a></h2> <p>Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes <code>C-</code>, <code>S-</code> and <code>A-</code>. Special keys are encoded as follows:</p> <div class="table-wrapper"><table><thead><tr><th>Key name</th><th>Representation</th></tr></thead><tbody> -<tr><td>Backspace</td><td><code>"backspace"</code></td></tr> -<tr><td>Space</td><td><code>"space"</code></td></tr> -<tr><td>Return/Enter</td><td><code>"ret"</code></td></tr> -<tr><td>-</td><td><code>"minus"</code></td></tr> -<tr><td>Left</td><td><code>"left"</code></td></tr> -<tr><td>Right</td><td><code>"right"</code></td></tr> -<tr><td>Up</td><td><code>"up"</code></td></tr> -<tr><td>Down</td><td><code>"down"</code></td></tr> -<tr><td>Home</td><td><code>"home"</code></td></tr> -<tr><td>End</td><td><code>"end"</code></td></tr> -<tr><td>Page Up</td><td><code>"pageup"</code></td></tr> -<tr><td>Page Down</td><td><code>"pagedown"</code></td></tr> -<tr><td>Tab</td><td><code>"tab"</code></td></tr> -<tr><td>Delete</td><td><code>"del"</code></td></tr> -<tr><td>Insert</td><td><code>"ins"</code></td></tr> -<tr><td>Null</td><td><code>"null"</code></td></tr> -<tr><td>Escape</td><td><code>"esc"</code></td></tr> +<tr><td>Backspace</td><td><code>"backspace"</code></td></tr> +<tr><td>Space</td><td><code>"space"</code></td></tr> +<tr><td>Return/Enter</td><td><code>"ret"</code></td></tr> +<tr><td>-</td><td><code>"minus"</code></td></tr> +<tr><td>Left</td><td><code>"left"</code></td></tr> +<tr><td>Right</td><td><code>"right"</code></td></tr> +<tr><td>Up</td><td><code>"up"</code></td></tr> +<tr><td>Down</td><td><code>"down"</code></td></tr> +<tr><td>Home</td><td><code>"home"</code></td></tr> +<tr><td>End</td><td><code>"end"</code></td></tr> +<tr><td>Page Up</td><td><code>"pageup"</code></td></tr> +<tr><td>Page Down</td><td><code>"pagedown"</code></td></tr> +<tr><td>Tab</td><td><code>"tab"</code></td></tr> +<tr><td>Delete</td><td><code>"del"</code></td></tr> +<tr><td>Insert</td><td><code>"ins"</code></td></tr> +<tr><td>Null</td><td><code>"null"</code></td></tr> +<tr><td>Escape</td><td><code>"esc"</code></td></tr> </tbody></table> </div> <p>Keys can be disabled by binding them to the <code>no_op</code> command.</p> @@ -2104,15 +2196,15 @@ t = ":run-shell-command cargo test" # Only these normal mode bindings will be used [keys.normal] -n = "normal_mode" -t = "goto_definition" +n = "normal_mode" +t = "goto_definition" # remember to add bindings to return to normal mode [keys.select] -esc = "normal_mode" +esc = "normal_mode" [keys.insert] -esc = "normal_mode" +esc = "normal_mode" </code></pre> <p>A list of commands is available in the <a href="https://docs.helix-editor.com/keymap.html">Keymap</a> documentation and in the source code at <a href="https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs"><code>helix-term/src/commands.rs</code></a> at the invocation of <code>static_commands!</code> macro and the <code>TypableCommandList</code>.</p> @@ -2134,10 +2226,10 @@ auto-LSP-formatting in Rust:</p> <pre><code class="language-toml"># in <config_dir>/helix/languages.toml [language-server.mylang-lsp] -command = "mylang-lsp" +command = "mylang-lsp" [[language]] -name = "rust" +name = "rust" auto-format = false </code></pre> </li> @@ -2152,14 +2244,14 @@ in the configuration directory and the built-in configuration.</p> <p>Each language is configured by adding a <code>[[language]]</code> section to a <code>languages.toml</code> file. For example:</p> <pre><code class="language-toml">[[language]] -name = "mylang" -scope = "source.mylang" -injection-regex = "mylang" -file-types = ["mylang", "myl"] -comment-token = "#" -indent = { tab-width = 2, unit = " " } -formatter = { command = "mylang-formatter" , args = ["--stdin"] } -language-servers = [ "mylang-lsp" ] +name = "mylang" +scope = "source.mylang" +injection-regex = "mylang" +file-types = ["mylang", "myl"] +comment-tokens = "#" +indent = { tab-width = 2, unit = " " } +formatter = { command = "mylang-formatter" , args = ["--stdin"] } +language-servers = [ "mylang-lsp" ] </code></pre> <p>These configuration keys are available:</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody> @@ -2167,18 +2259,21 @@ language-servers = [ "mylang-lsp" ] <tr><td><code>language-id</code></td><td>The language-id for language servers, checkout the table at <a href="https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentItem">TextDocumentItem</a> for the right id</td></tr> <tr><td><code>scope</code></td><td>A string like <code>source.js</code> that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually <code>source.<name></code> or <code>text.<name></code> in case of markup languages</td></tr> <tr><td><code>injection-regex</code></td><td>regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential <a href="https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection">language injection</a> site.</td></tr> -<tr><td><code>file-types</code></td><td>The filetypes of the language, for example <code>["yml", "yaml"]</code>. See the file-type detection section below.</td></tr> -<tr><td><code>shebangs</code></td><td>The interpreters from the shebang line, for example <code>["sh", "bash"]</code></td></tr> +<tr><td><code>file-types</code></td><td>The filetypes of the language, for example <code>["yml", "yaml"]</code>. See the file-type detection section below.</td></tr> +<tr><td><code>shebangs</code></td><td>The interpreters from the shebang line, for example <code>["sh", "bash"]</code></td></tr> <tr><td><code>roots</code></td><td>A set of marker files to look for when trying to find the workspace root. For example <code>Cargo.lock</code>, <code>yarn.lock</code></td></tr> <tr><td><code>auto-format</code></td><td>Whether to autoformat this language when saving</td></tr> <tr><td><code>diagnostic-severity</code></td><td>Minimal severity of diagnostic for it to be displayed. (Allowed values: <code>Error</code>, <code>Warning</code>, <code>Info</code>, <code>Hint</code>)</td></tr> -<tr><td><code>comment-token</code></td><td>The token to use as a comment-token</td></tr> -<tr><td><code>indent</code></td><td>The indent to use. Has sub keys <code>unit</code> (the text inserted into the document when indenting; usually set to N spaces or <code>"\t"</code> for tabs) and <code>tab-width</code> (the number of spaces rendered for a tab)</td></tr> +<tr><td><code>comment-tokens</code></td><td>The tokens to use as a comment token, either a single token <code>"//"</code> or an array <code>["//", "///", "//!"]</code> (the first token will be used for commenting). Also configurable as <code>comment-token</code> for backwards compatibility</td></tr> +<tr><td><code>block-comment-tokens</code></td><td>The start and end tokens for a multiline comment either an array or single table of <code>{ start = "/*", end = "*/"}</code>. The first set of tokens will be used for commenting, any pairs in the array can be uncommented</td></tr> +<tr><td><code>indent</code></td><td>The indent to use. Has sub keys <code>unit</code> (the text inserted into the document when indenting; usually set to N spaces or <code>"\t"</code> for tabs) and <code>tab-width</code> (the number of spaces rendered for a tab)</td></tr> <tr><td><code>language-servers</code></td><td>The Language Servers used for this language. See below for more information in the section <a href="languages.html#configuring-language-servers-for-a-language">Configuring Language Servers for a language</a></td></tr> <tr><td><code>grammar</code></td><td>The tree-sitter grammar to use (defaults to the value of <code>name</code>)</td></tr> <tr><td><code>formatter</code></td><td>The formatter for the language, it will take precedence over the lsp when defined. The formatter must be able to take the original file as input from stdin and write the formatted file to stdout</td></tr> +<tr><td><code>soft-wrap</code></td><td><a href="./configuration.html#editorsoft-wrap-section">editor.softwrap</a></td></tr> <tr><td><code>text-width</code></td><td>Maximum line length. Used for the <code>:reflow</code> command and soft-wrapping if <code>soft-wrap.wrap-at-text-width</code> is set, defaults to <code>editor.text-width</code></td></tr> <tr><td><code>workspace-lsp-roots</code></td><td>Directories relative to the workspace root that are treated as LSP roots. Should only be set in <code>.helix/config.toml</code>. Overwrites the setting of the same name in <code>config.toml</code> if set.</td></tr> +<tr><td><code>persistent-diagnostic-sources</code></td><td>An array of LSP diagnostic sources assumed unchanged when the language server resends the same set of diagnostics. Helix can track the position for these diagnostics internally instead. Useful for diagnostics that are recomputed on save.</td></tr> <tr><td><code>rulers</code></td><td>Overrides the <code>editor.rulers</code> config key for the language.</td></tr> <tr><td><code>rainbow-brackets</code></td><td>Overrides the <code>editor.rainbow-brackets</code> config key for the language.</td></tr> </tbody></table> @@ -2187,39 +2282,41 @@ language-servers = [ "mylang-lsp" ] <p>Helix determines which language configuration to use based on the <code>file-types</code> key from the above section. <code>file-types</code> is a list of strings or tables, for example:</p> -<pre><code class="language-toml">file-types = ["Makefile", "toml", { suffix = ".git/config" }] +<pre><code class="language-toml">file-types = ["toml", { glob = "Makefile" }, { glob = ".git/config" }, { glob = ".github/workflows/*.yaml" } ] </code></pre> <p>When determining a language configuration to use, Helix searches the file-types with the following priorities:</p> <ol> -<li>Exact match: if the filename of a file is an exact match of a string in a -<code>file-types</code> list, that language wins. In the example above, <code>"Makefile"</code> -will match against <code>Makefile</code> files.</li> -<li>Extension: if there are no exact matches, any <code>file-types</code> string that -matches the file extension of a given file wins. In the example above, the -<code>"toml"</code> matches files like <code>Cargo.toml</code> or <code>languages.toml</code>.</li> -<li>Suffix: if there are still no matches, any values in <code>suffix</code> tables -are checked against the full path of the given file. In the example above, -the <code>{ suffix = ".git/config" }</code> would match against any <code>config</code> files -in <code>.git</code> directories. Note: <code>/</code> is used as the directory separator but is -replaced at runtime with the appropriate path separator for the operating -system, so this rule would match against <code>.git\config</code> files on Windows.</li> +<li>Glob: values in <code>glob</code> tables are checked against the full path of the given +file. Globs are standard Unix-style path globs (e.g. the kind you use in Shell) +and can be used to match paths for a specific prefix, suffix, directory, etc. +In the above example, the <code>{ glob = "Makefile" }</code> config would match files +with the name <code>Makefile</code>, the <code>{ glob = ".git/config" }</code> config would match +<code>config</code> files in <code>.git</code> directories, and the <code>{ glob = ".github/workflows/*.yaml" }</code> +config would match any <code>yaml</code> files in <code>.github/workflow</code> directories. Note +that globs should always use the Unix path separator <code>/</code> even on Windows systems; +the matcher will automatically take the machine-specific separators into account. +If the glob isn't an absolute path or doesn't already start with a glob prefix, +<code>*/</code> will automatically be added to ensure it matches for any subdirectory.</li> +<li>Extension: if there are no glob matches, any <code>file-types</code> string that matches +the file extension of a given file wins. In the example above, the <code>"toml"</code> +config matches files like <code>Cargo.toml</code> or <code>languages.toml</code>.</li> </ol> <h2 id="language-server-configuration"><a class="header" href="#language-server-configuration">Language Server configuration</a></h2> <p>Language servers are configured separately in the table <code>language-server</code> in the same file as the languages <code>languages.toml</code></p> <p>For example:</p> <pre><code class="language-toml">[language-server.mylang-lsp] -command = "mylang-lsp" -args = ["--stdio"] +command = "mylang-lsp" +args = ["--stdio"] config = { provideFormatter = true } -environment = { "ENV1" = "value1", "ENV2" = "value2" } +environment = { "ENV1" = "value1", "ENV2" = "value2" } [language-server.efm-lsp-prettier] -command = "efm-langserver" +command = "efm-langserver" [language-server.efm-lsp-prettier.config] documentFormatting = true -languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] } +languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] } </code></pre> <p>These are the available options for a language server.</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody> @@ -2227,15 +2324,16 @@ languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${ <tr><td><code>args</code></td><td>A list of arguments to pass to the language server binary</td></tr> <tr><td><code>config</code></td><td>LSP initialization options</td></tr> <tr><td><code>timeout</code></td><td>The maximum time a request to the language server may take, in seconds. Defaults to <code>20</code></td></tr> -<tr><td><code>environment</code></td><td>Any environment variables that will be used when starting the language server <code>{ "KEY1" = "Value1", "KEY2" = "Value2" }</code></td></tr> +<tr><td><code>environment</code></td><td>Any environment variables that will be used when starting the language server <code>{ "KEY1" = "Value1", "KEY2" = "Value2" }</code></td></tr> +<tr><td><code>required-root-patterns</code></td><td>A list of <code>glob</code> patterns to look for in the working directory. The language server is started if at least one of them is found.</td></tr> </tbody></table> </div> <p>A <code>format</code> sub-table within <code>config</code> can be used to pass extra formatting options to <a href="https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_formatting">Document Formatting Requests</a>. For example, with typescript:</p> <pre><code class="language-toml">[language-server.typescript-language-server] -# pass format options according to https://github.com/typescript-language-server/typescript-language-server#workspacedidchangeconfiguration omitting the "[language].format." prefix. -config = { format = { "semicolons" = "insert", "insertSpaceBeforeFunctionParenthesis" = true } } +# pass format options according to https://github.com/typescript-language-server/typescript-language-server#workspacedidchangeconfiguration omitting the "[language].format." prefix. +config = { format = { "semicolons" = "insert", "insertSpaceBeforeFunctionParenthesis" = true } } </code></pre> <h3 id="configuring-language-servers-for-a-language"><a class="header" href="#configuring-language-servers-for-a-language">Configuring Language Servers for a language</a></h3> <p>The <code>language-servers</code> attribute in a language tells helix which language servers are used for this language.</p> @@ -2247,13 +2345,13 @@ it's often useful to only enable/disable certain language-server features for th so everything else should be handled by the <code>typescript-language-server</code> (which is configured by default). The language configuration for typescript could look like this:</p> <pre><code class="language-toml">[[language]] -name = "typescript" -language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ] +name = "typescript" +language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ] </code></pre> <p>or equivalent:</p> <pre><code class="language-toml">[[language]] -name = "typescript" -language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ] +name = "typescript" +language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ] </code></pre> <p>Each requested LSP feature is prioritized in the order of the <code>language-servers</code> array. For example, the first <code>goto-definition</code> supported language server (in this case <code>typescript-language-server</code>) will be taken for the relevant LSP request (command <code>goto_definition</code>). @@ -2284,8 +2382,8 @@ If a language server itself doesn't support a feature, the next language server <p>The source for a language's tree-sitter grammar is specified in a <code>[[grammar]]</code> section in <code>languages.toml</code>. For example:</p> <pre><code class="language-toml">[[grammar]] -name = "mylang" -source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" } +name = "mylang" +source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" } </code></pre> <p>Grammar configuration takes these keys:</p> <div class="table-wrapper"><table><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody> @@ -2305,9 +2403,9 @@ git repository:</p> <p>You may use a top-level <code>use-grammars</code> key to control which grammars are fetched and built when using <code>hx --grammar fetch</code> and <code>hx --grammar build</code>.</p> <pre><code class="language-toml"># Note: this key must come **before** the [[language]] and [[grammar]] sections -use-grammars = { only = [ "rust", "c", "cpp" ] } +use-grammars = { only = [ "rust", "c", "cpp" ] } # or -use-grammars = { except = [ "yaml", "json" ] } +use-grammars = { except = [ "yaml", "json" ] } </code></pre> <p>When omitted, all grammars are fetched and built.</p> <div style="break-before: page; page-break-before: always;"></div><h1 id="guides"><a class="header" href="#guides">Guides</a></h1> @@ -2393,7 +2491,7 @@ for example).</p> <tr><td><code>comment.around</code></td></tr> </tbody></table> </div> -<p><a href="https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=">Example query files</a> can be found in the helix GitHub repository.</p> +<p><a href="https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+path%3A%2A%2A/textobjects.scm&type=Code&ref=advsearch&l=&l=">Example query files</a> can be found in the helix GitHub repository.</p> <h2 id="queries-for-textobject-based-navigation"><a class="header" href="#queries-for-textobject-based-navigation">Queries for textobject based navigation</a></h2> <p>Tree-sitter based navigation in Helix is done using captures in the following order:</p> @@ -2416,6 +2514,14 @@ the capture.</p> <p>Note that it matters where these added indents begin. For example, multiple indent level increases that start on the same line only increase the total indent level by 1. See <a href="guides/indent.html#capture-types">Capture types</a>.</p> +<p>By default, Helix uses the <code>hybrid</code> indentation heuristic. This means that +indent queries are not used to compute the expected absolute indentation of a +line but rather the expected difference in indentation between the new and an +already existing line. This difference is then added to the actual indentation +of the already existing line. Since this makes errors in the indent queries +harder to find, it is recommended to disable it when testing via +<code>:set indent-heuristic tree-sitter</code>. The rest of this guide assumes that +the <code>tree-sitter</code> heuristic is used.</p> <h2 id="indent-queries"><a class="header" href="#indent-queries">Indent queries</a></h2> <p>When Helix is inserting a new line through <code>o</code>, <code>O</code>, or <code><ret></code>, to determine the indent level for the new line, the query in <code>indents.scm</code> is run on the @@ -2510,7 +2616,7 @@ actually have been extended).</li> // 3x @outdent <span class="boring">}</span></code></pre></pre> <pre><code class="language-scm">((block) @indent) -["}" ")"] @outdent +["}" ")"] @outdent </code></pre> <p>Note how on the second line, we have two blocks begin on the same line. In this case, since both captures occur on the same line, they are combined and only @@ -2550,7 +2656,7 @@ whitespace-sensitive.</p> the cursor on a line feed ends up being the entire inside of the class. Because of this, it will miss the entire function node and its indent capture, leading to an indent level one too small.</p> -<p>To address this case, <code>@extend</code> tells helix to "extend" the captured node's span +<p>To address this case, <code>@extend</code> tells helix to "extend" the captured node's span to the line feed and every consecutive line that has a greater indent level than the line of the node.</p> <pre><code class="language-scm">(parenthesized_expression) @indent @@ -2658,7 +2764,7 @@ similar to how <code>#set!</code> declarations work:</p> ) </code></pre> <p>The number of arguments depends on the predicate that's used. -Each argument is either a capture (<code>@name</code>) or a string (<code>"some string"</code>). +Each argument is either a capture (<code>@name</code>) or a string (<code>"some string"</code>). The following predicates are supported by tree-sitter:</p> <ul> <li> @@ -2671,6 +2777,11 @@ The first argument (a capture) must/must not be equal to the second argument The first argument (a capture) must/must not match the regex given in the second argument (a string).</p> </li> +<li> +<p><code>#any-of?</code>/<code>#not-any-of?</code>: +The first argument (a capture) must/must not be one of the other arguments +(strings).</p> +</li> </ul> <p>Additionally, we support some custom predicates for indent queries:</p> <ul> @@ -2705,21 +2816,21 @@ This scope applies to the whole captured node. This is only different from <pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)] </span><span class="boring">fn main() { </span>fn aha() { // โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ - let take = "on me"; // โโโโโโโโโโโโโโโโฎ scope: โ - let take = "me on"; // โโ "tail" โโ (block) @indent + let take = "on me"; // โโโโโโโโโโโโโโโโฎ scope: โ + let take = "me on"; // โโ "tail" โโ (block) @indent let ill = be_gone_days(1 || 2); // โ โ -} // โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโดโ "}" @outdent - // scope: "all" +} // โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโดโ "}" @outdent + // scope: "all" <span class="boring">}</span></code></pre></pre> <p>We can write the following query with the <code>#set!</code> declaration:</p> <pre><code class="language-scm">((block) @indent - (#set! "scope" "tail")) -("}" @outdent - (#set! "scope" "all")) + (#set! "scope" "tail")) +("}" @outdent + (#set! "scope" "all")) </code></pre> -<p>As we can see, the "tail" scope covers the node, except for the first line. +<p>As we can see, the "tail" scope covers the node, except for the first line. Everything up to and including the closing brace gets an indent level of 1. -Then, on the closing brace, we encounter an outdent with a scope of "all", which +Then, on the closing brace, we encounter an outdent with a scope of "all", which means the first line is included, and the indent level is cancelled out on this line. (Note these scopes are the defaults for <code>@indent</code> and <code>@outdent</code>โthey are written explicitly for demonstration.)</p> @@ -2729,7 +2840,7 @@ In addition to the <a href="http://tree-sitter.github.io/tree-sitter/syntax-high are a few Helix specific extensions that allow for more control.</p> <p>And example of a simple query that would highlight all strings as bash in Nix:</p> <pre><code class="language-scm">((string_expression (string_fragment) @injection.content) - (#set! injection.language "bash")) + (#set! injection.language "bash")) </code></pre> <h2 id="capture-types-1"><a class="header" href="#capture-types-1">Capture Types</a></h2> <ul> @@ -2787,6 +2898,10 @@ The first argument (a capture) must be equal to the second argument The first argument (a capture) must match the regex given in the second argument (a string).</p> </li> +<li> +<p><code>#any-of?</code> (standard): +The first argument (a capture) must be one of the other arguments (strings).</p> +</li> </ul> <div style="break-before: page; page-break-before: always;"></div><h1 id="adding-rainbow-bracket-queries"><a class="header" href="#adding-rainbow-bracket-queries">Adding Rainbow Bracket Queries</a></h1> <p>Helix uses <code>rainbows.scm</code> tree-sitter query files to provide rainbow bracket @@ -2805,7 +2920,7 @@ language itself. These queries will go into a <code>runtime/queries/tsq/rainbows.scm</code> file in the repository root.</p> <p>First we'll add the <code>@rainbow.bracket</code> captures. TSQ only has parentheses and square brackets:</p> -<pre><code class="language-tsq">["(" ")" "[" "]"] @rainbow.bracket +<pre><code class="language-tsq">["(" ")" "[" "]"] @rainbow.bracket </code></pre> <p>The ordering of the nodes within the alternation (square brackets) is not taken into consideration.</p> @@ -2816,7 +2931,7 @@ names of rules in the grammar. Brackets are usually written in tree-sitter grammars as literal strings, for example:</p> <pre><code class="language-js">{ // ... - arguments: seq("(", repeat($.argument), ")"), + arguments: seq("(", repeat($.argument), ")"), // ... } </code></pre> @@ -2863,7 +2978,7 @@ indirect descendants of some node captured with <code>@rainbow.scope</code>.</p> </code></pre> <p>If we want to highlight the <code><</code>, <code>></code> and <code></</code> nodes with rainbow colors, we capture them as <code>@rainbow.bracket</code>:</p> -<pre><code class="language-tsq">["<" ">" "</"] @rainbow.bracket +<pre><code class="language-tsq">["<" ">" "</"] @rainbow.bracket </code></pre> <p>And we capture <code>(element)</code> as <code>@rainbow.scope</code> because <code>(element)</code> nodes nest within each other: they increment the nesting level and switch to the next |