From acddfd6d3810521ce0bfff01386060170b506bc3 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 21 Jul 2025 20:48:39 +0000 Subject: [PATCH] Deploy PR #1030 preview --- docs-preview-1030/index.xhtml | 100 ++++++++++++++++++++++++++-------- 1 file changed, 78 insertions(+), 22 deletions(-) diff --git a/docs-preview-1030/index.xhtml b/docs-preview-1030/index.xhtml index 2b8573ed..b77eaa3d 100644 --- a/docs-preview-1030/index.xhtml +++ b/docs-preview-1030/index.xhtml @@ -1258,8 +1258,52 @@ allow custom keybindings, don’t be scared to implement a draft PR. We’ll hel you get it done.

-

Adding Plugins

Modular setup options
Details of toLuaObject
Lazy plugins

To add a new Neovim plugin, use npins

Use:

nix-shell -p npins or nix shell nixpkgs#npins

Then run:

npins add --name <plugin name> github <owner> <repo> -b <branch>

Be sure to replace any non-alphanumeric characters with - for --name

For example

npins add --name lazydev-nvim github folke lazydev.nvim -b main

You can now reference this plugin as a string.

config.vim.startPlugins = ["lazydev-nvim"];
-

Modular setup options

Most plugins is initialized with a call to require('plugin').setup({...}).

We use a special function that lets you easily add support for such setup +

Adding Plugins

With npins
Packaging Complex Plugins
Modular setup options
Details of toLuaObject
Lazy plugins

There are two methods for adding new Neovim plugins to nvf. npins is the +faster option that should be preferred if the plugin consists of pure Lua or +Vimscript code. In which case there is no building required, and we can easily +handle the copying of plugin files. Alternative method, which is required when +plugins try to build their own libraries (e.g., in Rust or C) that need to be +built with Nix to function correctly.

With npins

npins is the standard method of adding new plugins to nvf. You simply need +the repository URL for the plugin, and can add it as a source to be built +automatically with one command. To add a new Neovim plugin, use npins. For +example:

nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
+

Then run:

npins add --name <plugin name> github <owner> <repo> -b <branch>
+

Note

Be sure to replace any non-alphanumeric characters with - for --name. For +example

npins add --name lazydev-nvim github folke lazydev.nvim -b main
+

Once the npins command is done, you can start referencing the plugin as a +string.

{
+  config.vim.startPlugins = ["lazydev-nvim"];
+}
+
+

Packaging Complex Plugins

Some plugins require additional packages to be built and substituted to function +correctly. For example blink.cmp requires its own fuzzy matcher library, built +with Rust, to be installed or else defaults to a much slower Lua implementation. +In the Blink documentation, you are advised to build with cargo but that is +not ideal since we are leveraging the power of Nix. In this case the ideal +solution is to write a derivation for the plugin.

We use buildRustPackage to build the library from the repository root, and +copy everything in the postInstall phase.

postInstall = ''
+  cp -r {lua,plugin} "$out"
+
+  mkdir -p "$out/doc"
+  cp 'doc/'*'.txt' "$out/doc/"
+
+  mkdir -p "$out/target"
+  mv "$out/lib" "$out/target/release"
+'';
+

In a similar fashion, you may utilize stdenv.mkDerivation and other Nixpkgs +builders to build your library from source, and copy the relevant files and Lua +plugin files in the postInstall phase. Do note, however, that you still need +to fetch the plugin sources somehow. npins is, once again, the recommended +option to fetch the plugin sources. Refer to the previous section on how to use +npins to add a new plugin.

Plugins built from source must go into the flake/pkgs/by-name overlay. It will +automatically create flake outputs for individual packages. Lastly, you must add +your package to the plugin builder (pluginBuilders) function manually in +modules/wrapper/build/config.nix. Once done, you may refer to your plugin as a +string.

{
+  config.vim.startPlugins = ["blink-cmp"];
+}
+
+

Modular setup options

Most plugins is initialized with a call to require('plugin').setup({...}).

We use a special function that lets you easily add support for such setup options in a modular way: mkPluginSetupOption.

Once you have added the source of the plugin as shown above, you can define the setup options like this:

# in modules/.../your-plugin/your-plugin.nix
 
@@ -1293,7 +1337,7 @@ in {
     require('plugin-name').setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
   '';
 }
-

This above config will result in this lua script:

require('plugin-name').setup({
+

This above config will result in this Lua script:

require('plugin-name').setup({
   enable_feature_a = false,
   number_option = 3,
 })
@@ -1311,36 +1355,47 @@ own fields!
# in user's config
 }

Details of toLuaObject

As you’ve seen above, toLuaObject is used to convert our nix attrSet -cfg.setupOpts, into a lua table. Here are some rules of the conversion:

  1. nix null converts to lua nil

  2. number and strings convert to their lua counterparts

  3. nix attrSet/list convert into lua tables

  4. you can write raw lua code using lib.generators.mkLuaInline. This function -is part of nixpkgs.

Example:

vim.your-plugin.setupOpts = {
-  on_init = lib.generators.mkLuaInline ''
-    function()
-      print('we can write lua!')
-    end
-  '';
+cfg.setupOpts, into a lua table. Here are some rules of the conversion:
  1. Nix null converts to lua nil
  2. Number and strings convert to their lua counterparts
  3. Nix attribute sets ({}) and lists ([]) convert into Lua dictionaries and
+tables respectively. Here is an example of Nix -> Lua conversion.
    • {foo = "bar"} -> {["foo"] = "bar"}
    • ["foo" "bar"] -> {"foo", "bar"}
  4. You can write raw Lua code using lib.generators.mkLuaInline. This function
+is part of nixpkgs, and is accessible without relying on nvf’s extended
+library.
    • mkLuaInline "function add(a, b) return a + b end" will yield the
+following result:
    {
+ _type = "lua-inline";
+ expr = "function add(a, b) return a + b end";
 }
-
    
+

The above expression will be interpreted as a Lua expression in the final +config. Without the mkLuaInline function, you will only receive a string +literal. You can use it to feed plugin configuration tables Lua functions +that return specific values as expected by the plugins.

{
+   vim.your-plugin.setupOpts = {
+     on_init = lib.generators.mkLuaInline ''
+       function()
+         print('we can write lua!')
+       end
+     '';
+   };
+}
+

Lazy plugins

If the plugin can be lazy-loaded, vim.lazy.plugins should be used to add it. Lazy plugins are managed by lz.n.

# in modules/.../your-plugin/config.nix
-{lib, config, ...}:
-let
+{config, ...}: let
   cfg = config.vim.your-plugin;
 in {
   vim.lazy.plugins.your-plugin = {
-    # instead of vim.startPlugins, use this:
+    # Instead of vim.startPlugins, use this:
     package = "your-plugin";
 
-    # if your plugin uses the `require('your-plugin').setup{...}` pattern
+    # ıf your plugin uses the `require('your-plugin').setup{...}` pattern
     setupModule = "your-plugin";
     inherit (cfg) setupOpts;
 
-    # events that trigger this plugin to be loaded
+    # Events that trigger this plugin to be loaded
     event = ["DirChanged"];
     cmd = ["YourPluginCommand"];
 
-    # keymaps
+    # Plugin Keymaps
     keys = [
-      # we'll cover this in detail in the keymaps section
+      # We'll cover this in detail in the 'keybinds' section
       {
         key = "<leader>d";
         mode = "n";
@@ -1348,13 +1403,14 @@ in {
       }
     ];
   };
-;
 }

This results in the following lua code:

require('lz.n').load({
   {
     "name-of-your-plugin",
     after = function()
-      require('your-plugin').setup({--[[ your setupOpts ]]})
+      require('your-plugin').setup({
+        --[[ your setupOpts ]]--
+      })
     end,
 
     event = {"DirChanged"},
@@ -1364,8 +1420,8 @@ in {
     },
   }
 })
-

A full list of options can be found -[here](https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins

+

A full list of options can be found in the vim.lazy.plugins spec on the +rendered manual.