docs/user-guide: add lazy-loading.md

docs/mdbook/SUMMARY.md

@@ -8,6 +8,7 @@
 - [Helpers](./user-guide/helpers.md)
 - [FAQ](./user-guide/faq.md)
 - [Configuration examples](./user-guide/config-examples.md)
+- [Lazy Loading](./user-guide/lazy-loading.md)
 
 # Platforms
 

docs/user-guide/lazy-loading.md

@@ -0,0 +1,56 @@
+# Lazy Loading
+
+> [!WARNING]
+> This is an experimental option and may not work as expected with all plugins.
+> The API may change without notice. > Please report any issues you encounter.
+
+When the lazy loading functionality is enabled, the plugin's configuration is
+routed to the enabled lazy provider.
+
+## Supported Lazy Loading Providers
+
+It is recommended to become familiar with lazy loading strategies supported by
+your provider in their upstream documentation and the corresponding plugin's
+support.
+
+- [Lz.n](https://github.com/nvim-neorocks/lz.n?tab=readme-ov-file#plugin-spec)
+
+## Enabling Lazy Loading Per Plugin
+
+You can enable or disable lazy loading for a particular plugin through
+`${namespace}.${name}.lazyLoad.enable`.
+
+When a configuration is detected, we will automatically enable the lazy loading
+for the plugin with a configuration. If you are just wanting to store potential
+configuration without enabling it, you can explicitly disable it using the
+`${namespace}.${name}.lazyLoad.enable` option.
+
+When a plugin has lazy loading enabled, the Lua configuration for your plugin
+will be passed along to the corresponding lazy provider instead.
+
+## Configuring Triggers
+
+Currently, you need to define the trigger conditions in which a plugin will be
+loaded. This is done through the `${namespace}.${name}.lazyLoad.settings`
+option.
+
+```nix
+plugins.neotest = {
+  enable = true;
+  lazyLoad = {
+    settings = {
+      cmd = [
+        "Neotest"
+        "Neotest summary"
+      ];
+      keys = [
+        {
+          __unkeyed-1 = "<leader>nt";
+          __unkeyed-3 = "<CMD>Neotest summary<CR>";
+          desc = "Summary toggle";
+        }
+      ];
+    };
+  };
+};
+```