From fcb6f82892ad1c5831cb369a0328f2abb677f47f Mon Sep 17 00:00:00 2001
From: LilleAila <olai.solsvik@gmail.com>
Date: Sun, 19 Jan 2025 18:01:43 +0100
Subject: [PATCH 1/9] highlight: init

---
 docs/release-notes/rl-0.8.md      |   1 +
 modules/neovim/init/default.nix   |   1 +
 modules/neovim/init/highlight.nix | 106 ++++++++++++++++++++++++++++++
 3 files changed, 108 insertions(+)
 create mode 100644 modules/neovim/init/highlight.nix

diff --git a/docs/release-notes/rl-0.8.md b/docs/release-notes/rl-0.8.md
index 42927baf..f835abf1 100644
--- a/docs/release-notes/rl-0.8.md
+++ b/docs/release-notes/rl-0.8.md
@@ -102,6 +102,7 @@
   - `mini.trailspace`
   - `mini.visits`
 - Add [fzf-lua](https://github.com/ibhagwan/fzf-lua) in `vim.fzf-lua`
+- Add options to define highlights under `vim.highlight`
 
 [kaktu5](https://github.com/kaktu5):
 
diff --git a/modules/neovim/init/default.nix b/modules/neovim/init/default.nix
index 11d9cf59..b0c7e0ce 100644
--- a/modules/neovim/init/default.nix
+++ b/modules/neovim/init/default.nix
@@ -2,6 +2,7 @@
   imports = [
     ./basic.nix
     ./debug.nix
+    ./highlight.nix
     ./spellcheck.nix
   ];
 }
diff --git a/modules/neovim/init/highlight.nix b/modules/neovim/init/highlight.nix
new file mode 100644
index 00000000..d00fe74a
--- /dev/null
+++ b/modules/neovim/init/highlight.nix
@@ -0,0 +1,106 @@
+{
+  config,
+  lib,
+  ...
+}: let
+  inherit (lib.options) mkOption literalExpression;
+  inherit (lib.types) nullOr attrsOf listOf submodule bool ints str;
+  inherit (lib.strings) hasPrefix concatStringsSep;
+  inherit (lib.attrsets) mapAttrsToList;
+  inherit (lib.nvim.dag) entryAnywhere;
+  inherit (lib.nvim.lua) toLuaObject;
+  inherit (lib.nvim.types) hexColor;
+
+  mkColorOption = target:
+    mkOption {
+      type = nullOr hexColor;
+      default = null;
+      description = ''
+        The ${target} color to use. Written as color name or hex "#RRGGBB".
+      '';
+      example = "#ebdbb2";
+    };
+
+  mkBoolOption = name:
+    mkOption {
+      type = nullOr bool;
+      default = null;
+      description = ''Whether to enable ${name}'';
+      example = false;
+    };
+
+  cfg = config.vim.highlight;
+in {
+  options.vim.highlight = mkOption {
+    type = attrsOf (submodule {
+      # See :h nvim_set_hl
+      options = {
+        bg = mkColorOption "background";
+        fg = mkColorOption "foreground";
+        sp = mkColorOption "special";
+        blend = mkOption {
+          type = nullOr (ints.between 0 100);
+          default = null;
+          description = "Blend as an integer between 0 and 100";
+        };
+        bold = mkBoolOption "bold";
+        standout = mkBoolOption "standout";
+        underline = mkBoolOption "underline";
+        undercurl = mkBoolOption "undercurl";
+        underdouble = mkBoolOption "underdouble";
+        underdotted = mkBoolOption "underdotted";
+        underdashed = mkBoolOption "underdashed";
+        strikethrough = mkBoolOption "strikethrough";
+        italic = mkBoolOption "italic";
+        reverse = mkBoolOption "reverse";
+        nocombine = mkBoolOption "nocombine";
+        link = mkOption {
+          type = nullOr str;
+          default = null;
+          description = "The name of another highlight group to link to";
+        };
+        default = mkOption {
+          type = nullOr bool;
+          default = null;
+          description = "Don't override existing definition";
+        };
+        ctermfg = mkOption {
+          type = nullOr str;
+          default = null;
+          description = "The cterm foreground color to use";
+        };
+        ctermbg = mkOption {
+          type = nullOr str;
+          default = null;
+          description = "The cterm background color to use";
+        };
+        cterm = mkOption {
+          type = nullOr (listOf str);
+          default = null;
+          description = "The cterm arguments to use. See :h highlight-args";
+        };
+        force = mkBoolOption "force update";
+      };
+    });
+    default = {};
+    description = "Custom highlight to apply";
+    example = literalExpression ''
+      {
+        SignColumn = {
+          bg = "#282828";
+        };
+      }
+    '';
+  };
+
+  config = {
+    vim.luaConfigRC.highlight = let
+      highlights =
+        mapAttrsToList (
+          name: value: ''vim.api.nvim_set_hl(0, ${toLuaObject name}, ${toLuaObject value})''
+        )
+        cfg;
+    in
+      entryAnywhere (concatStringsSep "\n" highlights);
+  };
+}

From 5e3a0dcdc32259e50a78d763a6f5720b73b1de5e Mon Sep 17 00:00:00 2001
From: LilleAila <olai.solsvik@gmail.com>
Date: Sun, 19 Jan 2025 18:11:12 +0100
Subject: [PATCH 2/9] highlight: cterm as enum

---
 modules/neovim/init/highlight.nix | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/modules/neovim/init/highlight.nix b/modules/neovim/init/highlight.nix
index d00fe74a..8c110cac 100644
--- a/modules/neovim/init/highlight.nix
+++ b/modules/neovim/init/highlight.nix
@@ -4,7 +4,7 @@
   ...
 }: let
   inherit (lib.options) mkOption literalExpression;
-  inherit (lib.types) nullOr attrsOf listOf submodule bool ints str;
+  inherit (lib.types) nullOr attrsOf listOf submodule bool ints str enum;
   inherit (lib.strings) hasPrefix concatStringsSep;
   inherit (lib.attrsets) mapAttrsToList;
   inherit (lib.nvim.dag) entryAnywhere;
@@ -75,7 +75,22 @@ in {
           description = "The cterm background color to use";
         };
         cterm = mkOption {
-          type = nullOr (listOf str);
+          type = nullOr (listOf (enum [
+            "bold"
+            "underline"
+            "undercurl"
+            "underdouble"
+            "underdotted"
+            "underdashed"
+            "strikethrough"
+            "reverse"
+            "inverse"
+            "italic"
+            "standout"
+            "altfont"
+            "nocombine"
+            "NONE"
+          ]));
           default = null;
           description = "The cterm arguments to use. See :h highlight-args";
         };

From 653e5d6a176378386e803c767aa8da4dbdd96f11 Mon Sep 17 00:00:00 2001
From: LilleAila <olai.solsvik@gmail.com>
Date: Sun, 19 Jan 2025 19:36:32 +0100
Subject: [PATCH 3/9] highlight: implement suggestions

---
 docs/release-notes/rl-0.8.md      |  2 +-
 modules/neovim/init/highlight.nix | 16 ++++++++--------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/release-notes/rl-0.8.md b/docs/release-notes/rl-0.8.md
index f835abf1..7fe3d2e5 100644
--- a/docs/release-notes/rl-0.8.md
+++ b/docs/release-notes/rl-0.8.md
@@ -102,7 +102,7 @@
   - `mini.trailspace`
   - `mini.visits`
 - Add [fzf-lua](https://github.com/ibhagwan/fzf-lua) in `vim.fzf-lua`
-- Add options to define highlights under `vim.highlight`
+- Add options to define highlights under [](#opt-vim.highlight)
 
 [kaktu5](https://github.com/kaktu5):
 
diff --git a/modules/neovim/init/highlight.nix b/modules/neovim/init/highlight.nix
index 8c110cac..606f1c05 100644
--- a/modules/neovim/init/highlight.nix
+++ b/modules/neovim/init/highlight.nix
@@ -3,11 +3,11 @@
   lib,
   ...
 }: let
-  inherit (lib.options) mkOption literalExpression;
+  inherit (lib.options) mkOption;
   inherit (lib.types) nullOr attrsOf listOf submodule bool ints str enum;
-  inherit (lib.strings) hasPrefix concatStringsSep;
+  inherit (lib.strings) hasPrefix concatLines;
   inherit (lib.attrsets) mapAttrsToList;
-  inherit (lib.nvim.dag) entryAnywhere;
+  inherit (lib.nvim.dag) entryBetween;
   inherit (lib.nvim.lua) toLuaObject;
   inherit (lib.nvim.types) hexColor;
 
@@ -15,18 +15,18 @@
     mkOption {
       type = nullOr hexColor;
       default = null;
+      example = "#ebdbb2";
       description = ''
         The ${target} color to use. Written as color name or hex "#RRGGBB".
       '';
-      example = "#ebdbb2";
     };
 
   mkBoolOption = name:
     mkOption {
       type = nullOr bool;
       default = null;
-      description = ''Whether to enable ${name}'';
       example = false;
+      description = "Whether to enable ${name}";
     };
 
   cfg = config.vim.highlight;
@@ -98,14 +98,14 @@ in {
       };
     });
     default = {};
-    description = "Custom highlight to apply";
-    example = literalExpression ''
+    example = ''
       {
         SignColumn = {
           bg = "#282828";
         };
       }
     '';
+    description = "Custom highlights to apply";
   };
 
   config = {
@@ -116,6 +116,6 @@ in {
         )
         cfg;
     in
-      entryAnywhere (concatStringsSep "\n" highlights);
+      entryBetween ["lazyConfigs" "pluginConfigs" "extraPluginConfigs"] ["theme"] (concatLines highlights);
   };
 }

From 28bbe89fbc92ff6a1b6c180d9812ee6ddf706207 Mon Sep 17 00:00:00 2001
From: LilleAila <olai.solsvik@gmail.com>
Date: Mon, 20 Jan 2025 14:16:45 +0100
Subject: [PATCH 4/9] highlight: example without ''

---
 modules/neovim/init/highlight.nix | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/modules/neovim/init/highlight.nix b/modules/neovim/init/highlight.nix
index 606f1c05..8c7eca82 100644
--- a/modules/neovim/init/highlight.nix
+++ b/modules/neovim/init/highlight.nix
@@ -98,13 +98,11 @@ in {
       };
     });
     default = {};
-    example = ''
-      {
-        SignColumn = {
-          bg = "#282828";
-        };
-      }
-    '';
+    example = {
+      SignColumn = {
+        bg = "#282828";
+      };
+    };
     description = "Custom highlights to apply";
   };
 

From f58f41629f82ea7c88a84333ba261369194fe7de Mon Sep 17 00:00:00 2001
From: LilleAila <olai.solsvik@gmail.com>
Date: Mon, 20 Jan 2025 14:28:36 +0100
Subject: [PATCH 5/9] highlight: :h reference in single quotes

---
 modules/neovim/init/highlight.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/neovim/init/highlight.nix b/modules/neovim/init/highlight.nix
index 8c7eca82..7e992fd1 100644
--- a/modules/neovim/init/highlight.nix
+++ b/modules/neovim/init/highlight.nix
@@ -92,7 +92,7 @@ in {
             "NONE"
           ]));
           default = null;
-          description = "The cterm arguments to use. See :h highlight-args";
+          description = "The cterm arguments to use. See ':h highlight-args'";
         };
         force = mkBoolOption "force update";
       };

From 4b6021073cd9aa09f75c4c2e89fa18cd3224793a Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Wed, 22 Jan 2025 12:16:03 +0300
Subject: [PATCH 6/9] flake: bump nixpkgs

---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index c328bda1..ee19b7c8 100644
--- a/flake.lock
+++ b/flake.lock
@@ -77,11 +77,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1735523292,
-        "narHash": "sha256-opBsbR/nrGxiiF6XzlVluiHYb6yN/hEwv+lBWTy9xoM=",
+        "lastModified": 1737370608,
+        "narHash": "sha256-hFA6SmioeqvGW/XvZa9bxniAeulksCOcj3kokdNT/YE=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "6d97d419e5a9b36e6293887a89a078cf85f5a61b",
+        "rev": "300081d0cc72df578b02d914df941b8ec62240e6",
         "type": "github"
       },
       "original": {

From 547cbd28b61b605fa7e308f0575d1f4acb7f3aac Mon Sep 17 00:00:00 2001
From: ARCIII <88923299+ArmandoCIII@users.noreply.github.com>
Date: Sat, 25 Jan 2025 08:17:48 -0500
Subject: [PATCH 7/9] languages/zig: add dap support (#581)

* languages/zig: Added dap support

Implemented DAP support for zig. Included comment regarding redundant
`dap.adapters.lldb` code when both clang and zig dap modules are
enabled.

* languages/zig: Added dap support cleanup

Cleaned up code from the zig dap implementation for consistency.
---
 docs/release-notes/rl-0.8.md      |  5 +++
 modules/plugins/languages/zig.nix | 61 ++++++++++++++++++++++++++++++-
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/docs/release-notes/rl-0.8.md b/docs/release-notes/rl-0.8.md
index 95bb6661..b06a071f 100644
--- a/docs/release-notes/rl-0.8.md
+++ b/docs/release-notes/rl-0.8.md
@@ -122,3 +122,8 @@
 [ruff]: (https://github.com/astral-sh/ruff)
 
 - Add [ruff] as a formatter option in `vim.languages.python.format.type`.
+
+[ARCIII](https://github.com/ArmandoCIII):
+
+- Add `vim.languages.zig.dap` support through pkgs.lldb dap adapter.
+  Code Inspiration from `vim.languages.clang.dap` implementation.
diff --git a/modules/plugins/languages/zig.nix b/modules/plugins/languages/zig.nix
index 1b9a588b..2aa0e2b6 100644
--- a/modules/plugins/languages/zig.nix
+++ b/modules/plugins/languages/zig.nix
@@ -8,10 +8,12 @@
   inherit (lib.options) mkEnableOption mkOption;
   inherit (lib.modules) mkIf mkMerge mkDefault;
   inherit (lib.lists) isList;
-  inherit (lib.types) either listOf package str enum;
+  inherit (lib.types) bool either listOf package str enum;
   inherit (lib.nvim.lua) expToLua;
   inherit (lib.nvim.types) mkGrammarOption;
 
+  cfg = config.vim.languages.zig;
+
   defaultServer = "zls";
   servers = {
     zls = {
@@ -31,7 +33,35 @@
     };
   };
 
-  cfg = config.vim.languages.zig;
+  # TODO: dap.adapter.lldb is duplicated when enabling the
+  # vim.languages.clang.dap module. This does not cause
+  # breakage... but could be cleaner.
+  defaultDebugger = "lldb-vscode";
+  debuggers = {
+    lldb-vscode = {
+      package = pkgs.lldb;
+      dapConfig = ''
+        dap.adapters.lldb = {
+          type = 'executable',
+          command = '${cfg.dap.package}/bin/lldb-dap',
+          name = 'lldb'
+        }
+        dap.configurations.zig = {
+          {
+            name = 'Launch',
+            type = 'lldb',
+            request = 'launch',
+            program = function()
+              return vim.fn.input('Path to executable: ', vim.fn.getcwd() .. '/', 'file')
+            end,
+            cwd = "''${workspaceFolder}",
+            stopOnEntry = false,
+            args = {},
+          },
+        }
+      '';
+    };
+  };
 in {
   options.vim.languages.zig = {
     enable = mkEnableOption "Zig language support";
@@ -56,6 +86,26 @@ in {
         default = pkgs.zls;
       };
     };
+
+    dap = {
+      enable = mkOption {
+        type = bool;
+        default = config.vim.languages.enableDAP;
+        description = "Enable Zig Debug Adapter";
+      };
+
+      debugger = mkOption {
+        type = enum (attrNames debuggers);
+        default = defaultDebugger;
+        description = "Zig debugger to use";
+      };
+
+      package = mkOption {
+        type = package;
+        default = debuggers.${cfg.dap.debugger}.package;
+        description = "Zig debugger package.";
+      };
+    };
   };
 
   config = mkIf cfg.enable (mkMerge [
@@ -77,5 +127,12 @@ in {
         globals.zig_fmt_autosave = mkDefault 0;
       };
     })
+
+    (mkIf cfg.dap.enable {
+      vim = {
+        debugger.nvim-dap.enable = true;
+        debugger.nvim-dap.sources.zig-debugger = debuggers.${cfg.dap.debugger}.dapConfig;
+      };
+    })
   ]);
 }

From 9a9340960609a25762379113f6634c317decffc6 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Sun, 19 Jan 2025 20:26:52 +0300
Subject: [PATCH 8/9] lsp/lightbulb: cleanup; modularize autocommand behaviour

---
 docs/release-notes/rl-0.8.md                | 16 +++++++++---
 modules/plugins/lsp/lightbulb/config.nix    | 27 +++++++++++++++++----
 modules/plugins/lsp/lightbulb/lightbulb.nix | 22 +++++++++++++++--
 3 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/docs/release-notes/rl-0.8.md b/docs/release-notes/rl-0.8.md
index b06a071f..f5e9d0a0 100644
--- a/docs/release-notes/rl-0.8.md
+++ b/docs/release-notes/rl-0.8.md
@@ -31,6 +31,12 @@
   your Editorconfig configuration, or use an autocommand to set indentation
   values for buffers with the Nix filetype.
 
+- Add [](#opt-vim.lsp.lightbulb.autocmd.enable) for manually managing the
+  previously managed lightbulb autocommand.
+  - A warning will occur if [](#opt-vim.lsp.lightbulb.autocmd.enable) and
+    `vim.lsp.lightbulb.setupOpts.autocmd.enabled` are both set at the same time.
+    Pick only one.
+
 [amadaluzia](https://github.com/amadaluzia):
 
 [haskell-tools.nvim]: https://github.com/MrcJkb/haskell-tools.nvim
@@ -59,7 +65,8 @@
 - Add `vim.snippets.luasnip.setupOpts`, which was previously missing.
 - Add `"prettierd"` as a formatter option in
   `vim.languages.markdown.format.type`.
-- Add the following plugins from [mini.nvim](https://github.com/echasnovski/mini.nvim)
+- Add the following plugins from
+  [mini.nvim](https://github.com/echasnovski/mini.nvim)
   - `mini.ai`
   - `mini.align`
   - `mini.animate`
@@ -102,7 +109,8 @@
   - `mini.trailspace`
   - `mini.visits`
 - Add [fzf-lua](https://github.com/ibhagwan/fzf-lua) in `vim.fzf-lua`
-- Add [rainbow-delimiters](https://github.com/HiPhish/rainbow-delimiters.nvim) in `vim.visuals.rainbow-delimiters`
+- Add [rainbow-delimiters](https://github.com/HiPhish/rainbow-delimiters.nvim)
+  in `vim.visuals.rainbow-delimiters`
 - Add options to define highlights under [](#opt-vim.highlight)
 
 [kaktu5](https://github.com/kaktu5):
@@ -125,5 +133,5 @@
 
 [ARCIII](https://github.com/ArmandoCIII):
 
-- Add `vim.languages.zig.dap` support through pkgs.lldb dap adapter.
-  Code Inspiration from `vim.languages.clang.dap` implementation.
+- Add `vim.languages.zig.dap` support through pkgs.lldb dap adapter. Code
+  Inspiration from `vim.languages.clang.dap` implementation.
diff --git a/modules/plugins/lsp/lightbulb/config.nix b/modules/plugins/lsp/lightbulb/config.nix
index f17b8ad9..17e740ad 100644
--- a/modules/plugins/lsp/lightbulb/config.nix
+++ b/modules/plugins/lsp/lightbulb/config.nix
@@ -4,6 +4,7 @@
   ...
 }: let
   inherit (lib.modules) mkIf;
+  inherit (lib.strings) optionalString;
   inherit (lib.nvim.dag) entryAnywhere;
   inherit (lib.nvim.lua) toLuaObject;
 
@@ -12,13 +13,29 @@ in {
   config = mkIf (cfg.enable && cfg.lightbulb.enable) {
     vim = {
       startPlugins = ["nvim-lightbulb"];
-
       pluginRC.lightbulb = entryAnywhere ''
-        vim.api.nvim_command('autocmd CursorHold,CursorHoldI * lua require\'nvim-lightbulb\'.update_lightbulb()')
-
-        -- Enable trouble diagnostics viewer
-        require'nvim-lightbulb'.setup(${toLuaObject cfg.lightbulb.setupOpts})
+        local nvim_lightbulb = require("nvim-lightbulb")
+        nvim_lightbulb.setup(${toLuaObject cfg.lightbulb.setupOpts})
+        ${optionalString cfg.lightbulb.autocmd.enable ''
+          vim.api.nvim_create_autocmd(${toLuaObject cfg.lightbulb.autocmd.events}, {
+            pattern = ${toLuaObject cfg.lightbulb.autocmd.pattern},
+            callback = function()
+              nvim_lightbulb.update_lightbulb()
+            end,
+          })
+        ''}
       '';
     };
+
+    warnings = [
+      # This could have been an assertion, but the chances of collision is very low and asserting here
+      # might be too dramatic. Let's only warn the user, *in case* this occurs and is not intended. No
+      # error will be thrown if 'lightbulb.setupOpts.autocmd.enable' has not been set by the user.
+      (mkIf (cfg.lightbulb.autocmd.enable -> (cfg.lightbulb.setupOpts.autocmd.enabled or false)) ''
+        Both 'vim.lsp.lightbulb.autocmd.enable' and 'vim.lsp.lightbulb.setupOpts.autocmd.enable' are set
+        simultaneously. This might have performance implications due to frequent updates. Please set only
+        one option to handle nvim-lightbulb autocmd.
+      '')
+    ];
   };
 }
diff --git a/modules/plugins/lsp/lightbulb/lightbulb.nix b/modules/plugins/lsp/lightbulb/lightbulb.nix
index 4341cac6..012d54aa 100644
--- a/modules/plugins/lsp/lightbulb/lightbulb.nix
+++ b/modules/plugins/lsp/lightbulb/lightbulb.nix
@@ -1,11 +1,29 @@
 {lib, ...}: let
-  inherit (lib.options) mkEnableOption;
-  inherit (lib.nvim.types) mkPluginSetupOption;
+  inherit (lib.options) mkOption mkEnableOption;
+  inherit (lib.types) listOf str either;
+  inherit (lib.nvim.types) mkPluginSetupOption luaInline;
 in {
   options.vim.lsp = {
     lightbulb = {
       enable = mkEnableOption "Lightbulb for code actions. Requires an emoji font";
       setupOpts = mkPluginSetupOption "nvim-lightbulb" {};
+      autocmd = {
+        enable = mkEnableOption "updating lightbulb glyph automatically" // {default = true;};
+        events = mkOption {
+          type = listOf str;
+          default = ["CursorHold" "CursorHoldI"];
+          description = "Events on which to update nvim-lightbulb glyphs";
+        };
+
+        pattern = mkOption {
+          type = either str luaInline;
+          default = "*";
+          description = ''
+            File patterns or buffer names to match, determining which files or buffers trigger
+            glyph updates.
+          '';
+        };
+      };
     };
   };
 }

From a5b7b17947e42d3a990d2db8361d794987b1d963 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Sat, 25 Jan 2025 17:21:08 +0300
Subject: [PATCH 9/9] docs: improve manpages; mention helpful utilities

---
 docs/man/header.5 | 15 +++++++++------
 docs/man/nvf.1    | 41 ++++++++++++++++++++++++++++++-----------
 2 files changed, 39 insertions(+), 17 deletions(-)

diff --git a/docs/man/header.5 b/docs/man/header.5
index a28fc3dd..556a113a 100644
--- a/docs/man/header.5
+++ b/docs/man/header.5
@@ -1,13 +1,16 @@
-.TH "nvf" "5" "01/01/1980" "nvf"
+.TH "nvf" "5" "January 1, 1980" "nvf"
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
 .ad l
 .\" enable line breaks after slashes
 .cflags 4 /
+
 .SH "NAME"
-nvf configuration specification
-.SH "OPTIONS"
-.PP
-You can use the following options to configure nvf:
-.PP
+nvf \- Configuration specification for the nvf.
+
+.SH "DESCRIPTION"
+The nvf configuration specification provides a declarative structure for configuring Neovim using Nix with few
+lines of Nix. This document outlines the available options and their usage to create modular, reusable, and
+reproducible configurations using nvf's module system options. For tips, tricks and possible quirks with available
+plugins please visit https://notashelf.github.io/nvf/
diff --git a/docs/man/nvf.1 b/docs/man/nvf.1
index 0f1e36dc..d7519651 100644
--- a/docs/man/nvf.1
+++ b/docs/man/nvf.1
@@ -1,5 +1,5 @@
 .Dd January 1, 1980
-.Dt nvf 1
+.Dt NVF 1
 .Os nvf
 .\" disable hyphenation
 .nh
@@ -7,27 +7,46 @@
 .ad l
 .\" enable line breaks after slashes
 .cflags 4 /
+
 .Sh NAME
 .Nm nvf
-.Nd A highly modular, extensible and distro-agnostic Neovim configuration framework for Nix/NixOS.
-.
+.Nd A modular, extensible, and distro-agnostic Neovim configuration framework for Nix/NixOS.
+
+.Sh DESCRIPTION
+.Nm nvf
+is a highly modular, configurable, extensible, and easy-to-use Neovim configuration in Nix.
+Designed for flexibility and ease of use, nvf allows you to easily configure your fully featured
+Neovim instance with a few lines of Nix.
+
+.Sh COMMANDS
+The following commands are bundled with nvf to allow easier debugging of your configuration.
+
+.Bl -tag -width Ds
+.It Nm nvf-print-config
+Outputs the full configuration of the current `nvf` setup. This command is useful for debugging
+or inspecting the applied configuration.
+.Pp
+.It Nm nvf-print-config-path
+Prints the file path to the configuration file currently in use. This command is helpful for locating
+the source configuration file for troubleshooting or easily sharing it via online paste utilities.
+.El
+
 .Sh BUGS
 .Pp
-Please report any bugs that you might encounter on the
-\m[blue]\fBproject issue tracker\fR\m[]\&.
+Please report any bugs on the project issue tracker:
+.Lk https://github.com/notashelf/nvf/issues
 
 .Sh SEE ALSO
 .Pp
-\fBnvf\fR(5)
+.Fn nvf 5
 
 .Sh AUTHOR
 .Pp
-\fBnvf contributors\fR
+.Fn nvf contributors
 .RS 4
-Author.
+Primary contributors and maintainers of the project.
 .RE
 
 .Sh COPYRIGHT
-.br
-Copyright \(co 2023\(en2024 nvf contributors
-.br
+.Pp
+Copyright (c) 2023–2025 nvf contributors.