docs: clarify lazyLoad.after behavior and mention luaConfig.post

Author: yzx9

docs/user-guide/lazy-loading.md

@@ -31,11 +31,20 @@ provider's loading mechanism.
 If you are just wanting to store potential configuration without enabling it,
 you can explicitly disable it setting `lazyLoad.enable = false`.
 
-By default, we route the generated setup code to your lazy loading provider, but
-it can be overridden by using the `lazyLoad.settings` option.
+By default, we route the generated setup code (what Nixvim would normally put in
+`luaConfig.content`) to your lazy loading provider. For the `lz.n` backend, this
+means we automatically generate an `after` function for you, that will be called
+when a trigger condition is met.
 
-For `Lz.n`, the `lazyLoad.settings.after` option contains what it will call when
-a trigger condition is met.
+You can override this default by providing `lazyLoad.settings.after` yourself.
+Note that this is an **override**: once you set `lazyLoad.settings.after`, Nixvim
+will use your function instead of the auto-generated one, it will not "extend"
+or "wrap" the default behavior.
+
+If you only need to run some extra Lua **after** the plugin (or colorscheme) has
+been configured, you usually do **not** need to override `lazyLoad.settings.after`.
+Instead, you can use the module's `luaConfig.post` hook, see the plugin's /
+colorscheme's documentation for details
 
 ## Configuring Triggers
 
@@ -126,3 +135,28 @@ colorschemes.catppuccin = {
   lazyLoad.enable = true;
 };
 ```
+
+To configure special integrations after `catppuccin` has been set up (while
+still letting Nixvim manage lazy loading and the default `after`):
+
+```nix
+colorscheme = "catppuccin";
+colorschemes.catppuccin = {
+  enable = true;
+  lazyLoad.enable = true;
+
+  # This code runs after catppuccin's setup has completed,
+  # regardless of whether it was lazy-loaded or not.
+  luaConfig.post = ''
+    -- At this point catppuccin is configured, so we can safely
+    -- derive bufferline highlights or similar settings from it.
+    require('lz.n').trigger_load("bufferline.nvim")
+  '';
+};
+
+plugins.bufferline = {
+  enable = true;
+  settings.highlights.__raw = "require('catppuccin.special.bufferline').get_theme()";
+  lazyLoad.settings.lazy = true; # Lazy load manually
+};
+```