mirror of
https://github.com/nix-community/nixvim.git
synced 2025-11-08 19:46:06 +01:00
docs: improve consistency
Signed-off-by: saygo-png <saygo.mail@proton.me>
This commit is contained in:
saygo-png
Matt Sturgeon
parent
583d5d8982
commit
b9e5bac7bc
2 changed files with 48 additions and 48 deletions
|
|
@ -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
|
||||
|
||||
|
|
@ -24,18 +24,18 @@ Either command will start a HTTP server on port 8000 and open it in your browser
|
|||
## Nixvim Architecture
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
- _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`.\
|
||||
-> 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`.\
|
||||
-> See the [template](plugins/TEMPLATE.nix).
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ To add a new plugin you need to do the following.
|
|||
|
||||
#### `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,
|
||||
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].
|
||||
|
|
@ -296,15 +296,15 @@ In either case, you don't need to bother implementing this part. It is done auto
|
|||
|
||||
### 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`.
|
||||
|
||||
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]
|
||||
> 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.
|
||||
|
||||
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
|
||||
considerably. To use it, just install cachix and run `cachix use nix-community`.
|
||||
|
||||
|
|
|
|||
64
README.md
64
README.md
|
|
@ -7,7 +7,7 @@
|
|||
<a href="https://matrix.to/#/#nixvim:matrix.org">Chat</a>
|
||||
</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))
|
||||
- [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 -->
|
||||
|
||||
## 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
|
||||
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
|
||||
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 -->
|
||||
|
||||
## How does it work?
|
||||
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
|
||||
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`.
|
||||
|
||||
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>
|
||||
<summary>Example</summary>
|
||||
|
|
@ -88,17 +88,17 @@ If you have any question, please use the [discussions page](https://github.com/n
|
|||
## Installation
|
||||
|
||||
> [!WARNING]
|
||||
> 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`.
|
||||
> 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`.
|
||||
>
|
||||
> 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.
|
||||
|
||||
<details>
|
||||
<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:
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ To install it, edit your home-manager (or NixOS) configuration:
|
|||
let
|
||||
nixvim = import (builtins.fetchGit {
|
||||
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";
|
||||
});
|
||||
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
|
||||
flakes, just add the nixvim input:
|
||||
flakes, just add the `nixvim` input:
|
||||
|
||||
```nix
|
||||
{
|
||||
# ...
|
||||
inputs.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";
|
||||
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
|
|
@ -165,7 +165,7 @@ and `inputs.nixvim.nixDarwinModules.nixvim` for nix-darwin.
|
|||
</details>
|
||||
|
||||
## 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
|
||||
`nixvim.homeModules.nixvim`, `nixvim.nixDarwinModules.nixvim`, and
|
||||
`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
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
<details>
|
||||
|
|
@ -241,22 +241,22 @@ can use the following:
|
|||
```
|
||||
</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.
|
||||
|
||||
### 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
|
||||
- Adding custom nix modules to enhance nixvim
|
||||
- Change the nixpkgs used by nixvim
|
||||
- Adding custom nix modules to enhance Nixvim
|
||||
- Change the nixpkgs used by Nixvim
|
||||
|
||||
In this case, you can use the `makeNixvimWithModule` function.
|
||||
|
||||
It takes a set with the following keys:
|
||||
- `pkgs`: The nixpkgs to use (defaults to the nixpkgs pointed at by the nixvim flake)
|
||||
- `module`: The nix module definition used to extend nixvim.
|
||||
- `pkgs`: The nixpkgs to use (defaults to the nixpkgs pointed at by the Nixvim flake)
|
||||
- `module`: The nix module definition used to extend Nixvim.
|
||||
This is useful to pass additional module machinery like `options` or `imports`.
|
||||
- `extraSpecialArgs`: Extra arguments to pass to the modules when using functions.
|
||||
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`
|
||||
|
||||
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>
|
||||
<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`.
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
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
|
||||
|
|
@ -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.
|
||||
|
||||
## Options
|
||||
NeoVim has a lot of configuration options. You can find a list of them by doing
|
||||
`:h option-list` from within NeoVim.
|
||||
Neovim has a lot of configuration options. You can find a list of them by doing
|
||||
`: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:
|
||||
|
||||
```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.
|
||||
|
||||
## 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:
|
||||
|
||||
```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
|
||||
|
||||
| NixVim | Default | VimScript |
|
||||
| Nixvim | Default | VimScript |
|
||||
|---------|---------|---------------------------------------------------|
|
||||
| silent | false | `<silent>` |
|
||||
| nowait | false | `<silent>` |
|
||||
|
|
@ -460,7 +460,7 @@ leader key. This is easy with the `globals` attribute:
|
|||
```
|
||||
|
||||
## 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
|
||||
provided:
|
||||
|
||||
|
|
@ -468,14 +468,14 @@ provided:
|
|||
{
|
||||
programs.nixvim = {
|
||||
extraConfigLua = ''
|
||||
-- Print a little welcome message when nvim is opened!
|
||||
-- Print a little welcome message when Neovim is opened!
|
||||
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.
|
||||
|
||||
# Contributing
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue