Merge 72634c2603 into 6670d752c7

* docs: re-format README; clean up sections

* docs: update README with features section

.github/CONTRIBUTING.md

@@ -16,7 +16,7 @@ If you have any questions regarding those files, feel free to open an issue or [
 
 ## Contributing
 
-The contribution process is mostly documented in the [pull request template](.github/pull_request_template.md). You will find a checklist of items to complete before submitting a pull request. Please make sure you complete it before submitting a pull request. If you are unsure about any of the items, please ask.
+The contribution process is mostly documented in the [pull request template](pull_request_template.md). You will find a checklist of items to complete before submitting a pull request. Please make sure you complete it before submitting a pull request. If you are unsure about any of the items, please ask.
 
 ### Guidelines
 

.github/README.md

@@ -33,10 +33,9 @@
 
 <div align="center">
   <a>
-    A highly modular, configurable, extensible and easy to use Neovim configuration 
-    framework in Nix. Designed for flexibility and ease of use, this flake 
-    allows you to easily configure your Neovim instance with a few lines of 
-    Nix code.
+    nvf is a highly modular, configurable, extensible and easy to use Neovim configuration
+    in Nix. Designed for flexibility and ease of use, nvf allows you to easily configure
+    your fully featured Neovim instance with a few lines of Nix.
   </a>
 </div>
 
@@ -44,6 +43,7 @@
 
 <div align="center"><p>
 
+[Features]: #features
 [Get Started]: #get-started
 [Documentation]: #documentation
 [Help]: #help
@@ -51,119 +51,150 @@
 [FAQ]: #faq
 [Credits]: #credits
 
-**[<kbd> <br> Get Started <br> </kbd>][Get Started]**
-**[<kbd> <br> Documentation <br> </kbd>][Documentation]**
-**[<kbd> <br> Help <br> </kbd>][Help]**
-**[<kbd> <br> Contribute <br> </kbd>][Contribute]**
-**[<kbd> <br> FAQ <br> </kbd>][Faq]**
-**[<kbd> <br> Credits <br> </kbd>][Credits]**
+**[<kbd><br> Features <br></kbd>][Features]**
+**[<kbd><br> Get Started <br></kbd>][Get Started]**
+**[<kbd><br> Documentation <br></kbd>][Documentation]**
+**[<kbd><br> Help <br></kbd>][Help]**
+**[<kbd><br> Contribute <br></kbd>][Contribute]**
+**[<kbd><br> FAQ <br></kbd>][Faq]** **[<kbd><br> Credits <br></kbd>][Credits]**
 
 </p></div>
 
 ---
 
+## Features
+
+- **Reproducible**: Your configuration will behave the same _anywhere_. No
+  surprises, promise!
+- **Portable**: nvf depends _solely_ on your Nix store, and nothing else. No
+  more global binaries! Works on all platforms, without hassle.
+- **Customizable**: There are _almost no defaults_ to annoy you. nvf is fully
+  customizable through the Nix module system.
+- **Well-documented**: Documentation is priority. You will _never_ face
+  undocumented, obscure behaviour.
+- **Idiomatic**: nvf does things ✨ _the right way_ ✨ - the codebase is, and
+  will, remain maintainable for myself and any contributors.
+
 ## Get Started
 
-### Using `nix` CLI
+[nvf manual]: https://notashelf.github.io/nvf/
+[issue tracker]: https://github.com/NotAShelf/nvf/issues
 
-If you would like to try out the configuration before even thinking about
-installing it, you can run the following command
+If you are not sold on the concepts of **nvf**, and would like to try out the
+default configuration before even _thinking about_ installing it, you may run
+the following in order to take **nvf** out for a spin.
 
-```console
+```bash
+# Run the default package
 nix run github:notashelf/nvf
 ```
 
-This will get you a feel for the base configuration and UI design.
-The flake exposes `#nix` as the default package, providing minimal
-language support and various utilities.You may also use `#nix`,
-`#tidal` or `#maximal` to get try out different configurations.
+This will get you a feel for the base configuration and UI design. Though, none
+of the configuration options are final as **nvf** is designed to be modular and
+configurable.
 
-It is as simple as changing the target output to get a different
-configuration. For example, to get a configuration with `tidal` support, run:
+> [!TIP]
+> The flake exposes `#nix` as the default package, providing minimal language
+> support and various utilities. You may also use the `#nix` or `#maximal`
+> packages provided by the this flake to get try out different configurations.
 
-```console
-nix run github:notashelf/nvf#tidal
+It is as simple as changing the target output to get a different configuration.
+For example, to get a configuration with large language coverage, run:
+
+```bash
+# Run the maximal package
+nix run github:notashelf/nvf#maximal
 ```
 
 Similar instructions will apply for `nix profile install`. However, you are
 recommended to instead use the module system as described in the manual.
 
-> [!NOTE]  
-> The `maximal` configuration is _massive_ and will take a while to build.
-> To get a feel for the configuration, use the default `nix` or `tidal`
-> configurations. Should you choose to try out the `maximal` configuration,
-> using the binary cache as described in the manual is _strongly_ recommended.
+> [!NOTE]
+> The `maximal` configuration is quite large, and might take a while to build.
+> To get a feel for the configuration, use the default `nix` configuration.
+> Should you choose to try out the `maximal` configuration, using the binary
+> cache as described in the manual is _strongly_ recommended.
+
+If you are convinced, proceed to the next section to view the installation
+instructions.
 
 ## Documentation
 
-See the [**nvf** Manual](https://notashelf.github.io/nvf/) for
-detailed installation guides, configurations, available options, release notes
-and more. Tips for installing userspace plugins is also contained in the
-documentation.
+The _recommended_ way of installing **nvf** is using either the NixOS or the
+Home-Manager module, though it is completely possible and no less supported to
+install **nvf** as a standalone package, or a flake output.
 
-If you want to dive right into trying **nvf** you can get a fully
-featured configuration with `nix` language support by running:
+See the [**nvf** manual] for detailed and up-to-date installation guides,
+configurations, available options, release notes and more. Tips for installing
+userspace plugins is also contained in the documentation.
 
-```console
-nix run github:notashelf/nvf#nix
-```
-
-[Issues]: https://github.com/NotAShelf/nvf/issues
-
-Please create an issue on the [issue tracker](issues) if you find
-the documentation lacking or confusing. I also appreciate any contributions
-to the documentation.
+Please create an issue on the [issue tracker] if you find the documentation
+lacking or confusing. Any improvements to the documentation through pull
+requests are also welcome, and appreciated.
 
 ## Help
 
-You can create an issue on the [issue tracker](issues) to ask questions
-or report bugs. I am not yet on spaces like matrix or IRC, so please use the issue
-tracker for now.
+You can create an issue on the [issue tracker] to ask questions or report bugs.
+I am not yet on spaces like matrix or IRC, so please use the issue tracker for
+now.
 
 ## Contributing
 
 I am always looking for new ways to help improve this flake. If you would like
 to contribute, please read the [contributing guide](CONTRIBUTING.md) before
-submitting a pull request. You can also create an issue on the
-[issue tracker](issues) before submitting a pull request if you would
-like to discuss a feature or bug fix.
+submitting a pull request. You can also create an issue on the [issue tracker]
+before submitting a pull request if you would like to discuss a feature or bug
+fix.
 
 ## FAQ
 
+[appropriate issue template]: https://github.com/NotAShelf/nvf/issues/new/choose
+[list of branches]: https://github.com/NotAShelf/nvf/branches
+[list of open pull requests]: https://github.com/NotAShelf/nvf/pulls
+
+**Q**: What platforms are supported?
+<br/> **A**: nvf actively supports Linux and Darwin platforms using standalone
+Nix, NixOS or Home-Manager. Please take a look at the
+
 **Q**: Can you add _X_?
-<br/>
-**A**: Maybe! It is not one of our goals to support each and every Neovim
-plugin, however, I am always open to new modules and plugin setup additions
-to **nvf**. Use the [appropritate issue template](issues/new/choose) and I will
-consider a module addition.
+<br/> **A**: Maybe! It is not one of our goals to support each and every Neovim
+plugin, however, I am always open to new modules and plugin setup additions to
+**nvf**. Use the [appropriate issue template] and I will consider a module
+addition. As mentioned before, PRs adding new features are also welcome.
 
 **Q**: A plugin I need is not available in **nvf**. What to do?
-<br/>
-**A**: **nvf** exposes several APIs for you to be able to add your own
-plugin configurations! Please see the documentation on how you may do
-this.
+<br/> **A**: **nvf** exposes several APIs for you to be able to add your own
+plugin configurations! Please see the documentation on how you may do this.
 
 **Q**: Main branch is awfully silent, is the project dead?
-<br/>
-**A**: No! Sometimes we branch out (e.g. v0.6) to avoid breaking userspace
-and work in a separate branch until we make sure the new additions are
-implemented in the most comfortable way available to the end user. If you have
-not noticed any activity on the main branch, consider taking a look at the [list
-of branches](https://github.com/NotAShelf/nvf/branches=) or the [list of open
-pull requests](https://github.com/NotAShelf/nvf)
+<br/> **A**: No! Sometimes we branch out (e.g. `v0.6`) to avoid breaking
+userspace and work in a separate branch until we make sure the new additions are
+implemented in the most comfortable way possible for the end user. If you have
+not noticed any activity on the main branch, consider taking a look at the
+[list of branches] or the [list of open pull requests]. You may also consider
+_testing_ those release branches to get access to new features ahead of time and
+better prepare to breaking changes.
 
 ## Credits
 
 ### Contributors
 
-Special thanks to
+Special, heart-felt thanks to
 
 - [@fufexan](https://github.com/fufexan) - For the transition to flake-parts
-- [@FlafyDev](https://github.com/FlafyDev) - For getting the home-manager to work
-- [@n3oney](https://github.com/n3oney) - For making custom keybinds finally possible
-- [@horriblename](https://github.com/horriblename) - For actively implementing planned features and quality of life updates
+- [@FlafyDev](https://github.com/FlafyDev) - For getting the home-manager to
+  work
+- [@n3oney](https://github.com/n3oney) - For making custom keybinds finally
+  possible
+- [@horriblename](https://github.com/horriblename) - For actively implementing
+  planned features and quality of life updates
 - [@Yavko](https://github.com/Yavko) - For the amazing **nvf** logo
-- [@FrothyMarrow](https://github.com/FrothyMarrow) - For seeing mistakes that I could not
+- [@FrothyMarrow](https://github.com/FrothyMarrow) - For seeing mistakes that I
+  could not
+- [@Diniamo](https://github.com/Diniamo) - For actively submitting PRs, pull
+  requests and overall assistence
+- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, mnw and
+  occasional code improvements
 
 and everyone who has submitted issues or pull requests!
 
@@ -172,10 +203,18 @@ and everyone who has submitted issues or pull requests!
 This configuration borrows from and is based on a few other configurations,
 including:
 
-- [@jordanisaacs's](https://github.com/jordanisaacs) [neovim-flake](https://github.com/jordanisaacs/neovim-flake) that this flake is originally based on.
-- [@sioodmy's](https://github.com/sioodmy) [dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design choices.
-- [@wiltaylor's](https://github.com/wiltaylor) [neovim-flake](https://github.com/wiltaylor/neovim-flake) for plugin and design ideas.
-- [@gvolpe's](https://github.com/gvolpe) [neovim-flake](https://github.com/gvolpe/neovim-flake) for plugin, design and nix concepts.
+- [@jordanisaacs's](https://github.com/jordanisaacs)
+  [neovim-flake](https://github.com/jordanisaacs/neovim-flake) that this flake
+  is originally based on.
+- [@sioodmy's](https://github.com/sioodmy)
+  [dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design
+  choices.
+- [@wiltaylor's](https://github.com/wiltaylor)
+  [neovim-flake](https://github.com/wiltaylor/neovim-flake) for plugin and
+  design ideas.
+- [@gvolpe's](https://github.com/gvolpe)
+  [neovim-flake](https://github.com/gvolpe/neovim-flake) for plugin, design and
+  nix concepts.
 
 I am grateful for their previous work and inspiration, and I wholeheartedly
 recommend checking their work out.
@@ -183,11 +222,14 @@ recommend checking their work out.
 
 ## License
 
-Following the license of the [original neovim-flake](https://github.com/jordanisaacs/neovim-flake),
-**nvf** has been made available under the [**MIT License**](LICENSE). However, all assets
-and documentation are published under the 
+Following the license of the
+[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), **nvf**
+has been made available under the [**MIT License**](LICENSE). However, all
+assets and documentation are published under the
 [**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE).
 
+<h6 align="center">Yes, this includes the logo work too. Stop taking artwork that is not yours!</h6>
+
 ---
 
 <div align="right">

.github/workflows/cleanup.yml

@@ -0,0 +1,22 @@
+name: Cleanup
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 1 * *" # 4AM on 1st of every month
+    - cron: "0 4 15 * *" # 4AM on the 15th of every month
+jobs:
+  branches:
+    name: Cleanup old branches
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Delete old branches"
+        uses: beatlabs/delete-old-branches-action@v0.0.10
+        with:
+          repo_token: "${{ secrets.GITHUB_TOKEN }}"
+          date: "1 months ago"
+          dry_run: false
+          delete_tags: false
+          exclude_open_pr_branches: true

configuration.nix

@@ -19,6 +19,7 @@ isMaximal: {
       lspsaga.enable = false;
       trouble.enable = true;
       lspSignature.enable = true;
+      otter-nvim.enable = isMaximal;
       lsplines.enable = isMaximal;
       nvim-docs-view.enable = isMaximal;
     };
@@ -155,7 +156,7 @@ isMaximal: {
     };
 
     utility = {
-      ccc.enable = isMaximal;
+      ccc.enable = false;
       vim-wakatime.enable = false;
       icon-picker.enable = isMaximal;
       surround.enable = isMaximal;

docs/manual/configuring/dag-entries.md

@@ -5,16 +5,19 @@ can add code that relies on other code. However, if you don't know what the
 entries are called, it's hard to do that, so here is a list of the internal
 entries in nvf:
 
-`vim.luaConfigRC` (top-level DAG):
+## `vim.luaConfigRC` (top-level DAG) {#ch-vim-luaconfigrc}
 
 1. (`luaConfigPre`) - not a part of the actual DAG, instead, it's simply
    inserted before the rest of the DAG
 2. `globalsScript` - used to set globals defined in `vim.globals`
 3. `basic` - used to set basic configuration options
-4. `theme` (this is simply placed before `pluginConfigs`, meaning that surrounding entries don't depend on it) - used to set up the theme, which has to be done before other plugins
-5. `pluginConfigs` - the result of the nested `vim.pluginRC` (internal option,
-   see the [Custom Plugins](/index.xhtml#ch-custom-plugins) page for adding your own
-   plugins) DAG, used to set up internal plugins
-6. `extraPluginConfigs` - the result of `vim.extraPlugins`, which is not a
+4. `optionsScript` - used to set options defined in `vim.o`
+5. `theme` (this is simply placed before `pluginConfigs`, meaning that
+   surrounding entries don't depend on it) - used to set up the theme, which has
+   to be done before other plugins
+6. `pluginConfigs` - the result of the nested `vim.pluginRC` (internal option,
+   see the [Custom Plugins](/index.xhtml#ch-custom-plugins) page for adding your
+   own plugins) DAG, used to set up internal plugins
+7. `extraPluginConfigs` - the result of `vim.extraPlugins`, which is not a
    direct DAG, but is converted to, and resolved as one internally
-7. `mappings` - the result of `vim.maps`
+8. `mappings` - the result of `vim.maps`

docs/release-notes/rl-0.7.md

@@ -26,6 +26,28 @@ making good use of its extensive Lua API. Additionally, Vimscript is slow and
 brings unnecessary performance overhead while working with different
 configuration formats.
 
+### `vim.maps` rewrite {#sec-vim-maps-rewrite}
+
+Instead of specifying map modes using submodules (eg.: `vim.maps.normal`), a new
+`mode` option has mode has been introduced. It can be either a string, or a list
+of strings, where a string represents the short-name of the map mode(s), that
+the mapping should be set for. See `:help map-modes` for more information.
+
+For example:
+
+```nix
+vim.maps.normal."<leader>m" = { ... };
+```
+
+has to be replaced by
+
+```nix
+vim.maps."<leader>m" = {
+  mode = "n";
+  ...
+};
+```
+
 ### `vim.lsp.nvimCodeActionMenu` removed in favor of `vim.ui.fastaction` {#sec-nvim-code-action-menu-deprecation}
 
 The nvim-code-action-menu plugin has been archived and broken for a long time,
@@ -37,6 +59,7 @@ Note that we are looking to add more alternatives in the future like
 dressing.nvim and actions-preview.nvim, in case fastaction doesn't work for
 everyone.
 
+
 ## Changelog {#sec-release-0.7-changelog}
 
 [ItsSorae](https://github.com/ItsSorae):
@@ -132,6 +155,8 @@ everyone.
     has been introduced for setting up internal plugins. See the "DAG entries in
     nvf" manual page for more information.
 
+- Rewrite `vim.maps`, see the breaking changes section above.
+
 [NotAShelf](https://github.com/notashelf):
 
 [ts-error-translator.nvim]: https://github.com/dmmulroy/ts-error-translator.nvim
@@ -187,6 +212,12 @@ everyone.
 - Add [python-lsp-server](https://github.com/python-lsp/python-lsp-server) as an
   additional Python LSP server.
 
+- Add [](#opt-vim.options) to set `vim.o` values in in your nvf configuration
+  without using additional Lua. See option documentation for more details.
+
+- Add [](#opt-vim.dashboard.dashboard-nvim.setupOpts) to allow user
+  configuration for [dashboard.nvim](https://github.com/nvimdev/dashboard-nvim)
+
 [ppenguin](https://github.com/ppenguin):
 
 - Telescope:
@@ -196,3 +227,5 @@ everyone.
 [Soliprem](https://github.com/Soliprem)
 
 - Add LSP and Treesitter support for R under `vim.languages.R`.
+- Add Otter support under `vim.lsp.otter` and an assert to prevent conflict with
+  ccc

flake.lock

@@ -1405,6 +1405,22 @@
         "type": "github"
       }
     },
+    "plugin-otter-nvim": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1724585935,
+        "narHash": "sha256-euHwoK2WHLF/hrjLY2P4yGrIbYyBN38FL3q4CKNZmLY=",
+        "owner": "jmbuhr",
+        "repo": "otter.nvim",
+        "rev": "ca9ce67d0399380b659923381b58d174344c9ee7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "jmbuhr",
+        "repo": "otter.nvim",
+        "type": "github"
+      }
+    },
     "plugin-oxocarbon": {
       "flake": false,
       "locked": {
@@ -1895,6 +1911,7 @@
         "plugin-obsidian-nvim": "plugin-obsidian-nvim",
         "plugin-onedark": "plugin-onedark",
         "plugin-orgmode-nvim": "plugin-orgmode-nvim",
+        "plugin-otter-nvim": "plugin-otter-nvim",
         "plugin-oxocarbon": "plugin-oxocarbon",
         "plugin-plenary-nvim": "plugin-plenary-nvim",
         "plugin-project-nvim": "plugin-project-nvim",

flake.nix

@@ -13,8 +13,8 @@
       inherit inputs;
       specialArgs = {inherit lib;};
     } {
-      # provide overridable systems
-      # https://github.com/nix-systems/nix-systems
+      # Allow users to bring their own systems.
+      # «https://github.com/nix-systems/nix-systems»
       systems = import inputs.systems;
       imports = [
         ./flake/apps.nix
@@ -62,7 +62,6 @@
         pkgs,
         ...
       }: {
-        formatter = pkgs.alejandra;
         devShells = {
           default = self'.devShells.lsp;
           nvim-nix = pkgs.mkShell {packages = [config.packages.nix];};
@@ -70,6 +69,21 @@
             packages = with pkgs; [nil statix deadnix alejandra];
           };
         };
+
+        # Provide the default formatter. `nix fmt` in project root
+        # will format available files with the correct formatter.
+        # P.S: Please do not format with nixfmt! It messes with many
+        # syntax elements and results in unreadable code.
+        formatter = pkgs.alejandra;
+
+        # Check if codebase is properly formatted.
+        # This can be initiated with `nix build .#checks.<system>.nix-fmt`
+        # or with `nix flake check`
+        checks = {
+          nix-fmt = pkgs.runCommand "nix-fmt-check" {nativeBuildInputs = [pkgs.alejandra];} ''
+            alejandra --check ${self} < /dev/null | tee $out
+          '';
+        };
       };
     };
 
@@ -156,6 +170,11 @@
       flake = false;
     };
 
+    plugin-otter-nvim = {
+      url = "github:jmbuhr/otter.nvim";
+      flake = false;
+    };
+
     # Language support
     plugin-sqls-nvim = {
       url = "github:nanotee/sqls.nvim";

modules/neovim/mappings/config.nix

@@ -8,45 +8,26 @@
   cfg = config.vim;
 in {
   config = {
-    vim.maps = {
-      normal = mkIf cfg.disableArrows {
-        "<up>" = {
-          action = "<nop>";
-
-          noremap = false;
-        };
-        "<down>" = {
-          action = "<nop>";
-
-          noremap = false;
-        };
-        "<left>" = {
-          action = "<nop>";
-          noremap = false;
-        };
-        "<right>" = {
-          action = "<nop>";
-          noremap = false;
-        };
+    vim.maps = mkIf cfg.disableArrows {
+      "<up>" = {
+        mode = ["n" "i"];
+        action = "<nop>";
+        noremap = false;
       };
-
-      insert = mkIf cfg.disableArrows {
-        "<up>" = {
-          action = "<nop>";
-          noremap = false;
-        };
-        "<down>" = {
-          action = "<nop>";
-          noremap = false;
-        };
-        "<left>" = {
-          action = "<nop>";
-          noremap = false;
-        };
-        "<right>" = {
-          action = "<nop>";
-          noremap = false;
-        };
+      "<down>" = {
+        mode = ["n" "i"];
+        action = "<nop>";
+        noremap = false;
+      };
+      "<left>" = {
+        mode = ["n" "i"];
+        action = "<nop>";
+        noremap = false;
+      };
+      "<right>" = {
+        mode = ["n" "i"];
+        action = "<nop>";
+        noremap = false;
       };
     };
   };

modules/neovim/mappings/options.nix

@@ -1,61 +1,52 @@
 {lib, ...}: let
   inherit (lib.options) mkOption;
-  inherit (lib.types) bool str attrsOf nullOr submodule;
+  inherit (lib.types) either str listOf attrsOf nullOr submodule bool;
   inherit (lib.nvim.config) mkBool;
-  # Most of the keybindings code is highly inspired by pta2002/nixvim.
-  # Thank you!
+
   mapConfigOptions = {
-    silent =
-      mkBool false
-      "Whether this mapping should be silent. Equivalent to adding <silent> to a map.";
-
-    nowait =
-      mkBool false
-      "Whether to wait for extra input on ambiguous mappings. Equivalent to adding <nowait> to a map.";
-
-    script =
-      mkBool false
-      "Equivalent to adding <script> to a map.";
-
-    expr =
-      mkBool false
-      "Means that the action is actually an expression. Equivalent to adding <expr> to a map.";
-
-    unique =
-      mkBool false
-      "Whether to fail if the map is already defined. Equivalent to adding <unique> to a map.";
-
-    noremap =
-      mkBool true
-      "Whether to use the 'noremap' variant of the command, ignoring any custom mappings on the defined action. It is highly advised to keep this on, which is the default.";
-
     desc = mkOption {
       type = nullOr str;
       default = null;
       description = "A description of this keybind, to be shown in which-key, if you have it enabled.";
     };
+
+    action = mkOption {
+      type = str;
+      description = "The command to execute.";
+    };
+    lua = mkBool false ''
+      If true, `action` is considered to be lua code.
+      Thus, it will not be wrapped in `""`.
+    '';
+
+    silent = mkBool true "Whether this mapping should be silent. Equivalent to adding <silent> to a map.";
+    nowait = mkBool false "Whether to wait for extra input on ambiguous mappings. Equivalent to adding <nowait> to a map.";
+    script = mkBool false "Equivalent to adding <script> to a map.";
+    expr = mkBool false "Means that the action is actually an expression. Equivalent to adding <expr> to a map.";
+    unique = mkBool false "Whether to fail if the map is already defined. Equivalent to adding <unique> to a map.";
+    noremap = mkBool true "Whether to use the 'noremap' variant of the command, ignoring any custom mappings on the defined action. It is highly advised to keep this on, which is the default.";
   };
 
-  mapOption = submodule {
+  mapType = submodule {
     options =
       mapConfigOptions
       // {
-        action = mkOption {
-          type = str;
-          description = "The action to execute.";
-        };
-
-        lua = mkOption {
-          type = bool;
+        mode = mkOption {
+          type = either str (listOf str);
           description = ''
-            If true, `action` is considered to be lua code.
-            Thus, it will not be wrapped in `""`.
+            The short-name of the mode to set the keymapping for. Passing an empty string is the equivalent of `:map`.
+
+            See `:help map-modes` for a list of modes.
           '';
-          default = false;
         };
       };
   };
 
+  # legacy stuff
+  mapOption = submodule {
+    options = mapConfigOptions;
+  };
+
   mapOptions = mode:
     mkOption {
       description = "Mappings for ${mode} mode";
@@ -66,6 +57,7 @@ in {
   options.vim = {
     maps = mkOption {
       type = submodule {
+        freeformType = attrsOf mapType;
         options = {
           normal = mapOptions "normal";
           insert = mapOptions "insert";
@@ -82,15 +74,11 @@ in {
         };
       };
       default = {};
-      description = ''
-        Custom keybindings for any mode.
-
-        For plain maps (e.g. just 'map' or 'remap') use `maps.normalVisualOp`.
-      '';
-
+      description = "Custom keybindings.";
       example = ''
         maps = {
-          normal."<leader>m" = {
+          "<leader>m" = {
+            mode = "n";
             silent = true;
             action = "<cmd>make<CR>";
           }; # Same as nnoremap <leader>m <silent> <cmd>make<CR>

modules/plugins/dashboard/dashboard-nvim/config.nix

@@ -5,16 +5,17 @@
 }: let
   inherit (lib.modules) mkIf;
   inherit (lib.nvim.dag) entryAnywhere;
+  inherit (lib.nvim.lua) toLuaObject;
 
   cfg = config.vim.dashboard.dashboard-nvim;
 in {
   config = mkIf cfg.enable {
-    vim.startPlugins = [
-      "dashboard-nvim"
-    ];
+    vim = {
+      startPlugins = ["dashboard-nvim"];
 
-    vim.pluginRC.dashboard-nvim = entryAnywhere ''
-      require("dashboard").setup{}
-    '';
+      pluginRC.dashboard-nvim = entryAnywhere ''
+        require("dashboard").setup(${toLuaObject cfg.setupOpts})
+      '';
+    };
   };
 }

modules/plugins/dashboard/dashboard-nvim/dashboard-nvim.nix

@@ -1,7 +1,9 @@
 {lib, ...}: let
   inherit (lib.options) mkEnableOption;
+  inherit (lib.nvim.types) mkPluginSetupOption;
 in {
   options.vim.dashboard.dashboard-nvim = {
     enable = mkEnableOption "Fancy and Blazing Fast start screen plugin of neovim [dashboard.nvim]";
+    setupOpts = mkPluginSetupOption "dashboard.nvim" {};
   };
 }

modules/plugins/languages/ts.nix

@@ -226,7 +226,7 @@ in {
         {
           assertion = cfg.lsp.enable -> cfg.lsp.server != "tsserver";
           message = ''
-            As of a recent lspconfig update, he `tsserver` configuration has been renamed
+            As of a recent lspconfig update, the `tsserver` configuration has been renamed
             to `ts_ls` to match upstream behaviour of `lspconfig`, and the name `tsserver`
             is no longer considered valid by nvf. Please set `vim.languages.ts.lsp.server`
             to `"ts_ls"` instead of to `${cfg.lsp.server}`

modules/plugins/lsp/default.nix

@@ -13,6 +13,7 @@
     ./trouble
     ./lsp-signature
     ./lightbulb
+    ./otter
     ./lspkind
     ./lsplines
     ./nvim-docs-view

modules/plugins/lsp/otter/config.nix

@@ -0,0 +1,39 @@
+{
+  config,
+  lib,
+  ...
+}: let
+  inherit (lib.modules) mkIf mkMerge;
+  inherit (lib.nvim.dag) entryAnywhere;
+  inherit (lib.nvim.lua) toLuaObject;
+  inherit (lib.nvim.binds) addDescriptionsToMappings mkSetBinding;
+
+  cfg = config.vim.lsp;
+
+  self = import ./otter.nix {inherit lib;};
+  mappingDefinitions = self.options.vim.lsp.otter-nvim.mappings;
+  mappings = addDescriptionsToMappings cfg.otter-nvim.mappings mappingDefinitions;
+in {
+  config = mkIf (cfg.enable && cfg.otter-nvim.enable) {
+    assertions = [
+      {
+        assertion = !config.vim.utility.ccc.enable;
+        message = ''
+          ccc and otter have a breaking conflict. It's been reported upstream. Until it's fixed, disable one of them
+        '';
+      }
+    ];
+    vim = {
+      startPlugins = ["otter-nvim"];
+
+      maps.normal = mkMerge [
+        (mkSetBinding mappings.toggle "<cmd>lua require'otter'.activate()<CR>")
+      ];
+
+      pluginRC.otter-nvim = entryAnywhere ''
+        -- Enable otter diagnostics viewer
+        require("otter").setup({${toLuaObject cfg.otter-nvim.setupOpts}})
+      '';
+    };
+  };
+}

modules/plugins/lsp/otter/default.nix

@@ -0,0 +1,6 @@
+{
+  imports = [
+    ./otter.nix
+    ./config.nix
+  ];
+}

modules/plugins/lsp/otter/otter.nix

@@ -0,0 +1,64 @@
+{lib, ...}: let
+  inherit (lib.options) mkOption mkEnableOption;
+  inherit (lib.nvim.binds) mkMappingOption;
+  inherit (lib.types) bool str listOf;
+  inherit (lib.nvim.types) mkPluginSetupOption;
+in {
+  options.vim.lsp = {
+    otter-nvim = {
+      enable = mkEnableOption ''
+        lsp features and a code completion source for code embedded in other documents [otter-nvim]
+      '';
+      mappings = {
+        toggle = mkMappingOption "Activate LSP on Cursor Position [otter-nvim]" "<leader>lo";
+      };
+      setupOpts = mkPluginSetupOption "otter.nvim" {
+        lsp = {
+          diagnostic_update_event = mkOption {
+            type = listOf str;
+            default = ["BufWritePost"];
+            description = ''
+              `:h events` that cause the diagnostic to update.
+              Set to: {"BufWritePost", "InsertLeave", "TextChanged" }
+              for less performant but more instant diagnostic updates
+            '';
+          };
+        };
+        buffers = {
+          set_filetype = mkOption {
+            type = bool;
+            default = false;
+            description = ''
+              if set to true, the filetype of the otterbuffers will be set. Other wide only
+              the autocommand of lspconfig that attaches the language server will be
+              executed without stting the filetype
+            '';
+          };
+          write_to_disk = mkOption {
+            type = bool;
+            default = false;
+            description = ''
+              write <path>.otter.<embedded language extension> files to disk on save of main buffer.
+              Useful for some linters that require actual files.
+              Otter files are deleted on quit or main buffer close
+            '';
+          };
+        };
+        strip_wrapping_quote_characters = mkOption {
+          type = listOf str;
+          default = ["'" ''"'' "`"];
+          description = ''
+          '';
+        };
+        handle_leading_whitespace = mkOption {
+          type = bool;
+          default = false;
+          description = ''
+            otter may not work the way you expect when entire code blocks are indented
+            (eg. in Org files) When true, otter handles these cases fully.
+          '';
+        };
+      };
+    };
+  };
+}

modules/wrapper/rc/config.nix

@@ -3,87 +3,22 @@
   lib,
   ...
 }: let
-  inherit (builtins) map mapAttrs filter;
-  inherit (lib.options) mkOption;
-  inherit (lib.attrsets) mapAttrsToList filterAttrs getAttrs attrValues attrNames;
+  inherit (builtins) map mapAttrs filter removeAttrs attrNames;
+  inherit (lib.attrsets) mapAttrsToList filterAttrs attrsToList;
   inherit (lib.strings) concatLines concatMapStringsSep;
   inherit (lib.trivial) showWarnings;
-  inherit (lib.types) str nullOr;
   inherit (lib.generators) mkLuaInline;
   inherit (lib.nvim.dag) entryAfter mkLuarcSection resolveDag entryAnywhere;
   inherit (lib.nvim.lua) toLuaObject;
-  inherit (lib.nvim.config) mkBool;
 
   cfg = config.vim;
-
-  # Most of the keybindings code is highly inspired by pta2002/nixvim.
-  # Thank you!
-  mapConfigOptions = {
-    silent =
-      mkBool false
-      "Whether this mapping should be silent. Equivalent to adding <silent> to a map.";
-
-    nowait =
-      mkBool false
-      "Whether to wait for extra input on ambiguous mappings. Equivalent to adding <nowait> to a map.";
-
-    script =
-      mkBool false
-      "Equivalent to adding <script> to a map.";
-
-    expr =
-      mkBool false
-      "Means that the action is actually an expression. Equivalent to adding <expr> to a map.";
-
-    unique =
-      mkBool false
-      "Whether to fail if the map is already defined. Equivalent to adding <unique> to a map.";
-
-    noremap =
-      mkBool true
-      "Whether to use the 'noremap' variant of the command, ignoring any custom mappings on the defined action. It is highly advised to keep this on, which is the default.";
-
-    desc = mkOption {
-      type = nullOr str;
-      default = null;
-      description = "A description of this keybind, to be shown in which-key, if you have it enabled.";
-    };
-  };
-
-  genMaps = mode: maps: let
-    /*
-    Take a user-defined action (string or attrs) and return the following attribute set:
-    {
-      action = (string) the actual action to map to this key
-      config = (attrs) the configuration options for this mapping (noremap, silent...)
-    }
-    */
-    normalizeAction = action: {
-      # Extract the values of the config options that have been explicitly set by the user
-      config =
-        filterAttrs (_: v: v != null)
-        (getAttrs (attrNames mapConfigOptions) action);
-      action =
-        if action.lua
-        then mkLuaInline action.action
-        else action.action;
-    };
-  in
-    attrValues (mapAttrs
-      (key: action: let
-        normalizedAction = normalizeAction action;
-      in {
-        inherit (normalizedAction) action config;
-        inherit key;
-        inherit mode;
-      })
-      maps);
 in {
   config = let
-    filterNonNull = attrs: filterAttrs (_: value: value != null) attrs;
     globalsScript =
-      mapAttrsToList (name: value: "vim.g.${name} = ${toLuaObject value}")
-      (filterNonNull cfg.globals);
+      mapAttrsToList (name: value: "vim.g.${name} = ${toLuaObject value}") cfg.globals;
+
+    optionsScript =
+      mapAttrsToList (name: value: "vim.o.${name} = ${toLuaObject value}") cfg.options;
 
     extraPluginConfigs = resolveDag {
       name = "extra plugin configs";
@@ -97,46 +32,60 @@ in {
       mapResult = result: concatLines (map mkLuarcSection result);
     };
 
-    toLuaBindings = mode: maps:
-      map (value: ''
-        vim.keymap.set(${toLuaObject mode}, ${toLuaObject value.key}, ${toLuaObject value.action}, ${toLuaObject value.config})
-      '') (genMaps mode maps);
+    getAction = keymap:
+      if keymap.lua
+      then mkLuaInline keymap.action
+      else keymap.action;
 
-    # I'm not sure if every one of these will work.
-    allmap = toLuaBindings "" config.vim.maps.normalVisualOp;
-    nmap = toLuaBindings "n" config.vim.maps.normal;
-    vmap = toLuaBindings "v" config.vim.maps.visual;
-    xmap = toLuaBindings "x" config.vim.maps.visualOnly;
-    smap = toLuaBindings "s" config.vim.maps.select;
-    imap = toLuaBindings "i" config.vim.maps.insert;
-    cmap = toLuaBindings "c" config.vim.maps.command;
-    tmap = toLuaBindings "t" config.vim.maps.terminal;
-    lmap = toLuaBindings "l" config.vim.maps.lang;
-    omap = toLuaBindings "o" config.vim.maps.operator;
-    icmap = toLuaBindings "ic" config.vim.maps.insertCommand;
+    getOpts = keymap: {
+      inherit (keymap) desc silent nowait script expr unique noremap;
+    };
 
-    maps = [
-      nmap
-      imap
-      vmap
-      xmap
-      smap
-      cmap
-      omap
-      tmap
-      lmap
-      icmap
-      allmap
-    ];
-    mappings = concatLines (map concatLines maps);
+    toLuaKeymap = {
+      name,
+      value,
+    }: "vim.keymap.set(${toLuaObject value.mode}, ${toLuaObject name}, ${toLuaObject (getAction value)}, ${toLuaObject (getOpts value)})";
+
+    namedModes = {
+      "normal" = ["n"];
+      "insert" = ["i"];
+      "select" = ["s"];
+      "visual" = ["v"];
+      "terminal" = ["t"];
+      "normalVisualOp" = ["n" "v" "o"];
+      "visualOnly" = ["n" "x"];
+      "operator" = ["o"];
+      "insertCommand" = ["i" "c"];
+      "lang" = ["l"];
+      "command" = ["c"];
+    };
+
+    maps =
+      removeAttrs cfg.maps (attrNames namedModes)
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.normal;}) cfg.maps.normal
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.insert;}) cfg.maps.insert
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.select;}) cfg.maps.select
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.visual;}) cfg.maps.visual
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.terminal;}) cfg.maps.terminal
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.normalVisualOp;}) cfg.maps.normalVisualOp
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.visualOnly;}) cfg.maps.visualOnly
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.operator;}) cfg.maps.operator
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.insertCommand;}) cfg.maps.insertCommand
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.lang;}) cfg.maps.lang
+      // mapAttrs (_: legacyMap: legacyMap // {mode = namedModes.command;}) cfg.maps.command;
+
+    keymaps = concatLines (map toLuaKeymap (attrsToList (filterAttrs (_: value: value != null) maps)));
   in {
     vim = {
       luaConfigRC = {
+        # `vim.g` and `vim.o`
         globalsScript = entryAnywhere (concatLines globalsScript);
-        # basic
-        pluginConfigs = entryAfter ["basic"] pluginConfigs;
+        optionsScript = entryAfter ["basic"] (concatLines optionsScript);
+
+        # Basic
+        pluginConfigs = entryAfter ["optionsScript"] pluginConfigs;
         extraPluginConfigs = entryAfter ["pluginConfigs"] extraPluginConfigs;
-        mappings = entryAfter ["extraPluginConfigs"] mappings;
+        mappings = entryAfter ["extraPluginConfigs"] keymaps;
       };
 
       builtLuaConfigRC = let

modules/wrapper/rc/options.nix

@@ -129,16 +129,38 @@ in {
     globals = mkOption {
       type = attrs;
       default = {};
+      example = {"some_variable" = 42;};
       description = ''
         An attribute set containing global variable values
         for storing vim variables as early as possible. If
         populated, this option will set vim variables in the
         built luaConfigRC as the first item.
 
-        E.g. {foo = "bar"} will set `vim.g.foo` to "bar" where
-        the type of `bar` in the resulting vimscript will be
-        infered from the type of the value in the `{name = value}`
-        pair.
+        ::: {.note}
+        `{foo = "bar";}` will set `vim.g.foo` to "bar", where
+        the type of `bar` in the resulting Lua value will be
+        inferred from the type of the value in the `{name = value;}`
+        pair passed to the option.
+        :::
+      '';
+    };
+
+    options = mkOption {
+      type = attrs;
+      default = {};
+      example = {visualbell = true;};
+      description = ''
+        An attribute set containing vim options to be set
+        as early as possible. If populated, this option will
+        set vim options in the built luaConfigRC after `basic`
+        and before `pluginConfigs` DAG entries.
+
+        ::: {.note}
+        `{foo = "bar";}` will set `vim.o.foo` to "bar", where
+        the type of `bar` in the resulting Lua value will be
+        inferred from the type of the value in the`{name = value;}`
+        pair passed to the option.
+        :::
       '';
     };