mirror of https://github.com/helix-editor/helix
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
941 lines
69 KiB
HTML
941 lines
69 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="sidebar-visible no-js colibri">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title></title>
|
|
<meta name="robots" content="noindex" />
|
|
<!-- Custom HTML head -->
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
|
<meta name="description" content="">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff" />
|
|
|
|
<link rel="icon" href="favicon.svg">
|
|
<link rel="shortcut icon" href="favicon.png">
|
|
<link rel="stylesheet" href="css/variables.css">
|
|
<link rel="stylesheet" href="css/general.css">
|
|
<link rel="stylesheet" href="css/chrome.css">
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
|
<link rel="preconnect" href="https://fonts.gstatic.com">
|
|
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@200;400;500;700&display=swap" rel="stylesheet">
|
|
<link rel="stylesheet" href="fonts/fonts.css">
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" href="highlight.css">
|
|
<link rel="stylesheet" href="tomorrow-night.css">
|
|
<link rel="stylesheet" href="ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
</head>
|
|
<body>
|
|
<!-- Provide site root to javascript -->
|
|
<script type="text/javascript">
|
|
var path_to_root = "";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "colibri" : "colibri";
|
|
</script>
|
|
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script type="text/javascript">
|
|
try {
|
|
var theme = localStorage.getItem('mdbook-theme');
|
|
var sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script type="text/javascript">
|
|
var theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
var html = document.querySelector('html');
|
|
html.classList.remove('no-js')
|
|
html.classList.remove('colibri')
|
|
html.classList.add(theme);
|
|
html.classList.add('js');
|
|
</script>
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script type="text/javascript">
|
|
var html = document.querySelector('html');
|
|
var sidebar = 'hidden';
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
}
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<div class="sidebar-scrollbox">
|
|
<ol class="chapter"><li class="chapter-item expanded "><a href="install.html"><strong aria-hidden="true">1.</strong> Installation</a></li><li class="chapter-item expanded "><a href="usage.html"><strong aria-hidden="true">2.</strong> Usage</a></li><li class="chapter-item expanded "><a href="from-vim.html"><strong aria-hidden="true">3.</strong> Migrating from Vim</a></li><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">4.</strong> Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="themes.html"><strong aria-hidden="true">4.1.</strong> Themes</a></li><li class="chapter-item expanded "><a href="keymap.html"><strong aria-hidden="true">4.2.</strong> Keymap</a></li><li class="chapter-item expanded "><a href="remapping.html"><strong aria-hidden="true">4.3.</strong> Key Remapping</a></li><li class="chapter-item expanded "><a href="hooks.html"><strong aria-hidden="true">4.4.</strong> Hooks</a></li><li class="chapter-item expanded "><a href="languages.html"><strong aria-hidden="true">4.5.</strong> Languages</a></li></ol></li><li class="chapter-item expanded "><a href="guides/index.html"><strong aria-hidden="true">5.</strong> Guides</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="guides/adding_languages.html"><strong aria-hidden="true">5.1.</strong> Adding Languages</a></li><li class="chapter-item expanded "><a href="guides/textobject.html"><strong aria-hidden="true">5.2.</strong> Adding Textobject Queries</a></li></ol></li></ol>
|
|
</div>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky bordered">
|
|
<div class="left-buttons">
|
|
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</button>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="colibri">Colibri (default)</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title"></h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script type="text/javascript">
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="installation"><a class="header" href="#installation">Installation</a></h1>
|
|
<p>We provide pre-built binaries on the <a href="https://github.com/helix-editor/helix/releases">GitHub Releases page</a>.</p>
|
|
<p><a href="https://repology.org/project/helix/versions"><img src="https://repology.org/badge/vertical-allrepos/helix.svg" alt="Packaging status" /></a></p>
|
|
<h2 id="osx"><a class="header" href="#osx">OSX</a></h2>
|
|
<p>A Homebrew tap is available:</p>
|
|
<pre><code>brew tap helix-editor/helix
|
|
brew install helix
|
|
</code></pre>
|
|
<h2 id="linux"><a class="header" href="#linux">Linux</a></h2>
|
|
<h3 id="nixos"><a class="header" href="#nixos">NixOS</a></h3>
|
|
<p>A <a href="https://nixos.wiki/wiki/Flakes">flake</a> containing the package is available in
|
|
the project root. The flake can also be used to spin up a reproducible development
|
|
shell for working on Helix.</p>
|
|
<h3 id="arch-linux"><a class="header" href="#arch-linux">Arch Linux</a></h3>
|
|
<p>Releases are available in the <code>community</code> repository.</p>
|
|
<p>A <a href="https://aur.archlinux.org/packages/helix-git/">helix-git</a> package is also available on the AUR, which builds the master branch.</p>
|
|
<h2 id="build-from-source"><a class="header" href="#build-from-source">Build from source</a></h2>
|
|
<pre><code>git clone --recurse-submodules --shallow-submodules -j8 https://github.com/helix-editor/helix
|
|
cd helix
|
|
cargo install --path helix-term
|
|
</code></pre>
|
|
<p>This will install the <code>hx</code> binary to <code>$HOME/.cargo/bin</code>.</p>
|
|
<p>Helix also needs it's runtime files so make sure to copy/symlink the <code>runtime/</code> directory into the
|
|
config directory (for example <code>~/.config/helix/runtime</code> on Linux/macOS). This location can be overriden
|
|
via the <code>HELIX_RUNTIME</code> environment variable.</p>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="usage"><a class="header" href="#usage">Usage</a></h1>
|
|
<p>(Currently not fully documented, see the <a href="./keymap.html">keymappings</a> list for more.)</p>
|
|
<p>See <a href="https://github.com/helix-editor/helix/blob/master/runtime/tutor.txt">tutor.txt</a> (accessible via <code>hx --tutor</code> or <code>:tutor</code>) for a vimtutor-like introduction.</p>
|
|
<h2 id="registers"><a class="header" href="#registers">Registers</a></h2>
|
|
<p>Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with <code>"</code> being used to select a register:</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>
|
|
</ul>
|
|
<p>If there is a selected register before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:</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>
|
|
</ul>
|
|
<h3 id="special-registers"><a class="header" href="#special-registers">Special Registers</a></h3>
|
|
<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>Black hole</td></tr>
|
|
</tbody></table>
|
|
<blockquote>
|
|
<p>There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the <a href="keymap.html#space-mode">keymap</a> for the specifics.
|
|
The black hole register works as a no-op register, meaning no data will be written to / read from it.</p>
|
|
</blockquote>
|
|
<h2 id="surround"><a class="header" href="#surround">Surround</a></h2>
|
|
<p>Functionality similar to <a href="https://github.com/tpope/vim-surround">vim-surround</a> is built into
|
|
helix. The keymappings have been inspired from <a href="https://github.com/machakann/vim-sandwich">vim-sandwich</a>:</p>
|
|
<p><img src="https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif" alt="surround demo" /></p>
|
|
<ul>
|
|
<li><code>ms</code> - Add surround characters</li>
|
|
<li><code>mr</code> - Replace surround characters</li>
|
|
<li><code>md</code> - Delete surround characters</li>
|
|
</ul>
|
|
<p><code>ms</code> acts on a selection, so select the text first and use <code>ms<char></code>. <code>mr</code> and <code>md</code> work
|
|
on the closest pairs found and selections are not required; use counts to act in outer pairs.</p>
|
|
<p>It can also act on multiple seletions (yay!). For example, to change every occurance of <code>(use)</code> to <code>[use]</code>:</p>
|
|
<ul>
|
|
<li><code>%</code> to select the whole file</li>
|
|
<li><code>s</code> to split the selections on a search term</li>
|
|
<li>Input <code>use</code> and hit Enter</li>
|
|
<li><code>mr([</code> to replace the parens with square brackets</li>
|
|
</ul>
|
|
<p>Multiple characters are currently not supported, but planned.</p>
|
|
<h2 id="textobjects"><a class="header" href="#textobjects">Textobjects</a></h2>
|
|
<p>Currently supported: <code>word</code>, <code>surround</code>, <code>function</code>, <code>class</code>, <code>parameter</code>.</p>
|
|
<p><img src="https://user-images.githubusercontent.com/23398472/124231131-81a4bb00-db2d-11eb-9d10-8e577ca7b177.gif" alt="textobject-demo" />
|
|
<img src="https://user-images.githubusercontent.com/23398472/132537398-2a2e0a54-582b-44ab-a77f-eb818942203d.gif" alt="textobject-treesitter-demo" /></p>
|
|
<ul>
|
|
<li><code>ma</code> - Select around the object (<code>va</code> in vim, <code><alt-a></code> in kakoune)</li>
|
|
<li><code>mi</code> - Select inside the object (<code>vi</code> in vim, <code><alt-i></code> in kakoune)</li>
|
|
</ul>
|
|
<table><thead><tr><th>Key after <code>mi</code> or <code>ma</code></th><th>Textobject selected</th></tr></thead><tbody>
|
|
<tr><td><code>w</code></td><td>Word</td></tr>
|
|
<tr><td><code>W</code></td><td>WORD</td></tr>
|
|
<tr><td><code>(</code>, <code>[</code>, <code>'</code>, etc</td><td>Specified surround pairs</td></tr>
|
|
<tr><td><code>f</code></td><td>Function</td></tr>
|
|
<tr><td><code>c</code></td><td>Class</td></tr>
|
|
<tr><td><code>p</code></td><td>Parameter</td></tr>
|
|
</tbody></table>
|
|
<p>Note: <code>f</code>, <code>c</code>, etc need a tree-sitter grammar active for the current
|
|
document and a special tree-sitter query file to work properly. <a href="https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=">Only
|
|
some grammars</a>
|
|
currently have the query file implemented. Contributions are welcome !</p>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="migrating-from-vim"><a class="header" href="#migrating-from-vim">Migrating from Vim</a></h1>
|
|
<p>Helix's editing model is strongly inspired from vim and kakoune, and a notable
|
|
difference from vim (and the most striking similarity to kakoune) is that Helix
|
|
follows the <code>selection → action</code> model. This means that the whatever you are
|
|
going to act on (a word, a paragraph, a line, etc) is selected first and the
|
|
action itself (delete, change, yank, etc) comes second. A cursor is simply a
|
|
single width selection.</p>
|
|
<p>See also Kakoune's <a href="https://github.com/mawww/kakoune/wiki/Migrating-from-Vim">Migrating from Vim</a>.</p>
|
|
<blockquote>
|
|
<p>TODO: Mention texobjects, surround, registers</p>
|
|
</blockquote>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="configuration"><a class="header" href="#configuration">Configuration</a></h1>
|
|
<p>To override global configuration parameters, create a <code>config.toml</code> file located in your config directory:</p>
|
|
<ul>
|
|
<li>Linux and Mac: <code>~/.config/helix/config.toml</code></li>
|
|
<li>Windows: <code>%AppData%\helix\config.toml</code></li>
|
|
</ul>
|
|
<h2 id="editor"><a class="header" href="#editor">Editor</a></h2>
|
|
<p><code>[editor]</code> section of the config.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Default</th></tr></thead><tbody>
|
|
<tr><td><code>scrolloff</code></td><td>Number of lines of padding around the edge of the screen when scrolling.</td><td><code>3</code></td></tr>
|
|
<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>line-number</code></td><td>Line number display (<code>absolute</code>, <code>relative</code>)</td><td><code>absolute</code></td></tr>
|
|
<tr><td><code>smart-case</code></td><td>Enable smart case regex searching (case insensitive unless pattern contains upper case characters)</td><td><code>true</code></td></tr>
|
|
<tr><td><code>auto-pairs</code></td><td>Enable automatic insertion of pairs to parenthese, brackets, etc.</td><td><code>true</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>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>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>auto-info</code></td><td>Whether to display infoboxes</td><td><code>true</code></td></tr>
|
|
</tbody></table>
|
|
<p><code>[editor.filepicker]</code> section of the config. Sets options for file picker and global search. All but the last key listed in the default file-picker configuration below are IgnoreOptions: whether hidden files and files listed within ignore files are ignored by (not visible in) the helix file picker and global search. There is also one other key, <code>max-depth</code> available, which is not defined by default.</p>
|
|
<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>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 .gitignore, 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>
|
|
</tbody></table>
|
|
<h2 id="lsp"><a class="header" href="#lsp">LSP</a></h2>
|
|
<p>To display all language server messages in the status line add the following to your <code>config.toml</code>:</p>
|
|
<pre><code class="language-toml">[lsp]
|
|
display-messages = true
|
|
</code></pre>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="themes"><a class="header" href="#themes">Themes</a></h1>
|
|
<p>First you'll need to place selected themes in your <code>themes</code> directory (i.e <code>~/.config/helix/themes</code>), the directory might have to be created beforehand.</p>
|
|
<p>To use a custom theme add <code>theme = <name></code> to your <a href="./configuration.html"><code>config.toml</code></a> or override it during runtime using <code>:theme <name></code>.</p>
|
|
<p>The default theme.toml can be found <a href="https://github.com/helix-editor/helix/blob/master/theme.toml">here</a>, and user submitted themes <a href="https://github.com/helix-editor/helix/blob/master/runtime/themes">here</a>. </p>
|
|
<h2 id="creating-a-theme"><a class="header" href="#creating-a-theme">Creating a theme</a></h2>
|
|
<p>First create a file with the name of your theme as file name (i.e <code>mytheme.toml</code>) and place it in your <code>themes</code> directory (i.e <code>~/.config/helix/themes</code>).</p>
|
|
<p>Each line in the theme file is specified as below:</p>
|
|
<pre><code class="language-toml">key = { fg = "#ffffff", bg = "#000000", 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, and <code>modifiers</code> is a list of style modifiers. <code>bg</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"
|
|
</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"
|
|
</code></pre>
|
|
<h3 id="color-palettes"><a class="header" href="#color-palettes">Color palettes</a></h3>
|
|
<p>It's recommended define a palette of named colors, and refer to them from 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"
|
|
|
|
[palette]
|
|
white = "#ffffff"
|
|
black = "#000000"
|
|
</code></pre>
|
|
<p>Remember that the <code>[palette]</code> table includes all keys after its header,
|
|
so you should define the palette after normal theme options.</p>
|
|
<p>The default palette uses the terminal's default 16 colors, and the colors names
|
|
are listed below. The <code>[palette]</code> section in the config file takes precedence
|
|
over it and is merged into the default palette.</p>
|
|
<table><thead><tr><th>Color Name</th></tr></thead><tbody>
|
|
<tr><td><code>black</code></td></tr>
|
|
<tr><td><code>red</code></td></tr>
|
|
<tr><td><code>green</code></td></tr>
|
|
<tr><td><code>yellow</code></td></tr>
|
|
<tr><td><code>blue</code></td></tr>
|
|
<tr><td><code>magenta</code></td></tr>
|
|
<tr><td><code>cyan</code></td></tr>
|
|
<tr><td><code>gray</code></td></tr>
|
|
<tr><td><code>light-red</code></td></tr>
|
|
<tr><td><code>light-green</code></td></tr>
|
|
<tr><td><code>light-yellow</code></td></tr>
|
|
<tr><td><code>light-blue</code></td></tr>
|
|
<tr><td><code>light-magenta</code></td></tr>
|
|
<tr><td><code>light-cyan</code></td></tr>
|
|
<tr><td><code>light-gray</code></td></tr>
|
|
<tr><td><code>white</code></td></tr>
|
|
</tbody></table>
|
|
<h3 id="modifiers"><a class="header" href="#modifiers">Modifiers</a></h3>
|
|
<p>The following values may be used as modifiers. </p>
|
|
<p>Less common modifiers might not be supported by your terminal emulator.</p>
|
|
<table><thead><tr><th>Modifier</th></tr></thead><tbody>
|
|
<tr><td><code>bold</code></td></tr>
|
|
<tr><td><code>dim</code></td></tr>
|
|
<tr><td><code>italic</code></td></tr>
|
|
<tr><td><code>underlined</code></td></tr>
|
|
<tr><td><code>slow_blink</code></td></tr>
|
|
<tr><td><code>rapid_blink</code></td></tr>
|
|
<tr><td><code>reversed</code></td></tr>
|
|
<tr><td><code>hidden</code></td></tr>
|
|
<tr><td><code>crossed_out</code></td></tr>
|
|
</tbody></table>
|
|
<h3 id="scopes"><a class="header" href="#scopes">Scopes</a></h3>
|
|
<p>The following is a list of scopes available to use for styling.</p>
|
|
<h4 id="syntax-highlighting"><a class="header" href="#syntax-highlighting">Syntax highlighting</a></h4>
|
|
<p>These keys match <a href="https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme">tree-sitter scopes</a>.</p>
|
|
<p>For a given highlight produced, styling will be determined based on the longest matching theme key. For example, the highlight <code>function.builtin.static</code> would match the key <code>function.builtin</code> rather than <code>function</code>.</p>
|
|
<p>We use a similar set of scopes as
|
|
<a href="https://www.sublimetext.com/docs/scope_naming.html">SublimeText</a>. See also
|
|
<a href="https://macromates.com/manual/en/language_grammars">TextMate</a> scopes.</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>type</code> - Types</p>
|
|
<ul>
|
|
<li><code>builtin</code> - Primitive types provided by the language (<code>int</code>, <code>usize</code>)</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>constant</code> (TODO: constant.other.placeholder for %v)</p>
|
|
<ul>
|
|
<li><code>builtin</code> Special constants provided by the language (<code>true</code>, <code>false</code>, <code>nil</code> etc)
|
|
<ul>
|
|
<li><code>boolean</code></li>
|
|
</ul>
|
|
</li>
|
|
<li><code>character</code>
|
|
<ul>
|
|
<li><code>escape</code></li>
|
|
</ul>
|
|
</li>
|
|
<li><code>numeric</code> (numbers)
|
|
<ul>
|
|
<li><code>integer</code></li>
|
|
<li><code>float</code></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>string</code> (TODO: string.quoted.{single, double}, string.raw/.unquoted)?</p>
|
|
<ul>
|
|
<li><code>regexp</code> - Regular expressions</li>
|
|
<li><code>special</code>
|
|
<ul>
|
|
<li><code>path</code></li>
|
|
<li><code>url</code></li>
|
|
<li><code>symbol</code> - Erlang/Elixir atoms, Ruby symbols, Clojure keywords</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>comment</code> - Code comments</p>
|
|
<ul>
|
|
<li><code>line</code> - Single line comments (<code>//</code>)</li>
|
|
<li><code>block</code> - Block comments (e.g. (<code>/* */</code>)
|
|
<ul>
|
|
<li><code>documentation</code> - Documentation comments (e.g. <code>///</code> in Rust)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>variable</code> - Variables</p>
|
|
<ul>
|
|
<li><code>builtin</code> - Reserved language variables (<code>self</code>, <code>this</code>, <code>super</code>, etc)</li>
|
|
<li><code>parameter</code> - Function parameters</li>
|
|
<li><code>other</code>
|
|
<ul>
|
|
<li><code>member</code> - Fields of composite data types (e.g. structs, unions)</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>function</code> (TODO: ?)</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>label</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>punctuation</code></p>
|
|
<ul>
|
|
<li><code>delimiter</code> - Commas, colons</li>
|
|
<li><code>bracket</code> - Parentheses, angle brackets, etc.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>keyword</code></p>
|
|
<ul>
|
|
<li><code>control</code>
|
|
<ul>
|
|
<li><code>conditional</code> - <code>if</code>, <code>else</code></li>
|
|
<li><code>repeat</code> - <code>for</code>, <code>while</code>, <code>loop</code></li>
|
|
<li><code>import</code> - <code>import</code>, <code>export</code></li>
|
|
<li><code>return</code></li>
|
|
</ul>
|
|
</li>
|
|
<li><code>operator</code> - <code>or</code>, <code>in</code></li>
|
|
<li><code>directive</code> - Preprocessor directives (<code>#if</code> in C) </li>
|
|
<li><code>function</code> - <code>fn</code>, <code>func</code></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>operator</code> - <code>||</code>, <code>+=</code>, <code>></code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>function</code></p>
|
|
<ul>
|
|
<li><code>builtin</code></li>
|
|
<li><code>method</code></li>
|
|
<li><code>macro</code></li>
|
|
<li><code>special</code> (preprocesor in C)</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><code>tag</code> - Tags (e.g. <code><body></code> in HTML)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>namespace</code></p>
|
|
</li>
|
|
</ul>
|
|
<h4 id="interface"><a class="header" href="#interface">Interface</a></h4>
|
|
<p>These scopes are used for theming the editor interface.</p>
|
|
<table><thead><tr><th>Key</th><th>Notes</th></tr></thead><tbody>
|
|
<tr><td><code>ui.background</code></td><td></td></tr>
|
|
<tr><td><code>ui.cursor</code></td><td></td></tr>
|
|
<tr><td><code>ui.cursor.insert</code></td><td></td></tr>
|
|
<tr><td><code>ui.cursor.select</code></td><td></td></tr>
|
|
<tr><td><code>ui.cursor.match</code></td><td>Matching bracket etc.</td></tr>
|
|
<tr><td><code>ui.cursor.primary</code></td><td>Cursor with primary selection</td></tr>
|
|
<tr><td><code>ui.linenr</code></td><td></td></tr>
|
|
<tr><td><code>ui.linenr.selected</code></td><td></td></tr>
|
|
<tr><td><code>ui.statusline</code></td><td>Statusline</td></tr>
|
|
<tr><td><code>ui.statusline.inactive</code></td><td>Statusline (unfocused document)</td></tr>
|
|
<tr><td><code>ui.popup</code></td><td></td></tr>
|
|
<tr><td><code>ui.window</code></td><td></td></tr>
|
|
<tr><td><code>ui.help</code></td><td></td></tr>
|
|
<tr><td><code>ui.text</code></td><td></td></tr>
|
|
<tr><td><code>ui.text.focus</code></td><td></td></tr>
|
|
<tr><td><code>ui.info</code></td><td></td></tr>
|
|
<tr><td><code>ui.info.text</code></td><td></td></tr>
|
|
<tr><td><code>ui.menu</code></td><td></td></tr>
|
|
<tr><td><code>ui.menu.selected</code></td><td></td></tr>
|
|
<tr><td><code>ui.selection</code></td><td>For selections in the editing area</td></tr>
|
|
<tr><td><code>ui.selection.primary</code></td><td></td></tr>
|
|
<tr><td><code>warning</code></td><td>Diagnostics warning (gutter)</td></tr>
|
|
<tr><td><code>error</code></td><td>Diagnostics error (gutter)</td></tr>
|
|
<tr><td><code>info</code></td><td>Diagnostics info (gutter)</td></tr>
|
|
<tr><td><code>hint</code></td><td>Diagnostics hint (gutter)</td></tr>
|
|
<tr><td><code>diagnostic</code></td><td>For text in editing area</td></tr>
|
|
</tbody></table>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="keymap"><a class="header" href="#keymap">Keymap</a></h1>
|
|
<ul>
|
|
<li>Mappings marked (<strong>LSP</strong>) require an active language server for the file.</li>
|
|
<li>Mappings marked (<strong>TS</strong>) require a tree-sitter grammar for the filetype.</li>
|
|
</ul>
|
|
<h2 id="normal-mode"><a class="header" href="#normal-mode">Normal mode</a></h2>
|
|
<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>
|
|
</blockquote>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>h</code>/<code>Left</code></td><td>Move left</td><td><code>move_char_left</code></td></tr>
|
|
<tr><td><code>j</code>/<code>Down</code></td><td>Move down</td><td><code>move_line_down</code></td></tr>
|
|
<tr><td><code>k</code>/<code>Up</code></td><td>Move up</td><td><code>move_line_up</code></td></tr>
|
|
<tr><td><code>l</code>/<code>Right</code></td><td>Move right</td><td><code>move_char_right</code></td></tr>
|
|
<tr><td><code>w</code></td><td>Move next word start</td><td><code>move_next_word_start</code></td></tr>
|
|
<tr><td><code>b</code></td><td>Move previous word start</td><td><code>move_prev_word_start</code></td></tr>
|
|
<tr><td><code>e</code></td><td>Move next word end</td><td><code>move_next_word_end</code></td></tr>
|
|
<tr><td><code>W</code></td><td>Move next WORD start</td><td><code>move_next_long_word_start</code></td></tr>
|
|
<tr><td><code>B</code></td><td>Move previous WORD start</td><td><code>move_prev_long_word_start</code></td></tr>
|
|
<tr><td><code>E</code></td><td>Move next WORD end</td><td><code>move_next_long_word_end</code></td></tr>
|
|
<tr><td><code>t</code></td><td>Find 'till next char</td><td><code>find_till_char</code></td></tr>
|
|
<tr><td><code>f</code></td><td>Find next char</td><td><code>find_next_char</code></td></tr>
|
|
<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>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>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>PageUp</code></td><td>Move page up</td><td><code>page_up</code></td></tr>
|
|
<tr><td><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-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>v</code></td><td>Enter <a href="keymap.html#select--extend-mode">select (extend) mode</a></td><td><code>select_mode</code></td></tr>
|
|
<tr><td><code>g</code></td><td>Enter <a href="keymap.html#goto-mode">goto mode</a></td><td>N/A</td></tr>
|
|
<tr><td><code>m</code></td><td>Enter <a href="keymap.html#match-mode">match mode</a></td><td>N/A</td></tr>
|
|
<tr><td><code>:</code></td><td>Enter command mode</td><td><code>command_mode</code></td></tr>
|
|
<tr><td><code>z</code></td><td>Enter <a href="keymap.html#view-mode">view mode</a></td><td>N/A</td></tr>
|
|
<tr><td><code>Z</code></td><td>Enter sticky <a href="keymap.html#view-mode">view mode</a></td><td>N/A</td></tr>
|
|
<tr><td><code>Ctrl-w</code></td><td>Enter <a href="keymap.html#window-mode">window mode</a></td><td>N/A</td></tr>
|
|
<tr><td><code>Space</code></td><td>Enter <a href="keymap.html#space-mode">space mode</a></td><td>N/A</td></tr>
|
|
</tbody></table>
|
|
<h3 id="changes"><a class="header" href="#changes">Changes</a></h3>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>r</code></td><td>Replace with a character</td><td><code>replace</code></td></tr>
|
|
<tr><td><code>R</code></td><td>Replace with yanked text</td><td><code>replace_with_yanked</code></td></tr>
|
|
<tr><td><code>~</code></td><td>Switch case of the selected text</td><td><code>switch_case</code></td></tr>
|
|
<tr><td><code>`</code></td><td>Set the selected text to lower case</td><td><code>switch_to_lowercase</code></td></tr>
|
|
<tr><td><code>Alt-`</code></td><td>Set the selected text to upper case</td><td><code>switch_to_uppercase</code></td></tr>
|
|
<tr><td><code>i</code></td><td>Insert before selection</td><td><code>insert_mode</code></td></tr>
|
|
<tr><td><code>a</code></td><td>Insert after selection (append)</td><td><code>append_mode</code></td></tr>
|
|
<tr><td><code>I</code></td><td>Insert at the start of the line</td><td><code>prepend_to_line</code></td></tr>
|
|
<tr><td><code>A</code></td><td>Insert at the end of the line</td><td><code>append_to_line</code></td></tr>
|
|
<tr><td><code>o</code></td><td>Open new line below selection</td><td><code>open_below</code></td></tr>
|
|
<tr><td><code>O</code></td><td>Open new line above selection</td><td><code>open_above</code></td></tr>
|
|
<tr><td><code>.</code></td><td>Repeat last change</td><td>N/A</td></tr>
|
|
<tr><td><code>u</code></td><td>Undo change</td><td><code>undo</code></td></tr>
|
|
<tr><td><code>U</code></td><td>Redo change</td><td><code>redo</code></td></tr>
|
|
<tr><td><code>Alt-u</code></td><td>Move backward in history</td><td><code>earlier</code></td></tr>
|
|
<tr><td><code>Alt-U</code></td><td>Move forward in history</td><td><code>later</code></td></tr>
|
|
<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></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 (<strong>LSP</strong>)</td><td><code>format_selections</code></td></tr>
|
|
<tr><td><code>d</code></td><td>Delete selection</td><td><code>delete_selection</code></td></tr>
|
|
<tr><td><code>Alt-d</code></td><td>Delete selection, without yanking</td><td><code>delete_selection_noyank</code></td></tr>
|
|
<tr><td><code>c</code></td><td>Change selection (delete and enter insert mode)</td><td><code>change_selection</code></td></tr>
|
|
<tr><td><code>Alt-c</code></td><td>Change selection (delete and enter insert mode, without yanking)</td><td><code>change_selection_noyank</code></td></tr>
|
|
<tr><td><code>Ctrl-a</code></td><td>Increment object (number) under cursor</td><td><code>increment</code></td></tr>
|
|
<tr><td><code>Ctrl-x</code></td><td>Decrement object (number) under cursor</td><td><code>decrement</code></td></tr>
|
|
</tbody></table>
|
|
<h4 id="shell"><a class="header" href="#shell">Shell</a></h4>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>|</code></td><td>Pipe each selection through shell command, replacing with output</td><td><code>shell_pipe</code></td></tr>
|
|
<tr><td><code>Alt-|</code></td><td>Pipe each selection into shell command, ignoring output</td><td><code>shell_pipe_to</code></td></tr>
|
|
<tr><td><code>!</code></td><td>Run shell command, inserting output before each selection</td><td><code>shell_insert_output</code></td></tr>
|
|
<tr><td><code>Alt-!</code></td><td>Run shell command, appending output after each selection</td><td><code>shell_append_output</code></td></tr>
|
|
</tbody></table>
|
|
<h3 id="selection-manipulation"><a class="header" href="#selection-manipulation">Selection manipulation</a></h3>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>s</code></td><td>Select all regex matches inside selections</td><td><code>select_regex</code></td></tr>
|
|
<tr><td><code>S</code></td><td>Split selection into subselections on regex matches</td><td><code>split_selection</code></td></tr>
|
|
<tr><td><code>Alt-s</code></td><td>Split selection on newlines</td><td><code>split_selection_on_newline</code></td></tr>
|
|
<tr><td><code>&</code></td><td>Align selection in columns</td><td><code>align_selections</code></td></tr>
|
|
<tr><td><code>_</code></td><td>Trim whitespace from the selection</td><td><code>trim_selections</code></td></tr>
|
|
<tr><td><code>;</code></td><td>Collapse selection onto a single cursor</td><td><code>collapse_selection</code></td></tr>
|
|
<tr><td><code>Alt-;</code></td><td>Flip selection cursor and anchor</td><td><code>flip_selections</code></td></tr>
|
|
<tr><td><code>,</code></td><td>Keep only the primary selection</td><td><code>keep_primary_selection</code></td></tr>
|
|
<tr><td><code>Alt-,</code></td><td>Remove the primary selection</td><td><code>remove_primary_selection</code></td></tr>
|
|
<tr><td><code>C</code></td><td>Copy selection onto the next line (Add cursor below)</td><td><code>copy_selection_on_next_line</code></td></tr>
|
|
<tr><td><code>Alt-C</code></td><td>Copy selection onto the previous line (Add cursor above)</td><td><code>copy_selection_on_prev_line</code></td></tr>
|
|
<tr><td><code>(</code></td><td>Rotate main selection backward</td><td><code>rotate_selections_backward</code></td></tr>
|
|
<tr><td><code>)</code></td><td>Rotate main selection forward</td><td><code>rotate_selections_forward</code></td></tr>
|
|
<tr><td><code>Alt-(</code></td><td>Rotate selection contents backward</td><td><code>rotate_selection_contents_backward</code></td></tr>
|
|
<tr><td><code>Alt-)</code></td><td>Rotate selection contents forward</td><td><code>rotate_selection_contents_forward</code></td></tr>
|
|
<tr><td><code>%</code></td><td>Select entire file</td><td><code>select_all</code></td></tr>
|
|
<tr><td><code>x</code></td><td>Select current line, if already selected, extend to next line</td><td><code>extend_line</code></td></tr>
|
|
<tr><td><code>X</code></td><td>Extend selection to line bounds (line-wise selection)</td><td><code>extend_to_line_bounds</code></td></tr>
|
|
<tr><td></td><td>Expand selection to parent syntax node TODO: pick a key (<strong>TS</strong>)</td><td><code>expand_selection</code></td></tr>
|
|
<tr><td><code>J</code></td><td>Join lines inside selection</td><td><code>join_selections</code></td></tr>
|
|
<tr><td><code>K</code></td><td>Keep selections matching the regex</td><td><code>keep_selections</code></td></tr>
|
|
<tr><td><code>Alt-K</code></td><td>Remove selections matching the regex</td><td><code>remove_selections</code></td></tr>
|
|
<tr><td><code>$</code></td><td>Pipe each selection into shell command, keep selections where command returned 0</td><td><code>shell_keep_pipe</code></td></tr>
|
|
<tr><td><code>Ctrl-c</code></td><td>Comment/uncomment the selections</td><td><code>toggle_comments</code></td></tr>
|
|
</tbody></table>
|
|
<h3 id="search"><a class="header" href="#search">Search</a></h3>
|
|
<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>
|
|
<tr><td><code>n</code></td><td>Select next search match</td><td><code>search_next</code></td></tr>
|
|
<tr><td><code>N</code></td><td>Select previous search match</td><td><code>search_prev</code></td></tr>
|
|
<tr><td><code>*</code></td><td>Use current selection as the search pattern</td><td><code>search_selection</code></td></tr>
|
|
</tbody></table>
|
|
<h3 id="minor-modes"><a class="header" href="#minor-modes">Minor modes</a></h3>
|
|
<p>These sub-modes are accessible from normal mode and typically switch back to normal mode after a command.</p>
|
|
<h4 id="view-mode"><a class="header" href="#view-mode">View mode</a></h4>
|
|
<p>View mode is intended for scrolling and manipulating the view without changing
|
|
the selection. The "sticky" variant of this mode is persistent; use the Escape
|
|
key to return to normal mode after usage (useful when you're simply looking
|
|
over text and not actively editing it).</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>z</code> , <code>c</code></td><td>Vertically center the line</td><td><code>align_view_center</code></td></tr>
|
|
<tr><td><code>t</code></td><td>Align the line to the top of the screen</td><td><code>align_view_top</code></td></tr>
|
|
<tr><td><code>b</code></td><td>Align the line to the bottom of the screen</td><td><code>align_view_bottom</code></td></tr>
|
|
<tr><td><code>m</code></td><td>Align the line to the middle of the screen (horizontally)</td><td><code>align_view_middle</code></td></tr>
|
|
<tr><td><code>j</code> , <code>down</code></td><td>Scroll the view downwards</td><td><code>scroll_down</code></td></tr>
|
|
<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>f</code></td><td>Move page down</td><td><code>page_down</code></td></tr>
|
|
<tr><td><code>b</code></td><td>Move page up</td><td><code>page_up</code></td></tr>
|
|
<tr><td><code>d</code></td><td>Move half page down</td><td><code>half_page_down</code></td></tr>
|
|
<tr><td><code>u</code></td><td>Move half page up</td><td><code>half_page_up</code></td></tr>
|
|
</tbody></table>
|
|
<h4 id="goto-mode"><a class="header" href="#goto-mode">Goto mode</a></h4>
|
|
<p>Jumps to various locations.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>g</code></td><td>Go to the start of the 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>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>
|
|
<tr><td><code>t</code></td><td>Go to the top of the screen</td><td><code>goto_window_top</code></td></tr>
|
|
<tr><td><code>c</code></td><td>Go to the middle of the screen</td><td><code>goto_window_center</code></td></tr>
|
|
<tr><td><code>b</code></td><td>Go to the bottom of the screen</td><td><code>goto_window_bottom</code></td></tr>
|
|
<tr><td><code>d</code></td><td>Go to definition (<strong>LSP</strong>)</td><td><code>goto_definition</code></td></tr>
|
|
<tr><td><code>y</code></td><td>Go to type definition (<strong>LSP</strong>)</td><td><code>goto_type_definition</code></td></tr>
|
|
<tr><td><code>r</code></td><td>Go to references (<strong>LSP</strong>)</td><td><code>goto_reference</code></td></tr>
|
|
<tr><td><code>i</code></td><td>Go to implementation (<strong>LSP</strong>)</td><td><code>goto_implementation</code></td></tr>
|
|
<tr><td><code>a</code></td><td>Go to the last accessed/alternate file</td><td><code>goto_last_accessed_file</code></td></tr>
|
|
<tr><td><code>m</code></td><td>Go to the last modified/alternate file</td><td><code>goto_last_modified_file</code></td></tr>
|
|
<tr><td><code>n</code></td><td>Go to next buffer</td><td><code>goto_next_buffer</code></td></tr>
|
|
<tr><td><code>p</code></td><td>Go to previous buffer</td><td><code>goto_previous_buffer</code></td></tr>
|
|
<tr><td><code>.</code></td><td>Go to last modification in current file</td><td><code>goto_last_modification</code></td></tr>
|
|
</tbody></table>
|
|
<h4 id="match-mode"><a class="header" href="#match-mode">Match mode</a></h4>
|
|
<p>Enter this mode using <code>m</code> from normal mode. See the relavant section
|
|
in <a href="./usage.html">Usage</a> for an explanation about <a href="./usage.html#surround">surround</a>
|
|
and <a href="./usage.html#textobject">textobject</a> usage.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>m</code></td><td>Goto matching bracket (<strong>TS</strong>)</td><td><code>match_brackets</code></td></tr>
|
|
<tr><td><code>s</code> <code><char></code></td><td>Surround current selection with <code><char></code></td><td><code>surround_add</code></td></tr>
|
|
<tr><td><code>r</code> <code><from><to></code></td><td>Replace surround character <code><from></code> with <code><to></code></td><td><code>surround_replace</code></td></tr>
|
|
<tr><td><code>d</code> <code><char></code></td><td>Delete surround character <code><char></code></td><td><code>surround_delete</code></td></tr>
|
|
<tr><td><code>a</code> <code><object></code></td><td>Select around textobject</td><td><code>select_textobject_around</code></td></tr>
|
|
<tr><td><code>i</code> <code><object></code></td><td>Select inside textobject</td><td><code>select_textobject_inner</code></td></tr>
|
|
</tbody></table>
|
|
<p>TODO: Mappings for selecting syntax nodes (a superset of <code>[</code>).</p>
|
|
<h4 id="window-mode"><a class="header" href="#window-mode">Window mode</a></h4>
|
|
<p>This layer is similar to vim keybindings as kakoune does not support window.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<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>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>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>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>
|
|
<tr><td><code>l</code>, <code>Ctrl-l</code>, <code>right</code></td><td>Move to right split</td><td><code>jump_view_right</code></td></tr>
|
|
<tr><td><code>q</code>, <code>Ctrl-q</code></td><td>Close current window</td><td><code>wclose</code></td></tr>
|
|
<tr><td><code>o</code>, <code>Ctrl-o</code></td><td>Only keep the current window, closing all the others</td><td><code>wonly</code></td></tr>
|
|
</tbody></table>
|
|
<h4 id="space-mode"><a class="header" href="#space-mode">Space mode</a></h4>
|
|
<p>This layer is a kludge of mappings, mostly pickers.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>f</code></td><td>Open file picker</td><td><code>file_picker</code></td></tr>
|
|
<tr><td><code>b</code></td><td>Open buffer picker</td><td><code>buffer_picker</code></td></tr>
|
|
<tr><td><code>k</code></td><td>Show documentation for item under cursor in a <a href="keymap.html#popup">popup</a> (<strong>LSP</strong>)</td><td><code>hover</code></td></tr>
|
|
<tr><td><code>s</code></td><td>Open document symbol picker (<strong>LSP</strong>)</td><td><code>symbol_picker</code></td></tr>
|
|
<tr><td><code>S</code></td><td>Open workspace symbol picker (<strong>LSP</strong>)</td><td><code>workspace_symbol_picker</code></td></tr>
|
|
<tr><td><code>r</code></td><td>Rename symbol (<strong>LSP</strong>)</td><td><code>rename_symbol</code></td></tr>
|
|
<tr><td><code>a</code></td><td>Apply code action (<strong>LSP</strong>)</td><td><code>code_action</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>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>Join and yank selections to clipboard</td><td><code>yank_joined_to_clipboard</code></td></tr>
|
|
<tr><td><code>Y</code></td><td>Yank main selection to clipboard</td><td><code>yank_main_selection_to_clipboard</code></td></tr>
|
|
<tr><td><code>R</code></td><td>Replace selections by clipboard contents</td><td><code>replace_selections_with_clipboard</code></td></tr>
|
|
<tr><td><code>/</code></td><td>Global search in workspace folder</td><td><code>global_search</code></td></tr>
|
|
</tbody></table>
|
|
<blockquote>
|
|
<p>TIP: Global search displays results in a fuzzy picker, use <code>space + '</code> to bring it back up after opening a file.</p>
|
|
</blockquote>
|
|
<h5 id="popup"><a class="header" href="#popup">Popup</a></h5>
|
|
<p>Displays documentation for item under cursor.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody>
|
|
<tr><td><code>Ctrl-u</code></td><td>Scroll up</td></tr>
|
|
<tr><td><code>Ctrl-d</code></td><td>Scroll down</td></tr>
|
|
</tbody></table>
|
|
<h4 id="unimpaired"><a class="header" href="#unimpaired">Unimpaired</a></h4>
|
|
<p>Mappings in the style of <a href="https://github.com/tpope/vim-unimpaired">vim-unimpaired</a>.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>[d</code></td><td>Go to previous diagnostic (<strong>LSP</strong>)</td><td><code>goto_prev_diag</code></td></tr>
|
|
<tr><td><code>]d</code></td><td>Go to next diagnostic (<strong>LSP</strong>)</td><td><code>goto_next_diag</code></td></tr>
|
|
<tr><td><code>[D</code></td><td>Go to first diagnostic in document (<strong>LSP</strong>)</td><td><code>goto_first_diag</code></td></tr>
|
|
<tr><td><code>]D</code></td><td>Go to last diagnostic in document (<strong>LSP</strong>)</td><td><code>goto_last_diag</code></td></tr>
|
|
<tr><td><code>[space</code></td><td>Add newline above</td><td><code>add_newline_above</code></td></tr>
|
|
<tr><td><code>]space</code></td><td>Add newline below</td><td><code>add_newline_below</code></td></tr>
|
|
</tbody></table>
|
|
<h2 id="insert-mode"><a class="header" href="#insert-mode">Insert Mode</a></h2>
|
|
<table><thead><tr><th>Key</th><th>Description</th><th>Command</th></tr></thead><tbody>
|
|
<tr><td><code>Escape</code></td><td>Switch to normal mode</td><td><code>normal_mode</code></td></tr>
|
|
<tr><td><code>Ctrl-x</code></td><td>Autocomplete</td><td><code>completion</code></td></tr>
|
|
<tr><td><code>Ctrl-r</code></td><td>Insert a register content</td><td><code>insert_register</code></td></tr>
|
|
<tr><td><code>Ctrl-w</code></td><td>Delete previous word</td><td><code>delete_word_backward</code></td></tr>
|
|
<tr><td><code>Alt-d</code></td><td>Delete next word</td><td><code>delete_word_forward</code></td></tr>
|
|
<tr><td><code>Alt-b</code>, <code>Alt-Left</code></td><td>Backward a word</td><td><code>move_prev_word_end</code></td></tr>
|
|
<tr><td><code>Ctrl-b</code>, <code>Left</code></td><td>Backward a char</td><td><code>move_char_left</code></td></tr>
|
|
<tr><td><code>Alt-f</code>, <code>Alt-Right</code></td><td>Forward a word</td><td><code>move_next_word_start</code></td></tr>
|
|
<tr><td><code>Ctrl-f</code>, <code>Right</code></td><td>Forward a char</td><td><code>move_char_right</code></td></tr>
|
|
<tr><td><code>Ctrl-e</code>, <code>End</code></td><td>move to line end</td><td><code>goto_line_end_newline</code></td></tr>
|
|
<tr><td><code>Ctrl-a</code>, <code>Home</code></td><td>move to line start</td><td><code>goto_line_start</code></td></tr>
|
|
<tr><td><code>Ctrl-u</code></td><td>delete to start of line</td><td><code>kill_to_line_start</code></td></tr>
|
|
<tr><td><code>Ctrl-k</code></td><td>delete to end of line</td><td><code>kill_to_line_end</code></td></tr>
|
|
<tr><td><code>backspace</code>, <code>Ctrl-h</code></td><td>delete previous char</td><td><code>delete_char_backward</code></td></tr>
|
|
<tr><td><code>delete</code>, <code>Ctrl-d</code></td><td>delete previous char</td><td><code>delete_char_forward</code></td></tr>
|
|
<tr><td><code>Ctrl-p</code>, <code>Up</code></td><td>move to previous line</td><td><code>move_line_up</code></td></tr>
|
|
<tr><td><code>Ctrl-n</code>, <code>Down</code></td><td>move to next line</td><td><code>move_line_down</code></td></tr>
|
|
</tbody></table>
|
|
<h2 id="select--extend-mode"><a class="header" href="#select--extend-mode">Select / extend mode</a></h2>
|
|
<p>I'm still pondering whether to keep this mode or not. It changes movement
|
|
commands (including goto) to extend the existing selection instead of replacing it.</p>
|
|
<blockquote>
|
|
<p>NOTE: It's a bit confusing at the moment because extend hasn't been
|
|
implemented for all movement commands yet.</p>
|
|
</blockquote>
|
|
<h1 id="picker"><a class="header" href="#picker">Picker</a></h1>
|
|
<p>Keys to use within picker. Remapping currently not supported.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody>
|
|
<tr><td><code>Up</code>, <code>Ctrl-k</code>, <code>Ctrl-p</code></td><td>Previous entry</td></tr>
|
|
<tr><td><code>Down</code>, <code>Ctrl-j</code>, <code>Ctrl-n</code></td><td>Next entry</td></tr>
|
|
<tr><td><code>Ctrl-space</code></td><td>Filter options</td></tr>
|
|
<tr><td><code>Enter</code></td><td>Open selected</td></tr>
|
|
<tr><td><code>Ctrl-s</code></td><td>Open horizontally</td></tr>
|
|
<tr><td><code>Ctrl-v</code></td><td>Open vertically</td></tr>
|
|
<tr><td><code>Escape</code>, <code>Ctrl-c</code></td><td>Close picker</td></tr>
|
|
</tbody></table>
|
|
<h1 id="prompt"><a class="header" href="#prompt">Prompt</a></h1>
|
|
<p>Keys to use within prompt, Remapping currently not supported.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody>
|
|
<tr><td><code>Escape</code>, <code>Ctrl-c</code></td><td>Close prompt</td></tr>
|
|
<tr><td><code>Alt-b</code>, <code>Alt-Left</code></td><td>Backward a word</td></tr>
|
|
<tr><td><code>Ctrl-b</code>, <code>Left</code></td><td>Backward a char</td></tr>
|
|
<tr><td><code>Alt-f</code>, <code>Alt-Right</code></td><td>Forward a word</td></tr>
|
|
<tr><td><code>Ctrl-f</code>, <code>Right</code></td><td>Forward a char</td></tr>
|
|
<tr><td><code>Ctrl-e</code>, <code>End</code></td><td>Move prompt end</td></tr>
|
|
<tr><td><code>Ctrl-a</code>, <code>Home</code></td><td>Move prompt start</td></tr>
|
|
<tr><td><code>Ctrl-w</code></td><td>Delete previous word</td></tr>
|
|
<tr><td><code>Alt-d</code></td><td>Delete next word</td></tr>
|
|
<tr><td><code>Ctrl-u</code></td><td>Delete to start of line</td></tr>
|
|
<tr><td><code>Ctrl-k</code></td><td>Delete to end of line</td></tr>
|
|
<tr><td><code>backspace</code>, <code>Ctrl-h</code></td><td>Delete previous char</td></tr>
|
|
<tr><td><code>delete</code>, <code>Ctrl-d</code></td><td>Delete next char</td></tr>
|
|
<tr><td><code>Ctrl-s</code></td><td>Insert a word under doc cursor, may be changed to Ctrl-r Ctrl-w later</td></tr>
|
|
<tr><td><code>Ctrl-p</code>, <code>Up</code></td><td>Select previous history</td></tr>
|
|
<tr><td><code>Ctrl-n</code>, <code>Down</code></td><td>Select next history</td></tr>
|
|
<tr><td><code>Tab</code></td><td>Select next completion item</td></tr>
|
|
<tr><td><code>BackTab</code></td><td>Select previous completion item</td></tr>
|
|
<tr><td><code>Enter</code></td><td>Open selected</td></tr>
|
|
</tbody></table>
|
|
<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>One-way key remapping is temporarily supported via a simple TOML configuration
|
|
file. (More powerful solutions such as rebinding via commands will be
|
|
available in the future).</p>
|
|
<p>To remap keys, write a <code>config.toml</code> file in your <code>helix</code> configuration
|
|
directory (default <code>~/.config/helix</code> in Linux systems) with a structure like
|
|
this:</p>
|
|
<pre><code class="language-toml"># At most one section each of 'keys.normal', 'keys.insert' and 'keys.select'
|
|
[keys.normal]
|
|
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 Control-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
|
|
</code></pre>
|
|
<p>Control, 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>
|
|
<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>"lt"</code></td></tr>
|
|
<tr><td>></td><td><code>"gt"</code></td></tr>
|
|
<tr><td>+</td><td><code>"plus"</code></td></tr>
|
|
<tr><td>-</td><td><code>"minus"</code></td></tr>
|
|
<tr><td>;</td><td><code>"semicolon"</code></td></tr>
|
|
<tr><td>%</td><td><code>"percent"</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>
|
|
<p>Keys can be disabled by binding them to the <code>no_op</code> command.</p>
|
|
<p>Commands can be found at <a href="https://docs.helix-editor.com/keymap.html">Keymap</a> Commands.</p>
|
|
<blockquote>
|
|
<p>Commands can also be found 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>commands!</code> macro.</p>
|
|
</blockquote>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="hooks"><a class="header" href="#hooks">Hooks</a></h1>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="languages"><a class="header" href="#languages">Languages</a></h1>
|
|
<p>Language-specific settings and settings for particular language servers can be configured in a <code>languages.toml</code> file placed in your <a href="./configuration.html">configuration directory</a>. Helix actually uses two <code>languages.toml</code> files, the <a href="https://github.com/helix-editor/helix/blob/master/languages.toml">first one</a> is in the main helix repository; it contains the default settings for each language and is included in the helix binary at compile time. Users who want to see the available settings and options can either reference the helix repo's <code>languages.toml</code> file, or consult the table in the <a href="./guides/adding_languages.html">adding languages</a> section.</p>
|
|
<p>Changes made to the <code>languages.toml</code> file in a user's <a href="./configuration.html">configuration directory</a> are merged with helix's defaults on start-up, such that a user's settings will take precedence over defaults in the event of a collision. For example, the default <code>languages.toml</code> sets rust's <code>auto-format</code> to <code>true</code>. If a user wants to disable auto-format, they can change the <code>languages.toml</code> in their <a href="./configuration.html">configuration directory</a> to make the rust entry read like the example below; the new key/value pair <code>auto-format = false</code> will override the default when the two sets of settings are merged on start-up:</p>
|
|
<pre><code># in <config_dir>/helix/languages.toml
|
|
|
|
[[language]]
|
|
name = "rust"
|
|
auto-format = false
|
|
</code></pre>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="guides"><a class="header" href="#guides">Guides</a></h1>
|
|
<p>This section contains guides for adding new language server configurations,
|
|
tree-sitter grammers, textobject queries, etc.</p>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="adding-languages"><a class="header" href="#adding-languages">Adding languages</a></h1>
|
|
<h2 id="submodules"><a class="header" href="#submodules">Submodules</a></h2>
|
|
<p>To add a new language, you should first add a tree-sitter submodule. To do this,
|
|
you can run the command</p>
|
|
<pre><code class="language-sh">git submodule add -f <repository> helix-syntax/languages/tree-sitter-<name>
|
|
</code></pre>
|
|
<p>For example, to add tree-sitter-ocaml you would run</p>
|
|
<pre><code class="language-sh">git submodule add -f https://github.com/tree-sitter/tree-sitter-ocaml helix-syntax/languages/tree-sitter-ocaml
|
|
</code></pre>
|
|
<p>Make sure the submodule is shallow by doing</p>
|
|
<pre><code class="language-sh">git config -f .gitmodules submodule.helix-syntax/languages/tree-sitter-<name>.shallow true
|
|
</code></pre>
|
|
<p>or you can manually add <code>shallow = true</code> to <code>.gitmodules</code>.</p>
|
|
<h2 id="languagestoml"><a class="header" href="#languagestoml">languages.toml</a></h2>
|
|
<p>Next, you need to add the language to the <a href="https://github.com/helix-editor/helix/blob/master/languages.toml"><code>languages.toml</code></a> found in the root of
|
|
the repository; this <code>languages.toml</code> file is included at compilation time, and
|
|
is distinct from the <code>language.toml</code> file in the user's <a href="guides/../configuration.html">configuration
|
|
directory</a>.</p>
|
|
<p>These are the available keys and descriptions for the file.</p>
|
|
<table><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody>
|
|
<tr><td>name</td><td>The name of the language</td></tr>
|
|
<tr><td>scope</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>injection-regex</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>file-types</td><td>The filetypes of the language, for example <code>["yml", "yaml"]</code></td></tr>
|
|
<tr><td>shebangs</td><td>The interpreters from the shebang line, for example <code>["sh", "bash"]</code></td></tr>
|
|
<tr><td>roots</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>auto-format</td><td>Whether to autoformat this language when saving</td></tr>
|
|
<tr><td>comment-token</td><td>The token to use as a comment-token</td></tr>
|
|
<tr><td>indent</td><td>The indent to use. Has sub keys <code>tab-width</code> and <code>unit</code></td></tr>
|
|
<tr><td>config</td><td>Language server configuration</td></tr>
|
|
</tbody></table>
|
|
<h2 id="queries"><a class="header" href="#queries">Queries</a></h2>
|
|
<p>For a language to have syntax-highlighting and indentation among other things, you have to add queries. Add a directory for your language with the path <code>runtime/queries/<name>/</code>. The tree-sitter <a href="https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries">website</a> gives more info on how to write queries.</p>
|
|
<h2 id="common-issues"><a class="header" href="#common-issues">Common Issues</a></h2>
|
|
<ul>
|
|
<li>
|
|
<p>If you get errors when building after switching branches, you may have to remove or update tree-sitter submodules. You can update submodules by running</p>
|
|
<pre><code class="language-sh">git submodule sync; git submodule update --init
|
|
</code></pre>
|
|
</li>
|
|
<li>
|
|
<p>Make sure to not use the <code>--remote</code> flag. To remove submodules look inside the <code>.gitmodules</code> and remove directories that are not present inside of it.</p>
|
|
</li>
|
|
<li>
|
|
<p>If a parser is segfaulting or you want to remove the parser, make sure to remove the submodule <em>and</em> the compiled parser in <code>runtime/grammar/<name>.so</code></p>
|
|
</li>
|
|
<li>
|
|
<p>The indents query is <code>indents.toml</code>, <em>not</em> <code>indents.scm</code>. See <a href="https://github.com/helix-editor/helix/issues/114">this</a> issue for more information.</p>
|
|
</li>
|
|
</ul>
|
|
<div style="break-before: page; page-break-before: always;"></div><h1 id="adding-textobject-queries"><a class="header" href="#adding-textobject-queries">Adding Textobject Queries</a></h1>
|
|
<p>Textobjects that are language specific (<a href="guides/../usage.html#textobjects">like functions, classes, etc</a>)
|
|
require an accompanying tree-sitter grammar and a <code>textobjects.scm</code> query file
|
|
to work properly. Tree-sitter allows us to query the source code syntax tree
|
|
and capture specific parts of it. The queries are written in a lisp dialect.
|
|
More information on how to write queries can be found in the <a href="https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax">official tree-sitter
|
|
documentation</a>.</p>
|
|
<p>Query files should be placed in <code>runtime/queries/{language}/textobjects.scm</code>
|
|
when contributing. Note that to test the query files locally you should put
|
|
them under your local runtime directory (<code>~/.config/helix/runtime</code> on Linux
|
|
for example).</p>
|
|
<p>The following <a href="https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes">captures</a> are recognized:</p>
|
|
<table><thead><tr><th>Capture Name</th></tr></thead><tbody>
|
|
<tr><td><code>function.inside</code></td></tr>
|
|
<tr><td><code>function.around</code></td></tr>
|
|
<tr><td><code>class.inside</code></td></tr>
|
|
<tr><td><code>class.around</code></td></tr>
|
|
<tr><td><code>parameter.inside</code></td></tr>
|
|
</tbody></table>
|
|
<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>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
<script type="text/javascript">
|
|
window.playground_copyable = true;
|
|
</script>
|
|
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
<script type="text/javascript">
|
|
window.addEventListener('load', function() {
|
|
window.setTimeout(window.print, 100);
|
|
});
|
|
</script>
|
|
</body>
|
|
</html>
|