diff --git a/docs/manual/configuring.md b/docs/manual/configuring.md index 95195f78..8293806f 100644 --- a/docs/manual/configuring.md +++ b/docs/manual/configuring.md @@ -1,21 +1,34 @@ # 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](/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 ``` diff --git a/docs/manual/configuring/modules.md b/docs/manual/configuring/modules.md new file mode 100644 index 00000000..5a75ee92 --- /dev/null +++ b/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...enable` and `vim...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 + }; +} +``` + + + +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. + +