docs: restructure documentation

docs/manual/configuring.md

@@ -0,0 +1,7 @@
+# Configuring neovim-flake {#ch-configuring}
+
+```{=include=} chapters
+configuring/custom-package.md
+configuring/custom-plugins.md
+configuring/languages.md
+```

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

@@ -1,4 +1,4 @@
-# Configuring {#configuring-plugins}
+# 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`

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

@@ -1,6 +1,6 @@
 # New Method {#sec-new-method}
 
-As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
+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:
 

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

@@ -1,6 +1,8 @@
 # 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. See the configuration docs for details.
+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)

docs/manual/custom-package.md

@@ -1,12 +0,0 @@
-# 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
-  config.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.

docs/manual/custom-plugins.md

@@ -1,10 +0,0 @@
-# Custom Plugins {#ch-custom-plugins}
-
-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 `config.vim.startPlugins` array.
-
-```{=include=} sections
-custom-plugins/new-method.md
-custom-plugins/old-method.md
-custom-plugins/configuring.md
-```

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

@@ -1,18 +0,0 @@
-# Old Method {#sec-old-method}
-
-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.
-
-```nix
-{
-  # fetch plugin source from GitHub and add it to startPlugins
-  config.vim.startPlugins = [
-    (pkgs.fetchFromGitHub {
-      owner = "FrenzyExists";
-      repo = "aquarium-vim";
-      rev = "d09b1feda1148797aa5ff0dbca8d8e3256d028d5";
-      sha256 = "CtyEhCcGxxok6xFQ09feWpdEBIYHH+GIFVOaNZx10Bs=";
-    })
-  ];
-}
-```

docs/manual/default-configs.md

@@ -3,7 +3,7 @@
 While you can configure neovim-flake yourself using the builder, you can also use the pre-built configs that are available.
 Here are a few default configurations you can use.
 
-```{=include=} sections
+```{=include=} chapters
 default-configs/maximal.md
 default-configs/nix.md
 default-configs/tidal.md

docs/manual/hacking/guidelines.md

@@ -64,20 +64,28 @@ See [example commit message](#sec-guidelines-ex-commit-message) for a commit mes
 
 ## Example Commit {#sec-guidelines-ex-commit-message}
 
-The commit [69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef) contains the commit message
+The commit [69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
+in home-manager contains the commit message
 
 ```
-
 starship: allow running in Emacs if vterm is used
 
 The vterm buffer is backed by libvterm and can handle Starship prompts
 without issues.
+```
 
+Similarly, if you are contributing to neovim-flake, you would include the scope of the commit followed by
+the description
+
+```
+languages/ruby: init module
+
+Adds a language module for Ruby, and adds appropriate formatters and TS grammers
 ```
 
 Long description can be ommitted if the change is too simple to warrant it. A minor fix in spelling or a formatting
 change does not warrant long description, however, a module addition or removal does as you would like to provide the
-relevant context for your changes.
+relevant context, e.g. the reasoning behind it, for your commit.
 
 Finally, when adding a new module, say `modules/foo.nix`, we use the fixed commit format `foo: add module`.
 You can, of course, still include a long description if you wish.

docs/manual/installation.md

@@ -0,0 +1,11 @@
+# Installing neovim-flake {#ch-installation}
+
+There are multiple ways of installing neovim-flake on your system. You may either choose
+the standalone installation method, which does not depend on a module system and may
+be done on any system that has the Nix package manager or the appropriate modules
+for NixOS and home-manager as described in the [module installation section](#ch-module-installation)
+
+```{=include=} chapters
+installation/custom-configuration.md
+installation/modules.md
+```

docs/manual/installation/custom-configuration.md

@@ -0,0 +1,19 @@
+# Standalone Installation {#ch-standalone-installation}
+
+It is possible to install neovim-flake without depending on NixOS or home-manager as the parent
+module system, using the `neovimConfiguration` function exposed by neovim-flake extended library.
+It takes in the configuration as a module, and returns an attribute set as a result.
+
+```nix
+{
+  options = "The options that were available to configure";
+  config = "The outputted configuration";
+  pkgs = "The package set used to evaluate the module";
+  neovim = "The built neovim package";
+}
+```
+
+```{=include=} chapters
+standalone/nixos.md
+standalone/home-manager.md
+```

docs/manual/installation/modules.md

@@ -0,0 +1,6 @@
+# Module Installation {#ch-module-installation}
+
+```{=include=} chapters
+modules/nixos.md
+modules/home-manager.md
+```

docs/manual/installation/modules/home-manager.md

@@ -1,4 +1,4 @@
-# Home Manager {#ch-hm-module}
+# Home Manager Module {#ch-hm-module}
 
 The Home Manager module allows us to customize the different `vim` options from inside the home-manager configuration
 and it is the preferred way of configuring neovim-flake, both on NixOS and non-NixOS systems.

docs/manual/installation/modules/nixos.md

@@ -0,0 +1,3 @@
+# NixOS Module {#ch-nixos-module}
+
+This artice is a stub. It will be written as the NixOS module is finalized.

docs/manual/installation/standalone/home-manager.md

@@ -0,0 +1,37 @@
+# Standalone Installation (home-manager) {#ch-standalone-home-manager}
+
+The following is an example of a barebones vim configuration with the default theme enabled.
+
+```nix
+{
+  inputs.neovim-flake = {
+    url = "github:notashelf/neovim-flake";
+    inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = {nixpkgs, neovim-flake, ...}: let
+    system = "x86_64-linux";
+    pkgs = nixpkgs.legacyPackages.${system};
+    configModule = {
+      # Add any custom options (and feel free to upstream them!)
+      # options = ...
+
+      config.vim = {
+        theme.enable = true;
+      };
+    };
+
+    customNeovim = neovim-flake.lib.neovimConfiguration {
+      modules = [configModule];
+      inherit pkgs;
+    };
+  in {
+    # this is an example nixosConfiguration using the built neovim package
+    homeConfigurations = {
+      yourHostName = home-manager.lib.nixosSystem {
+        # TODO
+      };
+    };
+  };
+}
+```

docs/manual/installation/standalone/nixos.md

@@ -1,16 +1,4 @@
-# Custom Configuration {#ch-custom-configuration}
-
-Custom configuration is done with the `neovimConfiguration` while using the flake as a standalone package.
-It takes in the configuration as a module. The output of the configuration function is an attrset.
-
-```nix
-{
-  options = "The options that were available to configure";
-  config = "The outputted configuration";
-  pkgs = "The package set used to evaluate the module";
-  neovim = "The built neovim package";
-}
-```
+# Standalone Installation (NixOS) {#ch-standalone-nixos}
 
 The following is an example of a barebones vim configuration with the default theme enabled.
 
@@ -60,4 +48,4 @@ The following is an example of a barebones vim configuration with the default th
 
 Your built neovim configuration can be exposed as a flake output, or be added to your system packages to make
 it available across your system. You may also consider passing the flake output to home-manager to make it available
-to a specific user _without_ using the home-manager module.
+to a specific user.

docs/manual/manual.md

@@ -1,6 +1,6 @@
 # neovim-flake-manual {#neovim-flake-manual}
 
-## Version @VERSION@
+## Version @NVF_VERSION@
 
 ```{=include=} preface
 preface.md
@@ -8,12 +8,12 @@ try-it-out.md
 ```
 
 ```{=include=} parts
-custom-configs.md
-custom-package.md
-custom-plugins.md
 default-configs.md
-home-manager.md
-languages.md
+installation.md
+configuring.md
+```
+
+```{=include=} chapters
 hacking.md
 ```
 

docs/manual/options.md

@@ -1,5 +1,9 @@
 # Neovim Flake Configuration Options {#ch-options}
 
+Below are the options provided by neovim-flake provided in no particular order.
+They may include useful comments and warnings, or examples on how a module option
+is meant to be used.
+
 ```{=include=} options
 id-prefix: opt-
 list-id: neovim-flake-options

docs/manual/preface.md

@@ -1,6 +1,7 @@
-# Preface {#sec-preface}
+# Preface {#ch-preface}
 
 If you noticed a bug caused by neovim-flake then please consider reporting it over
 [the neovim-flake issue tracker](https://github.com/notashelf/neovim-flake/issues).
-Bugfixes, feature additions and upstreamed changes are welcome over
-[the neovim-flake pull requests tab](https://github.com/notashelf/neovim-flake/pulls).
+
+Bugfixes, feature additions and upstreamed changes from your local configurations
+are always welcome in the [the neovim-flake pull requests tab](https://github.com/notashelf/neovim-flake/pulls).

docs/manual/try-it-out.md

@@ -16,9 +16,7 @@ $ nix run github:notashelf/neovim-flake#nix # will run the default minimal confi
 ```
 
 Do keep in mind that this is **susceptible to garbage collection** meaning it will be removed from your Nix store
-once you garbage collect. If you wish to install neovim-flake, please take a look at
-[custom-configuration](#ch-custom-configuration) or [home-manager](#ch-hm-module) sections for installation
-instructions.
+once you garbage collect.
 
 ## Using Prebuilt Configs {#sec-using-prebuild-configs}
 
@@ -33,7 +31,7 @@ $ nix run github:notashelf/neovim-flake#maximal
 #### Nix {#sec-configs-nix}
 
 `Nix` configuration by default provides LSP/diagnostic support for Nix alongisde a set of visual and functional plugins.
-By running `nix run .`, which is the default package, you will build Neovim with this config.
+By running `nix run .#`, which is the default package, you will build Neovim with this config.
 
 #### Tidal {#sec-configs-tidal}