From f1d72cf0764db282a937d756b9a027978ae96e8f Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 5 May 2025 14:57:32 +0300 Subject: [PATCH] docs: clarify wording; add examples and remove redundancies --- docs/manual/configuring.md | 11 ++ docs/manual/configuring/autocmds.md | 119 ++++++++++++++++++ docs/manual/configuring/custom-package.md | 4 +- docs/manual/configuring/custom-plugins.md | 35 ++++-- .../configuring/custom-plugins/configuring.md | 46 ++++--- .../configuring/custom-plugins/lazy-method.md | 13 +- .../custom-plugins/legacy-method.md | 29 +++-- .../custom-plugins/non-lazy-method.md | 9 +- docs/manual/configuring/languages/lsp.md | 19 +-- docs/manual/default-configs.md | 10 -- docs/manual/default-configs/maximal.md | 11 -- docs/manual/default-configs/nix.md | 9 -- docs/manual/manual.md | 1 - docs/manual/tips.md | 6 + docs/manual/try-it-out.md | 30 ++++- 15 files changed, 262 insertions(+), 90 deletions(-) create mode 100644 docs/manual/configuring/autocmds.md delete mode 100644 docs/manual/default-configs.md delete mode 100644 docs/manual/default-configs/maximal.md delete mode 100644 docs/manual/default-configs/nix.md diff --git a/docs/manual/configuring.md b/docs/manual/configuring.md index f891c7a6..28c7e66a 100644 --- a/docs/manual/configuring.md +++ b/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 ``` diff --git a/docs/manual/configuring/autocmds.md b/docs/manual/configuring/autocmds.md new file mode 100644 index 00000000..be10e726 --- /dev/null +++ b/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. diff --git a/docs/manual/configuring/custom-package.md b/docs/manual/configuring/custom-package.md index 51d996b6..3e9e324a 100644 --- a/docs/manual/configuring/custom-package.md +++ b/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; } ``` diff --git a/docs/manual/configuring/custom-plugins.md b/docs/manual/configuring/custom-plugins.md index c621e03c..bf986a0f 100644 --- a/docs/manual/configuring/custom-plugins.md +++ b/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 -your convenience and bundles necessary dependencies into **nvf**'s runtime. In -case a plugin is not available in **nvf**, you may consider making a pull -request to **nvf** to include it as a module or you may add it to your -configuration locally. +**nvf** exposes a very wide variety of plugins by default, which are consumed by +module options. This is done for your convenience, and to bundle all necessary +dependencies into **nvf**'s runtime with full control of versioning, testing and +dependencies. In the case a plugin you need is _not_ available, you may consider +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 -plugin to the runtime, you need to add it to the [](#opt-vim.startPlugins) list -in your configuration. +:::{.info} -Adding a plugin to `startPlugins` will not allow you to configure the plugin -that you have added, but **nvf** provides multiple ways of configuring any custom -plugins that you might have added to your configuration. +To add a plugin to your runtime, you will need to add it to +[](#opt-vim.startPlugins) list in your configuration. This is akin to cloning a +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 diff --git a/docs/manual/configuring/custom-plugins/configuring.md b/docs/manual/configuring/custom-plugins/configuring.md index 42af11be..a4b3ce19 100644 --- a/docs/manual/configuring/custom-plugins/configuring.md +++ b/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 -`config.vim.lazy.plugins.*.setupOpts` `config.vim.extraPlugins.*.setup` or -`config.vim.luaConfigRC`. +be enough., for example, if the plugin requires a setup table. In that case, you +can write custom Lua configuration using one of -The first option uses an extended version of `lz.n`'s PluginSpec. `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. +- `config.vim.lazy.plugins.*.setupOpts` +- `config.vim.extraPlugins.*.setup` +- `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,7 +32,9 @@ 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 @@ -48,29 +57,36 @@ respectively. For example: } ``` -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 - # which will be *appended* to the rest of your configuration, inside your init.vim + # This will create a section called "aquarium" in the 'init.lua' with the + # 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')"; } ``` +[DAG system]: #ch-using-dags +[DAG section]: #ch-dag-entries ::: {.note} -One of the greatest strengths of nvf is the ability to order -snippets of configuration via the DAG system. It will allow specifying positions -of individual sections of configuration as needed. nvf provides helper functions +One of the **greatest strengths** of **nvf** is the ability to order +configuration snippets precisely using the [DAG system]. DAGs +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. ::: - diff --git a/docs/manual/configuring/custom-plugins/lazy-method.md b/docs/manual/configuring/custom-plugins/lazy-method.md index ae766535..c16966b8 100644 --- a/docs/manual/configuring/custom-plugins/lazy-method.md +++ b/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 -`lz.n` and `lzn-auto-require`. +As of version **0.7**, an API is exposed to allow configuring lazy-loaded +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 -`["BufReadPost" "BufNewFile" "BufWritePre"]` +You can consider the `LazyFile` event as an alias to the combination of +`"BufReadPost"`, `"BufNewFile"` and `"BufWritePre"`, i.e., a list containing all +three of those events: `["BufReadPost" "BufNewFile" "BufWritePre"]` diff --git a/docs/manual/configuring/custom-plugins/legacy-method.md b/docs/manual/configuring/custom-plugins/legacy-method.md index b2bddf43..6c399aaf 100644 --- a/docs/manual/configuring/custom-plugins/legacy-method.md +++ b/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 -package to `vim.startPlugins` and add its configuration as a DAG under one of -`vim.configRC` or `vim.luaConfigRC`. Users who have not yet updated to 0.5, or -prefer a more hands-on approach may use the old method where the load order of -the plugins is determined by DAGs. +Prior to version **0.5**, the method of adding new plugins was adding the plugin +package to [](#opt-vim.startPlugins) and adding its configuration as a DAG under +one of `vim.configRC` or [](#opt-vim.luaConfigRC). While `configRC` has been +deprecated, users who have not yet updated to 0.5 or those who prefer a more +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 -add it to [](#opt-vim.startPlugins) in order to make it available to Neovim at -runtime. +To add a plugin not available in **nvf** as a module to your configuration using +the legacy method, you must add it to [](#opt-vim.startPlugins) in order to make +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 -provide configuration as a DAG using the **nvf** extended library. +Once the package is available in Neovim's runtime, you may use the `luaConfigRC` +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 diff --git a/docs/manual/configuring/custom-plugins/non-lazy-method.md b/docs/manual/configuring/custom-plugins/non-lazy-method.md index d8477283..24ef7688 100644 --- a/docs/manual/configuring/custom-plugins/non-lazy-method.md +++ b/docs/manual/configuring/custom-plugins/non-lazy-method.md @@ -1,8 +1,9 @@ # Non-lazy Method {#sec-non-lazy-method} -As of version **0.5**, we have a more extensive API for configuring plugins, -under `vim.extraPlugins`. Instead of using DAGs exposed by the library, you may -use the extra plugin module as follows: +As of version **0.5**, we have a more extensive API for configuring plugins that +should be preferred over the legacy method. This API is available as +[](#opt-vim.extraPlugins). Instead of using DAGs exposed by the library +_directly_, you may use the extra plugin module as follows: ```nix {pkgs, ...}: { @@ -24,3 +25,5 @@ use the extra plugin module as follows: }; } ``` + +This provides a level of abstraction over the DAG system for faster iteration. diff --git a/docs/manual/configuring/languages/lsp.md b/docs/manual/configuring/languages/lsp.md index 6d6ed5bc..2ddc08b5 100644 --- a/docs/manual/configuring/languages/lsp.md +++ b/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..lsp.package` options you can provide -your own LSP package, or provide the command to launch the language server, as 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: +One of the strengths of **nvf** is convenient aliases to quickly configure LSP +servers through the Nix module system. By default the LSP packages for relevant +language modules will be pulled into the closure. If this is not desirable, you +may provide **a custom LSP package** (e.g., a Bash script that calls a command) +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"]; }; } diff --git a/docs/manual/default-configs.md b/docs/manual/default-configs.md deleted file mode 100644 index 96ffa81a..00000000 --- a/docs/manual/default-configs.md +++ /dev/null @@ -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 -``` diff --git a/docs/manual/default-configs/maximal.md b/docs/manual/default-configs/maximal.md deleted file mode 100644 index e1f5273e..00000000 --- a/docs/manual/default-configs/maximal.md +++ /dev/null @@ -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. ::: diff --git a/docs/manual/default-configs/nix.md b/docs/manual/default-configs/nix.md deleted file mode 100644 index 5210ef39..00000000 --- a/docs/manual/default-configs/nix.md +++ /dev/null @@ -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. diff --git a/docs/manual/manual.md b/docs/manual/manual.md index fd225766..18932896 100644 --- a/docs/manual/manual.md +++ b/docs/manual/manual.md @@ -8,7 +8,6 @@ try-it-out.md ``` ```{=include=} parts -default-configs.md installation.md configuring.md tips.md diff --git a/docs/manual/tips.md b/docs/manual/tips.md index f52cbca2..01bddc40 100644 --- a/docs/manual/tips.md +++ b/docs/manual/tips.md @@ -1,5 +1,11 @@ # 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/debugging-nvf.md tips/offline-docs.md diff --git a/docs/manual/try-it-out.md b/docs/manual/try-it-out.md index 8244c2b7..8714be80 100644 --- a/docs/manual/try-it-out.md +++ b/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 -the Maximal configuration. +It uses the same configuration template with the [Nix](#sec-configs-nix) +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. :::