Merge 797748a20c into cd81bbb904

.github/workflows/check.yml

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

docs/manual/configuring.md

@@ -3,10 +3,11 @@
 [helpful tips section]: ./tips.html#ch-helpful-tips
 [options reference]: ./options.html
 
-nvf allows for _very_ extensive configuration in Neovim through the Nix module
+**nvf** allows for _very_ extensive configuration in Neovim through the Nix
-interface. The below chapters describe several of the options exposed in nvf for
+module interface. The below chapters describe several of the options exposed in
-your convenience. You might also be interested in the [helpful tips section] for
+nvf for your convenience. You might also be interested in the
-more advanced or unusual configuration options supported by nvf.
+[helpful tips section] for more advanced or unusual configuration options
+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,12 +3,13 @@
 [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 end-user. We
+**nvf** is designed for the developer as much as it is designed for the
-would like for any contributor to be able to propagate their changes, or add new
+end-user. We would like for any contributor to be able to propagate their
-features to the project with minimum possible friction. As such, below are the
+changes, or add new features to the project with minimum possible friction. As
-guides and guidelines written to streamline the contribution process and to
+such, below are the guides and guidelines written to streamline the contribution
-ensure that your valuable input integrates into nvf's development as seamlessly
+process and to ensure that your valuable input integrates into **nvf**'s
-as possible without leaving any question marks in your head.
+development as seamlessly as possible without leaving any question marks in your
+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
@@ -23,24 +24,51 @@ please do not be afraid to submit a pull request, we will help you get it in.
 
 ## Getting Started {#sec-contrib-getting-started}
 
-You, naturally, would like to start by forking the repository to get started. If
+[Fork a repo guide]: https://help.github.com/articles/fork-a-repo/
-you are new to Git and GitHub, do have a look at GitHub's
+[Contributing Guidelines]: #sec-guidelines
-[Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for
+[Create a Pull Request]: https://help.github.com/articles/creating-a-pull-request
-instructions on how you can do this. Once you have a fork of **nvf**, you should
+
-create a separate branch based on the most recent `main` branch. Give your
+To contribute to **nvf**, you'll first want to fork the repository. If you are
-branch a reasonably descriptive name (e.g. `feature/debugger` or
+new to Git and GitHub, do have a look at GitHub's [Fork a repo guide] for
-`fix/pesky-bug`) and you are ready to work on your changes
+instructions on how you can do this. Once your fork is created, you should
+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](#sec-guidelines), push the branch to GitHub and
+[Contributing Guidelines], push the branch to GitHub and [Create a Pull Request]
-[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 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 instroduces 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
@@ -48,34 +76,26 @@ 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 uncertain how these rules affect the change you would like to make
+If you are not quite certain how those rules affect the change you are planning
-then feel free to start a discussion in the
+to make, then please start a friendly discussion in the [discussions tab] before
-[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not
+you begin developing. This is not a requirement, but it might answer some of
-necessarily) before you start developing.
+your burning questions and make the contribution process easier for all parties.
 
-### Adding Documentation {#sec-guidelines-documentation}
+### Formatting {#sec-guidelines-formatting}
 
-[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
+[code style section]: #sec-guidelines-code-style
 
-Almost all changes warrant updates to the documentation: at the very least, you
+There are various files within the **nvf** repository. To maintain a sense of
-must update the changelog. Both the manual and module options use
+consistency and to avoid clashing opinions on how formatters should behave, we
-[Nixpkgs Flavoured Markdown].
+are very opinionated on how those files should be formatted.
 
-The HTML version of this manual containing both the module option descriptions
+- Nix files **must** be formatted with the Alejandra formatter, following some
-and the documentation of **nvf** (such as this page) can be generated and opened
+  specific tips found in [Nix style section](#nix-sec-code-style-nix).
-by typing the following in a shell within a clone of the **nvf** Git repository:
+- Markdown files **must** be formatted with the `deno fmt` command, as described
+  in the [Markdown style section](#sec-code-style-markdown).
 
-```console
+Make sure your code is formatted as described in [code style section] before
-$ nix build .#docs-html
+your changes are submitted.
-$ 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}
 
@@ -98,7 +118,7 @@ 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}
 
 {long description}
@@ -106,19 +126,21 @@ necessarily, follow the given template from home-manager's own documentation
 
 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. As a rare exception,
+`{long description}` is an optional clarifying description.
-if there is no clear component, or your change affects many components, then the
+
-`{component}` part is optional. See
+[example commit message]: #sec-guidelines-ex-commit-message
-[example commit message](#sec-guidelines-ex-commit-message) for a commit message
+
-that fulfills these requirements.
+As a rare exception, if there is no clear component, or your change affects many
+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}
 
-The commit
+[sample commit from Home Manager]: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
-[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
@@ -128,30 +150,63 @@ 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 grammars
+Adds a language module for Ruby, adds appropriate formatters and Treesitter
+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 behind it, for your commit.
+relevant context, i.e., the reasoning for your commit.
 
-Finally, when adding a new module, say `modules/foo.nix`, we use the fixed
+For new plugin additions, the following is a good starting point:
-commit format `foo: add module`. You can, of course, still include a long
-description if you wish.
 
-In case of nested modules, i.e `modules/languages/java.nix` you are recommended
+```gitcommit
-to contain the parent as well - for example `languages/java: some major change`.
+plugin: init
+```
+
+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}
 
-Keep lines at a reasonable width, ideally 80 characters or less. This also
+Across the tree, you're encouraged to follow kebab-case for file names, and keep
-applies to string literals and module descriptions and documentation.
+text files (such as Markdown) to 80 characters or less. This 80 character
+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}
 
@@ -165,12 +220,16 @@ 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
 
@@ -190,23 +249,45 @@ module = {
 }
 ```
 
+<!-- markdownlint-enable MD013 -->
+
 If you move a line down after the merge operator, Alejandra will automatically
-unfold the whole merged attrset for you, which we **do not** want.
+unfold the whole merged attribute set 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
@@ -214,13 +295,13 @@ 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 = [
   item1
   item2
@@ -230,129 +311,161 @@ acceptableList= [
 
 ## Testing Changes {#sec-testing-changes}
 
-Once you have made your changes, you will need to test them thoroughly. If it is
+Once you have made your changes, you will need to test them thoroughly. To make
-a module, add your module option to `configuration.nix` (located in the root of
+testing easier you may either use the `configuration.nix` located in the
-this project) inside `neovimConfiguration`. Enable it, and then run the maximal
+repository root, or use the development package located in `flake/develop.nix`.
-configuration with `nix run .#maximal -Lv` to check for build errors. If neovim
+The development package allows you to quickly bootstrap a Neovim configuration
-opens in the current directory without any error messages (you can check the
+with only the required modules, instead of the packages that consume the
-output of `:messages` inside neovim to see if there are any errors), then your
+`configuration.nix`, so it is generally preferable. To use it navigate to the
-changes are good to go. Open your pull request, and it will be reviewed as soon
+`develop.nix` module, and update the `configuration` set with the Neovim
-as possible.
+configuration that you would like to test with. For example:
-
-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
 {
-  vim.keymaps = [
+  # Let's assume you are adding a new module for the Nix language.
-    {
+  # You will need to enable it here
-      key = "<leader>wq";
+  configuration = {
-      mode = ["n"];
+    vim.languages.nix.enable = true;
-      action = ":wq<CR>";
-      silent = true;
-      desc = "Save file and quit";
-    }
-  ];
-}
-```
 
-There are many settings available in the options. Please refer to the
+    # You can also enable other plugins that you wish to test with, for example
-[documentation](./options.html#option-vim-keymaps) to see a list of them.
+    # none-ls:
-
+    vim.lsp.null-ls = {
-**nvf** provides a helper function, so that you don't have to write the mapping
+      enable = true;
-attribute sets every time:
+      setupOpts = { /* Your setup options here */ };
-
-- `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;})
-    ];
   };
-}
 ```
 
-> [!NOTE]
+You may then run this package with `nix run .#develop` and check for build or
-> If you have come across a plugin that has an API that doesn't seem to easily
+runtime errors. If Neovim builds and opens without any errors, then your changes
-> allow custom keybindings, don't be scared to implement a draft PR. We'll help
+are good to go. Open your pull request, and it will be reviewed as soon as
-> you get it done.
+possible.
+
+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}
 
-There are two methods for adding new Neovim plugins to **nvf**. npins is the
+**nvf** generally tries to avoid using Neovim plugins from Nixpkgs, and thus
-faster option that should be preferred if the plugin consists of pure Lua or
+uses one of the two alternative methods where applicable. npins is the faster
-Vimscript code. In which case there is no building required, and we can easily
+option that should be preferred if the plugin consists of pure Lua or Vimscript
-handle the copying of plugin files. Alternative method, which is required when
+code. In which case there is no building required, and we can easily handle the
-plugins try to build their own libraries (e.g., in Rust or C) that need to be
+copying of plugin files. Alternative method, which is required when plugins try
-built with Nix to function correctly.
+to build their own libraries (e.g., in Rust, C or even Assembly) that need to be
+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 method of adding new plugins to **nvf**. You simply need
+npins is the standard, and as described above, the _faster_ method of adding new
-the repository URL for the plugin, and can add it as a source to be built
+plugins to **nvf**. You simply need the repository URL for the plugin, and you
-automatically with one command. To add a new Neovim plugin, use `npins`. For
+can add it as a source to be built automatically with just one command. To add a
-example:
+new Neovim plugin, use `npins`. For example:
 
 ```bash
 nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
@@ -364,16 +477,13 @@ 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
-Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
+> example
-example
+>
-
+> ```bash
-```bash
+> npins add --name lazydev-nvim github folke lazydev.nvim -b main
-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**.
@@ -399,6 +509,9 @@ 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"
 
@@ -408,6 +521,9 @@ postInstall = ''
     mkdir -p "$out/target"
     mv "$out/lib" "$out/target/release"
   '';
+  
+  # ...
+}
 ```
 
 In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs
@@ -429,7 +545,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({...})`.
 
@@ -503,7 +619,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:
@@ -544,7 +660,7 @@ As you've seen above, `toLuaObject` is used to convert our nix attrSet
    }
    ```
 
-### Lazy plugins {#sec-lazy-plugins}
+### Lazy Loading 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`.
@@ -604,3 +720,104 @@ 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,20 +1,23 @@
 # Introduction {#nvf-manual}
 
-Version @NVF_VERSION@
+Generated for nvf @NVF_VERSION@
 
 ## Preface {#ch-preface}
 
 ### What is nvf {#sec-what-is-it}
 
-**nvf** is a highly modular, configurable, extensible and easy to use Neovim
+[Nix]: https://nixos.org
-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.
 
-## Try it out {#ch-try-it-out}
+**nvf** is a highly modular, configurable, extensible and _easy to use_ Neovim
+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_.
 
-Thanks to the portability of Nix, you can try out nvf without actually
+## Try it Out {#ch-try-it-out}
+
+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:
@@ -27,20 +30,27 @@ 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 Configs {#sec-using-prebuilt-configs}
+## Using Prebuilt Configurations {#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]
@@ -61,7 +71,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.
 
@@ -87,12 +97,16 @@ companion or fun plugins.
 
 ## Installing nvf {#ch-installation}
 
+<!-- markdownlint-disable MD051 -->
+
 [module installation section]: #ch-module-installation
 
-There are multiple ways of installing nvf on your system. You may either choose
+<!-- markdownlint-enable MD051 -->
-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
+There are multiple ways of installing **nvf** on your system. You may either
-modules for NixOS and home-manager as described in the
+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].
 
 ```{=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 are
+To install **nvf** with flakes, you must make sure the following requirements
-met.
+are 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,5 +29,6 @@ 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,30 +5,9 @@ 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.
 
-## NodeJS {#ch-quirks-nodejs}
+```{=include=}
-
+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}
 
@@ -36,9 +15,9 @@ Solutions are:
 [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 systeme. If you
+Some quirks are not exactly quirks, but bugs in the module system. If you notice
-notice any issues with nvf, or this documentation, then please consider
+any issues with **nvf**, or this documentation, then please consider reporting
-reporting them over at the [issue tracker]. Issues tab, in addition to the
+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

docs/manual/quirks/nodejs.md

@@ -0,0 +1,29 @@
+## 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,9 +621,3 @@
 [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.

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

@@ -0,0 +1,9 @@
+# Release 0.5 {#sec-release-0-9}
+
+## Changelog {#sec-release-0-9-changelog}
+
+[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.

flake.nix

@@ -57,7 +57,7 @@
 
       perSystem = {pkgs, ...}: {
         # Provides the default formatter for 'nix fmt', which will format the
-        # entire tree with Alejandra. The wrapper script is necessary due to
+        # entire Nix source 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,11 +66,17 @@
           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 '{}'
           '';
         };
 
@@ -81,7 +87,16 @@
           # 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 | tee $out
+            alejandra --check ${self} < /dev/null
+            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,15 +1,23 @@
 {lib, ...}: {
-  perSystem = {
+  perSystem = {pkgs, ...}: {
-    pkgs,
+    # The default dev shell provides packages required to interact with
-    config,
+    # the codebase as described by the contributing guidelines. It includes the
-    self',
+    # formatters required, and a few additional goodies for linting work.
-    ...
-  }: {
     devShells = {
-      default = self'.devShells.lsp;
+      default = pkgs.mkShellNoCC {
-      nvim-nix = pkgs.mkShellNoCC {packages = [config.packages.nix];};
+        packages = with pkgs; [
-      lsp = pkgs.mkShellNoCC {
+          # Nix tooling
-        packages = with pkgs; [nil statix deadnix alejandra npins];
+          nil # LSP
+          statix # static checker
+          deadnix # dead code finder
+
+          # So that we can interact with plugin sources
+          npins
+
+          # Formatters
+          alejandra
+          deno
+        ];
       };
     };
 
@@ -18,7 +26,11 @@
     # 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;