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,93 @@
+# 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. Options mentioned will be in relation to
+the `${namespace}.${name}.lazyLoad` context.
+
+## 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.
+
+Currently we only support **one** lazy loader:
+
+-lz.n: [`plugins.lz-n`](/plugins/lz-n/index.md) -
+[upstream docs](https://github.com/nvim-neorocks/lz.n?tab=readme-ov-file#plugin-spec)
+
+## Enabling Lazy Loading Per Plugin
+
+There are a couple different ways to enable lazy loading for a particular
+plugin.
+
+- `enable` set to `true`.
+- `settings` containing some configuration.
+
+If you are just wanting to store potential configuration without enabling it,
+you can explicitly disable it setting `enable = false`.
+
+When a plugin has lazy loading enabled, the Lua configuration for your plugin
+will be passed along to the corresponding lazy provider instead. This behavior
+can be overridden by using the `settings` option that will be passed to the
+provider.
+
+For `Lz.n`, that is the `settings.after` option.
+
+## Configuring Triggers
+
+You need to define the trigger conditions in which a plugin will be loaded. This
+is done through the `settings` option.
+
+```nix
+plugins = {
+  grug-far = {
+    enable = true;
+    lazyLoad = {
+      settings = {
+        cmd = "GrugFar";
+      };
+    };
+  };
+};
+```
+
+```nix
+plugins = {
+  glow = {
+    enable = true;
+    lazyLoad.settings.ft = "markdown";
+  };
+```
+
+```nix
+plugins.toggleterm = {
+  enable = true;
+  lazyLoad = {
+    settings = {
+      cmd = "ToggleTerm";
+      keys = [
+        "<leader>tg"
+        "<leader>gg"
+      ];
+    };
+  };
+};
+```
+
+### Colorschemes
+
+Colorschemes do not require explicit settings configuration. In `lz-n`, we will
+set up the `colorscheme` trigger to the name of the `colorscheme` so that it is
+lazy loaded when the `colorscheme` is requested.
+
+```nix
+colorscheme = "catppuccin";
+colorschemes.catppuccin = {
+  enable = true;
+  lazyLoad.enable = true;
+};
+```