From e5f2726ffdcb66a0dea93036bfe24e35d8dd1f77 Mon Sep 17 00:00:00 2001
From: Nicolas Goudry <goudry.nicolas@gmail.com>
Date: Mon, 27 May 2024 09:45:41 +0200
Subject: [PATCH] docs(readme): add installation instructions and further
 details

---
 README.md           | 56 ++++++++++++++++++++++++++++++++++++++++++++-
 plugins/default.nix | 23 -------------------
 2 files changed, 55 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 29c6a3a..3496cdb 100644
--- a/README.md
+++ b/README.md
@@ -2,4 +2,58 @@
 
 **PERSONAL** configuration for [Neovim](https://neovim.io/) using [Nixvim](https://nix-community.github.io/nixvim/). Heavily inspired by [AstroNvim](https://astronvim.com/).
 
-🚧 **This is a work in progress** 🚧
+> [!NOTE]
+> This project uses the [flake system](https://nixos.wiki/wiki/Flakes) and is not intended to be used without Flakes.
+
+The [flake](./flake.nix) exports two packages:
+
+* `default`: Nixvim package built from the configuration files
+* `lite`: Same as above, without the LSP stuff
+
+> [!WARNING]
+> 🚧 **This is a work in progress** 🚧
+
+## 📥 Installation
+
+```nix
+{
+  inputs.nixvim-config.url = "github:nicolas-goudry/nixvim-config";
+
+  outputs = { nixvim-config, ... }: {
+    overlays.additions = final: _prev: {
+      nixvim = nixvim-config.packages.${_prev.system}.default;
+
+      # Or use the lite version
+      # nixvim = nixvim-config.packages.${_prev.system}.lite;
+    }
+  }
+}
+```
+
+## 🍱 Structure
+
+The config is mainly split in two directories:
+
+* [plugins](./plugins): Nixvim plugins configuration, using a custom load mechanism
+* [config](./config): nvim configuration (like options, global keymaps, etc)
+
+Other configuration attributes may be found in [`default.nix`](./default.nix) if they don’t justify being in a separate file.
+
+### 🥣 Configuration
+
+The configuration is split in multiple files organized by “topic” in the [config](./config) directory. These are auto-`import`ed in the main [`default.nix`](./default.nix) file.
+
+### 🥢 Plugins
+
+The plugins are not explicitly declared as Nixvim `plugins.<plugin>` attributes. Instead, they are looked up in and loaded from the [plugins](./plugins) directory.
+
+In short, a lambda will read the files in the directory and use the filename to assign a plugin to the right attribute. Example: `telescope.nix` will be loaded in `config.plugins.telescope`. Custom plugins are also supported, read further.
+
+Each plugin file must export a lambda, which is called with an attribute set containing the `nixpkgs`'s library as `lib`. Plugins may or may not use it. It must return an attribute set which can contain the following attributes:
+
+* `opts`: plugin options as expected by Nixvim
+* `rootOpts`: extra options for the root Nixvim `config` attribute
+  * this allows to further configure the plugin if it doesn’t expose a given option
+* `extra`: custom plugin not supported by Nixvim
+  * `extra.packages`: list of packages to be added as `extraPlugins` (ie. `vimPlugins.<plugin>`)
+  * `extra.config`: plugin configuration in lua
diff --git a/plugins/default.nix b/plugins/default.nix
index 9789744..a89f329 100644
--- a/plugins/default.nix
+++ b/plugins/default.nix
@@ -1,26 +1,3 @@
-# This file will load all plugins defined in the current directory (plugins)
-# and load their content in the 'plugins' nixvim attribute.
-
-# Each plugin file must export a lambda, which is called with an attrset
-# containing nixpkgs library as 'lib'. Plugins may or may not use it.
-
-# For plugins natively supported by nixvim, the plugin file must have the same
-# name as the plugin attribute name expected by nixvim (ie. 'telescope.nix' for
-# 'plugins.telescope'). The plugin lambda must return an attrset with at least
-# the 'opts' attribute, this attribute is the plugin options as expected by
-# nixvim.
-
-# For plugins not supported by nixvim, the plugin file can have any name. The
-# plugin lambda must return an attrset with the 'extra' attribute which is also
-# an attrset with two attributes: 'package' and 'config'. The 'package'
-# attribute is the plugin package in nixpkgs (ie. vimPlugins.<plugin>). The
-# 'config' attribute is the plugin configuration in Lua format.
-
-# Additionally, a 'rootOpts' can be returned alongside other attributes, this
-# attribute will be used to set extra options to the root nixvim options. For
-# example, this allows to set keymaps for plugins that do not have an internal
-# option to set keymaps.
-
 { lib, ... }@args:
 
 let