| `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` simply shows each line's number, while `relative` shows the distance from the current line. When unfocused or in insert mode, `relative` will still show absolute line numbers. | `absolute` |
| `cursorline`| Highlight all lines with a cursor. | `false` |
| `cursorcolumn`| Highlight all columns with a cursor. | `false` |
| `gutters`| Gutters to display: Available are `diagnostics` and `diff` and `line-numbers` and `spacer`, note that `diagnostics` also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty | `["diagnostics", "spacer", "line-numbers", "spacer", "diff"]` |
| `auto-completion`| Enable automatic pop up of auto-completion. | `true` |
| `auto-format`| Enable automatic formatting on save. | `true` |
| `auto-save`| Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal. | `false` |
| `idle-timeout`| Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` |
| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |
| `auto-info`| Whether to display infoboxes | `true` |
| `true-color`| Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` |
| `rulers`| List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` |
| `bufferline`| Renders a line at the top of the editor displaying open buffers. Can be `always`, `never` or `multiple` (only shown if more than one buffer is in use) | `never` |
| `color-modes`| Whether to color the mode indicator with different colors depending on the mode itself | `false` |
| Key | Description | Default |
|--|--|---------|
| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `5` |
| `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` simply shows each line's number, while `relative` shows the distance from the current line. When unfocused or in insert mode, `relative` will still show absolute line numbers. | `absolute` |
| `cursorline` | Highlight all lines with a cursor. | `false` |
| `cursorcolumn` | Highlight all columns with a cursor. | `false` |
| `gutters` | Gutters to display: Available are `diagnostics` and `diff` and `line-numbers` and `spacer`, note that `diagnostics` also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty | `["diagnostics", "spacer", "line-numbers", "spacer", "diff"]` |
| `auto-completion` | Enable automatic pop up of auto-completion. | `true` |
| `auto-save` | Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal. | `false` |
| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` |
| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |
| `auto-info` | Whether to display infoboxes | `true` |
| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` |
| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` |
| `bufferline` | Renders a line at the top of the editor displaying open buffers. Can be `always`, `never` or `multiple` (only shown if more than one buffer is in use) | `never` |
| `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` |
### `[editor.statusline]` Section
@ -127,10 +125,10 @@ The following statusline elements can be configured:
### `[editor.cursor-shape]` Section
Defines the shape of cursor in each mode. Valid values for these options are
`block`, `bar`, `underline`,or `hidden`.
Defines the shape of cursor in each mode.
Valid values for these options are `block`, `bar`, `underline`,or `hidden`.
> 💡Due to limitations of the terminal environment, only the primary cursor can
> 💡Due to limitations of the terminal environment, only the primary cursor can
> change shape.
| Key | Description | Default |
@ -145,20 +143,20 @@ Defines the shape of cursor in each mode. Valid values for these options are
### `[editor.file-picker]` Section
Set options for file picker and global search. Ignoring a file means it is not
visible in the Helix file picker and global search.
Sets options for file picker and global search. Ignoring a file means it is
not visible in the Helix file picker and global search.
All git related options are only enabled in a git repository.
> at the invocation of `static_commands!` macro and the `TypableCommandList`.
> Commands can also be found in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`.
Where `key` represents what you want to style, `fg` specifies the foreground
color, `bg` the background color, `underline` the underline `style`/`color`, and
`modifiers` is a list of style modifiers. `bg`, `underline` and `modifiers` can
be omitted to defer to the defaults.
Where `key` represents what you want to style, `fg` specifies the foreground color, `bg` the background color, `underline` the underline `style`/`color`, and `modifiers` is a list of style modifiers. `bg`, `underline` and `modifiers` can be omitted to defer to the defaults.
To specify only the foreground color:
@ -37,8 +37,7 @@ To specify only the foreground color:
key = "#ffffff"
```
If the key contains a dot `'.'`, it must be quoted to prevent it being parsed as
a [dotted key](https://toml.io/en/v1.0.0#keys).
If the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).
```toml
"key.key" = "#ffffff"
@ -55,16 +54,16 @@ If you plan to submit your theme for inclusion in Helix, it is recommended to
use the supplied linting tool to ensure compliance with the specifications:
```sh
cargo xtask themelint onedark # replace onedark with <name>
cargo xtask themelint onedark # replace onedark with <name>
```
## The Details of Theme Creation
### Color palettes
It's recommended to define a palette of named colors and refer to them in the
configuration values in your theme. To do this, add a table called`palette` to
your theme file:
It's recommended to define a palette of named colors, and refer to them in the
configuration values in your theme. To do this, add a table called
`palette` to your theme file:
```toml
"ui.background" = "white"
@ -75,8 +74,8 @@ white = "#ffffff"
black = "#000000"
```
Keep in mind that the [palette] table includes all keys after its header, so it
should be defined after the normal theme options.
Keep in mind that the `[palette]` table includes all keys after its header,
so it should be defined after the normal theme options.
The default palette uses the terminal's default 16 colors, and the colors names
are listed below. The `[palette]` section in the config file takes precedence
@ -103,29 +102,37 @@ over it and is merged into the default palette.
### Modifiers
The following values can be used as modifiers, providing they are supported by
The following values may be used as modifier, provided they are supported by
your terminal emulator.
| Modifier |
| ------------- |
| `bold` |
| `dim` |
| `italic` |
| `underlined` |
| `slow_blink` |
| `rapid_blink` |
| `reversed` |
| `hidden` |
| `crossed_out` |
> 💡 The `underlined` modifier is deprecated and only available for backwards
> compatibility. Its behavior is equivalent to setting `underline.style="line"`.
| Modifier |
| --- |
| `bold`|
| `dim`|
| `italic`|
| `underlined`|
| `slow_blink`|
| `rapid_blink`|
| `reversed`|
| `hidden`|
| `crossed_out`|
> 💡 The `underlined` modifier is deprecated and only available for backwards compatibility.
> Its behavior is equivalent to setting `underline.style="line"`.
### Underline Style
One of the following values can be used for `underline.style`, providing it is
One of the following values may be used as a value for `underline.style`, providing it is
supported by your terminal emulator.
| Modifier |
| --- |
| `line` |
| `curl` |
| `dashed` |
| `dotted` |
| `double_line` |
| Modifier |
| ------------- |
| `line` |
@ -136,7 +143,7 @@ supported by your terminal emulator.
### Inheritance
Extends other themes by setting the `inherits` property to an existing theme.
Extend other themes by setting the `inherits` property to an existing theme.
```toml
inherits = "boo_berry"
@ -158,9 +165,7 @@ The following is a list of scopes available to use for styling:
When determining styling for a highlight, the longest matching theme key will be
used. For example, if the highlight is `function.builtin.static,` the key
`function.builtin` will be used instead of function.
When determining styling for a highlight, the longest matching theme key will be used. For example, if the highlight is `function.builtin.static`, the key `function.builtin` will be used instead of `function`.
We use a similar set of scopes as
[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also
@ -174,10 +179,8 @@ We use a similar set of scopes as
- `variant`
- `constructor`
- `constant` (TODO: constant.other.placeholder for `%v)`
- `builtin` Special constants provided by the language (`true`, `false`, `nil`
etc.)
- `constant` (TODO: constant.other.placeholder for `%v`)
- `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)
- `boolean`
- `character`
- `escape`
@ -285,53 +288,58 @@ These scopes are used for theming the editor interface:
@ -5,6 +5,7 @@ Helix releases are versioned in the Calendar Versioning scheme:
we'll use `<tag>` as a placeholder for the tag being published.
* Merge the changelog PR
* Add new `<release>` entry in `contrib/Helix.appdata.xml` with release information according to the [AppStream spec](https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Releases.html)
David-Else
1 year ago