docs: Introduce an user guide (nix-community#1121)

docs/man/default.nix

@@ -5,7 +5,7 @@
   nixos-render-docs,
   pandoc,
 }: let
-  capitalizeHeaders = ''
+  manualFilter = ''
     local text = pandoc.text
 
     function Header(el)
@@ -17,17 +17,24 @@
           }
         end
     end
+
+    function Link(el)
+      return el.content
+    end
   '';
 
-  manHeader =
+  manHeader = let
+    mkMDSection = file: "<(pandoc --lua-filter <(echo \"$manualFilter\") -f gfm -t man ${file})";
+  in
     runCommand "nixvim-general-doc-manpage" {
       nativeBuildInputs = [pandoc];
-      inherit capitalizeHeaders;
+      inherit manualFilter;
     } ''
       mkdir -p $out
       cat \
         ${./nixvim-header-start.5} \
-        <(pandoc --lua-filter <(echo "$capitalizeHeaders") -f gfm -t man ${../helpers.md}) \
+        ${mkMDSection ../user-guide/helpers.md} \
+        ${mkMDSection ../user-guide/faq.md} \
         ${./nixvim-header-end.5} \
         >$out/nixvim-header.5
     '';

docs/mdbook/SUMMARY.md

@@ -1,5 +1,11 @@
 # Structure for nixvim docs 
 
+# User guide
+
+- [Installation](./user-guide/install.md)
+- [Helpers](./user-guide/helpers.md)
+- [FAQ](./user-guide/faq.md)
+
 # Options
 
 @NIXVIM_OPTIONS@
@@ -9,4 +15,3 @@
 ---
 
 [Contributing](./CONTRIBUTING.md)
-[Helpers](./helpers.md)

docs/mdbook/default.nix

@@ -217,7 +217,7 @@ with lib; let
     # Copy inputs into the build directory
     cp -r --no-preserve=all $inputs/* ./
     cp ${../../CONTRIBUTING.md} ./CONTRIBUTING.md
-    cp ${../helpers.md} ./helpers.md
+    cp -r ${../user-guide} ./user-guide
 
     # Copy the generated MD docs into the build directory
     # Using pkgs.writeShellScript helps to avoid the "bash: argument list too long" error

docs/user-guide/faq.md

@@ -0,0 +1,26 @@
+# Frequently Asked Questions
+
+## How do I use a plugin not implemented in nixvim
+
+Using a plugin not supported by nixvim, but packaged in nixpkgs is straightforward:
+
+- Register the plugin through `extraPlugins`: `extraPlugins = [pkgs.vimPlugins."<plugin name>"]`.
+- Configure the plugin through `extraConfigLua`: `extraConfigLua = "require('my-plugin').setup({foo = "bar"})";`
+
+## How do I use a plugin not packaged in nixpkgs
+
+This is straightforward too, you can add the following to `extraPlugins` for a plugin hosted on GitHub:
+
+```nix
+extraPlugins = [(pkgs.vimUtils.buildVimPlugin {
+    name = "my-plugin";
+    src = pkgs.fetchFromGitHub {
+        owner = "<owner>";
+        repo = "<repo>";
+        rev = "<commit hash>";
+        hash = "<nix NAR hash>";
+    };
+})];
+```
+
+The [nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#managing-plugins-with-vim-packages) has more information on this.

docs/user-guide/install.md

@@ -0,0 +1,73 @@
+# Installation
+
+You must use a `nixpkgs` version compatible with the nixvim version you choose.
+
+The `master` branch requires to use a _very recent_ version of nixpkgs unstable.
+In order to guarantee the compatibility between nixvim & nixpkgs it is recommended to always update both at the same time.
+
+When using a `stable` version you must use the corresponding nixvim branch, for example `nixos-23.11` when using NixOS 23.11.
+
+Failure to use the correct branch, or an old revision of nixpkgs will likely result in errors of the form `vimPlugins.<name> attribute not found`.
+
+NixVim can be used in four ways:
+- As a NixOS module
+- As a Home-Manager module
+- As a nix-darwin module
+- As a standalone derivation
+
+NixVim is also available for nix flakes, or directly through an import.
+
+## Accessing nixvim
+
+For a direct import you can add nixvim to your configuration as follows:
+```nix
+let 
+    nixvim = import (builtins.fetchGit {
+        url = "https://github.com/nix-community/nixvim";
+        # When using a different channel you can use `ref = "nixos-<version>"` to set it here
+    });
+in
+```
+
+When using flakes you can simply add `nixvim` to the inputs:
+```nix
+{
+    inputs.nixvim = {
+        url = "github:nix-community/nixvim";
+        # If using a stable channel you can use `url = "github:nix-community/nixvim/nixos-<version>"`
+        inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    # outputs...
+}
+```
+
+## Usage as a module (NixOS, Home-Manager, nix-darwin)
+
+When using NixVim as a module you must import the NixVim module into your module system.
+The three imports are:
+- `<nixvim>.homeManagerModules.nixvim`
+- `<nixvim>.nixosModules.nixvim`
+- `<nixvim>.nixDarwinModules.nixvim`
+
+`<nixvim>` refers to the way to access nixvim, depending on how you fetched nixvim as described in the previous section.
+
+The imports can be added as a `imports = [ <nixvim_import> ]` in a configuration file.
+
+You will then be able to enable nixvim through `programs.nixvim.enable = true`, and configure the
+options as `programs.nixvim.<path>.<to>.<option> = <value>`.
+
+## Standalone usage
+
+When using nixvim as a standalone derivation you can use the following functions, located in `<nixvim>.legacyPackages.${system}`:
+- `makeNixvim`: This function takes an attribute set of options values as arguments
+- `makeNixvimWithModule`: This function takes an attribute set of the form: `{pkgs, extraSpecialArgs, module}`.
+  The only required argument is `module`, being a NixOS module. This gives access to the `imports`, `options`, `config` variables, and using functions like `{config, ...}: { ... }`.
+
+There are also some helper functions in `<nixvim>.lib.${system}` like:
+- `check.mkTestDerivationFromNixvimModule`, taking the same arguments as `makeNixvimWithModule` and generates a check derivation.
+- `check.mkTestDerivationFromNvim`, taking an attribute set of the form `{name = "<derivation name>"; nvim = <nvim derivation>}`. The `nvim` is the standalone derivation provided by NixVim.
+
+The nixvim derivation can then be used like any other package!
+
+For more information you can look at the [nixvim standalone flake template](https://github.com/nix-community/nixvim/blob/main/templates/simple/flake.nix).