| `scroll-lines`| Number of lines to scroll per scroll wheel step. | `3` |
| `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"]` |
| `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` |
| `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` |
| `cursorline` | Highlight all lines with a cursor. | `false` |
| `cursorcolumn`| Highlight all columns 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"]` |
| `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-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` |
| `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` |
| `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` |
| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |
| `auto-info`| Whether to display infoboxes | `true` |
| `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` |
| `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. | `[]` |
| `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` |
| `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` |
| `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` |
### `[editor.statusline]` Section
### `[editor.statusline]` Section
@ -127,10 +125,10 @@ The following statusline elements can be configured:
### `[editor.cursor-shape]` Section
### `[editor.cursor-shape]` Section
Defines the shape of cursor in each mode. Valid values for these options are
Defines the shape of cursor in each mode.
`block`, `bar`, `underline`,or `hidden`.
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.
> change shape.
| Key | Description | Default |
| 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
### `[editor.file-picker]` Section
Set options for file picker and global search. Ignoring a file means it is not
Sets options for file picker and global search. Ignoring a file means it is
visible in the Helix file picker and global search.
not visible in the Helix file picker and global search.
All git related options are only enabled in a git repository.
All git related options are only enabled in a git repository.
> Commands can also be found in the source code at
> 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
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.
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:
To specify only the foreground color:
@ -37,8 +37,7 @@ To specify only the foreground color:
key = "#ffffff"
key = "#ffffff"
```
```
If the key contains a dot `'.'`, it must be quoted to prevent it being parsed as
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).
a [dotted key](https://toml.io/en/v1.0.0#keys).
```toml
```toml
"key.key" = "#ffffff"
"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:
use the supplied linting tool to ensure compliance with the specifications:
```sh
```sh
cargo xtask themelint onedark # replace onedark with <name>
cargo xtask themelint onedark # replace onedark with <name>
```
```
## The Details of Theme Creation
## The Details of Theme Creation
### Color palettes
### Color palettes
It's recommended to define a palette of named colors and refer to them in the
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
configuration values in your theme. To do this, add a table called
your theme file:
`palette` to your theme file:
```toml
```toml
"ui.background" = "white"
"ui.background" = "white"
@ -75,8 +74,8 @@ white = "#ffffff"
black = "#000000"
black = "#000000"
```
```
Keep in mind that the [palette] table includes all keys after its header, so it
Keep in mind that the `[palette]` table includes all keys after its header,
should be defined after the normal theme options.
so it should be defined after the normal theme options.
The default palette uses the terminal's default 16 colors, and the colors names
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
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
### 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.
your terminal emulator.
| Modifier |
| Modifier |
| ------------- |
| --- |
| `bold` |
| `bold`|
| `dim` |
| `dim`|
| `italic` |
| `italic`|
| `underlined` |
| `underlined`|
| `slow_blink` |
| `slow_blink`|
| `rapid_blink` |
| `rapid_blink`|
| `reversed` |
| `reversed`|
| `hidden` |
| `hidden`|
| `crossed_out` |
| `crossed_out`|
> 💡 The `underlined` modifier is deprecated and only available for backwards
> 💡 The `underlined` modifier is deprecated and only available for backwards compatibility.
> compatibility. Its behavior is equivalent to setting `underline.style="line"`.
> Its behavior is equivalent to setting `underline.style="line"`.
### Underline Style
### 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.
supported by your terminal emulator.
| Modifier |
| --- |
| `line` |
| `curl` |
| `dashed` |
| `dotted` |
| `double_line` |
| Modifier |
| Modifier |
| ------------- |
| ------------- |
| `line` |
| `line` |
@ -136,7 +143,7 @@ supported by your terminal emulator.
### Inheritance
### 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
```toml
inherits = "boo_berry"
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
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`.
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
We use a similar set of scopes as
[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also
[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`
- `variant`
- `constructor`
- `constructor`
- `constant` (TODO: constant.other.placeholder for `%v)`
- `constant` (TODO: constant.other.placeholder for `%v`)
- `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)
- `builtin` Special constants provided by the language (`true`, `false`, `nil`
etc.)
- `boolean`
- `boolean`
- `character`
- `character`
- `escape`
- `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.
we'll use `<tag>` as a placeholder for the tag being published.
* Merge the changelog PR
* 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