1 files changed, 104 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..561fa5e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,104 @@
+# Neovim Vanilla (wrapper)
+Neovim Vanilla is an option module for
+[home-manager](https://home-manager.dev/) and [NixOS](https://nixos.org/) to
+build a Neovim environment declaratively using Nix in a minimal fashion. Unlike
+[NixVim](https://github.com/nix-community/nixvim) or
+[NVF](https://github.com/NotAShelf/nvf), Neovim Vanilla doesn't try to take
+over your entire Neovim config. Its only job is to setup everything around your
+config so that you can get going quicker.
+
+Neovim Vanilla aims to replace your plugin manager (e.g.
+[lazy.nvim](https://lazy.folke.io/)), nvim package manager
+[mason.nvim](https://github.com/mason-org/mason.nvim), and even manages
+grammars for
+[nvim-treesitter](https://github.com/neovim-treesitter/nvim-treesitter)
+declaratively by leveraging `nixpkgs`. Due to the existence of previously
+mentioned Nix-based Neovim frameworks, basically every popular plugin, language
+server, linter, formatter, etc. are all already available in `nixpkgs`. Neovim
+Vanilla allows you to create a wrapped Neovim package that incorporates all of
+these and more into its environment.
+
+In addition, Neovim plugins from `nixpkgs` are guaranteed to work with the
+version of Neovim you install from `nixpkgs`. This ensures maximum stability
+and removes the friction of upgrading your plugins only to downgrade
+immediately after when you realize the plugin expects a newer Neovim version.
+
+This project is designed around the philosophy that it is an inherently bad
+idea to attempt to construct a script with Nix, it is better to leverage Nix
+for only what it is good at, and configure Neovim the intended way using lua.
+
+## Usage
+### In NixOS
+Import the flake into your `flake.nix` then include
+`inputs.neovim-vanilla-wrapped.nixosModules.neovim-vanilla-wrapped` in your
+NixOS modules. Then within your NixOS config:
+
+```nix
+programs.neovim-vanilla = {
+    enable = true;
+};
+```
+
+### In home-manager
+Import the flake into your `flake.nix` then include
+`inputs.neovim-vanilla-wrapped.hmModules.neovim-vanilla-wrapped` in your
+home-manager modules. Then within your home-manager config:
+
+```nix
+programs.neovim-vanilla = {
+    enable = true;
+};
+```
+
+## Full example config
+Here is an example config that sets up language servers, installs all
+treesitter parsers, and installs a few plugins for good measure:
+
+```nix
+programs.neovim-vanilla = {
+  enable = true;
+  viAlias = true;
+  vimAlias = true;
+  plugins = {
+    lsp = {
+      enable = true;
+      lspconfig.enable = true;  # Installs nvim-lspconfig plugin
+      languageServers.packages = with pkgs; [
+        # languageServers are only added to the wrapped neovim path, not the global path
+        python313Packages.python-lsp-server
+        vscode-langservers-extracted
+      ];
+    };
+    treesitter = {
+      enable = true;  # Installs the nvim-treesitter plugin and listed grammars
+      parsers.installAll = true;  # Individial parsers can also be installed if you don't want all of them
+    };
+    # Install plugins here
+    # 99% of the time, you want to use packages.start
+    packages.start = with pkgs.vimPlugins; [
+      autoclose-nvim
+      nvim-colorizer-lua
+    ];
+  };
+  extraPackages = with pkgs; [
+    # extraPackages are only added to the wrapped neovim path, not the global path
+    unzip  # For zip, xlsx, etc. files
+  ];
+};
+```
+
+You can inspect the module to find the full list of options.
+
+## Loading in Neovim
+Loading plugins in Neovim with Neovim Vanilla is identical to loading plugins
+when using `vim.pack`. Simply `require` the plugin's main module and run
+`setup` if required. E.g.:
+
+```lua
+require("autoclose").setup { options = { pair_spaces = true } }
+require("colorizer").setup { lazy_load = true }
+```
+
+Note that the main module does not nessisarily match the name of the package in
+`nixpkgs`, you will need to refer to the plugin docs for instructions on which
+module to import and use.