helix

Unnamed repository; edit this file 'description' to name the repository.

master 24Branches 30Tags

Clone

HTTPS

SSH

Open with VS Code

Diffstat (limited to 'book/src/themes.md')

-rw-r--r--

book/src/themes.md

257

1 files changed, 96 insertions, 161 deletions

diff --git a/book/src/themes.md b/book/src/themes.md
index 353a4684..322caea5 100644
--- a/book/src/themes.md
+++ b/book/src/themes.md

@@ -1,26 +1,14 @@

-## Themes

+# Themes

-To use a theme add `theme = "<name>"` to the top of your [`config.toml`](./configuration.md) file, or select it during runtime using `:theme <name>`.

-Separate themes can be configured for light and dark modes. On terminals supporting [mode 2031 dark/light detection](https://github.com/contour-terminal/contour/blob/master/docs/vt-extensions/color-palette-update-notifications.md), the theme mode is detected from the terminal.

-```toml

-[theme]

-dark = "catppuccin_frappe"

-light = "catppuccin_latte"

-## Optional. Used if the terminal doesn't declare a preference.

-## Defaults to the theme set for `dark` if not specified.

-# fallback = "catppuccin_frappe"

-```

+To use a theme add `theme = "<name>"` to your [`config.toml`](./configuration.md) at the very top of the file before the first section or select it during runtime using `:theme <name>`.

## Creating a theme

-Create a file with the name of your theme as the file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes` or `%AppData%\helix\themes` on Windows). The directory might have to be created beforehand.

+Create a file with the name of your theme as file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes`). The directory might have to be created beforehand.

-> 💡 The names "default" and "base16_default" are reserved for built-in themes

-> and cannot be overridden by user-defined themes.

+The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes.

-### Overview

+The default theme.toml can be found [here](https://github.com/helix-editor/helix/blob/master/theme.toml), and user submitted themes [here](https://github.com/helix-editor/helix/blob/master/runtime/themes).

Each line in the theme file is specified as below:

@@ -28,7 +16,7 @@ Each line in the theme file is specified as below:

key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] }

```

-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:

@@ -36,23 +24,15 @@ 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"

```

-For inspiration, you can find the default `theme.toml`

-[here](https://github.com/helix-editor/helix/blob/master/theme.toml) and

-user-submitted themes

-[here](https://github.com/helix-editor/helix/blob/master/runtime/themes).

-## The details of theme creation

### Color palettes

-It's recommended to define a palette of named colors, and refer to them in 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:

@@ -65,8 +45,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.

+Remember that the `[palette]` table includes all keys after its header,

+so you should define the palette after 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

@@ -74,7 +54,6 @@ over it and is merged into the default palette.

| Color Name |

| --- |

-| `default` |

| `black` |

| `red` |

| `green` |

@@ -94,8 +73,9 @@ over it and is merged into the default palette.

### Modifiers

-The following values may be used as modifier, provided they are supported by

-your terminal emulator.

+The following values may be used as modifiers.

+Less common modifiers might not be supported by your terminal emulator.

| Modifier |

| --- |

@@ -109,13 +89,14 @@ your terminal emulator.

| `hidden` |

| `crossed_out` |

-> 💡 The `underlined` modifier is deprecated and only available for backwards compatibility.

+> Note: The `underlined` modifier is deprecated and only available for backwards compatibility.

> Its behavior is equivalent to setting `underline.style="line"`.

-### Underline style

+### Underline Style

+One of the following values may be used as a value for `underline.style`.

-One of the following values may be used as a value for `underline.style`, providing it is

-supported by your terminal emulator.

+Some styles might not be supported by your terminal emulator.

| Modifier |

| --- |

@@ -128,7 +109,7 @@ supported by your terminal emulator.

### Inheritance

-Extend other themes by setting the `inherits` property to an existing theme.

+Extend upon other themes by setting the `inherits` property to an existing theme.

```toml

inherits = "boo_berry"

@@ -141,41 +122,27 @@ inherits = "boo_berry"

berry = "#2A2A4D"

```

-### Rainbow

-The `rainbow` key is used for rainbow highlight for matching brackets.

-The key is a list of styles.

-```toml

-rainbow = ["#ff0000", "#ffa500", "#fff000", { fg = "#00ff00", modifiers = ["bold"] }]

-```

-Colors from the palette and modifiers may be used.

### Scopes

-The following is a list of scopes available to use for styling:

+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/3-syntax-highlighting.html#highlights).

+These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme).

-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`.

+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

-[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also

+[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also

[TextMate](https://macromates.com/manual/en/language_grammars) scopes.

-- `attribute` - Class attributes, HTML tag attributes

+- `attribute` - Class attributes, html tag attributes

- `type` - Types

- `builtin` - Primitive types provided by the language (`int`, `usize`)

- - `parameter` - Generic type parameters (`T`)

- - `enum`

- - `variant`

- `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)

- `boolean`

- `character`

@@ -193,19 +160,16 @@ We use a similar set of scopes as

- `comment` - Code comments

- `line` - Single line comments (`//`)

- - `documentation` - Line documentation comments (e.g. `///` in Rust)

- - `block` - Block comments (e.g. (`/* */`)

- - `documentation` - Block documentation comments (e.g. `/** */` in Rust)

- - `unused` - Unused variables and patterns, e.g. `_` and `_foo`

+ - `block` - Block comments (e.g. (`/* */`)

+ - `documentation` - Documentation comments (e.g. `///` in Rust)

- `variable` - Variables

- - `builtin` - Reserved language variables (`self`, `this`, `super`, etc.)

+ - `builtin` - Reserved language variables (`self`, `this`, `super`, etc)

- `parameter` - Function parameters

- `other`

- `member` - Fields of composite data types (e.g. structs, unions)

- - `private` - Private fields that use a unique syntax (currently just ECMAScript-based languages)

-- `label` - `.class`, `#id` in CSS, etc.

+- `label`

- `punctuation`

- `delimiter` - Commas, colons

@@ -220,10 +184,10 @@ We use a similar set of scopes as

- `return`

- `exception`

- `operator` - `or`, `in`

- - `directive` - Preprocessor directives (`#if` in C)

+ - `directive` - Preprocessor directives (`#if` in C)

- `function` - `fn`, `func`

- `storage` - Keywords describing how things are stored

- - `type` - The type of something, `class`, `function`, `var`, `let`, etc.

+ - `type` - The type of something, `class`, `function`, `var`, `let`, etc.

- `modifier` - Storage modifiers like `static`, `mut`, `const`, `ref`, etc.

- `operator` - `||`, `+=`, `>`

@@ -231,17 +195,13 @@ We use a similar set of scopes as

- `function`

- `builtin`

- `method`

- - `private` - Private methods that use a unique syntax (currently just ECMAScript-based languages)

- `macro`

- `special` (preprocessor in C)

- `tag` - Tags (e.g. `<body>` in HTML)

- - `builtin`

- `namespace`

-- `special` - `derive` in Rust, etc.

- `markup`

- `heading`

- `marker`

@@ -249,15 +209,12 @@ We use a similar set of scopes as

- `list`

- `unnumbered`

- `numbered`

- - `checked`

- - `unchecked`

- `bold`

- `italic`

- - `strikethrough`

- `link`

- - `url` - URLs pointed to by links

- - `label` - non-URL link references

- - `text` - URL and image descriptions in links

+ - `url` - urls pointed to by links

+ - `label` - non-url link references

+ - `text` - url and image descriptions in links

- `quote`

- `raw`

- `inline`

@@ -265,101 +222,79 @@ We use a similar set of scopes as

- `diff` - version control changes

- `plus` - additions

- - `gutter` - gutter indicator

- `minus` - deletions

- - `gutter` - gutter indicator

- `delta` - modifications

- `moved` - renamed or moved files/changes

- - `conflict` - merge conflicts

- - `gutter` - gutter indicator

#### Interface

-These scopes are used for theming the editor interface:

+These scopes are used for theming the editor interface.

- `markup`

- `normal`

- - `completion` - for completion doc popup UI

- - `hover` - for hover popup UI

+ - `completion` - for completion doc popup ui

+ - `hover` - for hover popup ui

- `heading`

- - `completion` - for completion doc popup UI

- - `hover` - for hover popup UI

+ - `completion` - for completion doc popup ui

+ - `hover` - for hover popup ui

- `raw`

- `inline`

- - `completion` - for completion doc popup UI

- - `hover` - for hover popup UI

-| Key | Notes |

-| --- | --- |

-| `ui.background` | |

-| `ui.background.separator` | Picker separator below input line |

-| `ui.cursor` | |

-| `ui.cursor.normal` | |

-| `ui.cursor.insert` | |

-| `ui.cursor.select` | |

-| `ui.cursor.match` | Matching bracket etc. |

-| `ui.cursor.primary` | Cursor with primary selection |

-| `ui.cursor.primary.normal` | |

-| `ui.cursor.primary.insert` | |

-| `ui.cursor.primary.select` | |

-| `ui.debug.breakpoint` | Breakpoint indicator, found in the gutter |

-| `ui.debug.active` | Indicator for the line at which debugging execution is paused at, found in the gutter |

-| `ui.gutter` | Gutter |

-| `ui.gutter.selected` | Gutter for the line the cursor is on |

-| `ui.linenr` | Line numbers |

-| `ui.linenr.selected` | Line number for the line the cursor is on |

-| `ui.statusline` | Statusline |

-| `ui.statusline.inactive` | Statusline (unfocused document) |

-| `ui.statusline.normal` | Statusline mode during normal mode ([only if `editor.color-modes` is enabled][editor-section]) |

-| `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |

-| `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |

-| `ui.statusline.separator` | Separator character in statusline |

-| `ui.bufferline` | Style for the buffer line |

-| `ui.bufferline.active` | Style for the active buffer in buffer line |

-| `ui.bufferline.background` | Style for bufferline background |

-| `ui.popup` | Documentation popups (e.g. Space + k) |

-| `ui.popup.info` | Prompt for multiple key options |

-| `ui.picker.header` | Header row area in pickers with multiple columns |

-| `ui.picker.header.column` | Column names in pickers with multiple columns |

-| `ui.picker.header.column.active` | The column name in pickers with multiple columns where the cursor is entering into. |

-| `ui.window` | Borderlines separating splits |

-| `ui.help` | Description box for commands |

-| `ui.text` | Default text style, command prompts, popup text, etc. |

-| `ui.text.focus` | The currently selected line in the picker |

-| `ui.text.inactive` | Same as `ui.text` but when the text is inactive (e.g. suggestions) |

-| `ui.text.info` | The key: command text in `ui.popup.info` boxes |

-| `ui.text.directory` | Directory names in prompt completion |

-| `ui.virtual.ruler` | Ruler columns (see the [`editor.rulers` config][editor-section]) |

-| `ui.virtual.whitespace` | Visible whitespace characters |

-| `ui.virtual.indent-guide` | Vertical indent width guides |

-| `ui.virtual.inlay-hint` | Default style for inlay hints of all kinds |

-| `ui.virtual.inlay-hint.parameter` | Style for inlay hints of kind `parameter` (language servers are not required to set a kind) |

-| `ui.virtual.inlay-hint.type` | Style for inlay hints of kind `type` (language servers are not required to set a kind) |

-| `ui.virtual.wrap` | Soft-wrap indicator (see the [`editor.soft-wrap` config][editor-section]) |

-| `ui.virtual.jump-label` | Style for virtual jump labels |

-| `ui.menu` | Code and command completion menus |

-| `ui.menu.selected` | Selected autocomplete item |

-| `ui.menu.scroll` | `fg` sets thumb color, `bg` sets track color of scrollbar |

-| `ui.selection` | For selections in the editing area |

-| `ui.selection.primary` | |

-| `ui.highlight` | Highlighted lines in the picker preview |

-| `ui.highlight.frameline` | Line at which debugging execution is paused at |

-| `ui.cursorline.primary` | The line of the primary cursor ([if cursorline is enabled][editor-section]) |

-| `ui.cursorline.secondary` | The lines of any other cursors ([if cursorline is enabled][editor-section]) |

-| `ui.cursorcolumn.primary` | The column of the primary cursor ([if cursorcolumn is enabled][editor-section]) |

-| `ui.cursorcolumn.secondary` | The columns of any other cursors ([if cursorcolumn is enabled][editor-section]) |

-| `warning` | Diagnostics warning (gutter) |

-| `error` | Diagnostics error (gutter) |

-| `info` | Diagnostics info (gutter) |

-| `hint` | Diagnostics hint (gutter) |

-| `diagnostic` | Diagnostics fallback style (editing area) |

-| `diagnostic.hint` | Diagnostics hint (editing area) |

-| `diagnostic.info` | Diagnostics info (editing area) |

-| `diagnostic.warning` | Diagnostics warning (editing area) |

-| `diagnostic.error` | Diagnostics error (editing area) |

-| `diagnostic.unnecessary` | Diagnostics with unnecessary tag (editing area) |

-| `diagnostic.deprecated` | Diagnostics with deprecated tag (editing area) |

-| `tabstop` | Snippet placeholder |

+ - `completion` - for completion doc popup ui

+ - `hover` - for hover popup ui

+| Key | Notes |

+| --- | --- |

+| `ui.background` | |

+| `ui.background.separator` | Picker separator below input line |

+| `ui.cursor` | |

+| `ui.cursor.insert` | |

+| `ui.cursor.select` | |

+| `ui.cursor.match` | Matching bracket etc. |

+| `ui.cursor.primary` | Cursor with primary selection |

+| `ui.gutter` | Gutter |

+| `ui.gutter.selected` | Gutter for the line the cursor is on |

+| `ui.linenr` | Line numbers |

+| `ui.linenr.selected` | Line number for the line the cursor is on |

+| `ui.statusline` | Statusline |

+| `ui.statusline.inactive` | Statusline (unfocused document) |

+| `ui.statusline.normal` | Statusline mode during normal mode ([only if `editor.color-modes` is enabled][editor-section]) |

+| `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |

+| `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |

+| `ui.statusline.separator` | Separator character in statusline |

+| `ui.popup` | Documentation popups (e.g Space + k) |

+| `ui.popup.info` | Prompt for multiple key options |

+| `ui.window` | Border lines separating splits |

+| `ui.help` | Description box for commands |

+| `ui.text` | Command prompts, popup text, etc. |

+| `ui.text.focus` | |

+| `ui.text.info` | The key: command text in `ui.popup.info` boxes |

+| `ui.virtual.ruler` | Ruler columns (see the [`editor.rulers` config][editor-section]) |

+| `ui.virtual.whitespace` | Visible whitespace characters |

+| `ui.virtual.indent-guide` | Vertical indent width guides |

+| `ui.menu` | Code and command completion menus |

+| `ui.menu.selected` | Selected autocomplete item |

+| `ui.menu.scroll` | `fg` sets thumb color, `bg` sets track color of scrollbar |

+| `ui.selection` | For selections in the editing area |

+| `ui.selection.primary` | |

+| `ui.cursorline.primary` | The line of the primary cursor ([if cursorline is enabled][editor-section]) |

+| `ui.cursorline.secondary` | The lines of any other cursors ([if cursorline is enabled][editor-section]) |

+| `ui.cursorcolumn.primary` | The column of the primary cursor ([if cursorcolumn is enabled][editor-section]) |

+| `ui.cursorcolumn.secondary` | The columns of any other cursors ([if cursorcolumn is enabled][editor-section]) |

+| `warning` | Diagnostics warning (gutter) |

+| `error` | Diagnostics error (gutter) |

+| `info` | Diagnostics info (gutter) |

+| `hint` | Diagnostics hint (gutter) |

+| `diagnostic` | Diagnostics fallback style (editing area) |

+| `diagnostic.hint` | Diagnostics hint (editing area) |

+| `diagnostic.info` | Diagnostics info (editing area) |

+| `diagnostic.warning` | Diagnostics warning (editing area) |

+| `diagnostic.error` | Diagnostics error (editing area) |

+You can check compliance to spec with

+```shell

+cargo xtask themelint onedark # replace onedark with <name>

+```

[editor-section]: ./configuration.md#editor-section