aboutsummaryrefslogtreecommitdiff
path: root/book/src
diff options
context:
space:
mode:
Diffstat (limited to 'book/src')
-rw-r--r--book/src/configuration.md13
-rw-r--r--book/src/from-vim.md2
-rw-r--r--book/src/install.md4
-rw-r--r--book/src/keymap.md100
-rw-r--r--book/src/themes.md202
5 files changed, 194 insertions, 127 deletions
diff --git a/book/src/configuration.md b/book/src/configuration.md
index 00dfbbd8..5a28362d 100644
--- a/book/src/configuration.md
+++ b/book/src/configuration.md
@@ -5,6 +5,19 @@ To override global configuration parameters, create a `config.toml` file located
* Linux and Mac: `~/.config/helix/config.toml`
* Windows: `%AppData%\helix\config.toml`
+## Editor
+
+`[editor]` section of the config.
+
+| Key | Description | Default |
+|--|--|---------|
+| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `3` |
+| `mouse` | Enable mouse mode. | `true` |
+| `middle-click-paste` | Middle click paste support. | `true` |
+| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` |
+| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |
+| `line-number` | Line number display (`absolute`, `relative`) | `absolute` |
+
## LSP
To display all language server messages in the status line add the following to your `config.toml`:
diff --git a/book/src/from-vim.md b/book/src/from-vim.md
index 8e9bbac3..09f33386 100644
--- a/book/src/from-vim.md
+++ b/book/src/from-vim.md
@@ -7,4 +7,6 @@ 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.
+See also Kakoune's [Migrating from Vim](https://github.com/mawww/kakoune/wiki/Migrating-from-Vim).
+
> TODO: Mention texobjects, surround, registers
diff --git a/book/src/install.md b/book/src/install.md
index cd9c980e..b9febbcc 100644
--- a/book/src/install.md
+++ b/book/src/install.md
@@ -23,7 +23,9 @@ shell for working on Helix.
### Arch Linux
-Binary packages are available on AUR:
+Releases are available in the `community` repository.
+
+Packages are also available on AUR:
- [helix-bin](https://aur.archlinux.org/packages/helix-bin/) contains the pre-built release
- [helix-git](https://aur.archlinux.org/packages/helix-git/) builds the master branch
diff --git a/book/src/keymap.md b/book/src/keymap.md
index 861e46ac..51e56eaa 100644
--- a/book/src/keymap.md
+++ b/book/src/keymap.md
@@ -4,7 +4,7 @@
### Movement
-> NOTE: `f`, `F`, `t` and `T` are not confined to the current line.
+> NOTE: Unlike vim, `f`, `F`, `t` and `T` are not confined to the current line.
| Key | Description | Command |
| ----- | ----------- | ------- |
@@ -28,14 +28,14 @@
| `PageDown` | Move page down | `page_down` |
| `Ctrl-u` | Move half page up | `half_page_up` |
| `Ctrl-d` | Move half page down | `half_page_down` |
-| `Ctrl-i` | Jump forward on the jumplist TODO: conflicts tab | `jump_forward` |
+| `Ctrl-i` | Jump forward on the jumplist | `jump_forward` |
| `Ctrl-o` | Jump backward on the jumplist | `jump_backward` |
| `v` | Enter [select (extend) mode](#select--extend-mode) | `select_mode` |
| `g` | Enter [goto mode](#goto-mode) | N/A |
| `m` | Enter [match mode](#match-mode) | N/A |
| `:` | Enter command mode | `command_mode` |
| `z` | Enter [view mode](#view-mode) | N/A |
-| `Ctrl-w` | Enter [window mode](#window-mode) (maybe will be remove for spc w w later) | N/A |
+| `Ctrl-w` | Enter [window mode](#window-mode) | N/A |
| `Space` | Enter [space mode](#space-mode) | N/A |
| `K` | Show documentation for the item under the cursor | `hover` |
@@ -66,6 +66,16 @@
| `d` | Delete selection | `delete_selection` |
| `c` | Change selection (delete and enter insert mode) | `change_selection` |
+#### Shell
+
+| Key | Description | Command |
+| ------ | ----------- | ------- |
+| <code>&#124;</code> | Pipe each selection through shell command, replacing with output | `shell_pipe` |
+| <code>A-&#124;</code> | Pipe each selection into shell command, ignoring output | `shell_pipe_to` |
+| `!` | Run shell command, inserting output before each selection | `shell_insert_output` |
+| `A-!` | Run shell command, appending output after each selection | `shell_append_output` |
+
+
### Selection manipulation
| Key | Description | Command |
@@ -87,17 +97,10 @@
| | Expand selection to parent syntax node TODO: pick a key | `expand_selection` |
| `J` | Join lines inside selection | `join_selections` |
| `K` | Keep selections matching the regex TODO: overlapped by hover help | `keep_selections` |
+| `$` | Pipe each selection into shell command, keep selections where command returned 0 | `shell_keep_pipe` |
| `Space` | Keep only the primary selection TODO: overlapped by space mode | `keep_primary_selection` |
| `Ctrl-c` | Comment/uncomment the selections | `toggle_comments` |
-### Insert Mode
-
-| Key | Description | Command |
-| ----- | ----------- | ------- |
-| `Escape` | Switch to normal mode | `normal_mode` |
-| `Ctrl-x` | Autocomplete | `completion` |
-| `Ctrl-w` | Delete previous word | `delete_word_backward` |
-
### Search
> TODO: The search implementation isn't ideal yet -- we don't support searching
@@ -110,38 +113,11 @@ in reverse, or searching via smartcase.
| `N` | Add next search match to selection | `extend_search_next` |
| `*` | Use current selection as the search pattern | `search_selection` |
-### Unimpaired
-
-Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired)
-
-| Key | Description | Command |
-| ----- | ----------- | ------- |
-| `[d` | Go to previous diagnostic | `goto_prev_diag` |
-| `]d` | Go to next diagnostic | `goto_next_diag` |
-| `[D` | Go to first diagnostic in document | `goto_first_diag` |
-| `]D` | Go to last diagnostic in document | `goto_last_diag` |
-| `[space` | Add newline above | `add_newline_above` |
-| `]space` | Add newline below | `add_newline_below` |
-
-### Shell
+### Minor modes
-| Key | Description | Command |
-| ------ | ----------- | ------- |
-| `\|` | Pipe each selection through shell command, replacing with output | `shell_pipe` |
-| `A-\|` | Pipe each selection into shell command, ignoring output | `shell_pipe_to` |
-| `!` | Run shell command, inserting output before each selection | `shell_insert_output` |
-| `A-!` | Run shell command, appending output after each selection | `shell_append_output` |
-| `$` | Pipe each selection into shell command, keep selections where command returned 0 | `shell_keep_pipe` |
-
-## Select / extend mode
-
-I'm still pondering whether to keep this mode or not. It changes movement
-commands to extend the existing selection instead of replacing it.
-
-> NOTE: It's a bit confusing at the moment because extend hasn't been
-> implemented for all movement commands yet.
+These sub-modes are accessible from normal mode and typically switch back to normal mode after a command.
-## View mode
+#### View mode
View mode is intended for scrolling and manipulating the view without changing
the selection.
@@ -155,7 +131,7 @@ the selection.
| `j` | Scroll the view downwards | `scroll_down` |
| `k` | Scroll the view upwards | `scroll_up` |
-## Goto mode
+#### Goto mode
Jumps to various locations.
@@ -177,7 +153,7 @@ Jumps to various locations.
| `i` | Go to implementation | `goto_implementation` |
| `a` | Go to the last accessed/alternate file | `goto_last_accessed_file` |
-## Match mode
+#### Match mode
Enter this mode using `m` from normal mode. See the relavant section
in [Usage](./usage.md) for an explanation about [surround](./usage.md#surround)
@@ -192,11 +168,9 @@ and [textobject](./usage.md#textobject) usage.
| `a` `<object>` | Select around textobject | `select_textobject_around` |
| `i` `<object>` | Select inside textobject | `select_textobject_inner` |
-## Object mode
-
TODO: Mappings for selecting syntax nodes (a superset of `[`).
-## Window mode
+#### Window mode
This layer is similar to vim keybindings as kakoune does not support window.
@@ -207,9 +181,9 @@ This layer is similar to vim keybindings as kakoune does not support window.
| `h`, `Ctrl-h` | Horizontal bottom split | `hsplit` |
| `q`, `Ctrl-q` | Close current window | `wclose` |
-## Space mode
+#### Space mode
-This layer is a kludge of mappings I had under leader key in neovim.
+This layer is a kludge of mappings, mostly pickers.
| Key | Description | Command |
| ----- | ----------- | ------- |
@@ -226,6 +200,36 @@ This layer is a kludge of mappings I had under leader key in neovim.
| `Y` | Yank main selection to clipboard | `yank_main_selection_to_clipboard` |
| `R` | Replace selections by clipboard contents | `replace_selections_with_clipboard` |
+
+#### Unimpaired
+
+Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired).
+
+| Key | Description | Command |
+| ----- | ----------- | ------- |
+| `[d` | Go to previous diagnostic | `goto_prev_diag` |
+| `]d` | Go to next diagnostic | `goto_next_diag` |
+| `[D` | Go to first diagnostic in document | `goto_first_diag` |
+| `]D` | Go to last diagnostic in document | `goto_last_diag` |
+| `[space` | Add newline above | `add_newline_above` |
+| `]space` | Add newline below | `add_newline_below` |
+
+## Insert Mode
+
+| Key | Description | Command |
+| ----- | ----------- | ------- |
+| `Escape` | Switch to normal mode | `normal_mode` |
+| `Ctrl-x` | Autocomplete | `completion` |
+| `Ctrl-w` | Delete previous word | `delete_word_backward` |
+
+## Select / extend mode
+
+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.
+
+> NOTE: It's a bit confusing at the moment because extend hasn't been
+> implemented for all movement commands yet.
+
# Picker
Keys to use within picker. Remapping currently not supported.
diff --git a/book/src/themes.md b/book/src/themes.md
index 804baa1c..fe5259d5 100644
--- a/book/src/themes.md
+++ b/book/src/themes.md
@@ -30,85 +30,9 @@ if the key contains a dot `'.'`, it must be quoted to prevent it being parsed as
"key.key" = "#ffffff"
```
-Possible modifiers:
+### Color palettes
-| Modifier |
-| --- |
-| `bold` |
-| `dim` |
-| `italic` |
-| `underlined` |
-| `slow\_blink` |
-| `rapid\_blink` |
-| `reversed` |
-| `hidden` |
-| `crossed\_out` |
-
-Possible keys:
-
-| Key | Notes |
-| --- | --- |
-| `attribute` | |
-| `keyword` | |
-| `keyword.directive` | Preprocessor directives (\#if in C) |
-| `keyword.control` | Control flow |
-| `namespace` | |
-| `punctuation` | |
-| `punctuation.delimiter` | |
-| `operator` | |
-| `special` | |
-| `property` | |
-| `variable` | |
-| `variable.parameter` | |
-| `type` | |
-| `type.builtin` | |
-| `type.enum.variant` | Enum variants |
-| `constructor` | |
-| `function` | |
-| `function.macro` | |
-| `function.builtin` | |
-| `comment` | |
-| `variable.builtin` | |
-| `constant` | |
-| `constant.builtin` | |
-| `string` | |
-| `number` | |
-| `escape` | Escaped characters |
-| `label` | For lifetimes |
-| `module` | |
-| `ui.background` | |
-| `ui.cursor` | |
-| `ui.cursor.insert` | |
-| `ui.cursor.select` | |
-| `ui.cursor.match` | Matching bracket etc. |
-| `ui.cursor.primary` | Cursor with primary selection |
-| `ui.linenr` | |
-| `ui.linenr.selected` | |
-| `ui.statusline` | |
-| `ui.statusline.inactive` | |
-| `ui.popup` | |
-| `ui.window` | |
-| `ui.help` | |
-| `ui.text` | |
-| `ui.text.focus` | |
-| `ui.info` | |
-| `ui.info.text` | |
-| `ui.menu` | |
-| `ui.menu.selected` | |
-| `ui.selection` | For selections in the editing area |
-| `ui.selection.primary` | |
-| `warning` | LSP warning |
-| `error` | LSP error |
-| `info` | LSP info |
-| `hint` | LSP hint |
-
-These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme). We half-follow the common scopes from [macromates language grammars](https://macromates.com/manual/en/language_grammars) with some differences.
-
-For a given highlight produced, styling will be determined based on the longest matching theme key. So it's enough to provide function to highlight `function.macro` and `function.builtin` as well, but you can use more specific scopes to highlight specific cases differently.
-
-## Color palettes
-
-You can define a palette of named colors, and refer to them from the
+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
`palette` to your theme file:
@@ -146,3 +70,125 @@ over it and is merged into the default palette.
| `light-cyan` |
| `light-gray` |
| `white` |
+
+### Modifiers
+
+The following values may be used as modifiers.
+
+Less common modifiers might not be supported by your terminal emulator.
+
+| Modifier |
+| --- |
+| `bold` |
+| `dim` |
+| `italic` |
+| `underlined` |
+| `slow_blink` |
+| `rapid_blink` |
+| `reversed` |
+| `hidden` |
+| `crossed_out` |
+
+### Scopes
+
+The following is a list of scopes available to use for styling.
+
+#### Syntax highlighting
+
+These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme).
+
+For a given highlight produced, styling will be determined based on the longest matching theme key. For example, the highlight `function.builtin.static` would match the key `function.builtin` rather than `function`.
+
+We use a similar set of scopes as
+[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also
+[TextMate](https://macromates.com/manual/en/language_grammars) scopes.
+
+- `escape` (TODO: rename to (constant).character.escape)
+
+- `type` - Types
+ - `builtin` - Primitive types provided by the language (`int`, `usize`)
+
+- `constant` (TODO: constant.other.placeholder for %v)
+ - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)
+ - `boolean`
+ - `character`
+
+- `number` (TODO: rename to constant.number/.numeric.{integer, float, complex})
+- `string` (TODO: string.quoted.{single, double}, string.raw/.unquoted)?
+ - `regexp` - Regular expressions
+ - `special`
+ - `path`
+ - `url`
+
+- `comment` - Code comments
+ - `line` - Single line comments (`//`)
+ - `block` - Block comments (e.g. (`/* */`)
+ - `documentation` - Documentation comments (e.g. `///` in Rust)
+
+- `variable` - Variables
+ - `builtin` - Reserved language variables (`self`, `this`, `super`, etc)
+ - `parameter` - Function parameters
+ - `property`
+ - `function` (TODO: ?)
+
+- `label`
+
+- `punctuation`
+ - `delimiter` - Commas, colons
+ - `bracket` - Parentheses, angle brackets, etc.
+
+- `keyword`
+ - `control`
+ - `conditional` - `if`, `else`
+ - `repeat` - `for`, `while`, `loop`
+ - `import` - `import`, `export`
+ - (TODO: return?)
+ - `directive` - Preprocessor directives (`#if` in C)
+ - `function` - `fn`, `func`
+
+- `operator` - `||`, `+=`, `>`, `or`
+
+- `function`
+ - `builtin`
+ - `method`
+ - `macro`
+ - `special` (preprocesor in C)
+
+- `tag` - Tags (e.g. `<body>` in HTML)
+
+- `namespace`
+
+#### Interface
+
+These scopes are used for theming the editor interface.
+
+
+| Key | Notes |
+| --- | --- |
+| `ui.background` | |
+| `ui.cursor` | |
+| `ui.cursor.insert` | |
+| `ui.cursor.select` | |
+| `ui.cursor.match` | Matching bracket etc. |
+| `ui.cursor.primary` | Cursor with primary selection |
+| `ui.linenr` | |
+| `ui.linenr.selected` | |
+| `ui.statusline` | Statusline |
+| `ui.statusline.inactive` | Statusline (unfocused document) |
+| `ui.popup` | |
+| `ui.window` | |
+| `ui.help` | |
+| `ui.text` | |
+| `ui.text.focus` | |
+| `ui.info` | |
+| `ui.info.text` | |
+| `ui.menu` | |
+| `ui.menu.selected` | |
+| `ui.selection` | For selections in the editing area |
+| `ui.selection.primary` | |
+| `warning` | Diagnostics warning |
+| `error` | Diagnostics error |
+| `info` | Diagnostics info |
+| `hint` | Diagnostics hint |
+
+