Most, if not all, changes warrant changes to the documentation. Module options should be documented with Nixpkgs-flavoured Markdown, albeit with exceptions.

The HTML version of this manual containing both the module option descriptions and the documentation of neovim-flake (such as this page) can be generated and opened by typing the following in a shell within a clone of the neovim-flake Git repository:

$ nix build .#docs-html
$ xdg-open $PWD/result/share/doc/neovim-flake/index.html

Make sure your code is formatted as described in code-style section. To maintain consistency throughout the project you are encouraged to browse through existing code and adopt its style also in new code.

Similar to code style guidelines we encourage a consistent commit message format as described in commit style guidelines.

The commits in your pull request should be reasonably self-contained. Which means each and every commit in a pull request should make sense both on its own and in general context. That is, a second commit should not resolve an issue that is introduced in an earlier commit. In particular, you will be asked to amend any commit that introduces syntax errors or similar problems even if they are fixed in a later commit.

The commit messages should follow the seven rules, except for “Capitalize the subject line”. We also ask you to include the affected code component or module in the first line. A commit message ideally, but not necessarily, follow the given template from home-manager’s own documentation

  {component}: {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. 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.

The commit 69f8e47e9e74c8d3d060ca22e18246b7f7d988ef contains the commit message

starship: allow running in Emacs if vterm is used

The vterm buffer is backed by libvterm and can handle Starship prompts
without issues.

Long description can be ommitted if the change is too simple to warrant it. A minor fix in spelling or a formatting change does not warrant long description, however, a module addition or removal does as you would like to provide the relevant context for your changes.

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.

In case of nested modules, i.e modules/languages/java.nix you are recommended to contain the parent as well - for example languages/java: some major change.

Treewide Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals and module descriptions and documentation.

Nix neovim-flake is formatted by the alejandra tool and the formatting is checked in the pull request and push workflows. Run the nix fmt command inside the project repository before submitting your pull request.

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.

Please use one line code for attribute sets that contain only one subset. For example:

# parent modules should always be unfolded
# which means module = { value = ... } instead of module.value = { ... }
module = {
  value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible

    # same as parent modules, unfold submodules
    subModule = {
        # this is an option that contains more than one nested value
        someOtherValue = mkOption {
            type = lib.types.bool;
            description = "Some other description";
            default = true;
        };
    };
}

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.

module = {
  key = mkEnableOption "some description" // {
    default = true; # we want this to be inline
  }; # ...
}

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.

# this is ok

acceptableList = [
  item1 # comment
  item2
  item3 # some other comment
  item4
];

# this is not ok
listToBeAvoided = [item1 item2 /* comment */ item3 item4];

# this is ok
acceptableList = [item1];

# this is not ok
listToBeAvoided = [
  item1
];

To set a mapping, you should define it in vim.maps.<<mode>>. The available modes are:

An example, simple keybinding, can look like this:

{
  vim.maps.normal = {
    "<leader>wq" = {
      action = ":wq<CR>";
      silent = true;
      desc = "Save file and quit";
    };
  };
}

There are many settings available in the options. Please refer to the documentation to see a list of them.

neovim-flake provides a list of helper commands, so that you don’t have to write the mapping attribute sets every time:

Note that the Lua in these bindings is actual Lua, not pasted into a :lua command. Therefore, you either pass in a function like require('someplugin').some_function, without actually calling it, or you define your own function, like function() require('someplugin').some_function() end.

Additionally, to not have to repeat the descriptions, there’s another utility function with its own set of functions:

Utility function that takes two attrsets:

and merges them into { someKey = { value = "some_value"; description = "Some Description"; }; }

addDescriptionsToMappings = actualMappings: mappingDefinitions:

This function can be used in combination with the same mkBinding functions as above, except they only take two arguments - binding and action, and have different names:

You can read the source code of some modules to see them in action, but their usage should look something like this:

# plugindefinition.nix
{lib, ...}: with lib; {
  options.vim.plugin = {
    enable = mkEnableOption "Enable plugin";

    # Mappings should always be inside an attrset called mappings
    mappings = {
      # mkMappingOption is a helper function from lib,
      # that takes a description (which will also appear in which-key),
      # and a default mapping (which can be null)
      toggleCurrentLine = mkMappingOption "Toggle current line comment" "gcc";
      toggleCurrentBlock = mkMappingOption "Toggle current block comment" "gbc";

      toggleOpLeaderLine = mkMappingOption "Toggle line comment" "gc";
      toggleOpLeaderBlock = mkMappingOption "Toggle block comment" "gb";

      toggleSelectedLine = mkMappingOption "Toggle selected comment" "gc";
      toggleSelectedBlock = mkMappingOption "Toggle selected block" "gb";
    };

  };
}

# config.nix
{
  pkgs,
  config,
  lib,
  ...
}:
  with lib;
  with builtins; let
    cfg = config.vim.plugin;
    self = import ./plugindefinition.nix {inherit lib;};
    mappingDefinitions = self.options.vim.plugin;

    # addDescriptionsToMappings is a helper function from lib,
    # that merges mapping values and their descriptions
    # into one nice attribute set
    mappings = addDescriptionsToMappings cfg.mappings mappingDefinitions;
in {
  config = mkIf (cfg.enable) {
    # ...
    vim.maps.normal = mkMerge [
      # mkSetBinding is another helper function from lib,
      # that actually adds the mapping with a description.
      (mkSetBinding mappings.findFiles "<cmd> Telescope find_files<CR>")
      (mkSetBinding mappings.liveGrep "<cmd> Telescope live_grep<CR>")
      (mkSetBinding mappings.buffers "<cmd> Telescope buffers<CR>")
      (mkSetBinding mappings.helpTags "<cmd> Telescope help_tags<CR>")
      (mkSetBinding mappings.open "<cmd> Telescope<CR>")

      (mkSetBinding mappings.gitCommits "<cmd> Telescope git_commits<CR>")
      (mkSetBinding mappings.gitBufferCommits "<cmd> Telescope git_bcommits<CR>")
      (mkSetBinding mappings.gitBranches "<cmd> Telescope git_branches<CR>")
      (mkSetBinding mappings.gitStatus "<cmd> Telescope git_status<CR>")
      (mkSetBinding mappings.gitStash "<cmd> Telescope git_stash<CR>")

      (mkIf config.vim.lsp.enable (mkMerge [
        (mkSetBinding mappings.lspDocumentSymbols "<cmd> Telescope lsp_document_symbols<CR>")
        (mkSetBinding mappings.lspWorkspaceSymbols "<cmd> Telescope lsp_workspace_symbols<CR>")

        (mkSetBinding mappings.lspReferences "<cmd> Telescope lsp_references<CR>")
        (mkSetBinding mappings.lspImplementations "<cmd> Telescope lsp_implementations<CR>")
        (mkSetBinding mappings.lspDefinitions "<cmd> Telescope lsp_definitions<CR>")
        (mkSetBinding mappings.lspTypeDefinitions "<cmd> Telescope lsp_type_definitions<CR>")
        (mkSetBinding mappings.diagnostics "<cmd> Telescope diagnostics<CR>")
      ]))

      (
        mkIf config.vim.treesitter.enable
        (mkSetBinding mappings.treesitter "<cmd> Telescope treesitter<CR>")
      )
    ];
    # ...
  };
}