From b9e5bac7bc8a165dd6eb16d10d6093e54168f037 Mon Sep 17 00:00:00 2001 From: saygo-png Date: Sun, 28 Sep 2025 21:34:21 +0200 Subject: [PATCH] docs: improve consistency Signed-off-by: saygo-png --- CONTRIBUTING.md | 32 ++++++++++++------------- README.md | 64 ++++++++++++++++++++++++------------------------- 2 files changed, 48 insertions(+), 48 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddf22da0..68e4db9e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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`. diff --git a/README.md b/README.md index 14f15829..c0f1288b 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Chat -# 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 @@ ## 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)! ## 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"; }`.
Example @@ -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.
Without flakes -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.
## 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:
@@ -241,22 +241,22 @@ can use the following: ```
-You can then run neovim using `nix run .# -- `. This can be useful to test +You can then run Neovim using `nix run .# -- `. 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`:
devShell configuration @@ -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 | `` | | nowait | false | `` | @@ -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