Merge pull request #708 from NotAShelf/docs-cleanup-again

docs: yet another cleanup

docs/manual/configuring.md

@@ -1,5 +1,15 @@
 # Configuring nvf {#ch-configuring}
 
+[helpful tips section]: #ch-helpful-tips
+
+nvf allows for _very_ extensive configuration in Neovim through the Nix module
+interface. The below chapters describe several of the options exposed in nvf for
+your convenience. You might also be interested in the [helpful tips section] for
+more advanced or unusual configuration options supported by nvf.
+
+Note that this section does not cover module _options_. For an overview of all
+module options provided by nvf, please visit the [appendix](/options.html)
+
 ```{=include=} chapters
 configuring/custom-package.md
 configuring/custom-plugins.md
@@ -7,4 +17,5 @@ configuring/overriding-plugins.md
 configuring/languages.md
 configuring/dags.md
 configuring/dag-entries.md
+configuring/autocmds.md
 ```

docs/manual/configuring/autocmds.md

@@ -0,0 +1,119 @@
+# Autocommands and Autogroups {#ch-autocmds-augroups}
+
+This module allows you to declaratively configure Neovim autocommands and
+autogroups within your Nix configuration.
+
+## Autogroups (`vim.augroups`) {#sec-vim-augroups}
+
+Autogroups (`augroup`) organize related autocommands. This allows them to be
+managed collectively, such as clearing them all at once to prevent duplicates.
+Each entry in the list is a submodule with the following options:
+
+| Option   | Type   | Default | Description                                                                                          | Example           |
+| :------- | :----- | :------ | :--------------------------------------------------------------------------------------------------- | :---------------- |
+| `enable` | `bool` | `true`  | Enables or disables this autogroup definition.                                                       | `true`            |
+| `name`   | `str`  | _None_  | **Required.** The unique name for the autogroup.                                                     | `"MyFormatGroup"` |
+| `clear`  | `bool` | `true`  | Clears any existing autocommands within this group before adding new ones defined in `vim.autocmds`. | `true`            |
+
+**Example:**
+
+```nix
+{
+  vim.augroups = [
+    {
+      name = "MyCustomAuGroup";
+      clear = true; # Clear previous autocommands in this group on reload
+    }
+    {
+      name = "Formatting";
+      # clear defaults to true
+    }
+  ];
+}
+```
+
+## Autocommands (`vim.autocmds`) {#sec-vim-autocmds}
+
+Autocommands (`autocmd`) trigger actions based on events happening within Neovim
+(e.g., saving a file, entering a buffer). Each entry in the list is a submodule
+with the following options:
+
+| Option     | Type                  | Default | Description                                                                                                                                                                      | Example                                                          |
+| :--------- | :-------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
+| `enable`   | `bool`                | `true`  | Enables or disables this autocommand definition.                                                                                                                                 | `true`                                                           |
+| `event`    | `nullOr (listOf str)` | `null`  | **Required.** List of Neovim events that trigger this autocommand (e.g., `BufWritePre`, `FileType`).                                                                             | `[ "BufWritePre" ]`                                              |
+| `pattern`  | `nullOr (listOf str)` | `null`  | List of file patterns (globs) to match against (e.g., `*.py`, `*`). If `null`, matches all files for the given event.                                                            | `[ "*.lua", "*.nix" ]`                                           |
+| `callback` | `nullOr luaInline`    | `null`  | A Lua function to execute when the event triggers. Use `lib.nvim.types.luaInline` or `lib.options.literalExpression "mkLuaInline '''...'''"`. **Cannot be used with `command`.** | `lib.nvim.types.luaInline "function() print('File saved!') end"` |
+| `command`  | `nullOr str`          | `null`  | A Vimscript command to execute when the event triggers. **Cannot be used with `callback`.**                                                                                      | `"echo 'File saved!'"`                                           |
+| `group`    | `nullOr str`          | `null`  | The name of an `augroup` (defined in `vim.augroups`) to associate this autocommand with.                                                                                         | `"MyCustomAuGroup"`                                              |
+| `desc`     | `nullOr str`          | `null`  | A description for the autocommand (useful for introspection).                                                                                                                    | `"Format buffer on save"`                                        |
+| `once`     | `bool`                | `false` | If `true`, the autocommand runs only once and then automatically removes itself.                                                                                                 | `false`                                                          |
+| `nested`   | `bool`                | `false` | If `true`, allows this autocommand to trigger other autocommands.                                                                                                                | `false`                                                          |
+
+:::{.warning}
+
+You cannot define both `callback` (for Lua functions) and `command` (for
+Vimscript) for the same autocommand. Choose one.
+
+:::
+
+**Examples:**
+
+```nix
+{ lib, ... }:
+{
+  vim.augroups = [ { name = "UserSetup"; } ];
+
+  vim.autocmds = [
+    # Example 1: Using a Lua callback
+    {
+      event = [ "BufWritePost" ];
+      pattern = [ "*.lua" ];
+      group = "UserSetup";
+      desc = "Notify after saving Lua file";
+      callback = lib.nvim.types.luaInline ''
+        function()
+          vim.notify("Lua file saved!", vim.log.levels.INFO)
+        end
+      '';
+    }
+
+    # Example 2: Using a Vim command
+    {
+      event = [ "FileType" ];
+      pattern = [ "markdown" ];
+      group = "UserSetup";
+      desc = "Set spellcheck for Markdown";
+      command = "setlocal spell";
+    }
+
+    # Example 3: Autocommand without a specific group
+    {
+      event = [ "BufEnter" ];
+      pattern = [ "*.log" ];
+      desc = "Disable line numbers in log files";
+      command = "setlocal nonumber";
+      # No 'group' specified
+    }
+
+    # Example 4: Using Lua for callback
+    {
+      event = [ "BufWinEnter" ];
+      pattern = [ "*" ];
+      desc = "Simple greeting on entering a buffer window";
+      callback = lib.generators.mkLuaInline ''
+        function(args)
+          print("Entered buffer: " .. args.buf)
+        end
+      '';
+      
+      # Run only once per session trigger
+      once = true; 
+    }
+  ];
+}
+```
+
+These definitions are automatically translated into the necessary Lua code to
+configure `vim.api.nvim_create_augroup` and `vim.api.nvim_create_autocmd` when
+Neovim starts.

docs/manual/configuring/custom-package.md

@@ -1,12 +1,12 @@
 # Custom Neovim Package {#ch-custom-package}
 
 As of v0.5, you may now specify the Neovim package that will be wrapped with
-your configuration. This is done with the `vim.package` option.
+your configuration. This is done with the [](#opt-vim.package) option.
 
 ```nix
 {inputs, pkgs, ...}: {
   # using the neovim-nightly overlay
-  vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim;
+  vim.package = inputs.neovim-overlay.packages.${pkgs.stdenv.system}.neovim;
 }
 ```
 

docs/manual/configuring/custom-plugins.md

@@ -1,22 +1,33 @@
 # Custom Plugins {#ch-custom-plugins}
 
-**nvf**, by default, exposes a wide variety of plugins as module options for
+**nvf** exposes a very wide variety of plugins by default, which are consumed by
-your convenience and bundles necessary dependencies into **nvf**'s runtime. In
+module options. This is done for your convenience, and to bundle all necessary
-case a plugin is not available in **nvf**, you may consider making a pull
+dependencies into **nvf**'s runtime with full control of versioning, testing and
-request to **nvf** to include it as a module or you may add it to your
+dependencies. In the case a plugin you need is _not_ available, you may consider
-configuration locally.
+making a pull request to add the package you're looking for, or you may add it
+to your configuration locally. The below section describes how new plugins may
+be added to the user's configuration.
 
 ## Adding Plugins {#ch-adding-plugins}
 
-There are multiple ways of adding custom plugins to your **nvf** configuration.
+Per **nvf**'s design choices, there are several ways of adding custom plugins to
+your configuration as you need them. As we aim for extensive configuration, it
+is possible to add custom plugins (from nixpkgs, pinning tools, flake inputs,
+etc.) to your Neovim configuration before they are even implemented in **nvf**
+as a module.
 
-You can use custom plugins, before they are implemented in the flake. To add a
+:::{.info}
-plugin to the runtime, you need to add it to the [](#opt-vim.startPlugins) list
-in your configuration.
 
-Adding a plugin to `startPlugins` will not allow you to configure the plugin
+To add a plugin to your runtime, you will need to add it to
-that you have added, but **nvf** provides multiple ways of configuring any custom
+[](#opt-vim.startPlugins) list in your configuration. This is akin to cloning a
-plugins that you might have added to your configuration.
+plugin to `~/.config/nvim`, but they are only ever placed in the Nix store and
+never exposed to the outside world for purity and full isolation.
+
+:::
+
+As you would configure a cloned plugin, you must configure the new plugins that
+you've added to `startPlugins.` **nvf** provides multiple ways of configuring
+any custom plugins that you might have added to your configuration.
 
 ```{=include=} sections
 custom-plugins/configuring.md

docs/manual/configuring/custom-plugins/configuring.md

@@ -1,13 +1,20 @@
 # Configuring {#sec-configuring-plugins}
 
 Just making the plugin to your Neovim configuration available might not always
-be enough. In that case, you can write custom lua config using either
+be enough., for example, if the plugin requires a setup table. In that case, you
-`config.vim.lazy.plugins.*.setupOpts` `config.vim.extraPlugins.*.setup` or
+can write custom Lua configuration using one of
-`config.vim.luaConfigRC`.
 
-The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule`
+- `config.vim.lazy.plugins.*.setupOpts`
-and `setupOpt` can be used if the plugin uses a `require('module').setup(...)`
+- `config.vim.extraPlugins.*.setup`
-pattern. Otherwise, the `before` and `after` hooks should do what you need.
+- `config.vim.luaConfigRC`.
+
+## Lazy Plugins {#ch-vim-lazy-plugins}
+
+`config.vim.lazy.plugins.*.setupOpts` is useful for lazy-loading plugins, and
+uses an extended version of `lz.n's` `PluginSpec` to expose a familiar
+interface. `setupModule` and `setupOpt` can be used if the plugin uses a
+`require('module').setup(...)` pattern. Otherwise, the `before` and `after`
+hooks should do what you need.
 
 ```nix
 {
@@ -25,50 +32,61 @@ pattern. Otherwise, the `before` and `after` hooks should do what you need.
 }
 ```
 
-The second option uses an attribute set, which maps DAG section names to a
+## Standard API {#ch-vim-extra-plugins}
+
+`vim.extraPlugins` uses an attribute set, which maps DAG section names to a
 custom type, which has the fields `package`, `after`, `setup`. They allow you to
 set the package of the plugin, the sections its setup code should be after (note
 that the `extraPlugins` option has its own DAG scope), and the its setup code
 respectively. For example:
 
 ```nix
-config.vim.extraPlugins = with pkgs.vimPlugins; {
+{pkgs, ...}: {
-  aerial = {
+  config.vim.extraPlugins = {
-    package = aerial-nvim;
+    aerial = {
-    setup = "require('aerial').setup {}";
+      package = pkgs.vimPlugins.aerial-nvim;
-  };
+      setup = "require('aerial').setup {}";
+    };
 
-  harpoon = {
+    harpoon = {
-    package = harpoon;
+      package = pkgs.vimPlugins.harpoon;
-    setup = "require('harpoon').setup {}";
+      setup = "require('harpoon').setup {}";
-    after = ["aerial"]; # place harpoon configuration after aerial
+      after = ["aerial"]; # place harpoon configuration after aerial
+    };
   };
 }
 ```
 
-The third option also uses an attribute set, but this one is resolved as a DAG
+### Setup using luaConfigRC {#setup-using-luaconfigrc}
+
+`vim.luaConfigRC` also uses an attribute set, but this one is resolved as a DAG
 directly. The attribute names denote the section names, and the values lua code.
 For example:
 
 ```nix
 {
-  # this will create an "aquarium" section in your init.lua with the contents of your custom config
+  # This will create a section called "aquarium" in the 'init.lua' with the
-  # which will be *appended* to the rest of your configuration, inside your init.vim
+  # contents of your custom configuration. By default 'entryAnywhere' is implied
+  # in DAGs, so this will be inserted to an arbitrary position. In the case you 
+  # wish to control the position of this section with more precision, please
+  # look into the DAGs section of the manual.
   config.vim.luaConfigRC.aquarium = "vim.cmd('colorscheme aquiarum')";
 }
 ```
 
 <!-- deno-fmt-ignore-start -->
+[DAG system]: #ch-using-dags
+[DAG section]: #ch-dag-entries
 
 ::: {.note}
-One of the greatest strengths of nvf is the ability to order
+One of the **greatest strengths** of **nvf** is the ability to order
-snippets of configuration via the DAG system. It will allow specifying positions
+configuration snippets precisely using the [DAG system]. DAGs
-of individual sections of configuration as needed. nvf provides helper functions
+are a very powerful mechanism that allows specifying positions
+of individual sections of configuration as needed. We provide helper functions
 in the extended library, usually under `inputs.nvf.lib.nvim.dag` that you may
 use.
 
-Please refer to the [DAG section](#ch-dag-entries) in the nvf manual
+Please refer to the [DAG section] in the nvf manual
 to find out more about the DAG system.
 :::
-
 <!-- deno-fmt-ignore-end -->

docs/manual/configuring/custom-plugins/lazy-method.md

@@ -1,7 +1,8 @@
 # Lazy Method {#sec-lazy-method}
 
-As of version **0.7**, we exposed an API for configuring lazy-loaded plugins via
+As of version **0.7**, an API is exposed to allow configuring lazy-loaded
-`lz.n` and `lzn-auto-require`.
+plugins via `lz.n` and `lzn-auto-require`. Below is a comprehensive example of
+how it may be loaded to lazy-load an arbitrary plugin.
 
 ```nix
 {
@@ -41,7 +42,8 @@ As of version **0.7**, we exposed an API for configuring lazy-loaded plugins via
 
 ## LazyFile event {#sec-lazyfile-event}
 
-You can use the `LazyFile` user event to load a plugin when a file is opened:
+**nvf** re-implements `LazyFile` as a familiar user event to load a plugin when
+a file is opened:
 
 ```nix
 {
@@ -55,5 +57,6 @@ You can use the `LazyFile` user event to load a plugin when a file is opened:
 }
 ```
 
-You can consider `LazyFile` as an alias to
+You can consider the `LazyFile` event as an alias to the combination of
-`["BufReadPost" "BufNewFile" "BufWritePre"]`
+`"BufReadPost"`, `"BufNewFile"` and `"BufWritePre"`, i.e., a list containing all
+three of those events: `["BufReadPost" "BufNewFile" "BufWritePre"]`

docs/manual/configuring/custom-plugins/legacy-method.md

@@ -1,26 +1,31 @@
 # Legacy Method {#sec-legacy-method}
 
-Prior to version v0.5, the method of adding new plugins was adding the plugin
+Prior to version **0.5**, the method of adding new plugins was adding the plugin
-package to `vim.startPlugins` and add its configuration as a DAG under one of
+package to [](#opt-vim.startPlugins) and adding its configuration as a DAG under
-`vim.configRC` or `vim.luaConfigRC`. Users who have not yet updated to 0.5, or
+one of `vim.configRC` or [](#opt-vim.luaConfigRC). While `configRC` has been
-prefer a more hands-on approach may use the old method where the load order of
+deprecated, users who have not yet updated to 0.5 or those who prefer a more
-the plugins is determined by DAGs.
+hands-on approach may choose to use the old method where the load order of the
+plugins is explicitly determined by DAGs without internal abstractions.
 
-## Adding plugins {#sec-adding-plugins}
+## Adding New Plugins {#sec-adding-new-plugins}
 
-To add a plugin not available in nvf as a module to your configuration, you may
+To add a plugin not available in **nvf** as a module to your configuration using
-add it to [](#opt-vim.startPlugins) in order to make it available to Neovim at
+the legacy method, you must add it to [](#opt-vim.startPlugins) in order to make
-runtime.
+it available to Neovim at runtime.
 
 ```nix
 {pkgs, ...}: {
   # Add a Neovim plugin from Nixpkgs to the runtime.
+  # This does not need to come explicitly from packages. 'vim.startPlugins'
+  # takes a list of *string* (to load internal plugins) or *package* to load
+  # a Neovim package from any source.
   vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
 }
 ```
 
-And to configure the added plugin, you can use the `luaConfigRC` option to
+Once the package is available in Neovim's runtime, you may use the `luaConfigRC`
-provide configuration as a DAG using the **nvf** extended library.
+option to provide configuration as a DAG using the **nvf** extended library in
+order to configure the added plugin,
 
 ```nix
 {inputs, ...}: let
@@ -29,6 +34,8 @@ provide configuration as a DAG using the **nvf** extended library.
   # to specialArgs, the 'inputs' prefix may be omitted.
   inherit (inputs.nvf.lib.nvim.dag) entryAnywhere;
 in {
+  # luaConfigRC takes Lua configuration verbatim and inserts it at an arbitrary
+  # position by default or if 'entryAnywhere' is used.
   vim.luaConfigRC.aerial-nvim= entryAnywhere ''
     require('aerial').setup {
       -- your configuration here

docs/manual/configuring/custom-plugins/non-lazy-method.md

@@ -1,14 +1,15 @@
 # Non-lazy Method {#sec-non-lazy-method}
 
-As of version **0.5**, we have a more extensive API for configuring plugins,
+As of version **0.5**, we have a more extensive API for configuring plugins that
-under `vim.extraPlugins`. Instead of using DAGs exposed by the library, you may
+should be preferred over the legacy method. This API is available as
-use the extra plugin module as follows:
+[](#opt-vim.extraPlugins). Instead of using DAGs exposed by the library
+_directly_, you may use the extra plugin module as follows:
 
 ```nix
-{
+{pkgs, ...}: {
-  config.vim.extraPlugins = with pkgs.vimPlugins; {
+  config.vim.extraPlugins = {
     aerial = {
-      package = aerial-nvim;
+      package = pkgs.vimPlugins.aerial-nvim;
       setup = ''
         require('aerial').setup {
           -- some lua configuration here
@@ -17,10 +18,12 @@ use the extra plugin module as follows:
     };
 
     harpoon = {
-      package = harpoon;
+      package = pkgs.vimPlugins.harpoon;
       setup = "require('harpoon').setup {}";
       after = ["aerial"];
     };
   };
 }
 ```
+
+This provides a level of abstraction over the DAG system for faster iteration.

docs/manual/configuring/languages/lsp.md

@@ -1,17 +1,22 @@
 # LSP Custom Packages/Command {#sec-languages-custom-lsp-packages}
 
-In any of the `opt.languages.<language>.lsp.package` options you can provide
+One of the strengths of **nvf** is convenient aliases to quickly configure LSP
-your own LSP package, or provide the command to launch the language server, as a
+servers through the Nix module system. By default the LSP packages for relevant
-list of strings. You can use this to skip automatic installation of a language
+language modules will be pulled into the closure. If this is not desirable, you
-server, and instead use the one found in your `$PATH` during runtime, for
+may provide **a custom LSP package** (e.g., a Bash script that calls a command)
-example:
+or **a list of strings** to be interpreted as the command to launch the language
+server. By using a list of strings, you can use this to skip automatic
+installation of a language server, and instead use the one found in your `$PATH`
+during runtime, for example:
 
 ```nix
 vim.languages.java = {
   lsp = {
     enable = true;
-    # this expects jdt-language-server to be in your PATH
+
-    # or in `vim.extraPackages`
+    # This expects 'jdt-language-server' to be in your PATH or in
+    # 'vim.extraPackages.' There are no additional checks performed to see
+    # if the command provided is valid.
     package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
   };
 }

docs/manual/default-configs.md

@@ -1,10 +0,0 @@
-# Default Configs {#ch-default-configs}
-
-While you can configure **nvf** yourself using the builder, you can also use the
-pre-built configs that are available. Here are a few default configurations you
-can use.
-
-```{=include=} chapters
-default-configs/maximal.md
-default-configs/nix.md
-```

docs/manual/default-configs/maximal.md

@@ -1,11 +0,0 @@
-# Maximal {#sec-default-maximal}
-
-```bash
-$ nix run github:notashelf/nvf#maximal -- test.nix
-```
-
-It is the same fully configured Neovim as with the [Nix](#sec-default-nix)
-configuration, but with every supported language enabled.
-
-::: {.note} Running the maximal config will download _a lot_ of packages as it
-is downloading language servers, formatters, and more. :::

docs/manual/default-configs/nix.md

@@ -1,9 +0,0 @@
-# Nix {#sec-default-nix}
-
-```bash
-$ nix run github:notashelf/nvf#nix test.nix
-```
-
-Enables all the of Neovim plugins, with language support for specifically Nix.
-This lets you see what a fully configured neovim setup looks like without
-downloading a whole bunch of language servers and associated tools.

docs/manual/manual.md

@@ -8,7 +8,6 @@ try-it-out.md
 ```
 
 ```{=include=} parts
-default-configs.md
 installation.md
 configuring.md
 tips.md

docs/manual/tips.md

@@ -1,7 +1,14 @@
 # Helpful Tips {#ch-helpful-tips}
 
+This section provides helpful tips that may be considered "unorthodox" or "too
+advanced" for some users. We will cover basic debugging steps, offline
+documentation, configuring **nvf** with pure Lua and using custom plugin sources
+in **nvf** in this section. For general configuration tips, please see previous
+chapters.
+
 ```{=include=} chapters
-tips/pure-lua-config.md
 tips/debugging-nvf.md
 tips/offline-docs.md
+tips/pure-lua-config.md
+tips/plugin-sources.md
 ```

docs/manual/tips/plugin-sources.md

@@ -0,0 +1,131 @@
+# Adding Plugins From Different Sources {#sec-plugin-sources}
+
+**nvf** attempts to avoid depending on Nixpkgs for Neovim plugins. For the most
+part, this is accomplished by defining each plugin's source and building them
+from source.
+
+[npins]: https://github.com/andir/npins
+
+To define plugin sources, we use [npins] and pin each plugin source using
+builtin fetchers. You are not bound by this restriction. In your own
+configuration, any kind of fetcher or plugin source is fine.
+
+## Nixpkgs & Friends {#ch-plugins-from-nixpkgs}
+
+`vim.startPlugins` and `vim.optPlugins` options take either a **string**, in
+which case a plugin from nvf's internal plugins registry will be used, or a
+**package**. If your plugin does not require any setup, or ordering for it s
+configuration, then it is possible to add it to `vim.startPlugins` to load it on
+startup.
+
+```nix
+{pkgs, ...}: {
+  # Aerial does require some setup. In the case you pass a plugin that *does*
+  # require manual setup, then you must also call the setup function.
+  vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
+}
+```
+
+[`vim.extraPlugins`]: https://notashelf.github.io/nvf/options.html#opt-vim.extraPlugins
+
+This will fetch aerial.nvim from nixpkgs, and add it to Neovim's runtime path to
+be loaded manually. Although for plugins that require manual setup, you are
+encouraged to use [`vim.extraPlugins`].
+
+```nix
+{
+  vim.extraPlugins = {
+    aerial = {
+      package = pkgs.vimPlugins.aerial-nvim;
+      setup = "require('aerial').setup {}";
+    };
+  };
+}
+```
+
+[custom plugins section]: https://notashelf.github.io/nvf/index.xhtml#ch-custom-plugins
+
+More details on the extraPlugins API is documented in the
+[custom plugins section].
+
+## Building Your Own Plugins {#ch-plugins-from-source}
+
+In the case a plugin is not available in Nixpkgs, or the Nixpkgs package is
+outdated (or, more likely, broken) it is possible to build the plugins from
+source using a tool, such as [npins]. You may also use your _flake inputs_ as
+sources.
+
+Example using plugin inputs:
+
+```nix
+{
+  # In your flake.nix
+  inputs = {
+    aerial-nvim = {
+      url = "github:stevearc/aerial.nvim"
+      flake = false;
+    };
+  };
+
+  # Make sure that 'inputs' is properly propagated into Nvf, for example, through
+  # specialArgs.
+  outputs = { ... };
+}
+```
+
+In the case, you may use the input directly for the plugin's source attribute in
+`buildVimPlugin`.
+
+```nix
+# Make sure that 'inputs' is properly propagated! It will be missing otherwise
+# and the resulting errors might be too obscure.
+{inputs, ...}: let
+  aerial-from-source = pkgs.vimUtils.buildVimPlugin {
+      name = "aerial-nvim";
+      src = inputs.aerial-nvim;
+    };
+in {
+  vim.extraPlugins = {
+    aerial = {
+      package = aerial-from-source;
+      setup = "require('aerial').setup {}";
+    };
+  };
+}
+```
+
+Alternatively, if you do not want to keep track of the source using flake inputs
+or npins, you may call `fetchFromGitHub` (or other fetchers) directly. An
+example would look like this.
+
+```nix
+regexplainer = buildVimPlugin {
+  name = "nvim-regexplainer";
+  src = fetchFromGitHub {
+    owner = "bennypowers";
+    repo = "nvim-regexplainer";
+    rev = "4250c8f3c1307876384e70eeedde5149249e154f";
+    hash = "sha256-15DLbKtOgUPq4DcF71jFYu31faDn52k3P1x47GL3+b0=";
+  };
+
+  # The 'buildVimPlugin' imposes some "require checks" on all plugins build from
+  # source. Failing tests, if they are not relevant, can be disabled using the
+  # 'nvimSkipModule' argument to the 'buildVimPlugin' function.
+  nvimSkipModule = [
+    "regexplainer"
+    "regexplainer.buffers.init"
+    "regexplainer.buffers.popup"
+    "regexplainer.buffers.register"
+    "regexplainer.buffers.shared"
+    "regexplainer.buffers.split"
+    "regexplainer.component.descriptions"
+    "regexplainer.component.init"
+    "regexplainer.renderers.narrative.init"
+    "regexplainer.renderers.narrative.narrative"
+    "regexplainer.renderers.init"
+    "regexplainer.utils.defer"
+    "regexplainer.utils.init"
+    "regexplainer.utils.treesitter"
+  ];
+}
+```

docs/manual/try-it-out.md

@@ -26,7 +26,12 @@ $ nix run github:notashelf/nvf#nix
 $ nix run github:notashelf/nvf#maximal
 ```
 
-### Available Configs {#sec-available-configs}
+### Available Configurations {#sec-available-configs}
+
+:::{.info}
+
+The below configurations are provided for demonstration purposes, and are
+**not** designed to be installed as is. You may
 
 #### Nix {#sec-configs-nix}
 
@@ -34,15 +39,32 @@ $ nix run github:notashelf/nvf#maximal
 a set of visual and functional plugins. By running `nix run .#`, which is the
 default package, you will build Neovim with this config.
 
+```bash
+$ nix run github:notashelf/nvf#nix test.nix
+```
+
+This command will start Neovim with some opinionated plugin configurations, and
+is designed specifically for Nix. the `nix` configuration lets you see how a
+fully configured Neovim setup _might_ look like without downloading too many
+packages or shell utilities.
+
 #### Maximal {#sec-configs-maximal}
 
 `Maximal` is the ultimate configuration that will enable support for more
 commonly used language as well as additional complementary plugins. Keep in
 mind, however, that this will pull a lot of dependencies.
 
-::: {.tip}
+```bash
+$ nix run github:notashelf/nvf#maximal -- test.nix
+```
 
-You are _strongly_ recommended to use the binary cache if you would like to try
+It uses the same configuration template with the [Nix](#sec-configs-nix)
-the Maximal configuration.
+configuration, but supports many more languages, and enables more utility,
+companion or fun plugins.
+
+::: {.warning}
+
+Running the maximal config will download _a lot_ of packages as it is
+downloading language servers, formatters, and more.
 
 :::