From 8747a8576bfe965322ac32c98ab563fc7cd21d89 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Tue, 9 Feb 2021 15:45:44 +0000 Subject: [PATCH] Write documentation --- README.md | 225 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 215 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b09a2de4..7df6a5d7 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ NixVim is a [Neovim](https://neovim.io) distribution built around configured through Nix, all while leaving room for your plugins and your vimrc. ## What does it look like? -Here is a simple config that uses gruvbox as the colorscheme and uses the +Here is a simple configuration that uses gruvbox as the colorscheme and uses the lightline plugin: ```nix @@ -14,7 +14,6 @@ lightline plugin: enable = true; colorschemes.gruvbox.enable = true; - plugins.lightline.enable = true; }; } @@ -24,11 +23,32 @@ When we do this, lightline will be set up to a sensible default, and will use gruvbox as the colorscheme, no extra configuration required! ## Instalation -Right now, NixVim is only distributed as a Nix flake, which means you must -enable Nix flakes in order to use it. +### Without flakes +NixVim now ships with `flake-compat`, which makes it usable from any system. -It is fairly easy to enable flakes globally, just put this in -`/etc/nixos/configuration.nix` +To install it, edit your home-manager (or NixOS) configuration: + +```nix +{ pkgs, lib, ... }: +let + nixvim = import (lib.fetchGit { + url = "https://github.com/pta2002/nixvim"; + }); +in +{ + imports = [ + nixvim.homeManagerModules.nixvim + # Or, if you're not using home-manager: + nixvim.nixosModules.nixvim + ]; + + programs.nixvim.enable = true; +} +``` + +### Using flakes +This is the recommended method if you are already using flakes to manage your +sysyem. To enable flakes, add this to `/etc/nixos/configuration.nix` ```nix { pkgs, lib, ... }: @@ -41,8 +61,19 @@ It is fairly easy to enable flakes globally, just put this in } ``` -Then, you need to import the module. Information on how to do this will be added -soon. +Now, you need to import the module. If your system is already configured using +flakes, just add the nixvim input: + +```nix +{ + # ... + inputs.nixvim.url = github:pta2002/nixvim; +} +``` + +You can now access the module using `inputs.nixvim.homeManagerModules.nixvim`, +for a home-manager instalation, and `inputs.nixvim.nixosModules.nixvim`, if +you're not using it. ## How does it work? When you build the module (probably using home-manager), it will install all @@ -53,6 +84,180 @@ as fast as possible. Since everything is disabled by default, it will be as snappy as you want it to be. +# Documentation +Documentation is very much a work-in-progress. It will become available on this +repository's Wiki. + ## Plugins -NixVim provides a plugin system using Nix modules, allowing you to configure vim -similar to how you would configure NixOS services. +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: + +```nix +{ + programs.nixvim = { + plugins.lightline.enable = true; + }; +} +``` + +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 +module is planned. + +Not all plugins will have modules, so you might still want to fetch some. This +is not a problem, just use the `extraPlugins` option: + +```nix +{ + programs.nixvim = { + extraPlugins = with pkgs.vimPlugins; [ + vim-nix + ]; + }; +} +``` + +However, if you find yourself doing this a lot, please consider +contributing or requesting a module! + +### Colorschemes +Colorschemes are provided within a different scope: + +```nix +{ + programs.nixvim = { + # Enable gruvbox + colorschemes.gruvbox.enable = true; + }; +} +``` + +Just like with normal plugins, extra colorscheme options are provided as part +of its module. + +If your colorscheme isn't provided as a module, install it using +`extraPlugins` and set it using the `colorscheme` option: + +```nix +{ + programs.nixvim = { + extraPlugins = [ pkgs.vimPlugins.gruvbox ]; + colorscheme = "gruvbox"; + }; +} +``` + +All NixVim supported plugins will, by default, use the main colorscheme you +set, though this can be overriden in 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. + +All of these are configurable from within NixVim. All you have to do is set the +`options` attribute: + +```nix +{ + programs.nixvim = { + options = { + number = true; # Show line numbers + relativenumber = true; # Show relative line numbers + + shiftwidth = 2; # Tab width should be 2 + }; + }; +} +``` + +Please note that to, for example, disable numbers you would not set +`options.nonumber` to true, you'd set `options.number` to false. + +## Key mappings +It is fully possible to define key mappings from within NixVim. This is done +using the `maps` attribute: + +```nix +{ + programs.nixvim = { + maps = { + normalVisualOp.";" = ":"; + normal."m" = { + silent = true; + action = "make"; + }; + }; + }; +} +``` + +This is equivalent to this vimscript: + +```vim +noremap ; : +nnoremap m make +``` + +This table describes all modes for the `maps` option: + +| NixVim | NeoVim | +|----------------|--------------------------------------------------| +| normal | Normal mode | +| insert | Insert mode | +| visual | Visual and Select mode | +| select | Select mode | +| terminal | Terminal mode | +| normalVisualOp | Normal, visual, select and operator-pending mode | +| visualOnly | Visual mode only, without select | +| operator | Operator-pending mode | +| insertCommand | Insert and command-line mode | +| lang | Insert, command-line and lang-arg mode | +| command | Command-line mode | + +The map options can be set to either a string, containing just the action, +or to a set describing additional options: + +| NixVim | Default | VimScript | +|---------|---------|------------------------------------------| +| silent | false | `` | +| nowait | false | `` | +| script | false | `