NotAShelf/nvf
2
1
Fork 0
mirror of https://github.com/NotAShelf/nvf.git synced 2025-09-06 10:21:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

docs: clarify wording; add examples and remove redundancies

Browse source
This commit is contained in:
raf 2025-05-05 14:57:32 +03:00
commit f1d72cf076
Signed by: NotAShelf
GPG key ID: 29D95B64378DB4BF
15 changed files with 262 additions and 90 deletions
Download patch file Download diff file Expand all files Collapse all files

119
docs/manual/configuring/autocmds.md Normal file
View file

@ -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.

4
docs/manual/configuring/custom-package.md
View file

@ -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;
}
```

35
docs/manual/configuring/custom-plugins.md
View file

@ -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

46
docs/manual/configuring/custom-plugins/configuring.md
View file

@ -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')";
}
```
<!-- deno-fmt-ignore-start -->
[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.
:::
<!-- deno-fmt-ignore-end -->

13
docs/manual/configuring/custom-plugins/lazy-method.md
View file

@ -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"]`

29
docs/manual/configuring/custom-plugins/legacy-method.md
View file

@ -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

9
docs/manual/configuring/custom-plugins/non-lazy-method.md
View file

@ -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.

19
docs/manual/configuring/languages/lsp.md
View file

@ -1,17 +1,22 @@
# LSP Custom Packages/Command {#sec-languages-custom-lsp-packages}
In any of the `opt.languages.<language>.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"];
};
}