commit 4648d89d50bd617256837a0a917f316efc7c7182
parent 96957d80c6c3f8259e02292a29fe2e4a52ece710
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sat, 21 Feb 2026 14:52:13 -0500
docs: highlight, terminal SGR #37998
Diffstat:
6 files changed, 89 insertions(+), 97 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -1544,40 +1544,41 @@ nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()*
• {name} (`string`) Highlight group name, e.g. "ErrorMsg"
• {val} (`vim.api.keyset.highlight`) Highlight definition map,
accepts the following keys:
- • fg: color name or "#RRGGBB", see note.
• bg: color name or "#RRGGBB", see note.
- • fg_indexed: boolean When true, fg is a terminal palette
- index (0-255). Default is false.
- • bg_indexed: boolean Same as fg_indexed, but for background
- color.
- • sp: color name or "#RRGGBB"
+ • bg_indexed: boolean (default false) If true, bg is a
+ terminal palette index (0-255).
• blend: integer between 0 and 100
- • bold: boolean
+ • cterm: cterm attribute map, like |highlight-args|. If not
+ set, cterm attributes will match those from the attribute
+ map documented above.
+ • ctermbg: Sets background of cterm color |ctermbg|
+ • ctermfg: Sets foreground of cterm color |ctermfg|
+ • default: boolean Don't override existing definition
+ |:hi-default|
+ • fg: color name or "#RRGGBB", see note.
+ • fg_indexed: boolean (default false) If true, fg is a
+ terminal palette index (0-255).
+ • force: if true force update the highlight group when it
+ exists.
+ • link: Name of highlight group to link to. |:hi-link|
+ • sp: color name or "#RRGGBB"
• altfont: boolean
• blink: boolean
+ • bold: boolean
+ • conceal: boolean Concealment at the UI level (terminal
+ SGR), unrelated to |:syn-conceal|.
• dim: boolean
- • conceal: boolean
+ • italic: boolean
+ • nocombine: boolean
• overline: boolean
+ • reverse: boolean
• standout: boolean
- • underline: boolean
+ • strikethrough: boolean
• undercurl: boolean
- • underdouble: boolean
- • underdotted: boolean
• underdashed: boolean
- • strikethrough: boolean
- • italic: boolean
- • reverse: boolean
- • nocombine: boolean
- • link: name of another highlight group to link to, see
- |:hi-link|.
- • default: Don't override existing definition |:hi-default|
- • ctermfg: Sets foreground of cterm color |ctermfg|
- • ctermbg: Sets background of cterm color |ctermbg|
- • cterm: cterm attribute map, like |highlight-args|. If not
- set, cterm attributes will match those from the attribute
- map documented above.
- • force: if true force update the highlight group when it
- exists.
+ • underdotted: boolean
+ • underdouble: boolean
+ • underline: boolean
nvim_set_hl_ns({ns_id}) *nvim_set_hl_ns()*
Set active namespace for highlights defined with |nvim_set_hl()|. This can
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
@@ -2187,7 +2187,6 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end
--- values of the Normal group. If the Normal group has not been defined,
--- using these values results in an error.
---
----
--- If `link` is used in combination with other attributes; only the
--- `link` will take effect (see |:hi-link|).
---
@@ -2198,39 +2197,35 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end
--- `nvim_set_hl_ns()` or `nvim_win_set_hl_ns()` to activate them.
--- @param name string Highlight group name, e.g. "ErrorMsg"
--- @param val vim.api.keyset.highlight Highlight definition map, accepts the following keys:
---- - fg: color name or "#RRGGBB", see note.
--- - bg: color name or "#RRGGBB", see note.
---- - fg_indexed: boolean
---- When true, fg is a terminal palette index (0-255).
---- Default is false.
---- - bg_indexed: boolean
---- Same as fg_indexed, but for background color.
---- - sp: color name or "#RRGGBB"
+--- - bg_indexed: boolean (default false) If true, bg is a terminal palette index (0-255).
--- - blend: integer between 0 and 100
---- - bold: boolean
+--- - cterm: cterm attribute map, like `highlight-args`. If not set, cterm attributes
+--- will match those from the attribute map documented above.
+--- - ctermbg: Sets background of cterm color `ctermbg`
+--- - ctermfg: Sets foreground of cterm color `ctermfg`
+--- - default: boolean Don't override existing definition `:hi-default`
+--- - fg: color name or "#RRGGBB", see note.
+--- - fg_indexed: boolean (default false) If true, fg is a terminal palette index (0-255).
+--- - force: if true force update the highlight group when it exists.
+--- - link: Name of highlight group to link to. `:hi-link`
+--- - sp: color name or "#RRGGBB"
--- - altfont: boolean
--- - blink: boolean
+--- - bold: boolean
+--- - conceal: boolean Concealment at the UI level (terminal SGR), unrelated to `:syn-conceal`.
--- - dim: boolean
---- - conceal: boolean
+--- - italic: boolean
+--- - nocombine: boolean
--- - overline: boolean
+--- - reverse: boolean
--- - standout: boolean
---- - underline: boolean
+--- - strikethrough: boolean
--- - undercurl: boolean
---- - underdouble: boolean
---- - underdotted: boolean
--- - underdashed: boolean
---- - strikethrough: boolean
---- - italic: boolean
---- - reverse: boolean
---- - nocombine: boolean
---- - link: name of another highlight group to link to, see `:hi-link`.
---- - default: Don't override existing definition `:hi-default`
---- - ctermfg: Sets foreground of cterm color `ctermfg`
---- - ctermbg: Sets background of cterm color `ctermbg`
---- - cterm: cterm attribute map, like `highlight-args`. If not set,
---- cterm attributes will match those from the attribute map
---- documented above.
---- - force: if true force update the highlight group when it exists.
+--- - underdotted: boolean
+--- - underdouble: boolean
+--- - underline: boolean
function vim.api.nvim_set_hl(ns_id, name, val) end
--- Set active namespace for highlights defined with `nvim_set_hl()`. This can be set for
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
@@ -295,22 +295,22 @@ error('Cannot require a meta file')
--- @field winid? integer
--- @class vim.api.keyset.highlight
+--- @field altfont? boolean
+--- @field blink? boolean
--- @field bold? boolean
+--- @field conceal? boolean
+--- @field dim? boolean
+--- @field italic? boolean
+--- @field nocombine? boolean
+--- @field overline? boolean
+--- @field reverse? boolean
--- @field standout? boolean
--- @field strikethrough? boolean
---- @field underline? boolean
--- @field undercurl? boolean
---- @field underdouble? boolean
---- @field underdotted? boolean
--- @field underdashed? boolean
---- @field italic? boolean
---- @field reverse? boolean
---- @field altfont? boolean
---- @field dim? boolean
---- @field blink? boolean
---- @field conceal? boolean
---- @field overline? boolean
---- @field nocombine? boolean
+--- @field underdotted? boolean
+--- @field underdouble? boolean
+--- @field underline? boolean
--- @field default? boolean
--- @field cterm? vim.api.keyset.highlight_cterm
--- @field foreground? integer|string
diff --git a/src/nvim/api/keysets_defs.h b/src/nvim/api/keysets_defs.h
@@ -168,22 +168,22 @@ typedef struct {
typedef struct {
OptionalKeys is_set__highlight_;
+ Boolean altfont;
+ Boolean blink;
Boolean bold;
+ Boolean conceal;
+ Boolean dim;
+ Boolean italic;
+ Boolean nocombine;
+ Boolean overline;
+ Boolean reverse;
Boolean standout;
Boolean strikethrough;
- Boolean underline;
Boolean undercurl;
- Boolean underdouble;
- Boolean underdotted;
Boolean underdashed;
- Boolean italic;
- Boolean reverse;
- Boolean altfont;
- Boolean dim;
- Boolean blink;
- Boolean conceal;
- Boolean overline;
- Boolean nocombine;
+ Boolean underdotted;
+ Boolean underdouble;
+ Boolean underline;
Boolean default_ DictKey(default);
DictAs(highlight_cterm) cterm;
Union(Integer, String) foreground;
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
@@ -132,7 +132,6 @@ DictAs(get_hl_info) nvim_get_hl(Integer ns_id, Dict(get_highlight) *opts, Arena
/// values of the Normal group. If the Normal group has not been defined,
/// using these values results in an error.
///
-///
/// @note If `link` is used in combination with other attributes; only the
/// `link` will take effect (see |:hi-link|).
///
@@ -142,39 +141,35 @@ DictAs(get_hl_info) nvim_get_hl(Integer ns_id, Dict(get_highlight) *opts, Arena
/// |nvim_set_hl_ns()| or |nvim_win_set_hl_ns()| to activate them.
/// @param name Highlight group name, e.g. "ErrorMsg"
/// @param val Highlight definition map, accepts the following keys:
-/// - fg: color name or "#RRGGBB", see note.
/// - bg: color name or "#RRGGBB", see note.
-/// - fg_indexed: boolean
-/// When true, fg is a terminal palette index (0-255).
-/// Default is false.
-/// - bg_indexed: boolean
-/// Same as fg_indexed, but for background color.
-/// - sp: color name or "#RRGGBB"
+/// - bg_indexed: boolean (default false) If true, bg is a terminal palette index (0-255).
/// - blend: integer between 0 and 100
-/// - bold: boolean
+/// - cterm: cterm attribute map, like |highlight-args|. If not set, cterm attributes
+/// will match those from the attribute map documented above.
+/// - ctermbg: Sets background of cterm color |ctermbg|
+/// - ctermfg: Sets foreground of cterm color |ctermfg|
+/// - default: boolean Don't override existing definition |:hi-default|
+/// - fg: color name or "#RRGGBB", see note.
+/// - fg_indexed: boolean (default false) If true, fg is a terminal palette index (0-255).
+/// - force: if true force update the highlight group when it exists.
+/// - link: Name of highlight group to link to. |:hi-link|
+/// - sp: color name or "#RRGGBB"
/// - altfont: boolean
/// - blink: boolean
+/// - bold: boolean
+/// - conceal: boolean Concealment at the UI level (terminal SGR), unrelated to |:syn-conceal|.
/// - dim: boolean
-/// - conceal: boolean
+/// - italic: boolean
+/// - nocombine: boolean
/// - overline: boolean
+/// - reverse: boolean
/// - standout: boolean
-/// - underline: boolean
+/// - strikethrough: boolean
/// - undercurl: boolean
-/// - underdouble: boolean
-/// - underdotted: boolean
/// - underdashed: boolean
-/// - strikethrough: boolean
-/// - italic: boolean
-/// - reverse: boolean
-/// - nocombine: boolean
-/// - link: name of another highlight group to link to, see |:hi-link|.
-/// - default: Don't override existing definition |:hi-default|
-/// - ctermfg: Sets foreground of cterm color |ctermfg|
-/// - ctermbg: Sets background of cterm color |ctermbg|
-/// - cterm: cterm attribute map, like |highlight-args|. If not set,
-/// cterm attributes will match those from the attribute map
-/// documented above.
-/// - force: if true force update the highlight group when it exists.
+/// - underdotted: boolean
+/// - underdouble: boolean
+/// - underline: boolean
/// @param[out] err Error details, if any
///
// TODO(bfredl): val should take update vs reset flag
diff --git a/src/nvim/highlight_defs.h b/src/nvim/highlight_defs.h
@@ -27,6 +27,7 @@ typedef enum {
HL_ALTFONT = 0x0100,
HL_DIM = 0x0200,
HL_BLINK = 0x8000,
+ // SGR attribute, unrelated to HL_CONCEAL syntax flag.
HL_CONCEALED = 0x10000,
HL_OVERLINE = 0x20000,
HL_NOCOMBINE = 0x0400,
