doc/neovim: update treesitter section

doc/languages-frameworks/neovim.section.md

@@ -96,7 +96,7 @@ neovim.overrideAttrs (oldAttrs: {
 })
 ```
 
-### Specificities for some plugins {#neovim-plugin-specificities}
+## Specificities for some plugins {#neovim-plugin-specificities}
 
 ### Plugin optional configuration {#neovim-plugin-required-snippet}
 
@@ -105,7 +105,7 @@ patch those plugins but expose the necessary configuration under
 `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.
@@ -122,12 +122,34 @@ For instance:
 ```
 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 {
@@ -148,10 +170,127 @@ of precompiled grammars, you can use the `nvim-treesitter.withPlugins` function:
 
 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.

doc/redirects.json

@@ -4296,6 +4296,18 @@
     "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"
   ],