docs: restructure documentation

docs/manual/configuring/custom-package.md

@@ -0,0 +1,20 @@
+# Custom Neovim Package {#ch-custom-package}
+
+As of v0.5, you may now specify the neovim package that will be wrapped with your configuration. This is done with the `vim.package` option.
+
+```nix
+{inputs, pkgs, ...}: {
+  # using the neovim-nightly overlay
+  vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim;
+}
+```
+
+The neovim-nightly-overlay always exposes an unwrapped package. If using a different source, you are highly
+recommended to get an "unwrapped" version of the neovim package, similar to `neovim-unwrapped` in nixpkgs.
+
+```nix
+{ pkgs, ...}: {
+  # using the neovim-nightly overlay
+  vim.package = pkgs.neovim-unwrapped;
+}
+```

docs/manual/configuring/custom-plugins.md

@@ -0,0 +1,25 @@
+# Custom Plugins {#ch-custom-plugins}
+
+Neovim-flake, by default, exposes a wide variety of plugins as module options
+for your convience and bundles necessary dependencies into neovim-flake's
+runtime. In case a plugin is not available in neovim-flake, you may consider
+making a pull request to neovim-flake to include it as a module or you may add
+it to your configuration locally.
+
+## Adding Plugins {#ch-adding-plugins}
+
+There are multiple way of adding custom plugins to your neovim-flake
+configuration.
+
+You can use custom plugins, before they are implemented in the flake. To add a
+plugin, you need to add it to your config's `vim.startPlugins` array.
+
+Adding a plugin to `startPlugins` will not allow you to configure the plugin
+that you have addeed, but neovim-flake provides multiple way of configuring any
+custom plugins that you might have added to your configuration.
+
+```{=include=} sections
+custom-plugins/configuring.md
+custom-plugins/new-method.md
+custom-plugins/old-method.md
+```

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
+    }
+  '';
+}
+```

docs/manual/configuring/languages.md

@@ -0,0 +1,26 @@
+# Language Support {#ch-languages}
+
+Language specific support means there is a combination of language specific plugins, `treesitter` support, `nvim-lspconfig` language servers, and `null-ls`
+integration. This gets you capabilities ranging from autocompletion to formatting to diagnostics. The following languages have sections under the `vim.languages`
+attribute.
+
+- Rust: [vim.languages.rust.enable](#opt-vim.languages.rust.enable)
+- Nix: [vim.languages.nix.enable](#opt-vim.languages.nix.enable)
+- SQL: [vim.languages.sql.enable](#opt-vim.languages.sql.enable)
+- C/C++: [vim.languages.clang.enable](#opt-vim.languages.clang.enable)
+- Typescript/Javascript: [vim.languages.ts.enable](#opt-vim.languages.ts.enable)
+- Python: [vim.languages.python.enable](#opt-vim.languages.python.enable):
+- Zig: [vim.languages.zig.enable](#opt-vim.languages.zig.enable)
+- Markdown: [vim.languages.markdown.enable](#opt-vim.languages.markdown.enable)
+- HTML: [vim.languages.html.enable](#opt-vim.languages.html.enable)
+- Dart: [vim.languages.dart.enable](#opt-vim.languages.dart.enable)
+- Go: [vim.languages.go.enable](#opt-vim.languages.go.enable)
+- Lua: [vim.languages.lua.enable](#opt-vim.languages.lua.enable)
+- PHP: [vim.languages.php.enable](#opt-vim.languages.php.enable)
+
+Adding support for more languages, and improving support for existing ones are great places
+where you can contribute with a PR.
+
+```{=include=} sections
+languages/lsp.md
+```

docs/manual/configuring/languages/lsp.md

@@ -0,0 +1,16 @@
+# LSP Custom Packages/Command {#sec-languages-custom-lsp-packages}
+
+In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide
+the command to launch the language server, as a list of strings.
+
+You can use this to skip automatic installation of a language server, and instead
+use the one found in your `$PATH` during runtime, for example:
+
+```nix
+vim.languages.java = {
+  lsp = {
+    enable = true;
+    package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
+  };
+}
+```