Home Explore Blog CI



neovim

5th chunk of `runtime/doc/treesitter.txt`
6d1f1a0f616173b28ef2fcc30a58cbe9423d0acb4944120a0000000100000fa2
 `({lang})`.
        Note: This is meant to be used to include queries from another
        language. If you want your query to extend the queries of the same
        language, use `extends`.

    `extends`                                  *treesitter-query-modeline-extends*
        Specifies that this query should be used as an extension for the
        query, i.e. that it should be merged with the others.
        Note: The order of the extensions, and the query that will be used as
        a base depends on your 'runtimepath' value.

Note: These modeline comments must be at the top of the query, but can be
repeated, for example, the following two modeline blocks are both valid:
>query
    ;; inherits: typescript,jsx
    ;; extends
<
>query
    ;; extends
    ;;
    ;; inherits: css
<
==============================================================================
TREESITTER SYNTAX HIGHLIGHTING                          *treesitter-highlight*

Syntax highlighting is specified through queries named `highlights.scm`,
which match a |TSNode| in the parsed |TSTree| to a `capture` that can be
assigned a highlight group. For example, the query >query

    (parameters (identifier) @variable.parameter)
<
matches any `identifier` node inside a function `parameters` node to the
capture named `@variable.parameter`. For example, for a Lua code >lua

    function f(foo, bar) end
<
which will be parsed as (see |:InspectTree|): >query

    (function_declaration ; [1:1 - 24]
      name: (identifier) ; [1:10 - 10]
      parameters: (parameters ; [1:11 - 20]
        name: (identifier) ; [1:12 - 14]
        name: (identifier))) ; [1:17 - 19]
<
the above query will highlight `foo` and `bar` as `@variable.parameter`.

It is also possible to match literal expressions (provided the parser returns
them):
>query
    [
      "if"
      "else"
    ] @keyword.conditional
<
Assuming a suitable parser and `highlights.scm` query is found in runtimepath,
treesitter highlighting for the current buffer can be enabled simply via
|vim.treesitter.start()|.

                                                 *treesitter-highlight-groups*
The capture names, prefixed with `@`, are directly usable as highlight groups.
For many commonly used captures, the corresponding highlight groups are linked
to Nvim's standard |highlight-groups| by default (e.g., `@comment` links to
`Comment`) but can be overridden in colorschemes.

A fallback system is implemented, so that more specific groups fallback to
more generic ones. For instance, in a language that has separate doc comments
(e.g., c, java, etc.), `@comment.documentation` could be used. If this group
is not defined, the highlighting for an ordinary `@comment` is used. This way,
existing color schemes already work out of the box, but it is possible to add
more specific variants for queries that make them available.

As an additional rule, capture highlights can always be specialized by
language, by appending the language name after an additional dot. For
instance, to highlight comments differently per language: >vim

    hi @comment.c guifg=Blue
    hi @comment.lua guifg=DarkBlue
    hi link @comment.documentation.java String
<
The following is a list of standard captures used in queries for Nvim,
highlighted according to the current colorscheme (use |:Inspect| on one to see
the exact definition):

@variable                       various variable names
@variable.builtin               built-in variable names (e.g. `this`, `self`)
@variable.parameter             parameters of a function
@variable.parameter.builtin     special parameters (e.g. `_`, `it`)
@variable.member                object and struct fields

@constant               constant identifiers
@constant.builtin       built-in constant values
@constant.macro         constants defined by the preprocessor

@module                 modules or namespaces
@module.builtin         built-in modules or namespaces
@label                  `GOTO` and other labels (e.g. `label:` in C),

Title: Treesitter Syntax Highlighting with Highlights.scm
Summary
This section elaborates on Treesitter syntax highlighting, which is achieved using queries named `highlights.scm`. These queries match nodes in the parsed tree to captures, which are then associated with highlight groups. The section provides an example of how to match identifiers within function parameters and how to highlight literal expressions. It explains how to enable treesitter highlighting and discusses the usage of capture names as highlight groups. It details a fallback system where specific groups default to more generic ones and how capture highlights can be specialized by language. The section concludes with a list of standard captures used in queries.