doc/neovim: update treesitter section (#489421)

})

```

### Specificities for some plugins {#neovim-plugin-specificities}

## Specificities for some plugins {#neovim-plugin-specificities}

### Plugin optional configuration {#neovim-plugin-required-snippet}

`PLUGIN.passthru.initLua` for neovim plugins. For instance, the `unicode-vim` plugin

needs the path towards a unicode database so we expose the following snippet `vim.g.Unicode_data_directory="${self.unicode-vim}/autoload/unicode"` under `vimPlugins.unicode-vim.passthru.initLua`.

#### LuaRocks based plugins {#neovim-luarocks-based-plugins}

## LuaRocks based plugins {#neovim-luarocks-based-plugins}

In order to automatically handle plugin dependencies, several Neovim plugins

upload their package to [LuaRocks](https://www.luarocks.org). This means less work for nixpkgs maintainers in the long term as dependencies get updated automatically.

```

To update these packages, you should use the lua updater rather than vim's.

#### Treesitter {#neovim-plugin-treesitter}

## Treesitter {#neovim-plugin-treesitter}

By default `nvim-treesitter` encourages you to download, compile and install

the required Treesitter grammars at run time with `:TSInstall`. This works

poorly on NixOS.  Instead, to install the `nvim-treesitter` plugins with a set

of precompiled grammars, you can use the `nvim-treesitter.withPlugins` function:

[Treesitter](https://tree-sitter.github.io/) provides syntax parsing for Neovim, enabling features like:

Advanced syntax highlighting, Code folding, Indentation and more.

Most Neovim users manage treesitter through the `nvim-treesitter` plugin, which provides:

- Commands for managing grammars and queries,

  e.g. `:TSInstall`, which downloads, compiles and installs them at runtime.

- A custom indentation implementation ([`:h indentexpr`](https://neovim.io/doc/user/options.html#'indentexpr'))

  for languages with `indents.scm` queries.

These features build on top of treesitter functionality that is built into Neovim.

In nixpkgs, grammars and queries are precompiled and packaged separately. This means:

- You can use treesitter features **without** installing `nvim-treesitter`.

- You only need `nvim-treesitter` if you want its custom indentation implementation.

- Plugins that depend on grammars can reference them directly.

### Treesitter setup using `nvim-treesitter` {#neovim-plugin-nvim-treesitter}

::: {.tip}

Choose this approach if you want to use `nvim-treesitter`'s custom indentation expression.

:::

To install `nvim-treesitter` combined with a set of precompiled grammars,

you can use the `nvim-treesitter.withPlugins` function:

```nix

(pkgs.neovim.override {

To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`.

For how to configure `nvim-treesitter` and set up syntax highlighting, indentation, folding, etc.,

please refer to the `:help nvim-treesitter-quickstart` plugin documentation.

::: {.note}

When using Nix-managed grammars, `:checkhealth nvim-treesitter` will report no installed languages.

This is expected behavior because:

- The `nvim-treesitter` health check searches its configured install directory.

- Nix installs grammars to the Nix store and adds them to the `runtimepath` instead.

**To verify Nix-managed parsers and queries**, use `:checkhealth vim.treesitter` instead.

:::

### Treesitter setup using standalone grammars and queries {#neovim-plugin-treesitter-standalone}

::: {.tip}

Choose this approach if you

- Want minimal dependencies.

- Don't need `nvim-treesitter`'s custom indentation expression.

:::

You can install the standalone parsers and queries directly without installing `nvim-treesitter`:

```nix

(pkgs.neovim.override {

  configure = {

    packages.myPlugins =

      with pkgs.vimPlugins;

      let

        # Select the grammars you need

        treesitter-grammars = with nvim-treesitter-parsers; [

          nix

          python

        ];

        # Queries are needed for treesitter based syntax highlighting and folds.

        treesitter-queries = map (p: p.associatedQuery) treesitter-grammars;

      in

      {

        start = [

          # regular plugins

        ]

        ++ treesitter-grammars

        ++ treesitter-queries;

      };

  };

})

```

You can enable treesitter features for installed grammars in a `FileType` autocommand

or in an `ftplugin/<language>.lua` script, e.g.

```lua

vim.api.nvim_create_autocmd('FileType', {

  pattern = { 'rust', 'javascript', 'zig' },

  callback = function(ev)

    local bufnr = ev.buf

    -- Enable treesitter syntax highlighting and parsing for the current buffer

    -- (Requires queries to be installed)

    vim.treesitter.start(bufnr)

    -- Enable treesitter based code folding

    -- (folds are window-scoped, not buffer-scoped)

    -- (Requires queries to be installed)

    vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'

    vim.wo.foldmethod = 'expr'

  end,

})

```

### Treesitter grammars as plugin dependencies {#neovim-plugin-treesitter-grammar-dependencies}

Some Neovim plugins (like `neotest` adapters, `markdoc-nvim`, `hurl-nvim`) depend on treesitter grammars.

These dependencies are usually declared in plugin overrides.

::: {.important}

Some plugin READMEs may suggest that they depend on `nvim-treesitter`.

**This is almost always not the case.**

`nvim-treesitter` no longer provides a Lua module API for other plugins to use.

In the vast majority of cases, these plugins:

- **Depend on parsers** (not on `nvim-treesitter` or its queries).

- **Bundle their own queries** (either as `*.scm` files or hardcoded in the Lua sources).

:::

To add grammars as a plugin dependency, add an [override](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix):

```nix

{

  foo-nvim = super.foo-nvim.overrideAttrs {

    dependencies = with self.nvim-treesitter-parsers; [

      markdown

      markdown_inline

      html

    ];

  };

}

```

If a plugin actually does depend on the `nvim-treesitter` legacy module API, you can add

`nvim-treesitter-legacy` as a dependency:

```nix

{

  foo-legacy-nvim = super.foo-legacy-nvim.overrideAttrs {

    dependencies = with self; [

      nvim-treesitter-legacy

      nvim-treesitter-parsers.nix

    ];

  };

}

```

::: {.caution}

`nvim-treesitter-legacy` exists for the purpose of easing transition and will be removed in 26.11.

If a Neovim configuration contains both `nvim-treesitter` and `nvim-treesitter-legacy`, it will fail to evaluate.

:::

## Testing Neovim plugins {#testing-neovim-plugins}

### Testing Neovim plugins {#testing-neovim-plugins}

### neovimRequireCheck {#testing-neovim-plugins-neovim-require-check}

#### neovimRequireCheck {#testing-neovim-plugins-neovim-require-check}

`neovimRequireCheck` is a simple test which checks if Neovim can require lua modules without errors. This is often enough to catch missing dependencies.

It accepts a single string for a module, or a list of module strings to test.

    "index.html#neovim-plugin-treesitter",

    "index.html#vim-plugin-treesitter"

  ],

  "neovim-plugin-nvim-treesitter": [

    "index.html#neovim-plugin-nvim-treesitter",

    "index.html#vim-plugin-nvim-treesitter"

  ],

  "neovim-plugin-treesitter-standalone": [

    "index.html#neovim-plugin-treesitter-standalone",

    "index.html#vim-plugin-treesitter-standalone"

  ],

  "neovim-plugin-treesitter-grammar-dependencies": [

    "index.html#neovim-plugin-treesitter-grammar-dependencies",

    "index.html#vim-plugin-treesitter-grammar-dependencies"

  ],

  "managing-plugins-with-vim-plug": [

    "index.html#managing-plugins-with-vim-plug"

  ],