From b463792348fdb8c689c6f2bfb00e374fcade22d1 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Fri, 7 Mar 2025 16:20:46 +0300 Subject: [PATCH 1/4] docs/custom-plugins: avoid using `with` scopes in the manual --- .../configuring/custom-plugins/configuring.md | 20 ++++++++++--------- .../custom-plugins/non-lazy-method.md | 8 ++++---- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/manual/configuring/custom-plugins/configuring.md b/docs/manual/configuring/custom-plugins/configuring.md index c0935f03..fb7cfffa 100644 --- a/docs/manual/configuring/custom-plugins/configuring.md +++ b/docs/manual/configuring/custom-plugins/configuring.md @@ -32,16 +32,18 @@ that the `extraPlugins` option has its own DAG scope), and the its setup code respectively. For example: ```nix -config.vim.extraPlugins = with pkgs.vimPlugins; { - aerial = { - package = aerial-nvim; - setup = "require('aerial').setup {}"; - }; +{pkgs, ...}: { + config.vim.extraPlugins = { + aerial = { + package = pkgs.vimPlugins.aerial-nvim; + setup = "require('aerial').setup {}"; + }; - harpoon = { - package = harpoon; - setup = "require('harpoon').setup {}"; - after = ["aerial"]; # place harpoon configuration after aerial + harpoon = { + package = pkgs.vimPlugins.harpoon; + setup = "require('harpoon').setup {}"; + after = ["aerial"]; # place harpoon configuration after aerial + }; }; } ``` diff --git a/docs/manual/configuring/custom-plugins/non-lazy-method.md b/docs/manual/configuring/custom-plugins/non-lazy-method.md index 351af2eb..d8477283 100644 --- a/docs/manual/configuring/custom-plugins/non-lazy-method.md +++ b/docs/manual/configuring/custom-plugins/non-lazy-method.md @@ -5,10 +5,10 @@ under `vim.extraPlugins`. Instead of using DAGs exposed by the library, you may use the extra plugin module as follows: ```nix -{ - config.vim.extraPlugins = with pkgs.vimPlugins; { +{pkgs, ...}: { + config.vim.extraPlugins = { aerial = { - package = aerial-nvim; + package = pkgs.vimPlugins.aerial-nvim; setup = '' require('aerial').setup { -- some lua configuration here @@ -17,7 +17,7 @@ use the extra plugin module as follows: }; harpoon = { - package = harpoon; + package = pkgs.vimPlugins.harpoon; setup = "require('harpoon').setup {}"; after = ["aerial"]; }; From 902ffe710b01757319e21896e1f04cdaae8cfcbd Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Wed, 12 Mar 2025 03:53:16 +0300 Subject: [PATCH 2/4] docs/manual: document building plugins from source --- docs/manual/tips.md | 3 +- docs/manual/tips/plugin-sources.md | 131 +++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+), 1 deletion(-) create mode 100644 docs/manual/tips/plugin-sources.md diff --git a/docs/manual/tips.md b/docs/manual/tips.md index 6e6dc9c2..f52cbca2 100644 --- a/docs/manual/tips.md +++ b/docs/manual/tips.md @@ -1,7 +1,8 @@ # Helpful Tips {#ch-helpful-tips} ```{=include=} chapters -tips/pure-lua-config.md tips/debugging-nvf.md tips/offline-docs.md +tips/pure-lua-config.md +tips/plugin-sources.md ``` diff --git a/docs/manual/tips/plugin-sources.md b/docs/manual/tips/plugin-sources.md new file mode 100644 index 00000000..7cf6a470 --- /dev/null +++ b/docs/manual/tips/plugin-sources.md @@ -0,0 +1,131 @@ +# Adding Plugins From Different Sources {#sec-plugin-sources} + +**nvf** attempts to avoid depending on Nixpkgs for Neovim plugins. For the most +part, this is accomplished by defining each plugin's source and building them +from source. + +[npins]: https://github.com/andir/npins + +To define plugin sources, we use [npins] and pin each plugin source using +builtin fetchers. You are not bound by this restriction. In your own +configuration, any kind of fetcher or plugin source is fine. + +## Nixpkgs & Friends {#ch-plugins-from-nixpkgs} + +`vim.startPlugins` and `vim.optPlugins` options take either a **string**, in +which case a plugin from nvf's internal plugins registry will be used, or a +**package**. If your plugin does not require any setup, or ordering for it s +configuration, then it is possible to add it to `vim.startPlugins` to load it on +startup. + +```nix +{pkgs, ...}: { + # Aerial does require some setup. In the case you pass a plugin that *does* + # require manual setup, then you must also call the setup function. + vim.startPlugins = [pkgs.vimPlugins.aerial-nvim]; +} +``` + +[`vim.extraPlugins`]: https://notashelf.github.io/nvf/options.html#opt-vim.extraPlugins + +This will fetch aerial.nvim from nixpkgs, and add it to Neovim's runtime path to +be loaded manually. Although for plugins that require manual setup, you are +encouraged to use [`vim.extraPlugins`]. + +```nix +{ + vim.extraPlugins = { + aerial = { + package = pkgs.vimPlugins.aerial-nvim; + setup = "require('aerial').setup {}"; + }; + }; +} +``` + +[custom plugins section]: https://notashelf.github.io/nvf/index.xhtml#ch-custom-plugins + +More details on the extraPlugins API is documented in the +[custom plugins section]. + +## Building Your Own Plugins {#ch-plugins-from-source} + +In the case a plugin is not available in Nixpkgs, or the Nixpkgs package is +outdated (or, more likely, broken) it is possible to build the plugins from +source using a tool, such as [npins]. You may also use your _flake inputs_ as +sources. + +Example using plugin inputs: + +```nix +{ + # In your flake.nix + inputs = { + aerial-nvim = { + url = "github:stevearc/aerial.nvim" + flake = false; + }; + }; + + # Make sure that 'inputs' is properly propagated into Nvf, for example, through + # specialArgs. + outputs = { ... }; +} +``` + +In the case, you may use the input directly for the plugin's source attribute in +`buildVimPlugin`. + +```nix +# Make sure that 'inputs' is properly propagated! It will be missing otherwise +# and the resulting errors might be too obscure. +{inputs, ...}: let + aerial-from-source = pkgs.vimUtils.buildVimPlugin { + name = "aerial-nvim"; + src = inputs.aerial-nvim; + }; +in { + vim.extraPlugins = { + aerial = { + package = aerial-from-source; + setup = "require('aerial').setup {}"; + }; + }; +} +``` + +Alternatively, if you do not want to keep track of the source using flake inputs +or npins, you may call `fetchFromGitHub` (or other fetchers) directly. An +example would look like this. + +```nix +regexplainer = buildVimPlugin { + name = "nvim-regexplainer"; + src = fetchFromGitHub { + owner = "bennypowers"; + repo = "nvim-regexplainer"; + rev = "4250c8f3c1307876384e70eeedde5149249e154f"; + hash = "sha256-15DLbKtOgUPq4DcF71jFYu31faDn52k3P1x47GL3+b0="; + }; + + # The 'buildVimPlugin' imposes some "require checks" on all plugins build from + # source. Failing tests, if they are not relevant, can be disabled using the + # 'nvimSkipModule' argument to the 'buildVimPlugin' function. + nvimSkipModule = [ + "regexplainer" + "regexplainer.buffers.init" + "regexplainer.buffers.popup" + "regexplainer.buffers.register" + "regexplainer.buffers.shared" + "regexplainer.buffers.split" + "regexplainer.component.descriptions" + "regexplainer.component.init" + "regexplainer.renderers.narrative.init" + "regexplainer.renderers.narrative.narrative" + "regexplainer.renderers.init" + "regexplainer.utils.defer" + "regexplainer.utils.init" + "regexplainer.utils.treesitter" + ]; +} +``` From 15fbd146aa0ddc1d02b12ab1c4e3eecf5299aaa6 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Sun, 16 Mar 2025 00:43:13 +0300 Subject: [PATCH 3/4] wrappper: remove `with pkgs.vimPlugins` from example --- modules/wrapper/environment/options.nix | 37 ++++++++++++++++--------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/modules/wrapper/environment/options.nix b/modules/wrapper/environment/options.nix index c401f506..cbe999ad 100644 --- a/modules/wrapper/environment/options.nix +++ b/modules/wrapper/environment/options.nix @@ -54,9 +54,7 @@ in { optPlugins = pluginsOpt { default = []; - example = '' - [pkgs.vimPlugins.vim-ghost] - ''; + example = "[pkgs.vimPlugins.vim-ghost]"; description = '' List of plugins to optionally load on startup. @@ -73,8 +71,8 @@ in { type = attrsOf extraPluginType; default = {}; description = '' - A list of plugins and their configurations that will be - set up after builtin plugins. + Plugins and their configurations that will be set up after + builtin plugins. This option takes a special type that allows you to order your custom plugins using nvf's modified DAG library. @@ -82,17 +80,31 @@ in { example = literalMD '' ```nix - with pkgs.vimPlugins; { + { aerial = { - package = aerial-nvim; + package = pkgs.vimPlugins.aerial-nvim; setup = "require('aerial').setup {}"; }; harpoon = { - package = harpoon; + package = pkgs.vimPlugins.harpoon; setup = "require('harpoon').setup {}"; after = ["aerial"]; # place harpoon configuration after aerial }; + + # Example for packages built from source + deferred-clipboard = { + package = buildVimPlugin { + name = "deferred-clipboard"; + src = (fetchFromGitHub { + owner = "EtiamNullam"; + repo = "deferred-clipboard.nvim"; + rev = "810a29d166eaa41afc220cc7cd85eeaa3c43b37f"; + hash = "sha256-nanNQEtpjv0YKEkkrPmq/5FPxq+Yj/19cs0Gf7YgKjU="; + }; + }); + setup = "require('deferred-clipboard').setup {}"; + }; } ``` ''; @@ -101,21 +113,20 @@ in { extraPackages = mkOption { type = listOf package; default = []; - example = ''[pkgs.fzf pkgs.ripgrep]''; + example = "[pkgs.fzf pkgs.ripgrep]"; description = '' List of additional packages to make available to the Neovim wrapper. ''; }; - # this defaults to `true` in the wrapper + # This defaults to `true` in the wrapper # and since we pass this value to the wrapper # with an inherit, it should be `true` here as well withRuby = - mkEnableOption '' - Ruby support in the Neovim wrapper. - '' + mkEnableOption "" // { + description = "Whether to enable Ruby support in the Neovim wrapper"; default = true; }; From 7b58caaa9ff001c6ce0e9a04c3a4aa03f6b9bb45 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Sun, 16 Mar 2025 00:53:49 +0300 Subject: [PATCH 4/4] init/autocmds: add example to the autocmds option --- modules/neovim/init/autocmds.nix | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/modules/neovim/init/autocmds.nix b/modules/neovim/init/autocmds.nix index 5da7bc55..e74dd620 100644 --- a/modules/neovim/init/autocmds.nix +++ b/modules/neovim/init/autocmds.nix @@ -126,6 +126,20 @@ in { autocmds = mkOption { type = listOf autocommandType; default = []; + example = literalExpression '' + [ + { + enable = true; + desc = "Highlight yanks on copy"; + pattern = ["*"]; + callback = lib.generators.mkLuaInline ''' + function() + vim.highlight.on_yank({ timeout = 500 }) + end + '''; + } + ] + ''; description = '' A list of Neovim autocommands to be registered.