Merge pull request #15114 from theHamsta/treesitter-hl-priority

feat(treesitter): allow to set highlight priority for queries

3 files changed, 18 insertions, 4 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 4dcf5b7bbc..9b8259c2fb 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2334,8 +2334,9 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                                 inserted (true for right, false for left).
                                 Defaults to false.
                               • priority: a priority value for the highlight
-                                group. For example treesitter highlighting
-                                uses a value of 100.
+                                group. Default: 4096. For example, treesitter
+                                highlighting uses a default value of 100 (see
+                                |lua-treesitter-highlight-priority|).
 
                 Return: ~
                     Id of the created/updated extmark
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 416ea3a08a..340db92ae3 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -294,6 +294,19 @@ identical identifiers, highlighting both as |hl-WarningMsg|: >
     ((binary_expression left: (identifier) @WarningMsg.left right: (identifier) @WarningMsg.right)
      (eq? @WarningMsg.left @WarningMsg.right))
 <
+Treesitter Highlighting Priority            *lua-treesitter-highlight-priority*
+
+Tree-sitter uses |nvim_buf_set_extmark()| to set highlights with a default 
+priority of 100. This enables plugins to set a highlighting priority lower or
+higher than tree-sitter. It is also possible to change the priority of an
+individual query pattern manually by setting its `"priority"` metadata attribute: >
+
+    (
+      (super_important_node) @ImportantHighlight
+      ; Give the whole query highlight priority higher than the default (100)
+      (set! "priority" 105)
+    )
+<
 
 ==============================================================================
 Lua module: vim.treesitter                               *lua-treesitter-core*
diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua
index 84b6a5f135..cf3cdf4505 100644
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -248,7 +248,7 @@ local function on_line_impl(self, buf, line)
     end
 
     while line >= state.next_row do
-      local capture, node = state.iter()
+      local capture, node, metadata = state.iter()
 
       if capture == nil then break end
 
@@ -260,7 +260,7 @@ local function on_line_impl(self, buf, line)
                                { end_line = end_row, end_col = end_col,
                                  hl_group = hl,
                                  ephemeral = true,
-                                 priority = 100 -- Low but leaves room below
+                                 priority = tonumber(metadata.priority) or 100 -- Low but leaves room below
                                 })
       end
       if start_row > line then