From 5dff6a8cab2162c7eae87239286f64bb9df1b865 Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Fri, 5 Jun 2026 13:24:37 +0100
Subject: [PATCH] docs/platforms/standalone: document convenience functions

Co-authored-by: Austin Horstman <khaneliman12@gmail.com>
---
 docs/platforms/standalone.md | 82 ++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/platforms/standalone.md b/docs/platforms/standalone.md
index a1c58a64..35046396 100644
--- a/docs/platforms/standalone.md
+++ b/docs/platforms/standalone.md
@@ -157,6 +157,88 @@ The example assumes the standalone configuration is exported as the `default` pa
 }
 ```
 
+## Convenience functions
+
+For simple use cases, Nixvim provides helper functions that combine configuration evaluation and output selection.
+
+These are thin wrappers around `evalNixvim` selecting `config.build.package` or `config.build.test`.
+
+See the [reference docs][lib.nixvim.modules] for more detail.
+
+### buildNixvim
+
+Builds a Nixvim package from a module or list of modules.
+
+```nix
+buildNixvim {
+  imports = [ ./config ];
+  nixpkgs.hostPlatform = system;
+}
+```
+
+Equivalent to:
+
+```nix
+(evalNixvim {
+  inherit system;
+  modules = [ ./config ];
+}).config.build.package
+```
+
+### buildNixvimWith
+
+Like `buildNixvim`, but accepts the full set of arguments supported by `evalNixvim`.
+
+```nix
+buildNixvimWith {
+  inherit system;
+  modules = [ ./config ];
+}
+```
+
+Equivalent to:
+
+```nix
+(evalNixvim {
+  inherit system;
+  modules = [ ./config ];
+}).config.build.package
+```
+
+### testNixvim
+
+Produces a test derivation from an existing Nixvim package.
+
+```nix
+testNixvim myNvim
+```
+
+Equivalent to:
+
+```nix
+myNvim.config.build.test
+```
+
+### testNixvimWith
+
+Evaluates a configuration and returns its test derivation.
+
+```nix
+testNixvimWith {
+  inherit system;
+  modules = [ ./config ];
+}
+```
+
+Equivalent to:
+
+```nix
+(evalNixvim {
+  inherit system;
+  modules = [ ./config ];
+}).config.build.test
+```
+
 [lib.nixvim.modules]: ../lib/nixvim/modules/index.md
 [evalModules-output]: https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules
 [evalModules-type]: https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules-return-value-type