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

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

11
docs/manual/configuring.md
View file

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

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"];
};
}

10
docs/manual/default-configs.md
View file

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

11
docs/manual/default-configs/maximal.md
View file

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

9
docs/manual/default-configs/nix.md
View file

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

1
docs/manual/manual.md
View file

@ -8,7 +8,6 @@ try-it-out.md
```
```{=include=} parts
default-configs.md
installation.md
configuring.md
tips.md

6
docs/manual/tips.md
View file

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

30
docs/manual/try-it-out.md
View file

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