diff --git a/doc/languages-frameworks/neovim.section.md b/doc/languages-frameworks/neovim.section.md index d7b9e29e0640a..a73997c761d1d 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,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/.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. diff --git a/doc/redirects.json b/doc/redirects.json index bd630c3f56a66..4fd8f57e75bb8 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" ],