Faces

#1

Declaration

A face refers how the specified text is displayed, it has a foreground
color, a background color, and some attributes. The value of a face has
the following format:

fg_color[,bg_color][+attributes][@base]

fg_color, bg_color
a color whose value can be expressed in the following formats:

black, red, green, yellow, blue, magenta, cyan, white; bright-black, bright-red, bright-green, bright-yellow; bright-blue, bright-magenta, bright-cyan, bright-white
a named color

default
keep the existing color

rgb:RRGGBB
hexadecimal value

attributes
string whose individual letters set an attribute:

u
underline

r
reverse

b
bold

B
blink

d
dim

i
italic

F
final, override the previous face instead of merging with it an will
only be replaced if another face with the final attribute is applied

f
final foreground, as final but only applies to face’s foreground color

g
final background, as final but only applies to face’s background color

a
final attributes, as final but only applies to face’s attributes

base
The base face on which this face applies, which can be any face name, as
long as a cycle is not introduced. A face can reference itself, in which
case it will apply on top of the parent scope version.

Builtin faces

The following default faces are used by color schemes to highlight
certain areas of the user interface:

Default
default colors

PrimarySelection
main selection face for every selected character except the cursor

SecondarySelection
secondary selection face for every selected character except the cursor

PrimaryCursor
cursor of the primary selection

SecondaryCursor
cursor of the secondary selection

PrimaryCursorEol
cursor of the primary selection when it lies on and end of line
character

SecondaryCursorEol
cursor of the secondary selection when it lies on and end of line
character

MenuForeground
face for the selected element in menus

MenuBackground
face for the not selected elements in menus

MenuInfo
face for additional information for elements in menus

Information
face for the informations windows and information messages

Error
face of error messages

StatusLine
face used for the status line

StatusLineMode
face used for the current mode except the normal mode

StatusLineInfo
face used for special information

StatusLineValue
face used for special values (numeric prefixes, registers, etc.)

StatusCursor
face used for the status line cursor

Prompt
face used prompt displayed on the status line

BufferPadding
face applied on the ~ characters that follow the last line of a buffer

Builtin highlighters faces

The following faces are used by builtin highlighters if enabled. (See
:doc highlighters).

LineNumbers
face used by the number-lines highlighter

LineNumberCursor
face used to highlight the line number of the main selection

LineNumbersWrapped
face used to highlight the line number of wrapped lines

MatchingChar
face used by the show-matching highlighter

Whitespace
face used by the show-whitespaces highlighter

Markup strings

In certain contexts, Kakoune can take a markup string, which is a string
syntax will enable the face facename until another face gets activated,
or the end of the string is reached.

For example, the following command displays the text “default” in the
Default face, and “error” in the Error face:

echo -markup 'default {Error}error{Default} default'

Inside a markup string, a literal { character is written \{, and a
literal backslash (\) that precedes a { character is escaped as well
(\\).

Interfacing
Scopes