diff --git a/docs/manual/configuring.md b/docs/manual/configuring.md index 28c7e66a..f891c7a6 100644 --- a/docs/manual/configuring.md +++ b/docs/manual/configuring.md @@ -1,15 +1,5 @@ # 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 @@ -17,5 +7,4 @@ 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 deleted file mode 100644 index be10e726..00000000 --- a/docs/manual/configuring/autocmds.md +++ /dev/null @@ -1,119 +0,0 @@ -# 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 3e9e324a..51d996b6 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 [](#opt-vim.package) option. +your configuration. This is done with the `vim.package` option. ```nix {inputs, pkgs, ...}: { # using the neovim-nightly overlay - vim.package = inputs.neovim-overlay.packages.${pkgs.stdenv.system}.neovim; + vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim; } ``` diff --git a/docs/manual/configuring/custom-plugins.md b/docs/manual/configuring/custom-plugins.md index bf986a0f..c621e03c 100644 --- a/docs/manual/configuring/custom-plugins.md +++ b/docs/manual/configuring/custom-plugins.md @@ -1,33 +1,22 @@ # Custom Plugins {#ch-custom-plugins} -**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. +**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. ## Adding Plugins {#ch-adding-plugins} -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. +There are multiple ways of adding custom plugins to your **nvf** configuration. -:::{.info} +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. -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. +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. ```{=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 a4b3ce19..42af11be 100644 --- a/docs/manual/configuring/custom-plugins/configuring.md +++ b/docs/manual/configuring/custom-plugins/configuring.md @@ -1,20 +1,13 @@ # Configuring {#sec-configuring-plugins} Just making the plugin to your Neovim configuration available might not always -be enough., for example, if the plugin requires a setup table. In that case, you -can write custom Lua configuration using one of +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`. -- `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. +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. ```nix { @@ -32,9 +25,7 @@ hooks should do what you need. } ``` -## Standard API {#ch-vim-extra-plugins} - -`vim.extraPlugins` uses an attribute set, which maps DAG section names to a +The second option 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 @@ -57,36 +48,29 @@ respectively. For example: } ``` -### Setup using luaConfigRC {#setup-using-luaconfigrc} - -`vim.luaConfigRC` also uses an attribute set, but this one is resolved as a DAG +The third option 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 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. + # 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 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 -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 +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 in the extended library, usually under `inputs.nvf.lib.nvim.dag` that you may use. -Please refer to the [DAG section] in the nvf manual +Please refer to the [DAG section](#ch-dag-entries) 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 c16966b8..ae766535 100644 --- a/docs/manual/configuring/custom-plugins/lazy-method.md +++ b/docs/manual/configuring/custom-plugins/lazy-method.md @@ -1,8 +1,7 @@ # Lazy Method {#sec-lazy-method} -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. +As of version **0.7**, we exposed an API for configuring lazy-loaded plugins via +`lz.n` and `lzn-auto-require`. ```nix { @@ -42,8 +41,7 @@ how it may be loaded to lazy-load an arbitrary plugin. ## LazyFile event {#sec-lazyfile-event} -**nvf** re-implements `LazyFile` as a familiar user event to load a plugin when -a file is opened: +You can use the `LazyFile` user event to load a plugin when a file is opened: ```nix { @@ -57,6 +55,5 @@ a file is opened: } ``` -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"]` +You can consider `LazyFile` as an alias to +`["BufReadPost" "BufNewFile" "BufWritePre"]` diff --git a/docs/manual/configuring/custom-plugins/legacy-method.md b/docs/manual/configuring/custom-plugins/legacy-method.md index 6c399aaf..b2bddf43 100644 --- a/docs/manual/configuring/custom-plugins/legacy-method.md +++ b/docs/manual/configuring/custom-plugins/legacy-method.md @@ -1,31 +1,26 @@ # Legacy Method {#sec-legacy-method} -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. +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. -## Adding New Plugins {#sec-adding-new-plugins} +## Adding plugins {#sec-adding-plugins} -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. +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. ```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]; } ``` -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, +And to configure the added plugin, you can use the `luaConfigRC` option to +provide configuration as a DAG using the **nvf** extended library. ```nix {inputs, ...}: let @@ -34,8 +29,6 @@ order to configure the added plugin, # 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 24ef7688..d8477283 100644 --- a/docs/manual/configuring/custom-plugins/non-lazy-method.md +++ b/docs/manual/configuring/custom-plugins/non-lazy-method.md @@ -1,9 +1,8 @@ # Non-lazy Method {#sec-non-lazy-method} -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: +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: ```nix {pkgs, ...}: { @@ -25,5 +24,3 @@ _directly_, you may 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 2ddc08b5..6d6ed5bc 100644 --- a/docs/manual/configuring/languages/lsp.md +++ b/docs/manual/configuring/languages/lsp.md @@ -1,22 +1,17 @@ # LSP Custom Packages/Command {#sec-languages-custom-lsp-packages} -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: +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: ```nix vim.languages.java = { lsp = { enable = true; - - # 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. + # this expects jdt-language-server to be in your PATH + # or in `vim.extraPackages` package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"]; }; } diff --git a/docs/manual/default-configs.md b/docs/manual/default-configs.md new file mode 100644 index 00000000..96ffa81a --- /dev/null +++ b/docs/manual/default-configs.md @@ -0,0 +1,10 @@ +# 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 new file mode 100644 index 00000000..e1f5273e --- /dev/null +++ b/docs/manual/default-configs/maximal.md @@ -0,0 +1,11 @@ +# 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 new file mode 100644 index 00000000..5210ef39 --- /dev/null +++ b/docs/manual/default-configs/nix.md @@ -0,0 +1,9 @@ +# 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 18932896..fd225766 100644 --- a/docs/manual/manual.md +++ b/docs/manual/manual.md @@ -8,6 +8,7 @@ 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 01bddc40..f52cbca2 100644 --- a/docs/manual/tips.md +++ b/docs/manual/tips.md @@ -1,11 +1,5 @@ # 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 8714be80..8244c2b7 100644 --- a/docs/manual/try-it-out.md +++ b/docs/manual/try-it-out.md @@ -26,12 +26,7 @@ $ nix run github:notashelf/nvf#nix $ nix run github:notashelf/nvf#maximal ``` -### 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 +### Available Configs {#sec-available-configs} #### Nix {#sec-configs-nix} @@ -39,32 +34,15 @@ The below configurations are provided for demonstration purposes, and are 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. -```bash -$ nix run github:notashelf/nvf#maximal -- test.nix -``` +::: {.tip} -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. +You are _strongly_ recommended to use the binary cache if you would like to try +the Maximal configuration. ::: diff --git a/modules/plugins/languages/dart.nix b/modules/plugins/languages/dart.nix index c2a1810d..9cbd0783 100644 --- a/modules/plugins/languages/dart.nix +++ b/modules/plugins/languages/dart.nix @@ -143,6 +143,8 @@ in { }) (mkIf ftcfg.enable { + lsp.enable = true; + startPlugins = [ ( if ftcfg.enableNoResolvePatch