From 15b1a1ffcafc3b0ef825d336d7590f3a14e063b9 Mon Sep 17 00:00:00 2001
From: Axel Karjalainen <axel@axka.fi>
Date: Fri, 17 Oct 2025 19:20:07 +0300
Subject: [PATCH] docs: document `programs.nixvim` submodule

---
 docs/lib/index.md          | 50 ++++++++++++++++++++++++++++++++++----
 docs/user-guide/install.md | 25 +++++++++++++++++++
 2 files changed, 70 insertions(+), 5 deletions(-)

diff --git a/docs/lib/index.md b/docs/lib/index.md
index 3a4f2f4a..3f96f923 100644
--- a/docs/lib/index.md
+++ b/docs/lib/index.md
@@ -10,8 +10,7 @@ If Nixvim is built using the standalone method, you can access our "helpers" as
 }
 ```
 
-If Nixvim is being used as as a home-manager module, a nixos module, or as a darwin module,
-our "helpers" can be accessed via the `config.lib` option:
+If Nixvim is being used as as a home-manager module, a nixos module, or as a darwin module, our "helpers" can be accessed via the `config.lib` option:
 
 ```nix
 { config, ... }:
@@ -19,7 +18,46 @@ let
   helpers = config.lib.nixvim;
 in
 {
-  # Your config
+  programs.nixvim = {
+    # Your config
+    fooOption = helpers.mkRaw "print('hello')";
+  };
+}
+```
+
+The extended `lib` is also accessible in the `lib` module argument in the `programs.nixvim` submodule:
+```nix
+{
+  programs.nixvim =
+    { lib, ... }:
+    {
+      # You can use lib.nixvim in your config
+      fooOption = lib.nixvim.mkRaw "print('hello')";
+    };
+}
+```
+
+You can also import inside the submodule:
+
+<!-- This is also in /docs/user-guide/install.md -->
+
+```nix
+# home-config.nix
+{
+  # Imported modules are scoped within the `programs.nixvim` submodule
+  programs.nixvim.imports = [ ./nixvim.nix ];
+}
+```
+
+```nix
+# nixvim.nix
+{ lib, ... }:
+{
+  # You can use lib.nixvim in your config
+  fooOption = lib.nixvim.mkRaw "print('hello')";
+
+  # Configure NixVim without prefixing with `plugins.nixvim`
+  plugins.my-plugin.enable = true;
 }
 ```
 
@@ -28,8 +66,10 @@ Or you can access the extended `lib` used in standalone builds via the `nixvimLi
 ```nix
 { nixvimLib, ... }:
 {
-  # You can use nixvimLib.nixvim in your config
-  fooOption = nixvimLib.nixvim.mkRaw "print('hello')";
+  programs.nixvim = {
+    # You can use nixvimLib.nixvim in your config
+    fooOption = nixvimLib.nixvim.mkRaw "print('hello')";
+  };
 }
 ```
 
diff --git a/docs/user-guide/install.md b/docs/user-guide/install.md
index 14fefeb7..0fbdd6d8 100644
--- a/docs/user-guide/install.md
+++ b/docs/user-guide/install.md
@@ -67,6 +67,31 @@ The imports can be added as a `imports = [ <nixvim_import> ]` in a configuration
 You will then be able to enable nixvim through `programs.nixvim.enable = true`, and configure the
 options as `programs.nixvim.<path>.<to>.<option> = <value>`.
 
+> [!TIP]
+> Use `programs.nixvim.imports` to include modules configuring NixVim so you get NixVim's extended `lib` in the `lib` module argument and you don't have to prefix everything with `programs.nixvim`.
+>
+> <!-- This is also in /docs/lib/index.md -->
+>
+> ```nix
+> # home-config.nix
+> {
+>   # Imported modules are scoped within the `programs.nixvim` submodule
+>   programs.nixvim.imports = [ ./nixvim.nix ];
+> }
+> ```
+>
+> ```nix
+> # nixvim.nix
+> { lib, ... }:
+> {
+>   # You can use lib.nixvim in your config
+>   fooOption = lib.nixvim.mkRaw "print('hello')";
+>
+>   # Configure NixVim without prefixing with `plugins.nixvim`
+>   plugins.my-plugin.enable = true;
+> }
+> ```
+
 When you use nixvim as a module, an additional module argument is passed on allowing you to peek through the configuration with `hmConfig`, `nixosConfig`, and `darwinConfig` for home-manager, NixOS, and nix-darwin respectively.
 This is useful if you use nixvim both as part of an environment and standalone.