nix-community/nixvim
1
0
Fork 0
mirror of https://github.com/nix-community/nixvim.git synced 2025-11-08 19:46:06 +01:00
Code Activity

docs: improve consistency

Browse source 
Signed-off-by: saygo-png <saygo.mail@proton.me>
This commit is contained in:
saygo-png 2025-09-28 21:34:21 +02:00 • committed by Matt Sturgeon
parent 583d5d8982
commit b9e5bac7bc
2 changed files with 48 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

32
CONTRIBUTING.md
View file

@ -1,6 +1,6 @@
# Contributing (and hacking onto) nixvim # Contributing (and hacking onto) Nixvim
This document is mainly for contributors to nixvim, but it can also be useful for extending nixvim. This document is mainly for contributors to Nixvim, but it can also be useful for extending Nixvim.
## Submitting a change ## Submitting a change
@ -24,18 +24,18 @@ Either command will start a HTTP server on port 8000 and open it in your browser
## Nixvim Architecture ## Nixvim Architecture
Nixvim is mainly built around `pkgs.neovimUtils.makeNeovimConfig`. Nixvim is mainly built around `pkgs.neovimUtils.makeNeovimConfig`.
This function takes a list of plugins (and a few other misc options), and generates a configuration for neovim. This function takes a list of plugins (and a few other misc options), and generates a configuration for Neovim.
This can then be passed to `pkgs.wrapNeovimUnstable` to generate a derivation that bundles the plugins, extra programs and the lua configuration. This can then be passed to `pkgs.wrapNeovimUnstable` to generate a derivation that bundles the plugins, extra programs and the lua configuration.
All the options that nixvim expose end up in those three places. This is done in the `modules/output.nix` file. All the options that Nixvim exposes end up in those three places. This is done in the `modules/output.nix` file.
The guiding principle of nixvim is to only add to the `init.lua` what the user added to the configuration. This means that we must trim out all the options that were not set. The guiding principle of Nixvim is to only add to the `init.lua` what the user added to the configuration. This means that we must trim out all the options that were not set.
This is done by making most of the options of the type `types.nullOr ....`, and not setting any option that is null. This is done by making most of the options of the type `types.nullOr ....`, and not setting any option that is `null`.
### Plugin configurations ### Plugin configurations
Most of nixvim is dedicated to wrapping neovim plugins such that we can configure them in Nix. Most of Nixvim is dedicated to wrapping Neovim plugins such that we can configure them in Nix.
To add a new plugin you need to do the following. To add a new plugin you need to do the following.
1. Add a file in the correct sub-directory of [`plugins`](plugins). 1. Add a file in the correct sub-directory of [`plugins`](plugins).
@ -48,10 +48,10 @@ To add a new plugin you need to do the following.
2. The vast majority of plugins fall into one of those two categories: 2. The vast majority of plugins fall into one of those two categories:
- _vim plugins_: They are configured through **global variables** (`g:plugin_foo_option` in vimscript and `vim.g.plugin_foo_option` in lua).\ - _Vim plugins_: They are configured through **global variables** (`g:plugin_foo_option` in vimscript and `vim.g.plugin_foo_option` in lua).\
For those, you should use the `lib.nixvim.plugins.mkVimPlugin`.\ For those, you should use the `lib.nixvim.plugins.mkVimPlugin`.\
-> See [this plugin](plugins/by-name/direnv/default.nix) for an example. -> See [this plugin](plugins/by-name/direnv/default.nix) for an example.
- _neovim plugins_: They are configured through a `setup` function (`require('plugin').setup({opts})`).\ - _Neovim plugins_: They are configured through a `setup` function (`require('plugin').setup({opts})`).\
For those, you should use the `lib.nixvim.plugins.mkNeovimPlugin`.\ For those, you should use the `lib.nixvim.plugins.mkNeovimPlugin`.\
-> See the [template](plugins/TEMPLATE.nix). -> See the [template](plugins/TEMPLATE.nix).
@ -59,7 +59,7 @@ To add a new plugin you need to do the following.
#### `mkNeovimPlugin` #### `mkNeovimPlugin`
The `mkNeovimPlugin` function provides a standardize way to create a `Neovim` plugin. The `mkNeovimPlugin` function provides a standardize way to create a Neovim plugin.
This is intended to be used with lua plugins that have a `setup` function, This is intended to be used with lua plugins that have a `setup` function,
although it is flexible enough to be used with similar variants of plugins. although it is flexible enough to be used with similar variants of plugins.
A template plugin can be found in (plugins/TEMPLATE.nix)[https://github.com/nix-community/nixvim/blob/main/plugins/TEMPLATE.nix]. A template plugin can be found in (plugins/TEMPLATE.nix)[https://github.com/nix-community/nixvim/blob/main/plugins/TEMPLATE.nix].
@ -296,15 +296,15 @@ In either case, you don't need to bother implementing this part. It is done auto
### Tests ### Tests
Most of the tests of nixvim consist of creating a neovim derivation with the supplied nixvim configuration, and then try to execute neovim to check for any output. All output is considered to be an error. Most of the tests of Nixvim consist of creating a Neovim derivation with the supplied Nixvim configuration, and then try to execute Neovim to check for any output. All output is considered to be an error.
The tests are located in the [tests/test-sources](tests/test-sources) directory, and should be added to a file in the same hierarchy than the repository. For example if a plugin is defined in `./plugins/ui/foo.nix` the test should be added in `./tests/test-sources/ui/foo.nix`. The tests are located in the [tests/test-sources](tests/test-sources) directory, and should be added to a file in the same hierarchy than the repository. For example if a plugin is defined in `./plugins/ui/foo.nix` the test should be added in `./tests/test-sources/ui/foo.nix`.
Tests can either be a simple attribute set, or a function taking `{pkgs}` as an input. The keys of the set are configuration names, and the values are a nixvim configuration. Tests can either be a simple attribute set, or a function taking `{pkgs}` as an input. The keys of the set are configuration names, and the values are a Nixvim configuration.
You can specify the special `test` attribute in the configuration that will not be interpreted by nixvim, but only the test runner. The following keys are available: You can specify the special `test` attribute in the configuration that will not be interpreted by Nixvim, but only the test runner. The following keys are available:
- `test.runNvim`: Set to `false` to avoid launching nvim with this configuration and simply build the configuration. - `test.runNvim`: Set to `false` to avoid launching Neovim with this configuration and simply build the configuration.
> [!TIP] > [!TIP]
> A single test can be run with `nix develop --command tests --interactive`. This launches the testing suite in interactive mode, allowing you to easily search for and select specific tests to run. > A single test can be run with `nix develop --command tests --interactive`. This launches the testing suite in interactive mode, allowing you to easily search for and select specific tests to run.
@ -314,9 +314,9 @@ You can specify the special `test` attribute in the configuration that will not
The full test suite can still be run locally with `nix flake check --all-systems` if needed. The full test suite can still be run locally with `nix flake check --all-systems` if needed.
There are a second set of tests, unit tests for nixvim itself, defined in `tests/lib-tests.nix` that use the `pkgs.lib.runTests` framework. There are a second set of tests, unit tests for Nixvim itself, defined in `tests/lib-tests.nix` that use the `pkgs.lib.runTests` framework.
If you want to speed up tests, we have set up a Cachix for nixvim. If you want to speed up tests, we have set up a Cachix for Nixvim.
This way, only tests whose dependencies have changed will be re-run, speeding things up This way, only tests whose dependencies have changed will be re-run, speeding things up
considerably. To use it, just install cachix and run `cachix use nix-community`. considerably. To use it, just install cachix and run `cachix use nix-community`.

64
README.md
View file

@ -7,7 +7,7 @@
<a href="https://matrix.to/#/#nixvim:matrix.org">Chat</a> <a href="https://matrix.to/#/#nixvim:matrix.org">Chat</a>
</h2> </h2>
# NixVim - A Neovim configuration system for nix # Nixvim - A Neovim configuration system for nix
- [Quick set up tutorial](https://www.youtube.com/watch?v=b641h63lqy0) (by [@Vimjoyer](https://www.youtube.com/@vimjoyer)) - [Quick set up tutorial](https://www.youtube.com/watch?v=b641h63lqy0) (by [@Vimjoyer](https://www.youtube.com/@vimjoyer))
- [Nixvim: How to configure Neovim with the power of Nix](https://www.youtube.com/watch?v=GOe0C7Qtypk) (NeovimConf 2023 talk by [@GaetanLepage](https://glepage.com/)) - [Nixvim: How to configure Neovim with the power of Nix](https://www.youtube.com/watch?v=GOe0C7Qtypk) (NeovimConf 2023 talk by [@GaetanLepage](https://glepage.com/))
@ -15,7 +15,7 @@
<!-- START DOCS --> <!-- START DOCS -->
## What is it? ## What is it?
NixVim is a [Neovim](https://neovim.io) distribution built around Nixvim is a [Neovim](https://neovim.io) distribution built around
[Nix](https://nixos.org) modules. It is distributed as a Nix flake, and [Nix](https://nixos.org) modules. It is distributed as a Nix flake, and
configured through Nix, all while leaving room for your plugins and your vimrc. configured through Nix, all while leaving room for your plugins and your vimrc.
@ -37,13 +37,13 @@ lualine plugin:
When we do this, lualine will be set up to a sensible default, and will use When we do this, lualine will be set up to a sensible default, and will use
catppuccin as the colorscheme, no extra configuration required! catppuccin as the colorscheme, no extra configuration required!
Check out [this list of real world nixvim configs](https://nix-community.github.io/nixvim/user-guide/config-examples.html)! Check out [this list of real world Nixvim configs](https://nix-community.github.io/nixvim/user-guide/config-examples.html)!
<!-- STOP DOCS --> <!-- STOP DOCS -->
## How does it work? ## How does it work?
When you build the module (probably using home-manager), it will install all When you build the module (probably using home-manager), it will install all
your plugins and generate a lua config for NeoVim with all the options your plugins and generate a lua config for Neovim with all the options
specified. Because it uses lua, this ensures that your configuration will load specified. Because it uses lua, this ensures that your configuration will load
as fast as possible. as fast as possible.
@ -62,7 +62,7 @@ If you just want to add additional lines of lua to your `init.lua`, you can use
`extraConfigLua`, `extraConfigLuaPre`, and `extraConfigLuaPost`. `extraConfigLua`, `extraConfigLuaPre`, and `extraConfigLuaPost`.
If you want to assign lua code to an option that'd normally accept another type If you want to assign lua code to an option that'd normally accept another type
(string, int, etc), you can use nixvim's "raw type", `{ __raw = "lua code"; }`. (string, int, etc), you can use Nixvim's "raw type", `{ __raw = "lua code"; }`.
<details> <details>
<summary>Example</summary> <summary>Example</summary>
@ -88,17 +88,17 @@ If you have any question, please use the [discussions page](https://github.com/n
## Installation ## Installation
> [!WARNING] > [!WARNING]
> NixVim needs to be installed with a compatible nixpkgs version. > Nixvim needs to be installed with a compatible nixpkgs version.
> This means that the `main` branch of NixVim requires to be installed with `nixpkgs-unstable`. > This means that the `main` branch of Nixvim requires to be installed with `nixpkgs-unstable`.
> >
> If you want to use NixVim with nixpkgs 25.05 you should use the `nixos-25.05` branch. > If you want to use Nixvim with nixpkgs 25.05 you should use the `nixos-25.05` branch.
For more detail, see the [Installation](https://nix-community.github.io/nixvim) section of our documentation. For more detail, see the [Installation](https://nix-community.github.io/nixvim) section of our documentation.
<details> <details>
<summary><strong>Without flakes</strong></summary> <summary><strong>Without flakes</strong></summary>
NixVim now ships with `flake-compat`, which makes it usable from any system. Nixvim now ships with `flake-compat`, which makes it usable from any system.
To install it, edit your home-manager (or NixOS) configuration: To install it, edit your home-manager (or NixOS) configuration:
@ -107,7 +107,7 @@ To install it, edit your home-manager (or NixOS) configuration:
let let
nixvim = import (builtins.fetchGit { nixvim = import (builtins.fetchGit {
url = "https://github.com/nix-community/nixvim"; url = "https://github.com/nix-community/nixvim";
# If you are not running an unstable channel of nixpkgs, select the corresponding branch of nixvim. # If you are not running an unstable channel of nixpkgs, select the corresponding branch of Nixvim.
# ref = "nixos-25.05"; # ref = "nixos-25.05";
}); });
in in
@ -143,14 +143,14 @@ system. To enable flakes, add this to `/etc/nixos/configuration.nix`
``` ```
Now, you need to import the module. If your system is already configured using Now, you need to import the module. If your system is already configured using
flakes, just add the nixvim input: flakes, just add the `nixvim` input:
```nix ```nix
{ {
# ... # ...
inputs.nixvim = { inputs.nixvim = {
url = "github:nix-community/nixvim"; url = "github:nix-community/nixvim";
# If you are not running an unstable channel of nixpkgs, select the corresponding branch of nixvim. # If you are not running an unstable channel of nixpkgs, select the corresponding branch of Nixvim.
# url = "github:nix-community/nixvim/nixos-25.05"; # url = "github:nix-community/nixvim/nixos-25.05";
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
@ -165,7 +165,7 @@ and `inputs.nixvim.nixDarwinModules.nixvim` for nix-darwin.
</details> </details>
## Usage ## Usage
NixVim can be used in four ways: through the home-manager, nix-darwin, NixOS modules, Nixvim can be used in four ways: through the home-manager, nix-darwin, NixOS modules,
and standalone through the `makeNixvim` function. To use the modules, just import the and standalone through the `makeNixvim` function. To use the modules, just import the
`nixvim.homeModules.nixvim`, `nixvim.nixDarwinModules.nixvim`, and `nixvim.homeModules.nixvim`, `nixvim.nixDarwinModules.nixvim`, and
`nixvim.nixosModules.nixvim` modules, depending on which system `nixvim.nixosModules.nixvim` modules, depending on which system
@ -193,7 +193,7 @@ To get started with a standalone configuration, you can use the template by runn
nix flake init --template github:nix-community/nixvim nix flake init --template github:nix-community/nixvim
``` ```
Alternatively, if you want a minimal flake to allow building a custom neovim you Alternatively, if you want a minimal flake to allow building a custom Neovim you
can use the following: can use the following:
<details> <details>
@ -241,22 +241,22 @@ can use the following:
``` ```
</details> </details>
You can then run neovim using `nix run .# -- <file>`. This can be useful to test You can then run Neovim using `nix run .# -- <file>`. This can be useful to test
config changes easily. config changes easily.
### Advanced Usage ### Advanced Usage
You may want more control over the nixvim modules, like: You may want more control over the Nixvim modules, like:
- Splitting your configuration in multiple files - Splitting your configuration in multiple files
- Adding custom nix modules to enhance nixvim - Adding custom nix modules to enhance Nixvim
- Change the nixpkgs used by nixvim - Change the nixpkgs used by Nixvim
In this case, you can use the `makeNixvimWithModule` function. In this case, you can use the `makeNixvimWithModule` function.
It takes a set with the following keys: It takes a set with the following keys:
- `pkgs`: The nixpkgs to use (defaults to the nixpkgs pointed at by the nixvim flake) - `pkgs`: The nixpkgs to use (defaults to the nixpkgs pointed at by the Nixvim flake)
- `module`: The nix module definition used to extend nixvim. - `module`: The nix module definition used to extend Nixvim.
This is useful to pass additional module machinery like `options` or `imports`. This is useful to pass additional module machinery like `options` or `imports`.
- `extraSpecialArgs`: Extra arguments to pass to the modules when using functions. - `extraSpecialArgs`: Extra arguments to pass to the modules when using functions.
Can be `self` in a flake, for example. Can be `self` in a flake, for example.
@ -265,7 +265,7 @@ For more detail, see the [Standalone Usage](https://nix-community.github.io/nixv
### With a `devShell` ### With a `devShell`
You can also use nixvim to define an instance which will only be available inside a Nix `devShell`: You can also use Nixvim to define an instance which will only be available inside a Nix `devShell`:
<details> <details>
<summary>devShell configuration</summary> <summary>devShell configuration</summary>
@ -292,7 +292,7 @@ If the option `enableMan` is set to `true` (by default it is), man pages will al
be installed containing the same information, they can be viewed with `man nixvim`. be installed containing the same information, they can be viewed with `man nixvim`.
## Plugins ## Plugins
After you have installed NixVim, you will no doubt want to enable some plugins. After you have installed Nixvim, you will no doubt want to enable some plugins.
Plugins are based on a modules system, similarly to NixOS and Home Manager. Plugins are based on a modules system, similarly to NixOS and Home Manager.
So, to enable some supported plugin, all you have to do is enable its module: So, to enable some supported plugin, all you have to do is enable its module:
@ -305,7 +305,7 @@ So, to enable some supported plugin, all you have to do is enable its module:
} }
``` ```
Of course, if that was everything, there wouldn't be much point to NixVim, you'd Of course, if that was everything, there wouldn't be much point to Nixvim, you'd
just use a regular plugin manager. All options for supported plugins are exposed just use a regular plugin manager. All options for supported plugins are exposed
as options of that module. For now, there is no documentation yet, but there are as options of that module. For now, there is no documentation yet, but there are
detailed explanations in the source code. Detailed documentation for every detailed explanations in the source code. Detailed documentation for every
@ -354,14 +354,14 @@ If your colorscheme isn't provided as a module, install it using
} }
``` ```
All NixVim supported plugins will, by default, use the main colorscheme you All Nixvim supported plugins will, by default, use the main colorscheme you
set, though this can be overridden on a per-plugin basis. set, though this can be overridden on a per-plugin basis.
## Options ## Options
NeoVim has a lot of configuration options. You can find a list of them by doing Neovim has a lot of configuration options. You can find a list of them by doing
`:h option-list` from within NeoVim. `:h option-list` from within Neovim.
All of these are configurable from within NixVim. All you have to do is set the All of these are configurable from within Nixvim. All you have to do is set the
`opts` attribute: `opts` attribute:
```nix ```nix
@ -381,7 +381,7 @@ Please note that to, for example, disable numbers you would not set
`opts.nonumber` to true, you'd set `opts.number` to false. `opts.nonumber` to true, you'd set `opts.number` to false.
## Key mappings ## Key mappings
It is fully possible to define key mappings from within NixVim. This is done It is fully possible to define key mappings from within Nixvim. This is done
using the `keymaps` attribute: using the `keymaps` attribute:
```nix ```nix
@ -436,7 +436,7 @@ Each keymap can specify the following settings in the `options` attrs.
[Abbreviation]: https://neovim.io/doc/user/usr_24.html#_abbreviations [Abbreviation]: https://neovim.io/doc/user/usr_24.html#_abbreviations
| NixVim | Default | VimScript | | Nixvim | Default | VimScript |
|---------|---------|---------------------------------------------------| |---------|---------|---------------------------------------------------|
| silent | false | `<silent>` | | silent | false | `<silent>` |
| nowait | false | `<silent>` | | nowait | false | `<silent>` |
@ -460,7 +460,7 @@ leader key. This is easy with the `globals` attribute:
``` ```
## Additional config ## Additional config
Sometimes NixVim won't be able to provide for all your customization needs. Sometimes Nixvim won't be able to provide for all your customization needs.
In these cases, the `extraConfigVim` and `extraConfigLua` options are In these cases, the `extraConfigVim` and `extraConfigLua` options are
provided: provided:
@ -468,14 +468,14 @@ provided:
{ {
programs.nixvim = { programs.nixvim = {
extraConfigLua = '' extraConfigLua = ''
-- Print a little welcome message when nvim is opened! -- Print a little welcome message when Neovim is opened!
print("Hello world!") print("Hello world!")
''; '';
}; };
} }
``` ```
If you feel like what you are doing manually should be supported in NixVim, If you feel like what you are doing manually should be supported in Nixvim,
please open an issue. please open an issue.
# Contributing # Contributing