docs: restructure documentation

docs/manual/configuring/custom-plugins/configuring.md

@@ -0,0 +1,23 @@
+# Configuring {#sec-configuring-plugins}
+
+Just making the plugin to your neovim configuration available might not always be enough.
+In that case, you can write custom vimscript or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC`
+respectively. These options are attribute sets, and you need to give the configuration you're adding some name, like this:
+
+```nix
+{
+  # this will create an "aquarium" section in your init.vim with the contents of your custom config
+  # which will be *appended* to the rest of your configuration, inside your init.vim
+  config.vim.configRC.aquarium = "colorscheme aquiarum";
+}
+```
+
+:::{.note}
+If your configuration needs to be put in a specific place in the config, you can use functions from
+`inputs.neovim-flake.lib.nvim.dag` to order it.
+Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix to find out more about
+the DAG system.
+:::
+
+Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue
+with your findings so that we can make it available for everyone easily.

docs/manual/configuring/custom-plugins/new-method.md

@@ -0,0 +1,26 @@
+# New Method {#sec-new-method}
+
+As of version **0.5**, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
+
+Instead of using DAGs exposed by the library, you may use the extra plugin module as follows:
+
+```nix
+{
+  config.vim.extraPlugins = with pkgs.vimPlugins; {
+    aerial = {
+      package = aerial-nvim;
+      setup = ''
+        require('aerial').setup {
+          -- some lua configuration here
+        }
+      '';
+    };
+
+    harpoon = {
+      package = harpoon;
+      setup = "require('harpoon').setup {}";
+      after = ["aerial"];
+    };
+  };
+}
+```

docs/manual/configuring/custom-plugins/old-method.md

@@ -0,0 +1,33 @@
+# Old Method {#sec-old-method}
+
+Prior to version 0.5, the method of adding new plugins was adding the plugin package to `vim.startPlugins` and add
+its configuration as a DAG under `vim.configRC` or `vim.luaConfigRC`. Users who have not yet updated to 0.5, or prefer
+a more hands-on approach may use the old method where the load order of the plugins is determined by DAGs.
+
+## Adding plugins {#sec-adding-plugins}
+
+To add a plugin to neovim-flake's runtime, you may add it
+
+```nix
+{pkgs, ...}: {
+  # add a package from nixpkgs to startPlugins
+  vim.startPlugins = [
+    pkgs.vimPlugins.aerial-nvim  ];
+}
+```
+
+And to configure the added plugin, you can use the `luaConfigRC` option to provide configuration
+as a DAG using the neovim-flake extended library.
+
+```nix
+{inputs, ...}: let
+  # assuming you have an input called neovim-flake pointing at the neovim-flake repo
+  inherit (inputs.neovim-flake.lib.nvim.dag) entryAnywhere;
+in {
+  vim.luaConfigRC.aerial-nvim= entryAnywhere ''
+    require('aerial').setup {
+      -- your configuration here
+    }
+  '';
+}
+```