From b7b442737a8d81abaec087189a72776c2dc9976e Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Sat, 19 Jul 2025 14:14:40 -0400
Subject: [PATCH 01/13] utility/undotree: init module

---
 modules/plugins/utility/undotree/undotree.nix | 25 +++++++++++++++++++
 npins/sources.json                            | 13 ++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 modules/plugins/utility/undotree/undotree.nix

diff --git a/modules/plugins/utility/undotree/undotree.nix b/modules/plugins/utility/undotree/undotree.nix
new file mode 100644
index 00000000..936253e5
--- /dev/null
+++ b/modules/plugins/utility/undotree/undotree.nix
@@ -0,0 +1,25 @@
+{ lib, ... }:
+let
+  inherit (lib.types) bool int;
+  inherit (lib.options) mkEnableOption mkOption;
+
+  inherit (lib.nvim.types) mkPluginSetupOption;
+in
+{
+  options.vim.undotree = {
+    enable = mkEnableOption "undotree";
+    setupOpts = mkPluginSetupOption "undotree" {
+      # enable_feature_a = mkOption {
+      #   type = bool;
+      #   default = false;
+      #   # ...
+      # };
+      #
+      # number_option = mkOption {
+      #   type = int;
+      #   default = 3;
+      #   # ...
+      # };
+    };
+  };
+}
diff --git a/npins/sources.json b/npins/sources.json
index 00dcea83..3c3bc3c3 100644
--- a/npins/sources.json
+++ b/npins/sources.json
@@ -2497,6 +2497,19 @@
       "url": "https://github.com/chomosuke/typst-preview.nvim/archive/dea4525d5420b7c32eebda7de15a6beb9d6574fa.tar.gz",
       "hash": "0y658l2ibq0x4cwa4rl3lab7aw4ba68xcrdnxp81p2rsk0d60qq4"
     },
+    "undotree": {
+      "type": "Git",
+      "repository": {
+        "type": "GitHub",
+        "owner": "mbbill",
+        "repo": "undotree"
+      },
+      "branch": "master",
+      "submodules": false,
+      "revision": "28f2f54a34baff90ea6f4a735ef1813ad875c743",
+      "url": "https://github.com/mbbill/undotree/archive/28f2f54a34baff90ea6f4a735ef1813ad875c743.tar.gz",
+      "hash": "0k9qfp64rbwy1lc62x0vkwfl3qlx8633lfbhqxkf64yqwi81ysp5"
+    },
     "vim-dirtytalk": {
       "type": "Git",
       "repository": {

From 81d566ac39b8531ffc985e228684552851356720 Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Sat, 19 Jul 2025 14:44:47 -0400
Subject: [PATCH 02/13] utility/undotree: removed unimportant boilerplate

---
 configuration.nix                             |  9 ++++++---
 modules/plugins/utility/default.nix           |  1 +
 modules/plugins/utility/undotree/config.nix   |  6 ++++++
 modules/plugins/utility/undotree/default.nix  |  6 ++++++
 modules/plugins/utility/undotree/undotree.nix | 18 +-----------------
 5 files changed, 20 insertions(+), 20 deletions(-)
 create mode 100644 modules/plugins/utility/undotree/config.nix
 create mode 100644 modules/plugins/utility/undotree/default.nix

diff --git a/configuration.nix b/configuration.nix
index 424d7173..80a34157 100644
--- a/configuration.nix
+++ b/configuration.nix
@@ -43,7 +43,7 @@ isMaximal: {
     # This section does not include a comprehensive list of available language modules.
     # To list all available language module options, please visit the nvf manual.
     languages = {
-      enableFormat = true; #
+      enableFormat = true;
       enableTreesitter = true;
       enableExtraDiagnostics = true;
 
@@ -184,6 +184,7 @@ isMaximal: {
       project-nvim.enable = isMaximal;
     };
 
+    undotree.enable = isMaximal;
     utility = {
       ccc.enable = false;
       vim-wakatime.enable = false;
@@ -194,7 +195,6 @@ isMaximal: {
       leetcode-nvim.enable = isMaximal;
       multicursors.enable = isMaximal;
       smart-splits.enable = isMaximal;
-
       motion = {
         hop.enable = true;
         leap.enable = true;
@@ -238,7 +238,10 @@ isMaximal: {
           nix = "110";
           ruby = "120";
           java = "130";
-          go = ["90" "130"];
+          go = [
+            "90"
+            "130"
+          ];
         };
       };
       fastaction.enable = true;
diff --git a/modules/plugins/utility/default.nix b/modules/plugins/utility/default.nix
index 8069b6c1..79d7d924 100644
--- a/modules/plugins/utility/default.nix
+++ b/modules/plugins/utility/default.nix
@@ -26,5 +26,6 @@
     ./wakatime
     ./yanky-nvim
     ./yazi-nvim
+    ./undotree
   ];
 }
diff --git a/modules/plugins/utility/undotree/config.nix b/modules/plugins/utility/undotree/config.nix
new file mode 100644
index 00000000..7f2ffeba
--- /dev/null
+++ b/modules/plugins/utility/undotree/config.nix
@@ -0,0 +1,6 @@
+{ ... }:
+{
+  vim.lazy.plugins.undotree = {
+    cmd = [ "UndotreeToggle" ];
+  };
+}
diff --git a/modules/plugins/utility/undotree/default.nix b/modules/plugins/utility/undotree/default.nix
new file mode 100644
index 00000000..012d8454
--- /dev/null
+++ b/modules/plugins/utility/undotree/default.nix
@@ -0,0 +1,6 @@
+{
+  imports = [
+    ./undotree.nix
+    ./config.nix
+  ];
+}
diff --git a/modules/plugins/utility/undotree/undotree.nix b/modules/plugins/utility/undotree/undotree.nix
index 936253e5..be9a92ab 100644
--- a/modules/plugins/utility/undotree/undotree.nix
+++ b/modules/plugins/utility/undotree/undotree.nix
@@ -1,25 +1,9 @@
 { lib, ... }:
 let
-  inherit (lib.types) bool int;
-  inherit (lib.options) mkEnableOption mkOption;
-
-  inherit (lib.nvim.types) mkPluginSetupOption;
+  inherit (lib.options) mkEnableOption;
 in
 {
   options.vim.undotree = {
     enable = mkEnableOption "undotree";
-    setupOpts = mkPluginSetupOption "undotree" {
-      # enable_feature_a = mkOption {
-      #   type = bool;
-      #   default = false;
-      #   # ...
-      # };
-      #
-      # number_option = mkOption {
-      #   type = int;
-      #   default = 3;
-      #   # ...
-      # };
-    };
   };
 }

From b7191033376981a711c2fae18d904608cdb24096 Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Sat, 19 Jul 2025 18:57:31 -0400
Subject: [PATCH 03/13] formatted files

---
 configuration.nix                           | 9 +++------
 modules/plugins/utility/undotree/config.nix | 1 +
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/configuration.nix b/configuration.nix
index 80a34157..0d53fec9 100644
--- a/configuration.nix
+++ b/configuration.nix
@@ -43,7 +43,7 @@ isMaximal: {
     # This section does not include a comprehensive list of available language modules.
     # To list all available language module options, please visit the nvf manual.
     languages = {
-      enableFormat = true;
+      enableFormat = true; #
       enableTreesitter = true;
       enableExtraDiagnostics = true;
 
@@ -183,7 +183,6 @@ isMaximal: {
     projects = {
       project-nvim.enable = isMaximal;
     };
-
     undotree.enable = isMaximal;
     utility = {
       ccc.enable = false;
@@ -195,6 +194,7 @@ isMaximal: {
       leetcode-nvim.enable = isMaximal;
       multicursors.enable = isMaximal;
       smart-splits.enable = isMaximal;
+
       motion = {
         hop.enable = true;
         leap.enable = true;
@@ -238,10 +238,7 @@ isMaximal: {
           nix = "110";
           ruby = "120";
           java = "130";
-          go = [
-            "90"
-            "130"
-          ];
+          go = ["90" "130"];
         };
       };
       fastaction.enable = true;
diff --git a/modules/plugins/utility/undotree/config.nix b/modules/plugins/utility/undotree/config.nix
index 7f2ffeba..9b7e4d6f 100644
--- a/modules/plugins/utility/undotree/config.nix
+++ b/modules/plugins/utility/undotree/config.nix
@@ -1,6 +1,7 @@
 { ... }:
 {
   vim.lazy.plugins.undotree = {
+    package = "undotree";
     cmd = [ "UndotreeToggle" ];
   };
 }

From 861d6f3ed7d68b16381b9893ec6603e9e30ed6d3 Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Sat, 19 Jul 2025 19:10:30 -0400
Subject: [PATCH 04/13] updated release notes

---
 docs/release-notes/rl-0.8.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/release-notes/rl-0.8.md b/docs/release-notes/rl-0.8.md
index e18c95fe..c4ad963c 100644
--- a/docs/release-notes/rl-0.8.md
+++ b/docs/release-notes/rl-0.8.md
@@ -37,6 +37,7 @@
 [snacks.nvim]: https://github.com/folke/snacks.nvim
 [oil.nvim]: https://github.com/stevearc/oil.nvim
 [hunk.nvim]: https://github.com/julienvincent/hunk.nvim
+[undotree]: https://github.com/mbbill/undotree
 
 - Add [typst-preview.nvim] under
   `languages.typst.extensions.typst-preview-nvim`.

From 1bb94549338942b11ee5e65dc185b0d762ef84ba Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Sat, 19 Jul 2025 23:14:01 -0400
Subject: [PATCH 05/13] utility/undotree: added extra commands to lazy loader

---
 modules/plugins/utility/undotree/config.nix | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/modules/plugins/utility/undotree/config.nix b/modules/plugins/utility/undotree/config.nix
index 9b7e4d6f..6a674d95 100644
--- a/modules/plugins/utility/undotree/config.nix
+++ b/modules/plugins/utility/undotree/config.nix
@@ -2,6 +2,12 @@
 {
   vim.lazy.plugins.undotree = {
     package = "undotree";
-    cmd = [ "UndotreeToggle" ];
+    cmd = [
+      "UndotreeToggle"
+      "UndotreeShow"
+      "UndotreeHide"
+      "UndotreePersistUndo"
+      "UndotreeFocus"
+    ];
   };
 }

From 60dd59ecae3a0fe9981aaa6a0b8cd3a54b2f3ba3 Mon Sep 17 00:00:00 2001
From: Abhirath A <85126640+abhirath-a@users.noreply.github.com>
Date: Sun, 20 Jul 2025 05:39:20 -0400
Subject: [PATCH 06/13] utility/undotree: removed unnecessary lazy inputs

Co-authored-by: raf <raf@notashelf.dev>
---
 modules/plugins/utility/undotree/config.nix | 1 -
 1 file changed, 1 deletion(-)

diff --git a/modules/plugins/utility/undotree/config.nix b/modules/plugins/utility/undotree/config.nix
index 6a674d95..d954d49f 100644
--- a/modules/plugins/utility/undotree/config.nix
+++ b/modules/plugins/utility/undotree/config.nix
@@ -1,4 +1,3 @@
-{ ... }:
 {
   vim.lazy.plugins.undotree = {
     package = "undotree";

From 4847c099ebceacb073b2cddfb0c0e41fe75ea84d Mon Sep 17 00:00:00 2001
From: Abhirath A <85126640+abhirath-a@users.noreply.github.com>
Date: Sun, 20 Jul 2025 05:39:51 -0400
Subject: [PATCH 07/13] utility/undotree: added description to enable

Co-authored-by: raf <raf@notashelf.dev>
---
 modules/plugins/utility/undotree/undotree.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/plugins/utility/undotree/undotree.nix b/modules/plugins/utility/undotree/undotree.nix
index be9a92ab..2483a1ec 100644
--- a/modules/plugins/utility/undotree/undotree.nix
+++ b/modules/plugins/utility/undotree/undotree.nix
@@ -4,6 +4,6 @@ let
 in
 {
   options.vim.undotree = {
-    enable = mkEnableOption "undotree";
+    enable = mkEnableOption "undo history visualizer for Vim [undotree]";
   };
 }

From 8dd53be9109e37415ed54ba669f11484c196c0db Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Sun, 20 Jul 2025 14:51:46 +0300
Subject: [PATCH 08/13] flake: move packages to a by-name overlay

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I6a6a69642d9409f7d32e01a140cb62c2173b5226
---
 flake/packages.nix                            | 160 +++++++++++-------
 .../by-name/avante-nvim/package.nix}          |  20 ++-
 .../by-name/blink-cmp/package.nix}            |   0
 3 files changed, 108 insertions(+), 72 deletions(-)
 rename flake/{avante-nvim/default.nix => pkgs/by-name/avante-nvim/package.nix} (72%)
 rename flake/{blink/default.nix => pkgs/by-name/blink-cmp/package.nix} (100%)

diff --git a/flake/packages.nix b/flake/packages.nix
index 5161b34f..7d39afcb 100644
--- a/flake/packages.nix
+++ b/flake/packages.nix
@@ -9,84 +9,114 @@
     lib,
     ...
   }: let
+    inherit (lib.customisation) makeScope;
+    inherit (lib.attrsets) isDerivation isAttrs concatMapAttrs;
+    inherit (lib.strings) concatStringsSep;
+    inherit (lib.filesystem) packagesFromDirectoryRecursive;
+
+    # Entrypoint for nvf documentation and relevant packages.
     docs = import ../docs {inherit pkgs inputs lib;};
+
+    # Helper function for creating demo configurations for nvf
+    # TODO: make this more generic.
     buildPkg = maximal:
       (args.config.flake.lib.nvim.neovimConfiguration {
         inherit pkgs;
         modules = [(import ../configuration.nix maximal)];
       }).neovim;
+
+    # This constructs a by-name overlay similar to the one found in Nixpkgs.
+    # The goal is to automatically discover and packages found in pkgs/by-name
+    # as long as they have a 'package.nix' in the package directory. We also
+    # pass 'inputs' and 'pins' to all packages in the 'callPackage' scope, therefore
+    # they are always available in the relevant 'package.nix' files.
+    # ---
+    # The logic is borrowed from drupol/pkgs-by-name-for-flake-parts, available
+    # under the MIT license.
+    flattenPkgs = separator: path: value:
+      if isDerivation value
+      then {
+        ${concatStringsSep separator path} = value;
+      }
+      else if isAttrs value
+      then concatMapAttrs (name: flattenPkgs separator (path ++ [name])) value
+      else
+        # Ignore the functions which makeScope returns
+        {};
+
+    inputsScope = makeScope pkgs.newScope (_: {
+      inherit inputs;
+      inherit (self) pins;
+    });
+
+    scopeFromDirectory = directory:
+      packagesFromDirectoryRecursive {
+        inherit directory;
+        inherit (inputsScope) newScope callPackage;
+      };
+
+    legacyPackages = scopeFromDirectory ./pkgs/by-name;
   in {
-    packages = {
-      blink-cmp = pkgs.callPackage ./blink {};
-      avante-nvim = let
-        pin = self.pins.avante-nvim;
-      in
-        pkgs.callPackage ./avante-nvim {
-          version = pin.branch;
-          src = pkgs.fetchFromGitHub {
-            inherit (pin.repository) owner repo;
-            rev = pin.revision;
-            sha256 = pin.hash;
-          };
-          pins = self.pins;
-        };
+    packages =
+      (flattenPkgs "/" [] legacyPackages)
+      // {
+        inherit (docs.manual) htmlOpenTool;
 
-      inherit (docs.manual) htmlOpenTool;
-      # Documentation
-      docs = docs.manual.html;
-      docs-html = docs.manual.html;
-      docs-manpages = docs.manPages;
-      docs-json = docs.options.json;
-      docs-linkcheck = let
-        site = config.packages.docs;
-      in
-        pkgs.testers.lycheeLinkCheck {
-          inherit site;
+        # Documentation
+        docs = docs.manual.html;
+        docs-html = docs.manual.html;
+        docs-manpages = docs.manPages;
+        docs-json = docs.options.json;
+        docs-linkcheck = let
+          site = config.packages.docs;
+        in
+          pkgs.testers.lycheeLinkCheck {
+            inherit site;
 
-          remap = {
-            "https://notashelf.github.io/nvf/" = site;
+            remap = {
+              "https://notashelf.github.io/nvf/" = site;
+            };
+
+            extraConfig = {
+              exclude = [];
+              include_mail = true;
+              include_verbatim = true;
+            };
           };
 
-          extraConfig = {
-            exclude = [];
-            include_mail = true;
-            include_verbatim = true;
-          };
-        };
+        # Helper utility for building the HTML manual and opening it in the
+        # browser with $BROWSER or using xdg-open as a fallback tool.
+        # Adapted from Home-Manager, available under the MIT license.
+        docs-html-wrapped = let
+          xdg-open = lib.getExe' pkgs.xdg-utils "xdg-open";
+          docs-html = docs.manual.html + /share/doc/nvf;
+        in
+          pkgs.writeShellScriptBin "docs-html-wrapped" ''
+            set -euo pipefail
 
-      # Helper utility for building the HTML manual and opening it in the
-      # browser with $BROWSER or using xdg-open as a fallback tool.
-      # Adapted from Home-Manager, available under the MIT license.
-      docs-html-wrapped = let
-        xdg-open = lib.getExe' pkgs.xdg-utils "xdg-open";
-        docs-html = docs.manual.html + /share/doc/nvf;
-      in
-        pkgs.writeShellScriptBin "docs-html-wrapped" ''
-          set -euo pipefail
+            if [[ ! -v BROWSER || -z $BROWSER ]]; then
+              for candidate in xdg-open open w3m; do
+              BROWSER="$(type -P $candidate || true)"
+                if [[ -x $BROWSER ]]; then
+                  break;
+                fi
+              done
+            fi
 
-          if [[ ! -v BROWSER || -z $BROWSER ]]; then
-            for candidate in xdg-open open w3m; do
-            BROWSER="$(type -P $candidate || true)"
-              if [[ -x $BROWSER ]]; then
-                break;
-              fi
-            done
-          fi
+            if [[ ! -v BROWSER || -z $BROWSER ]]; then
+              echo "$0: unable to start a web browser; please set \$BROWSER"
+              echo "$0: Trying xdg-open as a fallback"
+              ${xdg-open} ${docs-html}/index.xhtml
+            else
+              echo "\$BROWSER is set. Attempting to open manual"
+              exec "$BROWSER" "${docs-html}/index.xhtml"
+            fi
+          '';
 
-          if [[ ! -v BROWSER || -z $BROWSER ]]; then
-            echo "$0: unable to start a web browser; please set \$BROWSER"
-            echo "$0: Trying xdg-open as a fallback"
-            ${xdg-open} ${docs-html}/index.xhtml
-          else
-            echo "\$BROWSER is set. Attempting to open manual"
-            exec "$BROWSER" "${docs-html}/index.xhtml"
-          fi
-        '';
-
-      # Exposed neovim configurations
-      nix = buildPkg false;
-      maximal = buildPkg true;
-      default = config.packages.nix;
-    };
+        # Exposed neovim configurations
+        nix = buildPkg false;
+        maximal = buildPkg true;
+        default = config.packages.nix;
+      };
   };
 }
diff --git a/flake/avante-nvim/default.nix b/flake/pkgs/by-name/avante-nvim/package.nix
similarity index 72%
rename from flake/avante-nvim/default.nix
rename to flake/pkgs/by-name/avante-nvim/package.nix
index 0d128bae..4f8cdd9d 100644
--- a/flake/avante-nvim/default.nix
+++ b/flake/pkgs/by-name/avante-nvim/package.nix
@@ -1,4 +1,5 @@
 {
+  pins,
   openssl,
   pkg-config,
   rustPlatform,
@@ -6,11 +7,17 @@
   vimUtils,
   makeWrapper,
   pkgs,
-  version,
-  src,
   ...
 }: let
-  inherit version src;
+  # From npins
+  pin = pins.avante-nvim;
+  version = pin.branch;
+  src = pkgs.fetchFromGitHub {
+    inherit (pin.repository) owner repo;
+    rev = pin.revision;
+    sha256 = pin.hash;
+  };
+
   avante-nvim-lib = rustPlatform.buildRustPackage {
     pname = "avante-nvim-lib";
     inherit version src;
@@ -48,10 +55,9 @@ in
       ext = stdenv.hostPlatform.extensions.sharedLibrary;
     in ''
       mkdir -p $out/build
-      ln -s ${avante-nvim-lib}/lib/libavante_repo_map${ext} $out/build/avante_repo_map${ext}
-      ln -s ${avante-nvim-lib}/lib/libavante_templates${ext} $out/build/avante_templates${ext}
-      ln -s ${avante-nvim-lib}/lib/libavante_tokenizers${ext} $out/build/avante_tokenizers${ext}
-      ln -s ${avante-nvim-lib}/lib/libavante_html2md${ext} $out/build/avante_html2md${ext}
+      for lib in avante_repo_map avante_templates avante_tokenizers avante_html2md; do
+        ln -s ${avante-nvim-lib}/lib/lib$lib${ext} $out/build/$$lib${ext}
+      done
     '';
 
     nvimSkipModules = [
diff --git a/flake/blink/default.nix b/flake/pkgs/by-name/blink-cmp/package.nix
similarity index 100%
rename from flake/blink/default.nix
rename to flake/pkgs/by-name/blink-cmp/package.nix

From 40a5b70c303682c61c6edff198a1db890fb4dec2 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Sun, 20 Jul 2025 16:13:19 +0300
Subject: [PATCH 09/13] docs/hacking: describe packaging complex plugins; more
 examples

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I6a6a6964ca83a42728d43e4a77b5737e9983016b
---
 docs/manual/hacking/additional-plugins.md | 159 +++++++++++++++++-----
 1 file changed, 123 insertions(+), 36 deletions(-)

diff --git a/docs/manual/hacking/additional-plugins.md b/docs/manual/hacking/additional-plugins.md
index 0ed252c7..1f7ba778 100644
--- a/docs/manual/hacking/additional-plugins.md
+++ b/docs/manual/hacking/additional-plugins.md
@@ -1,25 +1,92 @@
 # Adding Plugins {#sec-additional-plugins}
 
-To add a new Neovim plugin, use `npins`
+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.
 
-Use:
+## With npins {#sec-npins-for-plugins}
 
-`nix-shell -p npins` or `nix shell nixpkgs#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:
+
+```bash
+nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
+```
 
 Then run:
 
-`npins add --name <plugin name> github <owner> <repo> -b <branch>`
+```bash
+npins add --name <plugin name> github <owner> <repo> -b <branch>
+```
 
-Be sure to replace any non-alphanumeric characters with `-` for `--name`
+::: {.note}
 
-For example 
+Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
+example
 
-`npins add --name lazydev-nvim github folke lazydev.nvim -b main`
+```bash
+npins add --name lazydev-nvim github folke lazydev.nvim -b main
+```
 
-You can now reference this plugin as a **string**.
+:::
+
+Once the `npins` command is done, you can start referencing the plugin as a
+**string**.
 
 ```nix
-config.vim.startPlugins = ["lazydev-nvim"];
+{
+  config.vim.startPlugins = ["lazydev-nvim"];
+}
+```
+
+## Packaging Complex Plugins {#sec-pkgs-for-plugins}
+
+[blink.cmp]: https://github.com/Saghen/blink.cmp
+
+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.
+
+```nix
+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**.
+
+```nix
+{
+  config.vim.startPlugins = ["blink-cmp"];
+}
 ```
 
 ## Modular setup options {#sec-modular-setup-options}
@@ -70,7 +137,7 @@ in {
 }
 ```
 
-This above config will result in this lua script:
+This above config will result in this Lua script:
 
 ```lua
 require('plugin-name').setup({
@@ -101,23 +168,41 @@ own fields!
 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.
+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:
 
-Example:
+   ```nix
+   {
+    _type = "lua-inline";
+    expr = "function add(a, b) return a + b end";
+   }
+   ```
 
-```nix
-vim.your-plugin.setupOpts = {
-  on_init = lib.generators.mkLuaInline ''
-    function()
-      print('we can write lua!')
-    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.
+
+   ```nix
+   {
+      vim.your-plugin.setupOpts = {
+        on_init = lib.generators.mkLuaInline ''
+          function()
+            print('we can write lua!')
+          end
+        '';
+      };
+   }
+   ```
 
 ## Lazy plugins {#sec-lazy-plugins}
 
@@ -126,25 +211,24 @@ Lazy plugins are managed by `lz.n`.
 
 ```nix
 # 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";
@@ -152,7 +236,6 @@ in {
       }
     ];
   };
-;
 }
 ```
 
@@ -163,7 +246,9 @@ 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"},
@@ -175,5 +260,7 @@ require('lz.n').load({
 })
 ```
 
-A full list of options can be found
-[here](https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins
+[`vim.lazy.plugins` spec]: 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.

From 0a1dda51d0b548d960c0d6d344efeffede8af233 Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Sun, 20 Jul 2025 14:15:49 -0400
Subject: [PATCH 10/13] utility/undotree: formatted code

---
 modules/plugins/utility/undotree/undotree.nix | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/modules/plugins/utility/undotree/undotree.nix b/modules/plugins/utility/undotree/undotree.nix
index 2483a1ec..aac130fe 100644
--- a/modules/plugins/utility/undotree/undotree.nix
+++ b/modules/plugins/utility/undotree/undotree.nix
@@ -1,8 +1,6 @@
-{ lib, ... }:
-let
+{lib, ...}: let
   inherit (lib.options) mkEnableOption;
-in
-{
+in {
   options.vim.undotree = {
     enable = mkEnableOption "undo history visualizer for Vim [undotree]";
   };

From cec4a941976b27cf9083d2be42d9fc3178fb7769 Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Sun, 20 Jul 2025 15:52:38 -0400
Subject: [PATCH 11/13] utility/undotree: moved undotree to utility object

---
 configuration.nix                             | 11 +++++++----
 modules/plugins/utility/undotree/config.nix   |  2 +-
 modules/plugins/utility/undotree/undotree.nix |  2 +-
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/configuration.nix b/configuration.nix
index 0d53fec9..1834f344 100644
--- a/configuration.nix
+++ b/configuration.nix
@@ -43,7 +43,7 @@ isMaximal: {
     # This section does not include a comprehensive list of available language modules.
     # To list all available language module options, please visit the nvf manual.
     languages = {
-      enableFormat = true; #
+      enableFormat = true;
       enableTreesitter = true;
       enableExtraDiagnostics = true;
 
@@ -183,7 +183,7 @@ isMaximal: {
     projects = {
       project-nvim.enable = isMaximal;
     };
-    undotree.enable = isMaximal;
+
     utility = {
       ccc.enable = false;
       vim-wakatime.enable = false;
@@ -194,7 +194,7 @@ isMaximal: {
       leetcode-nvim.enable = isMaximal;
       multicursors.enable = isMaximal;
       smart-splits.enable = isMaximal;
-
+      undotree.enable = isMaximal;
       motion = {
         hop.enable = true;
         leap.enable = true;
@@ -238,7 +238,10 @@ isMaximal: {
           nix = "110";
           ruby = "120";
           java = "130";
-          go = ["90" "130"];
+          go = [
+            "90"
+            "130"
+          ];
         };
       };
       fastaction.enable = true;
diff --git a/modules/plugins/utility/undotree/config.nix b/modules/plugins/utility/undotree/config.nix
index d954d49f..deecdbcc 100644
--- a/modules/plugins/utility/undotree/config.nix
+++ b/modules/plugins/utility/undotree/config.nix
@@ -1,5 +1,5 @@
 {
-  vim.lazy.plugins.undotree = {
+  vim.lazy.plugins.utility.undotree = {
     package = "undotree";
     cmd = [
       "UndotreeToggle"
diff --git a/modules/plugins/utility/undotree/undotree.nix b/modules/plugins/utility/undotree/undotree.nix
index aac130fe..70846737 100644
--- a/modules/plugins/utility/undotree/undotree.nix
+++ b/modules/plugins/utility/undotree/undotree.nix
@@ -1,7 +1,7 @@
 {lib, ...}: let
   inherit (lib.options) mkEnableOption;
 in {
-  options.vim.undotree = {
+  options.vim.utility.undotree = {
     enable = mkEnableOption "undo history visualizer for Vim [undotree]";
   };
 }

From 338577d9c9296beba0d0a31885490a2344687e03 Mon Sep 17 00:00:00 2001
From: Abhi <85126640+abhirath-a@users.noreply.github.com>
Date: Mon, 21 Jul 2025 14:15:13 -0400
Subject: [PATCH 12/13] utility/undotree: removed utility category from lazy
 loader

---
 modules/plugins/utility/undotree/config.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/plugins/utility/undotree/config.nix b/modules/plugins/utility/undotree/config.nix
index deecdbcc..d954d49f 100644
--- a/modules/plugins/utility/undotree/config.nix
+++ b/modules/plugins/utility/undotree/config.nix
@@ -1,5 +1,5 @@
 {
-  vim.lazy.plugins.utility.undotree = {
+  vim.lazy.plugins.undotree = {
     package = "undotree";
     cmd = [
       "UndotreeToggle"

From 4437cc740abc4a5ebde6d94f153049fc259a340a Mon Sep 17 00:00:00 2001
From: raf <me@notashelf.dev>
Date: Mon, 21 Jul 2025 21:57:11 +0300
Subject: [PATCH 13/13] meta: undo nixfmt style hint

---
 configuration.nix | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/configuration.nix b/configuration.nix
index 1834f344..ac0ad32b 100644
--- a/configuration.nix
+++ b/configuration.nix
@@ -238,10 +238,7 @@ isMaximal: {
           nix = "110";
           ruby = "120";
           java = "130";
-          go = [
-            "90"
-            "130"
-          ];
+          go = ["90" "130"];
         };
       };
       fastaction.enable = true;