From a959a3f60c32b217842eb9e9e7a4f2c3852af304 Mon Sep 17 00:00:00 2001 From: Marc Jakobi Date: Wed, 11 Feb 2026 12:43:07 +0100 Subject: [PATCH 1/2] doc/neovim: update treesitter section --- doc/languages-frameworks/neovim.section.md | 146 ++++++++++++++++++++- doc/redirects.json | 12 ++ 2 files changed, 154 insertions(+), 4 deletions(-) diff --git a/doc/languages-frameworks/neovim.section.md b/doc/languages-frameworks/neovim.section.md index d7b9e29e0640..60fb81587972 100644 --- a/doc/languages-frameworks/neovim.section.md +++ b/doc/languages-frameworks/neovim.section.md @@ -124,10 +124,32 @@ To update these packages, you should use the lua updater rather than vim's. #### 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,6 +170,122 @@ 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/.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} diff --git a/doc/redirects.json b/doc/redirects.json index bd630c3f56a6..4fd8f57e75bb 100644 --- a/doc/redirects.json +++ b/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" ], From 5ad3a9556252f858b138ec8e7976304122281be0 Mon Sep 17 00:00:00 2001 From: Marc Jakobi Date: Wed, 11 Feb 2026 23:28:45 +0100 Subject: [PATCH 2/2] doc/neovim: promote subsection headings --- doc/languages-frameworks/neovim.section.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/languages-frameworks/neovim.section.md b/doc/languages-frameworks/neovim.section.md index 60fb81587972..a73997c761d1 100644 --- a/doc/languages-frameworks/neovim.section.md +++ b/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,7 +122,7 @@ For instance: ``` To update these packages, you should use the lua updater rather than vim's. -#### Treesitter {#neovim-plugin-treesitter} +## Treesitter {#neovim-plugin-treesitter} [Treesitter](https://tree-sitter.github.io/) provides syntax parsing for Neovim, enabling features like: Advanced syntax highlighting, Code folding, Indentation and more. @@ -142,7 +142,7 @@ In nixpkgs, grammars and queries are precompiled and packaged separately. This m - 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} +### Treesitter setup using `nvim-treesitter` {#neovim-plugin-nvim-treesitter} ::: {.tip} Choose this approach if you want to use `nvim-treesitter`'s custom indentation expression. @@ -182,7 +182,7 @@ This is expected behavior because: **To verify Nix-managed parsers and queries**, use `:checkhealth vim.treesitter` instead. ::: -##### Treesitter setup using standalone grammars and queries {#neovim-plugin-treesitter-standalone} +### Treesitter setup using standalone grammars and queries {#neovim-plugin-treesitter-standalone} ::: {.tip} Choose this approach if you @@ -239,7 +239,7 @@ vim.api.nvim_create_autocmd('FileType', { }) ``` -##### Treesitter grammars as plugin dependencies {#neovim-plugin-treesitter-grammar-dependencies} +### 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. @@ -287,9 +287,10 @@ If a plugin actually does depend on the `nvim-treesitter` legacy module API, you 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.