.github/workflows/check.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Check Flake
         run: nix flake check
 
-  format-sources:
+  format-with-alejandra:
     name: "Check formatting"
     runs-on: ubuntu-latest
     if: "!contains(github.event.pull_request.title, '[skip ci]')"

docs/manual/configuring.md

@@ -3,11 +3,10 @@
 [helpful tips section]: ./tips.html#ch-helpful-tips
 [options reference]: ./options.html
 
-**nvf** allows for _very_ extensive configuration in Neovim through the Nix
+nvf allows for _very_ extensive configuration in Neovim through the Nix module
-module interface. The below chapters describe several of the options exposed in
+interface. The below chapters describe several of the options exposed in nvf for
-nvf for your convenience. You might also be interested in the
+your convenience. You might also be interested in the [helpful tips section] for
-[helpful tips section] for more advanced or unusual configuration options
+more advanced or unusual configuration options supported by nvf.
-supported by nvf.
 
 Note that this section does not cover module _options_. For an overview of all
 module options provided by nvf, please visit the [options reference]

docs/manual/hacking.md

@@ -3,13 +3,12 @@
 [open issues]: https://github.com/notashelf/nvf/issues
 [new issue]: https://github.com/notashelf/nvf/issues/new
 
-**nvf** is designed for the developer as much as it is designed for the
+nvf is designed for the developer as much as it is designed for the end-user. We
-end-user. We would like for any contributor to be able to propagate their
+would like for any contributor to be able to propagate their changes, or add new
-changes, or add new features to the project with minimum possible friction. As
+features to the project with minimum possible friction. As such, below are the
-such, below are the guides and guidelines written to streamline the contribution
+guides and guidelines written to streamline the contribution process and to
-process and to ensure that your valuable input integrates into **nvf**'s
+ensure that your valuable input integrates into nvf's development as seamlessly
-development as seamlessly as possible without leaving any question marks in your
+as possible without leaving any question marks in your head.
-head.
 
 This section is directed mainly towards those who wish to contribute code into
 the project. If you instead wish to report a bug, or discuss a potential new
@@ -24,52 +23,24 @@ please do not be afraid to submit a pull request, we will help you get it in.
 
 ## Getting Started {#sec-contrib-getting-started}
 
-[Fork a repo guide]: https://help.github.com/articles/fork-a-repo/
+You, naturally, would like to start by forking the repository to get started. If
-[Contributing Guidelines]: #sec-guidelines
+you are new to Git and GitHub, do have a look at GitHub's
-[Create a Pull Request]: https://help.github.com/articles/creating-a-pull-request
+[Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for
-
+instructions on how you can do this. Once you have a fork of **nvf**, you should
-To contribute to **nvf**, you'll first want to fork the repository. If you are
+create a separate branch based on the most recent `main` branch. Give your
-new to Git and GitHub, do have a look at GitHub's [Fork a repo guide] for
+branch a reasonably descriptive name (e.g. `feature/debugger` or
-instructions on how you can do this. Once your fork is created, you should
+`fix/pesky-bug`) and you are ready to work on your changes
-create a separate branch based on the most recent `main` branch. While you _can_
-work on the main branch of your repository, it is generally preferable to use
-feature branches. You should give your branch a reasonably descriptive name
-(e.g. `feature/new-debugger` or `fix/pesky-bug`) and you are ready to work on
-your changes!
 
 Implement your changes and commit them to the newly created branch and when you
 are happy with the result, and positive that it fulfills our
-[Contributing Guidelines], push the branch to GitHub and [Create a Pull Request]
+[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and
+[create a pull request](https://help.github.com/articles/creating-a-pull-request).
 The default pull request template available on the **nvf** repository will guide
 you through the rest of the process, and we'll gently nudge you in the correct
 direction if there are any mistakes.
 
-Before submitting your pull request, please ensure that:
-
-- The code is formatted as described in the formatting section
-- The commit message fits the contributing guidelines (**nvf** does not use
-  Conventional Commits!)
-- You have updated the changelog entry and optionally updated the documentation
-  with important information
-
-None of those are reasons for a Pull Request to be closed, but it will reduce
-the number of "roundtrips", or rather, the back-and-forth required before we can
-merge your Pull Request.
-
-> [!IMPORTANT]
-> If you do not agree with the idea of using Microsoft GitHub for contributions,
-> that is perfectly understandable. Unless you refuse to have your code hosted
-> on this platform, you may submit _patches_ through e-mail.
->
-> You may send your patches to [@NotAShelf](https://github.com/notashelf) using
-> the public e-mail located on the GitHub page. Though, please remember to
-> adhere to the contributing guidelines strictly, as e-mail introduces a
-> significant overhead to the communication process.
-
 ## Guidelines {#sec-guidelines}
 
-[discussions tab]: https://github.com/NotAShelf/nvf/discussions
-
 If your contribution tightly follows the guidelines, then there is a good chance
 it will be merged without too much trouble. Some of the guidelines will be
 strictly enforced, others will remain as gentle nudges towards the correct
@@ -77,26 +48,34 @@ direction. As we have no automated system enforcing those guidelines, please try
 to double check your changes before making your pull request in order to avoid
 "faulty" code slipping by.
 
-If you are not quite certain how those rules affect the change you are planning
+If you are uncertain how these rules affect the change you would like to make
-to make, then please start a friendly discussion in the [discussions tab] before
+then feel free to start a discussion in the
-you begin developing. This is not a requirement, but it might answer some of
+[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not
-your burning questions and make the contribution process easier for all parties.
+necessarily) before you start developing.
 
-### Formatting {#sec-guidelines-formatting}
+### Adding Documentation {#sec-guidelines-documentation}
 
-[code style section]: #sec-guidelines-code-style
+[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
 
-There are various files within the **nvf** repository. To maintain a sense of
+Almost all changes warrant updates to the documentation: at the very least, you
-consistency and to avoid clashing opinions on how formatters should behave, we
+must update the changelog. Both the manual and module options use
-are very opinionated on how those files should be formatted.
+[Nixpkgs Flavoured Markdown].
 
-- Nix files **must** be formatted with the Alejandra formatter, following some
+The HTML version of this manual containing both the module option descriptions
-  specific tips found in [Nix style section](#nix-sec-code-style-nix).
+and the documentation of **nvf** (such as this page) can be generated and opened
-- Markdown files **must** be formatted with the `deno fmt` command, as described
+by typing the following in a shell within a clone of the **nvf** Git repository:
-  in the [Markdown style section](#sec-code-style-markdown).
 
-Make sure your code is formatted as described in [code style section] before
+```console
-your changes are submitted.
+$ nix build .#docs-html
+$ xdg-open $PWD/result/share/doc/nvf/index.html
+```
+
+### Formatting Code {#sec-guidelines-formatting}
+
+Make sure your code is formatted as described in
+[code-style section](#sec-guidelines-code-style). To maintain consistency
+throughout the project you are encouraged to browse through existing code and
+adopt its style also in new code.
 
 ### Formatting Commits {#sec-guidelines-commit-message-style}
 
@@ -119,29 +98,27 @@ The commit messages should follow the
 component or module in the first line. A commit message ideally, but not
 necessarily, follow the given template from home-manager's own documentation
 
-```gitcommit
+```
-{component}: {description}
+  {component}: {description}
 
-{long description}
+  {long description}
 ```
 
 where `{component}` refers to the code component (or module) your change
 affects, `{description}` is a very brief description of your change, and
-`{long description}` is an optional clarifying description.
+`{long description}` is an optional clarifying description. As a rare exception,
-
+if there is no clear component, or your change affects many components, then the
-[example commit message]: #sec-guidelines-ex-commit-message
+`{component}` part is optional. See
-
+[example commit message](#sec-guidelines-ex-commit-message) for a commit message
-As a rare exception, if there is no clear component, or your change affects many
+that fulfills these requirements.
-components, then the `{component}` part is optional. See
-[example commit message] for a commit message that fulfills these requirements.
 
 #### Example Commit {#sec-guidelines-ex-commit-message}
 
-[sample commit from Home Manager]: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
+The commit
+[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
+in home-manager contains the following commit message.
 
-The [sample commit from Home Manager] contains the following commit message.
+```
-
-```gitcommit
 starship: allow running in Emacs if vterm is used
 
 The vterm buffer is backed by libvterm and can handle Starship prompts
@@ -151,63 +128,30 @@ without issues.
 Similarly, if you are contributing to **nvf**, you would include the scope of
 the commit followed by the description:
 
-```gitcommit
+```
 languages/ruby: init module
 
-Adds a language module for Ruby, adds appropriate formatters and Treesitter
+Adds a language module for Ruby, adds appropriate formatters and Treesitter grammars
-grammars
 ```
 
 Long description can be omitted 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, i.e., the reasoning for your commit.
+relevant context, i.e. the reasoning behind it, for your commit.
 
-For new plugin additions, the following is a good starting point:
+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.
 
-```gitcommit
+In case of nested modules, i.e `modules/languages/java.nix` you are recommended
-plugin: init
+to contain the parent as well - for example `languages/java: some major change`.
-```
-
-You can, of course, still include a long description if you wish.
-
-```gitcommit
-neotree: init
-
-This adds the neo-tree plugin.
-```
-
-In case of nested modules, e.g., `modules/languages/java.nix` you are
-recommended to contain the parent as well -- for example
-`languages/java: some major change` , or if it's a new language module,
-`languages/java: init`
 
 ### Code Style {#sec-guidelines-code-style}
 
 #### Treewide {#sec-code-style-treewide}
 
-Across the tree, you're encouraged to follow kebab-case for file names, and keep
+Keep lines at a reasonable width, ideally 80 characters or less. This also
-text files (such as Markdown) to 80 characters or less. This 80 character
+applies to string literals and module descriptions and documentation.
-recommendation also applies to option descriptions and string literals inside of
-Nix files.
-
-#### Markdown {#sec-code-style-markdown}
-
-Various Markdown files are used for documentation in the **nvf** repository.
-Besides the README, the manual is written almost entirely in Markdown. Since
-**nvf** uses a special variant of CommonMark, dubbed "Nixpkgs-flavored
-CommonMark" within this repository, you are encouraged to use the `deno fmt`
-command (provided by `pkgs.deno`) to format your Markdown sources. To avoid
-accidentally formatting HTML or CSS files, you might want to specify the file
-extension as follows:
-
-```bash
-# Format all Markdown files within the repository
-$ deno fmt --ext md **/*.md
-```
-
-You may also pass `--check` to the `deno fmt` command above to see if your
-formatting complies with the project standards.
 
 #### Nix {#sec-code-style-nix}
 
@@ -221,16 +165,12 @@ While Alejandra is mostly opinionated on how code looks after formatting,
 certain changes are done at the user's discretion based on how the original code
 was structured.
 
-##### Attribute Sets
-
 Please use one line code for attribute sets that contain only one subset. For
 example:
 
-<!-- markdownlint-disable MD013 -->
-
 ```nix
-# Parent modules should always be unfolded.
+# parent modules should always be unfolded
-# which means `module = { value = ... }` instead of `module.value = { ... }`.
+# which means module = { value = ... } instead of module.value = { ... }
 module = {
   value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
 
@@ -250,45 +190,23 @@ module = {
 }
 ```
 
-<!-- markdownlint-enable MD013 -->
-
 If you move a line down after the merge operator, Alejandra will automatically
-unfold the whole merged attribute set for you, which we **do not** want.
+unfold the whole merged attrset for you, which we **do not** want.
 
 ```nix
 module = {
-  # This is wrong!
   key = mkEnableOption "some description" // {
     default = true; # we want this to be inline
-  }; 
+  }; # ...
-
-  # ...
 }
 ```
 
-Though, if the right-hand side is more than a single line, it is okay to move to
-a new line. For example:
-
-```nix
-module = {
-  # This is okay!
-  key = mkEnableOption "some description" // {
-    default = true; 
-    example = false;
-  };
-
-  # ...
-}
-```
-
-##### Lists
-
 For lists, it is mostly up to your own discretion how you want to format them,
 but please try to unfold lists if they contain multiple items and especially if
 they are to include comments.
 
 ```nix
-# This is ok
+# this is ok
 acceptableList = [
   item1 # comment
   item2
@@ -296,14 +214,14 @@ acceptableList = [
   item4
 ];
 
-# This is *not* ok
+# this is not ok
 listToBeAvoided = [item1 item2 /* comment */ item3 item4];
 
-# This is ok
+# this is ok
 acceptableList = [item1 item2];
 
-# This is also ok if the list is expected to contain more elements
+# this is also ok if the list is expected to contain more elements
-acceptableList = [
+acceptableList= [
   item1
   item2
   # more items if needed...
@@ -312,161 +230,129 @@ acceptableList = [
 
 ## Testing Changes {#sec-testing-changes}
 
-Once you have made your changes, you will need to test them thoroughly. To make
+Once you have made your changes, you will need to test them thoroughly. If it is
-testing easier you may either use the `configuration.nix` located in the
+a module, add your module option to `configuration.nix` (located in the root of
-repository root, or use the development package located in `flake/develop.nix`.
+this project) inside `neovimConfiguration`. Enable it, and then run the maximal
-The development package allows you to quickly bootstrap a Neovim configuration
+configuration with `nix run .#maximal -Lv` to check for build errors. If neovim
-with only the required modules, instead of the packages that consume the
+opens in the current directory without any error messages (you can check the
-`configuration.nix`, so it is generally preferable. To use it navigate to the
+output of `:messages` inside neovim to see if there are any errors), then your
-`develop.nix` module, and update the `configuration` set with the Neovim
+changes are good to go. Open your pull request, and it will be reviewed as soon
-configuration that you would like to test with. For example:
+as possible.
+
+If it is not a new module, but a change to an existing one, then make sure the
+module you have changed is enabled in the maximal configuration by editing
+`configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same
+procedure as adding a new module will apply here.
+
+## Keybinds {#sec-keybinds}
+
+As of 0.4, there exists an API for writing your own keybinds and a couple of
+useful utility functions are available in the
+[extended standard library](https://github.com/NotAShelf/nvf/tree/main/lib). The
+following section contains a general overview to how you may utilize said
+functions.
+
+## Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
+
+To set a mapping, you should define it in `vim.keymaps`.
+
+An example, simple keybinding, can look like this:
 
 ```nix
 {
-  # Let's assume you are adding a new module for the Nix language.
+  vim.keymaps = [
-  # You will need to enable it here
+    {
-  configuration = {
+      key = "<leader>wq";
-    vim.languages.nix.enable = true;
+      mode = ["n"];
+      action = ":wq<CR>";
+      silent = true;
+      desc = "Save file and quit";
+    }
+  ];
+}
+```
 
-    # You can also enable other plugins that you wish to test with, for example
+There are many settings available in the options. Please refer to the
-    # none-ls:
+[documentation](./options.html#option-vim-keymaps) to see a list of them.
-    vim.lsp.null-ls = {
+
-      enable = true;
+**nvf** provides a helper function, so that you don't have to write the mapping
-      setupOpts = { /* Your setup options here */ };
+attribute sets every time:
+
+- `mkKeymap`, which mimics neovim's `vim.keymap.set` function
+
+You can read the source code of some modules to see them in action, but the
+usage should look something like this:
+
+```nix
+# plugindefinition.nix
+{lib, ...}: let
+  inherit (lib.options) mkEnableOption;
+  inherit (lib.nvim.binds) mkMappingOption;
+in {
+  options.vim.plugin = {
+    enable = mkEnableOption "Enable plugin";
+
+    # Mappings should always be inside an attrset called mappings
+    mappings = {
+      workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "<leader>lwd";
+      documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "<leader>ld";
+      lspReferences = mkMappingOption "LSP References [trouble]" "<leader>lr";
+      quickfix = mkMappingOption "QuickFix [trouble]" "<leader>xq";
+      locList = mkMappingOption "LOCList [trouble]" "<leader>xl";
+      symbols = mkMappingOption "Symbols [trouble]" "<leader>xs";
     };
+}
+```
+
+```nix
+# config.nix
+{
+  config,
+  lib,
+  options,
+  ...
+}: let
+  inherit (lib.modules) mkIf;
+  inherit (lib.nvim.binds) mkKeymap;
+
+  cfg = config.vim.plugin;
+
+  keys = cfg.mappings;
+  inherit (options.vim.lsp.trouble) mappings;
+in {
+  config = mkIf cfg.enable {
+    vim.keymaps = [
+      (mkKeymap "n" keys.workspaceDiagnostics "<cmd>Trouble toggle diagnostics<CR>" {desc = mappings.workspaceDiagnostics.description;})
+      (mkKeymap "n" keys.documentDiagnostics "<cmd>Trouble toggle diagnostics filter.buf=0<CR>" {desc = mappings.documentDiagnostics.description;})
+      (mkKeymap "n" keys.lspReferences "<cmd>Trouble toggle lsp_references<CR>" {desc = mappings.lspReferences.description;})
+      (mkKeymap "n" keys.quickfix "<cmd>Trouble toggle quickfix<CR>" {desc = mappings.quickfix.description;})
+      (mkKeymap "n" keys.locList "<cmd>Trouble toggle loclist<CR>" {desc = mappings.locList.description;})
+      (mkKeymap "n" keys.symbols "<cmd>Trouble toggle symbols<CR>" {desc = mappings.symbols.description;})
+    ];
   };
+}
 ```
 
-You may then run this package with `nix run .#develop` and check for build or
+> [!NOTE]
-runtime errors. If Neovim builds and opens without any errors, then your changes
+> If you have come across a plugin that has an API that doesn't seem to easily
-are good to go. Open your pull request, and it will be reviewed as soon as
+> allow custom keybindings, don't be scared to implement a draft PR. We'll help
-possible.
+> you get it done.
-
-If your changes are rather large, or if you would like to instead test with a
-more complex configuration then you might use the `configuration.nix` for
-testing. Make your changes, and then build either the default or `maximal`
-package to test your changes.
-
-> [!IMPORTANT]
-> `configuration.nix` is a module used to bootstrap **demo** packages and should
-> generally not be changed unless migrating old APIs or updating the set of
-> default plugins. Similarly, the `develop.nix` file is for reference, and
-> testing configurations **should not be committed**.
-
-## Adding Documentation {#sec-guidelines-documentation}
-
-[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
-[in-house documentation generator]: https://github.com/feel-co/ndg
-[library documentation]: https://github.com/feel-co/ndg/blob/main/ndg-commonmark/docs/SYNTAX.md
-
-Almost all changes to **nvf**'s codebase warrant updates to the documentation.
-At the very least, you must update the relevant changelog document to describe
-your changes. The documentation files found within the repository use a superset
-of [Nixpkgs Flavoured Markdown] thanks to our
-[in-house documentation generator].
-
-As a general rule of thumb:
-
-- Everything in the CommonMark spec is supported
-- Everything in Nixpkgs Flavoured Markdown is supported
-- Github Flavored Markdown is supported for Tables and Admonitions
-
-By feeding NDG, our documentation generator, Markdown sources we can generate a
-HTML manual with various goodies, including a **search page** and an **options
-page**. The latter, found under `options.html` contains module options, similar
-to the official Nixpkgs search utility. The supported syntax for NDG can be
-found over at the [library documentation].
-
-### Building the Documentation
-
-The HTML version of this documentation, dubbed the "nvf manual", can be
-generated and opened by typing the following in a shell within a clone of the
-**nvf** Git repository:
-
-```sh
-# Build the online manual
-$ nix build .#docs-html
-
-# Open it with a valid browser
-$ xdg-open $PWD/result/share/doc/nvf/index.html
-```
-
-Additionally, if you are adding new links to the documentation it is **generally
-recommended** that you run the package that identifies dead URLs in the
-documentation:
-
-```sh
-# Build the link checker package
-$ nix build .#docs-linkcheck
-```
-
-You must ensure that the **HTML Documentation** builds before submitting a pull
-request. If the documentation builds, an automatic "preview" build will be
-deployed automatically for your Pull Request. You may use this preview to view
-your changes as your Pull Request is updated.
-
-### Formatting Changelog Entries
-
-For additions, removals or any general change that concerns the users you must
-add a changelog entry. The changelog entries are later included in the rendered
-manual for users hoping to learn what has changed.
-
-To maintain consistency, you must follow the following format in the changelog:
-
-```markdown
-[username](https://github.com/username):
-
-- Added ...
-- Removed ...
-- Changed ...
-```
-
-If this is your first contribution, you should add yourself to the changelog.
-Linking your GitHub account is not a strict requirement; it can be any page that
-people can use to discover you. Below the link to your profile, you should
-include a brief description of your changes. Those descriptions must be in past
-tense, unlike commit messages.
-
-While adding a new section, please insert the section at an arbitrary location
-under the `## Changelog` section rather than the end of the document. This helps
-avoid merge conflicts.
-
-### Breaking Changes
-
-If you are introducing _breaking_ changes to the repository, then you must also
-briefly mention what has changed in the breaking changes section of the
-changelog document that you are editing. If this section does not yet exist, you
-must create it.
-
-```markdown
-# Release 0.9 {#sec-release-0-9}
-
-## Breaking changes
-
-- We broke everything, please migrate!
-```
-
-This section is _critical_, as it is used to communicate to the users what has
-changed in the codebase and what breakage they may expect upon an update. To be
-comprehensive, you should include migration steps or how users may mitigate
-breakage depending on the context of the change.
 
 ## Adding Plugins {#sec-additional-plugins}
 
-**nvf** generally tries to avoid using Neovim plugins from Nixpkgs, and thus
+There are two methods for adding new Neovim plugins to **nvf**. npins is the
-uses one of the two alternative methods where applicable. npins is the faster
+faster option that should be preferred if the plugin consists of pure Lua or
-option that should be preferred if the plugin consists of pure Lua or Vimscript
+Vimscript code. In which case there is no building required, and we can easily
-code. In which case there is no building required, and we can easily handle the
+handle the copying of plugin files. Alternative method, which is required when
-copying of plugin files. Alternative method, which is required when plugins try
+plugins try to build their own libraries (e.g., in Rust or C) that need to be
-to build their own libraries (e.g., in Rust, C or even Assembly) that need to be
+built with Nix to function correctly.
-built with Nix to function correctly. In this case you must use a local overlay.
 
 ### With npins {#sec-npins-for-plugins}
 
-npins is the standard, and as described above, the _faster_ method of adding new
+npins is the standard method of adding new plugins to **nvf**. You simply need
-plugins to **nvf**. You simply need the repository URL for the plugin, and you
+the repository URL for the plugin, and can add it as a source to be built
-can add it as a source to be built automatically with just one command. To add a
+automatically with one command. To add a new Neovim plugin, use `npins`. For
-new Neovim plugin, use `npins`. For example:
+example:
 
 ```bash
 nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
@@ -478,13 +364,16 @@ Then run:
 npins add --name <plugin name> github <owner> <repo> -b <branch>
 ```
 
-> [!NOTE]
+::: {.note}
-> Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
+
-> example
+Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
->
+example
-> ```bash
+
-> npins add --name lazydev-nvim github folke lazydev.nvim -b main
+```bash
-> ```
+npins add --name lazydev-nvim github folke lazydev.nvim -b main
+```
+
+:::
 
 Once the `npins` command is done, you can start referencing the plugin as a
 **string**.
@@ -510,21 +399,15 @@ We use `buildRustPackage` to build the library from the repository root, and
 copy everything in the `postInstall` phase.
 
 ```nix
-{
+postInstall = ''
-  # ...
+  cp -r {lua,plugin} "$out"
-  
-  postInstall = ''
-    cp -r {lua,plugin} "$out"
 
-    mkdir -p "$out/doc"
+  mkdir -p "$out/doc"
-    cp 'doc/'*'.txt' "$out/doc/"
+  cp 'doc/'*'.txt' "$out/doc/"
 
-    mkdir -p "$out/target"
+  mkdir -p "$out/target"
-    mv "$out/lib" "$out/target/release"
+  mv "$out/lib" "$out/target/release"
-  '';
+'';
-  
-  # ...
-}
 ```
 
 In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs
@@ -546,7 +429,7 @@ your package to the plugin builder (`pluginBuilders`) function manually in
 }
 ```
 
-### Modular Setup Options {#sec-modular-setup-options}
+### Modular setup options {#sec-modular-setup-options}
 
 Most plugins is initialized with a call to `require('plugin').setup({...})`.
 
@@ -620,7 +503,7 @@ own fields!
 }
 ```
 
-### Details of `toLuaObject` {#sec-details-of-toluaobject}
+### Details of toLuaObject {#sec-details-of-toluaobject}
 
 As you've seen above, `toLuaObject` is used to convert our nix attrSet
 `cfg.setupOpts`, into a lua table. Here are some rules of the conversion:
@@ -661,7 +544,7 @@ As you've seen above, `toLuaObject` is used to convert our nix attrSet
    }
    ```
 
-### Lazy Loading Plugins {#sec-lazy-plugins}
+### Lazy plugins {#sec-lazy-plugins}
 
 If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it.
 Lazy plugins are managed by `lz.n`.
@@ -721,104 +604,3 @@ require('lz.n').load({
 
 A full list of options can be found in the [`vim.lazy.plugins` spec] on the
 rendered manual.
-
-## Keybinds {#sec-keybinds}
-
-[extended standard library]: https://github.com/NotAShelf/nvf/tree/main/lib
-
-As of 0.4, there exists an API for writing your own keybinds and a couple of
-useful utility functions are available in the [extended standard library]. The
-following section contains a general overview to how you may utilize said
-functions.
-
-### Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
-
-To set a mapping, you should define it in `vim.keymaps`. As an example, a simple
-keybinding can look like this:
-
-```nix
-{
-  vim.keymaps = [
-    {
-      key = "<leader>wq";
-      mode = ["n"];
-      action = ":wq<CR>";
-      silent = true;
-      desc = "Save file and quit";
-    }
-  ];
-}
-```
-
-[module option documentation]: options.html#option-vim-keymaps
-
-There are many other settings available in the keymap module. Please refer to
-the [module option documentation] for a full and up-to-date list of them.
-
-To make adding new keymaps for your favorite plugins easier, **nvf** provides a
-helper function. This is so that you do not have to write the mapping attribute
-sets every time:
-
-- `mkKeymap`, which mimics Neovim's `vim.keymap.set` function
-
-You can read the source code of some modules to see them in action, but the
-usage should look something like this:
-
-```nix
-# pluginDefinition.nix
-{lib, ...}: let
-  inherit (lib.options) mkEnableOption;
-  inherit (lib.nvim.binds) mkMappingOption;
-in {
-  options.vim.plugin = {
-    enable = mkEnableOption "Enable plugin";
-
-    # Mappings should always be inside an attrset called mappings
-    mappings = {
-      workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "<leader>lwd";
-      documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "<leader>ld";
-      lspReferences = mkMappingOption "LSP References [trouble]" "<leader>lr";
-      quickfix = mkMappingOption "QuickFix [trouble]" "<leader>xq";
-      locList = mkMappingOption "LOCList [trouble]" "<leader>xl";
-      symbols = mkMappingOption "Symbols [trouble]" "<leader>xs";
-    };
-}
-```
-
-<!-- markdownlint-disable MD013  -->
-
-```nix
-# config.nix
-{
-  config,
-  lib,
-  options,
-  ...
-}: let
-  inherit (lib.modules) mkIf;
-  inherit (lib.nvim.binds) mkKeymap;
-
-  cfg = config.vim.plugin;
-
-  keys = cfg.mappings;
-  inherit (options.vim.lsp.trouble) mappings;
-in {
-  config = mkIf cfg.enable {
-    vim.keymaps = [
-      (mkKeymap "n" keys.workspaceDiagnostics "<cmd>Trouble toggle diagnostics<CR>" {desc = mappings.workspaceDiagnostics.description;})
-      (mkKeymap "n" keys.documentDiagnostics "<cmd>Trouble toggle diagnostics filter.buf=0<CR>" {desc = mappings.documentDiagnostics.description;})
-      (mkKeymap "n" keys.lspReferences "<cmd>Trouble toggle lsp_references<CR>" {desc = mappings.lspReferences.description;})
-      (mkKeymap "n" keys.quickfix "<cmd>Trouble toggle quickfix<CR>" {desc = mappings.quickfix.description;})
-      (mkKeymap "n" keys.locList "<cmd>Trouble toggle loclist<CR>" {desc = mappings.locList.description;})
-      (mkKeymap "n" keys.symbols "<cmd>Trouble toggle symbols<CR>" {desc = mappings.symbols.description;})
-    ];
-  };
-}
-```
-
-<!-- markdownlint-enable MD013 -->
-
-> [!TIP]
-> If you have come across a plugin that has an API that doesn't seem to easily
-> allow custom keybindings, don't be scared to implement a draft PR. We'll help
-> you get it done.

docs/manual/index.md

@@ -1,23 +1,20 @@
 # Introduction {#nvf-manual}
 
-Generated for nvf @NVF_VERSION@
+Version @NVF_VERSION@
 
 ## Preface {#ch-preface}
 
 ### What is nvf {#sec-what-is-it}
 
-[Nix]: https://nixos.org
+**nvf** is a highly modular, configurable, extensible and easy to use Neovim
+configuration framework built and designed to be used with Nix. Boasting
+flexibility, robustness and ease of use, this projecct allows you to configure a
+fully featured Neovim instance with a few lines of Nix with lots of options for
+advanced users as well.
 
-**nvf** is a highly modular, configurable, extensible and _easy to use_ Neovim
+## Try it out {#ch-try-it-out}
-configuration framework built for and designed to be used with [Nix]. Boasting
-flexibility, robustness and ease of use (among other positive traits), this
-project allows you to configure a fully featured Neovim instance with a few
-lines of Nix while leaving all kinds of doors open for integrating Lua in your
-configurations _whether you are a beginner or an advanced user_.
 
-## Try it Out {#ch-try-it-out}
+Thanks to the portability of Nix, you can try out nvf without actually
-
-Thanks to the portability of Nix, you can try out **nvf** without actually
 installing it to your machine. Below are the commands you may run to try out
 different configurations provided by this flake. As of v0.5, two specialized
 configurations are provided:
@@ -30,27 +27,20 @@ You may try out any of the provided configurations using the `nix run` command
 on a system where Nix is installed.
 
 ```sh
-# Add the nvf cache
 $ cachix use nvf                   # Optional: it'll save you CPU resources and time
-
-# Run the minimal configuration with the cache enabled
 $ nix run github:notashelf/nvf#nix # Will run the default minimal configuration
 ```
 
 Do keep in mind that this is **susceptible to garbage collection** meaning that
 the built outputs will be removed from your Nix store once you garbage collect.
 
-## Using Prebuilt Configurations {#sec-using-prebuilt-configs}
+## Using Prebuilt Configs {#sec-using-prebuilt-configs}
-
-<!-- markdownlint-disable MD014 -->
 
 ```bash
 $ nix run github:notashelf/nvf#nix
 $ nix run github:notashelf/nvf#maximal
 ```
 
-<!-- markdownlint-enable MD014 -->
-
 ### Available Configurations {#sec-available-configs}
 
 > [!NOTE]
@@ -71,7 +61,7 @@ $ nix run github:notashelf/nvf#nix test.nix
 ```
 
 This command will start Neovim with some opinionated plugin configurations, and
-is designed specifically for Nix. The `nix` configuration lets you see how a
+is designed specifically for Nix. the `nix` configuration lets you see how a
 fully configured Neovim setup _might_ look like without downloading too many
 packages or shell utilities.
 
@@ -97,16 +87,12 @@ companion or fun plugins.
 
 ## Installing nvf {#ch-installation}
 
-<!-- markdownlint-disable MD051 -->
-
 [module installation section]: #ch-module-installation
 
-<!-- markdownlint-enable MD051 -->
+There are multiple ways of installing nvf on your system. You may either choose
-
+the standalone installation method, which does not depend on a module system and
-There are multiple ways of installing **nvf** on your system. You may either
+may be done on any system that has the Nix package manager or the appropriate
-choose the standalone installation method, which does not depend on a module
+modules for NixOS and home-manager as described in the
-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].
 
 ```{=include=}

docs/manual/installation/modules/flakes.md

@@ -1,7 +1,7 @@
-#### Prerequisites {#sec-flakes-prerequisites}
+### Prerequisites {#sec-flakes-prerequisites}
 
-To install **nvf** with flakes, you must make sure the following requirements
+To install nvf with flakes, you must make sure the following requirements are
-are met.
+met.
 
 1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later
    version of Nix from nixpkgs.
@@ -29,6 +29,5 @@ are met.
      following additional flags to `nix` and `home-manager`:
 
      ```sh
-     # Temporarily enables "nix-command" and "flakes" experimental features.
      $ nix --extra-experimental-features "nix-command flakes" <sub-commands>
      ```

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

@@ -1,7 +1,7 @@
-## Home Manager Module {#ch-hm-module}
+# Home-Manager Module {#ch-hm-module}
 
-The Home Manager module allows us to customize the different `vim` options from
+The home-manager module allows us to customize the different `vim` options from
-inside the Home Manager configuration without having to call for the wrapper
+inside the home-manager configuration without having to call for the wrapper
 yourself. It is the recommended way to use **nvf** alongside the NixOS module
 depending on your needs.
 

docs/manual/installation/modules/nixos.md

@@ -1,11 +1,11 @@
-## NixOS Module {#ch-nixos-module}
+# NixOS Module {#ch-nixos-module}
 
 The NixOS module allows us to customize the different `vim` options from inside
 the NixOS configuration without having to call for the wrapper yourself. It is
 the recommended way to use **nvf** alongside the home-manager module depending
 on your needs.
 
-### With Flakes {#sec-nixos-flakes}
+## With Flakes {#sec-nixos-flakes}
 
 ```{=include=}
 flakes.md

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

@@ -1,4 +1,4 @@
-## Standalone Installation on Home-Manager {#ch-standalone-hm}
+# Standalone Installation on Home-Manager {#ch-standalone-hm}
 
 Your built Neovim configuration can be exposed as a flake output to make it
 easier to share across machines, repositories and so on. Or it can be added to

docs/manual/installation/standalone/nixos.md

@@ -1,4 +1,4 @@
-## Standalone Installation on NixOS {#ch-standalone-nixos}
+# Standalone Installation on NixOS {#ch-standalone-nixos}
 
 Your built Neovim configuration can be exposed as a flake output to make it
 easier to share across machines, repositories and so on. Or it can be added to

docs/manual/quirks.md

@@ -5,9 +5,30 @@ be it a result of generating Lua from Nix, or the state of packaging. This page,
 in turn, will list any known modules or plugins that are known to misbehave, and
 possible workarounds that you may apply.
 
-```{=include=}
+## NodeJS {#ch-quirks-nodejs}
-quirks/nodejs.md
+
-```
+### eslint-plugin-prettier {#sec-eslint-plugin-prettier}
+
+When working with NodeJS, everything works as expected, but some projects have
+settings that can fool nvf.
+
+If [this plugin](https://github.com/prettier/eslint-plugin-prettier) or similar
+is included, you might get a situation where your eslint configuration diagnoses
+your formatting according to its own config (usually `.eslintrc.js`).
+
+The issue there is your formatting is made via prettierd.
+
+This results in auto-formatting relying on your prettier config, while your
+eslint config diagnoses formatting
+[which it's not supposed to](https://prettier.io/docs/en/comparison.html))
+
+In the end, you get discrepancies between what your editor does and what it
+wants.
+
+Solutions are:
+
+1. Don't add a formatting config to eslint, and separate prettier and eslint.
+2. PR this repo to add an ESLint formatter and configure nvf to use it.
 
 ## Bugs & Suggestions {#ch-bugs-suggestions}
 
@@ -15,10 +36,10 @@ quirks/nodejs.md
 [discussions tab]: https://github.com/notashelf/nvf/discussions
 [pull requests tab]: https://github.com/notashelf/nvf/pulls
 
-Some quirks are not exactly quirks, but bugs in the module system. If you notice
+Some quirks are not exactly quirks, but bugs in the module systeme. If you
-any issues with **nvf**, or this documentation, then please consider reporting
+notice any issues with nvf, or this documentation, then please consider
-them over at the [issue tracker]. Issues tab, in addition to the
+reporting them over at the [issue tracker]. Issues tab, in addition to the
 [discussions tab] is a good place as any to request new features.
 
-You may also consider submitting bug fixes, feature additions and upstreamed
+You may also consider submitting bugfixes, feature additions and upstreamed
 changes that you think are critical over at the [pull requests tab].

docs/manual/quirks/nodejs.md

@@ -1,29 +0,0 @@
-## NodeJS {#ch-quirks-nodejs}
-
-### eslint-plugin-prettier {#sec-eslint-plugin-prettier}
-
-[eslint-plugin-prettier]: https://github.com/prettier/eslint-plugin-prettier
-[not supposed to]: https://prettier.io/docs/en/comparison.html
-
-When working with NodeJS, which is _obviously_ known for its meticulous
-standards, most things are bound to work as expected but some projects, tools
-and settings may fool the default configurations of tools provided by **nvf**.
-
-If
-
-If [eslint-plugin-prettier] or similar is included, you might get a situation
-where your Eslint configuration diagnoses your formatting according to its own
-config (usually `.eslintrc.js`). The issue there is your formatting is made via
-prettierd.
-
-This results in auto-formatting relying on your prettier configuration, while
-your Eslint configuration diagnoses formatting "issues" while it's
-[not supposed to]. In the end, you get discrepancies between what your editor
-does and what it wants.
-
-Solutions are:
-
-1. Don't add a formatting config to Eslint, instead separate Prettier and
-   Eslint.
-2. PR the repo in question to add an ESLint formatter, and configure **nvf** to
-   use it.

docs/manual/release-notes/rl-0.8.md

@@ -621,3 +621,13 @@
 [JudahZF](https://github.com/JudahZF):
 
 - Added gitFiles mapping option to telescope
+
+[Ring-A-Ding-Ding-Baby](https://github.com/Ring-A-Ding-Ding-Baby)
+
+- Aligned `codelldb` adapter setup with [rustaceanvim]’s built-in logic.
+- Added `languages.rust.dap.backend` option to choose between `codelldb` and
+  `lldb-dap` adapters.
+
+[Libadoxon](https://github.com/Libadoxon)
+
+- `toggleterm` open map now also works when in terminal mode

docs/manual/release-notes/rl-0.9.md

@@ -2,14 +2,9 @@
 
 ## Breaking changes
 
-- Nixpkgs has merged a fully incompatible rewrite of
+- Nixpkgs merged a full and incompatible rewrite of vimPlugins.nvim-treesitter.
-  `vimPlugins.nvim-treesitter`. Namely, it changes from the frozen `master`
+  The changes affected how grammars are built and it caused issues when neovim
-  branch to the new main branch. This change also affects how grammars are
+  attempted to load languages and could not find files in expected locations.
-  built, and forces us to change a few things around.
-  - We must now use `"nvim-treesitter".setup` over the old `.configs`.
-    Additionally, built grammars **no longer include queries by default**,
-    therefore queries not managed by nvf will lack their respective syntax
-    highlighting capabilities.
 
 ## Changelog {#sec-release-0-9-changelog}
 
@@ -20,9 +15,8 @@
 
 [thamenato](https://github.com/thamenato):
 
-- Attempt to adapt nvim-treesitter to (breaking) Nixpkgs changes. Some
+- Attempt to adapt nvim-treesitter to (breaking) Nixpkgs changes. Some treesitte grammars
-  treesitter grammars were changed to prefer `grammarPlugins` over
+  were changed to prefer `grammarPlugins` over `builtGrammars`.
-  `builtGrammars`.
 
 [jfeo](https://github.com/jfeo):
 
@@ -30,13 +24,3 @@
 
 - Added [ccc.nvim] option {option}`vim.utility.ccc.setupOpts` with the existing
   hard-coded options as default values.
-
-[Ring-A-Ding-Ding-Baby](https://github.com/Ring-A-Ding-Ding-Baby):
-
-- Aligned `codelldb` adapter setup with [rustaceanvim]’s built-in logic.
-- Added `languages.rust.dap.backend` option to choose between `codelldb` and
-  `lldb-dap` adapters.
-
-[Libadoxon](https://github.com/Libadoxon):
-
-- `toggleterm` open map now also works when in terminal mode

flake.nix

@@ -57,7 +57,7 @@
 
       perSystem = {pkgs, ...}: {
         # Provides the default formatter for 'nix fmt', which will format the
-        # entire Nix source with Alejandra. The wrapper script is necessary due to
+        # entire tree with Alejandra. The wrapper script is necessary due to
         # changes to the behaviour of Nix, which now encourages wrappers for
         # tree-wide formatting.
         formatter = pkgs.writeShellApplication {
@@ -66,17 +66,11 @@
           runtimeInputs = [
             pkgs.alejandra
             pkgs.fd
-            pkgs.deno
           ];
 
           text = ''
             # Find Nix files in the tree and format them with Alejandra
-            echo "Formatting Nix files"
             fd "$@" -t f -e nix -x alejandra -q '{}'
-
-            # Same for Markdown files, but with deno
-            echo "Formatting Markdown files"
-            fd "$@" -t f -e md -x deno fmt -q '{}'
           '';
         };
 
@@ -87,16 +81,7 @@
           # This can be initiated with `nix build .#checks.<system>.nix-fmt`
           # or with `nix flake check`
           nix-fmt = pkgs.runCommand "nix-fmt-check" {nativeBuildInputs = [pkgs.alejandra];} ''
-            alejandra --check ${self} < /dev/null
+            alejandra --check ${self} < /dev/null | tee $out
-            touch $out
-          '';
-
-          # Check if Markdown sources are properly formatted
-          # This can be initiated with `nix build .#checks.<system>.md-fmt`
-          # or with `nix flake check`
-          md-fmt = pkgs.runCommand "md-fmt-check" {nativeBuildInputs = [pkgs.deno];} ''
-            deno fmt --check ${self} --ext md
-            touch $out
           '';
         };
       };

flake/develop.nix

@@ -1,23 +1,15 @@
 {lib, ...}: {
-  perSystem = {pkgs, ...}: {
+  perSystem = {
-    # The default dev shell provides packages required to interact with
+    pkgs,
-    # the codebase as described by the contributing guidelines. It includes the
+    config,
-    # formatters required, and a few additional goodies for linting work.
+    self',
+    ...
+  }: {
     devShells = {
-      default = pkgs.mkShellNoCC {
+      default = self'.devShells.lsp;
-        packages = with pkgs; [
+      nvim-nix = pkgs.mkShellNoCC {packages = [config.packages.nix];};
-          # Nix tooling
+      lsp = pkgs.mkShellNoCC {
-          nil # LSP
+        packages = with pkgs; [nil statix deadnix alejandra npins];
-          statix # static checker
-          deadnix # dead code finder
-
-          # So that we can interact with plugin sources
-          npins
-
-          # Formatters
-          alejandra
-          deno
-        ];
       };
     };
 
@@ -26,11 +18,7 @@
     # testing, but make sure to discard the changes before creating a pull
     # request.
     packages.dev = let
-      configuration = {
+      configuration = {};
-        # This is essentially the configuration that will be passed to the
-        # builder function. For example:
-        # vim.languages.nix.enable = true;
-      };
 
       customNeovim = lib.nvim.neovimConfiguration {
         inherit pkgs;