docs/configuring: add modules section

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I6a6a6964f2e65a11acab2a2f7413a5f94bff3815

docs/manual/configuring.md

@@ -1,21 +1,34 @@
 # Configuring nvf {#ch-configuring}
 
+<!-- markdownlint-disable MD051 -->
+
 [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.
+<!-- markdownlint-enable MD051 -->
 
-Note that this section does not cover module _options_. For an overview of all
-module options provided by nvf, please visit the [appendix](/nvf/options.html)
+nvf allows for _very_ extensive configuration for your Neovim setups through a
+Nix module interface. This interface allows you to express almost everything
+using a single DSL, Nix. 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 such as Nix/Lua hybrid setups.
+
+::: {.note}
+
+This section does not cover module _options_. For an overview of all module
+options provided by nvf, please visit the [appendix](/nvf/options.html)
+
+:::
 
 ```{=include=} chapters
 configuring/custom-package.md
 configuring/custom-plugins.md
 configuring/overriding-plugins.md
+
+configuring/modules.md
 configuring/languages.md
+configuring/autocmds.md
+
 configuring/dags.md
 configuring/dag-entries.md
-configuring/autocmds.md
 ```

docs/manual/configuring/modules.md

@@ -0,0 +1,58 @@
+## Using the Module Interface {#ch-module-interface}
+
+Before describing the module interface, it is worth nothing that NVF is a hybrid
+wrapper. It does not lock you into one of Lua or Nix, and both languages are
+considered first-class citizens for configuring your editor. However, Nix is the
+primarily supported language for NVF. While [DAGs](#ch-using-dags) allow for the
+surgical insertion of Lua code into your configuration, in most cases you will
+be more interested in using or extending the Nix-based module system.
+
+### {#ch-using-modules}
+
+Up until v0.6, most modules exposed all supported plugin options as individual
+module options. With the release of v0.6, almost every module has been converted
+to a new `setupOpts` format that provides complete user freedom over a plugin's
+`setup({})` function.
+
+The anatomy of a typical **plugin** module consists of two primary options:
+
+`vim.<category>.<plugin>.enable` and `vim.<category>.<plugin>.setupOpts`. The
+first option is disabled by default, and dictates whether the plugin is enabled.
+If set to `true`, the plugin will be enabled and added to your Neovim's runtime
+path. The second is an attribute set (`{}`) that will be converted to the
+plugin's setup table. From Lua-based setups you may be used to something like
+this:
+
+```lua
+require("nvim-autopairs").setup({
+  check_ts = true,
+  disable_filetype = { "TelescopePrompt", "vim" }
+})
+```
+
+This is the typical setup table. It is sometimes expressed slightly differently
+(e.g., the table might be stored as a variable) but the gist is that you pass a
+table to the `setup()` function. The principle of `setupOpts` is the same. It
+converts a Nix attribute set to a Lua table using the `toLuaObject` function
+located in nvf's extended library. The same configuration would be expressed in
+Nix as follows:
+
+```nix
+{
+  setupOpts = {
+    check_ts = true; # boolean
+    disable_filetype = ["TelescopePrompt" "vim"]; # Lua table
+  };
+}
+```
+
+<!-- markdownlint-disable MD051 MD059 -->
+
+The `setupOpts` option is freeform, so anything you put in it will be converted
+to its Lua equivalent and will appear in your built `init.lua`. You can find
+details about `toLuaObject` [here](#sec-details-of-toluaobject). The top-level
+DAG entries in **nvf** are documented in the [DAG entries](#ch-dag-entries)
+section. You can read more about DAGs in the [using DAGs](#ch-using-dags)
+section.
+
+<!-- markdownlint-enable MD051 MD059 -->