Merge 2853877219 into f5c91f6a66

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
+<!-- markdownlint-enable MD051 -->
-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
+nvf allows for _very_ extensive configuration for your Neovim setups through a
-module options provided by nvf, please visit the [appendix](/nvf/options.html)
+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 -->

docs/manual/hacking/additional-plugins.md

@@ -165,15 +165,33 @@ own fields!
 
 ## Details of toLuaObject {#sec-details-of-toluaobject}
 
-As you've seen above, `toLuaObject` is used to convert our nix attrSet
+As you've seen above, `toLuaObject` is used to convert our `cfg.setupOpts`, a
-`cfg.setupOpts`, into a lua table. Here are some rules of the conversion:
+Nix attribute set, into Lua tables across the codebase. Here are some rules of
+the conversion:
 
-1. Nix `null` converts to lua `nil`
+1. Nix `null` converts to Lua `nil`
-2. Number and strings convert to their lua counterparts
+   - `foo = null;` -> `foo = nil`
+2. Number and strings convert to their Lua counterparts
 3. Nix attribute sets (`{}`) and lists (`[]`) convert into Lua dictionaries and
    tables respectively. Here is an example of Nix -> Lua conversion.
    - `{foo = "bar"}` -> `{["foo"] = "bar"}`
    - `["foo" "bar"]` -> `{"foo", "bar"}`
+   - You may also write **mixed tables** using `toLuaObject`, using a special
+     syntax to describe a key's position in the table. Let's say you want to get
+     something like `{"foo", bar = "baz"}` expressed in Lua using Nix. The
+     appropriate Nix syntax to express mixed tables is as follows:
+
+     ```nix
+     # Notice the position indicator, "@1"
+     { "@1" = "foo"; bar = "baz"; };
+     ```
+
+     This will result in a mixed Lua table that is as follows:
+
+     ```lua
+     {"foo", bar = "baz"}
+     ```
+
 4. You can write raw Lua code using `lib.generators.mkLuaInline`. This function
    is part of nixpkgs, and is accessible without relying on **nvf**'s extended
    library.