From 8a74f41a208b2fb64b2e3f5e1eccb49a20bdc92d Mon Sep 17 00:00:00 2001
From: Austin Horstman <khaneliman12@gmail.com>
Date: Tue, 10 Dec 2024 10:36:31 -0600
Subject: [PATCH] docs/user-guide: add lazy-loading.md

---
 docs/mdbook/SUMMARY.md          |  1 +
 docs/user-guide/lazy-loading.md | 88 +++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 docs/user-guide/lazy-loading.md

diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md
index cf281108b8..d08c19fd7d 100644
--- a/docs/mdbook/SUMMARY.md
+++ b/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
 
diff --git a/docs/user-guide/lazy-loading.md b/docs/user-guide/lazy-loading.md
new file mode 100644
index 0000000000..ec400affd8
--- /dev/null
+++ b/docs/user-guide/lazy-loading.md
@@ -0,0 +1,88 @@
+# 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.
+
+- [Lz.n](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
+
+Currently, 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"
+      ];
+    };
+  };
+};
+```
+
+The only exception to this is `colorschemes`. 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;
+};
+```