diff --git a/book/book.toml b/book/book.toml index 3ccaf71e0..2277a0bd9 100644 --- a/book/book.toml +++ b/book/book.toml @@ -3,8 +3,9 @@ authors = ["Blaž Hrastnik"] language = "en" multilingual = false src = "src" -theme = "colibri" edit-url-template = "https://github.com/helix-editor/helix/tree/master/book/{path}?mode=edit" [output.html] cname = "docs.helix-editor.com" +default-theme = "colibri" +preferred-dark-theme = "colibri" diff --git a/book/src/configuration.md b/book/src/configuration.md index 00dfbbd83..5a28362d7 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -5,6 +5,19 @@ # Configuration * 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"]`
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 8e9bbac39..09f33386b 100644 --- a/book/src/from-vim.md +++ b/book/src/from-vim.md @@ -7,4 +7,6 @@ # Migrating from Vim 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 cd9c980e3..b9febbccd 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -23,7 +23,9 @@ ### NixOS ### 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 861e46ac7..51e56eaaa 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -4,7 +4,7 @@ ## Normal mode ### 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 @@ ### Movement | `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 @@ ### Changes | `d` | Delete selection | `delete_selection` | | `c` | Change selection (delete and enter insert mode) | `change_selection` | +#### Shell + +| 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` | + + ### Selection manipulation | Key | Description | Command | @@ -87,17 +97,10 @@ ### Selection manipulation | | 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 @@ ### Search | `N` | Add next search match to selection | `extend_search_next` | | `*` | Use current selection as the search pattern | `search_selection` | -### Unimpaired +### Minor modes -Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired) +These sub-modes are accessible from normal mode and typically switch back to normal mode after a command. -| 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 - -| 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. - -## View mode +#### View mode View mode is intended for scrolling and manipulating the view without changing the selection. @@ -155,7 +131,7 @@ ## View mode | `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 @@ ## Goto mode | `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 @@ ## Match mode | `a` `` | Select around textobject | `select_textobject_around` | | `i` `` | 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 @@ ## Window mode | `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 @@ ## Space mode | `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 804baa1ce..fe5259d57 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -30,85 +30,9 @@ ## Creating a theme "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 @@ ## Color palettes | `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. `` 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 | + + diff --git a/book/theme/css/general.css b/book/theme/css/general.css index 7749bdedb..ddc2387a0 100644 --- a/book/theme/css/general.css +++ b/book/theme/css/general.css @@ -114,6 +114,19 @@ h6:target::before { margin-bottom: .875em; } +.content ul li { +margin-bottom: .25rem; +} +.content ul { + list-style-type: square; +} +.content ul ul, .content ol ul { + margin-bottom: .5rem; +} +.content li p { + margin-bottom: .5em; +} + .content p { line-height: 1.45em; } .content ol { line-height: 1.45em; } .content ul { line-height: 1.45em; } diff --git a/book/theme/css/variables.css b/book/theme/css/variables.css index a49d6794c..db1a11b85 100644 --- a/book/theme/css/variables.css +++ b/book/theme/css/variables.css @@ -69,7 +69,7 @@ --links: #2b79a2; - --inline-code-color: #c5c8c6;; + --inline-code-color: #c5c8c6; --theme-popup-bg: #141617; --theme-popup-border: #43484d; @@ -110,7 +110,7 @@ --links: #20609f; - --inline-code-color: #301900; + --inline-code-color: #a39e9b; --theme-popup-bg: #fafafa; --theme-popup-border: #cccccc; @@ -151,7 +151,7 @@ --links: #2b79a2; - --inline-code-color: #c5c8c6;; + --inline-code-color: #c5c8c6; --theme-popup-bg: #161923; --theme-popup-border: #737480; @@ -192,7 +192,7 @@ --links: #2b79a2; - --inline-code-color: #6e6b5e; + --inline-code-color: #c5c8c6; --theme-popup-bg: #e1e1db; --theme-popup-border: #b38f6b; @@ -234,7 +234,7 @@ --links: #2b79a2; - --inline-code-color: #c5c8c6;; + --inline-code-color: #6e6b5e; --theme-popup-bg: #141617; --theme-popup-border: #43484d; @@ -261,6 +261,7 @@ .colibri { --bg: #3b224c; --fg: #bcbdd0; + --heading-fg: #fff; --sidebar-bg: #281733; --sidebar-fg: #c8c9db; @@ -276,18 +277,19 @@ /* --links: #a4a0e8; */ --links: #ECCDBA; - --inline-code-color: #c5c8c6;; + --inline-code-color: hsl(48.7, 7.8%, 70%); --theme-popup-bg: #161923; --theme-popup-border: #737480; --theme-hover: rgba(0,0,0, .2); - --quote-bg: hsl(226, 15%, 17%); + --quote-bg: #281733; --quote-border: hsl(226, 15%, 22%); - --table-border-color: hsl(226, 23%, 16%); - --table-header-bg: hsl(226, 23%, 31%); + --table-border-color: hsl(226, 23%, 76%); + --table-header-bg: hsla(226, 23%, 31%, 0); --table-alternate-bg: hsl(226, 23%, 14%); + --table-border-line: hsla(201deg, 20%, 92%, 0.2); --searchbar-border-color: #aaa; --searchbar-bg: #aeaec6; @@ -300,6 +302,7 @@ } .colibri { +/* --bg: #ffffff; --fg: #452859; --fg: #5a5977; @@ -318,7 +321,7 @@ --links: #6F44F0; - --inline-code-color: #697C81; + --inline-code-color: #a39e9b; --theme-popup-bg: #161923; --theme-popup-border: #737480; @@ -341,4 +344,5 @@ --searchresults-border-color: #5c5c68; --searchresults-li-bg: #242430; --search-mark-bg: #a2cff5; +*/ } diff --git a/book/theme/highlight.css b/book/theme/highlight.css index c23432272..8dce7d65f 100644 --- a/book/theme/highlight.css +++ b/book/theme/highlight.css @@ -1,83 +1,56 @@ -/* - * An increased contrast highlighting scheme loosely based on the - * "Base16 Atelier Dune Light" theme by Bram de Haan - * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune) - * Original Base16 color scheme by Chris Kempson - * (https://github.com/chriskempson/base16) - */ - -/* Comment */ +pre code.hljs { + display:block; + overflow-x:auto; + padding:1em +} +code.hljs { + padding:3px 5px +} +.hljs { + background:#2f1e2e; + color:#a39e9b +} .hljs-comment, .hljs-quote { - color: #575757; + color:#8d8687 } - -/* Red */ -.hljs-variable, -.hljs-template-variable, -.hljs-attribute, -.hljs-tag, +.hljs-link, +.hljs-meta, .hljs-name, .hljs-regexp, -.hljs-link, -.hljs-name, +.hljs-selector-class, .hljs-selector-id, -.hljs-selector-class { - color: #d70025; +.hljs-tag, +.hljs-template-variable, +.hljs-variable { + color:#ef6155 } - -/* Orange */ -.hljs-number, -.hljs-meta, .hljs-built_in, -.hljs-builtin-name, +.hljs-deletion, .hljs-literal, -.hljs-type, -.hljs-params { - color: #b21e00; +.hljs-number, +.hljs-params, +.hljs-type { + color:#f99b15 } - -/* Green */ +.hljs-attribute, +.hljs-section, +.hljs-title { + color:#fec418 +} +.hljs-addition, +.hljs-bullet, .hljs-string, -.hljs-symbol, -.hljs-bullet { - color: #008200; +.hljs-symbol { + color:#48b685 } - -/* Blue */ -.hljs-title, -.hljs-section { - color: #0030f2; -} - -/* Purple */ .hljs-keyword, .hljs-selector-tag { - color: #9d00ec; + color:#815ba4 } - -.hljs { - display: block; - overflow-x: auto; - background: #f6f7f6; - color: #000; - padding: 0.5em; -} - .hljs-emphasis { - font-style: italic; + font-style:italic } - .hljs-strong { - font-weight: bold; -} - -.hljs-addition { - color: #22863a; - background-color: #f0fff4; -} - -.hljs-deletion { - color: #b31d28; - background-color: #ffeef0; + font-weight:700 } diff --git a/runtime/queries/ocaml/highlights.scm b/runtime/queries/ocaml/highlights.scm index 5554574d2..160f2cb41 100644 --- a/runtime/queries/ocaml/highlights.scm +++ b/runtime/queries/ocaml/highlights.scm @@ -60,7 +60,7 @@ [(number) (signed_number)] @number -(character) @constant.builtin.character +(character) @constant.character (string) @string diff --git a/runtime/queries/rust/highlights.scm b/runtime/queries/rust/highlights.scm index c76d6adf8..956a5dacd 100644 --- a/runtime/queries/rust/highlights.scm +++ b/runtime/queries/rust/highlights.scm @@ -149,7 +149,7 @@ (mutable_specifier) @keyword.mut - +; TODO: variable.mut to highlight mutable identifiers via locals.scm ; ------- ; Guess Other Types diff --git a/runtime/themes/dark_plus.toml b/runtime/themes/dark_plus.toml index c105d52b0..7eeb3f952 100644 --- a/runtime/themes/dark_plus.toml +++ b/runtime/themes/dark_plus.toml @@ -34,6 +34,7 @@ "comment" = { fg = "#6A9955" } "string" = { fg = "#ce9178" } +"string.regexp" = { fg = "regex" } "number" = { fg = "#b5cea8" } "escape" = { fg = "#d7ba7d" } diff --git a/runtime/themes/monokai.toml b/runtime/themes/monokai.toml index 2407591a0..a8f03ff3c 100644 --- a/runtime/themes/monokai.toml +++ b/runtime/themes/monokai.toml @@ -34,6 +34,7 @@ "comment" = { fg = "#88846F" } "string" = { fg = "#e6db74" } +"string.regexp" = { fg = "regex" } "number" = { fg = "#ae81ff" } "escape" = { fg = "#ae81ff" } diff --git a/theme.toml b/theme.toml index 867a0d2cf..49f46b0b9 100644 --- a/theme.toml +++ b/theme.toml @@ -28,9 +28,7 @@ escape = "honey" label = "honey" # TODO: diferentiate doc comment -# concat (ERROR) @syntax-error and "MISSING ;" selectors for errors - -module = "#ff0000" +# concat (ERROR) @error.syntax and "MISSING ;" selectors for errors "ui.background" = { bg = "midnight" } "ui.linenr" = { fg = "comet" }