### Install NVF without Flakes using fetchTarball

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/modules/home-manager.md

Instructions for installing NVF on a system not using flakes, utilizing `builtins.fetchTarball` to get the repository. Remember to manually update the URL and hash for dependency management.

```nix
# home.nix
let
  nvf = import (builtins.fetchTarball {
    url = "https://github.com/notashelf/nvf/archive/<commit or tag>.tar.gz";
    # Optionally, you can add 'sha256' for verification and caching
    # sha256 = "<sha256>";
  });
in {
  imports = [
    # Import the NixOS module from your fetched input
    nvf.homeManagerModules.nvf
  ];

  # Once the module is imported, you may use `programs.nvf` as exposed by the
  # NixOS module.
  programs.nvf.enable = true;
}
```

--------------------------------

### Configure Plugin with Manual Setup

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/tips/plugin-sources.md

For plugins requiring manual setup, use `vim.extraPlugins`. This allows specifying the package and a setup function to be called.

```nix
{
  vim.extraPlugins = {
    aerial = {
      package = pkgs.vimPlugins.aerial-nvim;
      setup = "require('aerial').setup {}";
    };
  };
}
```

--------------------------------

### Configure NVF Settings with Home Manager

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/modules/home-manager.md

Example configuration for the `programs.nvf` option within your Home Manager setup. This enables NVF and configures specific Vim settings like aliases and LSP.

```nix
{
  programs.nvf = {
    enable = true;
    # your settings need to go into the settings attribute set
    # most settings are documented in the appendix
    settings = {
      vim.viAlias = false;
      vim.vimAlias = true;
      vim.lsp = {
        enable = true;
      };
    };
  };
}
```

--------------------------------

### Example Home Manager Flake Configuration

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/modules/home-manager.md

A complete example of a `flake.nix` file demonstrating how to integrate NVF with Home Manager. This includes setting up inputs and configuring the home manager output.

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    nvf.url = "github:notashelf/nvf";
  };

  outputs = { nixpkgs, home-manager, nvf, ... }:
    {
    # ↓ this is your home output in the flake schema, expected by home-manager
    "your-username@your-hostname" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        nvf.homeManagerModules.default # <- this imports the home-manager module that provides the options
        ./home.nix # <- your home entrypoint, `programs.nvf.*` may be defined here
      ];
    };
  };
}
```

--------------------------------

### Configure plugin setup options

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

In your plugin's config file, use `mkPluginSetupOption` to generate Lua configuration for the plugin's setup function, converting Nix options to Lua objects.

```nix
# in modules/.../your-plugin/config.nix
{lib, config, ...}:
let
  cfg = config.vim.your-plugin;
in {
  vim.luaConfigRC = lib.nvim.dag.entryAnywhere ''
    require('plugin-name').setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
  '';
}
```

--------------------------------

### Example NixOS configuration with Flakes

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/modules/nixos.md

A complete example of how to set up nvf within a NixOS flake configuration. This includes defining inputs and importing the nvf module.

```nix
{ 
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nvf.url = "github:notashelf/nvf";
  };

  outputs = { nixpkgs, nvf, ... }: { 
    # ↓ this is your host output in the flake schema
    nixosConfigurations."your-hostname" = nixpkgs.lib.nixosSystem { 
      modules = [ 
        nvf.nixosModules.default # <- this imports the NixOS module that provides the options
        ./configuration.nix # <- your host entrypoint, `programs.nvf.*` may be defined here
      ];
    };
  };
}
```

--------------------------------

### Example Standalone Neovim Flake Configuration

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/custom-configuration.md

An example flake that exposes a custom Neovim configuration using `neovimConfiguration`. This setup allows running Neovim with `nix run` and sharing the configuration.

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nvf.url = "github:notashelf/nvf";
  };

  outputs = {nixpkgs, ...} @ inputs:
    {
      packages.x86_64-linux = {
        # Set the default package to the wrapped instance of Neovim.
        # This will allow running your Neovim configuration with
        # `nix run` and in addition, sharing your configuration with
        # other users in case your repository is public.
        default =
          (inputs.nvf.lib.neovimConfiguration {
            pkgs = nixpkgs.legacyPackages.x86_64-linux;
            modules = [
              {
                config.vim = {
                  # Enable custom theming options
                  theme.enable = true;

                  # Enable Treesitter
                  treesitter.enable = true;

                  # Other options will go here. Refer to the config
                  # reference in Appendix B of the nvf manual.
                  # ...
                };
              }
            ];
          })
          .neovim;
      };
    };
}
```

--------------------------------

### Lazy Loading a Plugin with vim.lazy.plugins

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Shows how to configure a plugin for lazy loading using `vim.lazy.plugins`. This example specifies package, setup module, options, and triggers like events and commands.

```nix
# in modules/.../your-plugin/config.nix
{
  config,
  pkgs,
}: let
  cfg = config.vim.your-plugin;
in {
  vim.lazy.plugins.your-plugin = {
    # Instead of vim.startPlugins, use this:
    package = "your-plugin";

    # ıf your plugin uses the `require('your-plugin').setup{...}` pattern
    setupModule = "your-plugin";
    inherit (cfg) setupOpts;

    # Events that trigger this plugin to be loaded
    event = ["DirChanged"];
    cmd = ["YourPluginCommand"];

    # Plugin Keymaps
    keys = [
      # We'll cover this in detail in the 'keybinds' section
      {
        key = "<leader>d";
        mode = "n";
        action = ":YourPluginCommand";
      }
    ];
  };
}
```

--------------------------------

### Run Default nvf Package

Source: https://github.com/notashelf/nvf/blob/main/README.md

Execute the default nvf package using Nix to get a feel for the base configuration and UI design without installation.

```bash
# Run the default package
$ nix run github:notashelf/nvf
```

--------------------------------

### Define modular plugin setup options

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Use `mkPluginSetupOption` to define modular setup options for a plugin. This allows users to configure features and add custom fields.

```nix
# in modules/.../your-plugin/your-plugin.nix

{lib, ...}:
let
  inherit (lib.types) bool int;
  inherit (lib.nvim.types) mkPluginSetupOption;
in {
  options.vim.your-plugin = {
    setupOpts = mkPluginSetupOption "plugin name" {
      enable_feature_a = mkOption {
        type = bool;
        default = false;
        # ...
      };

      number_option = mkOption {
        type = int;
        default = 3;
        # ...
      };
    };
  };
}
```

--------------------------------

### Configure Custom LSP Server with `vim.lsp.servers`

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/languages/lsp.md

Modify existing LSP definitions or register custom LSPs using the `vim.lsp.servers` submodule. This example shows how to get a language server from PATH and define a new custom LSP entry with its command, filetypes, and root markers.

```nix
{lib, ...}:
{
  vim.lsp.servers = {
    # Get `basedpyright-langserver` from PATH, e.g., a dev shell.
    basedpyright.cmd = lib.mkForce ["basedpyright-langserver" "--stdio"];

    # Define a custom LSP entry using `vim.lsp.servers`:
    ty = {
      cmd = lib.mkDefault [(lib.getExe pkgs.ty) "server"];
      filetypes = ["python"];
      root_markers = [
        ".git"
        "pyproject.toml"
        "setup.cfg"
        "requirements.txt"
        "Pipfile"
        "pyrightconfig.json"
      ];

    # If your LSP accepts custom settings. See `:help lsp-config` for more details
    # on available fields. This is a freeform field.
    settings.ty = { /* ... */ };
  };
}
```

--------------------------------

### Add Plugin from Nixpkgs Registry

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/tips/plugin-sources.md

Use `vim.startPlugins` to load plugins directly from Nixpkgs. This is suitable for plugins that do not require specific setup or ordering.

```nix
{pkgs, ...}:
{
  # Aerial does require some setup. In the case you pass a plugin that *
does* require manual setup, then you must also call the setup function.
  vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
}
```

--------------------------------

### User configuration for plugin setup options

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Users can customize plugin setup options in their own configuration, overriding defaults and adding new fields, including nested ones.

```nix
# in user's config
{
  vim.your-plugin.setupOpts = {
    enable_feature_a = true;
    number_option = 4;
    another_field = "hello";
    size = { # nested fields work as well
      top = 10;
    };
  };
}
```

--------------------------------

### Nix to Lua Conversion Example

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Illustrates the conversion of Nix attribute sets and lists to their Lua counterparts.

```nix
{ _type = "lua-inline";
 expr = "function add(a, b) return a + b end";
}
```

--------------------------------

### Configure Lazy-Loading Plugin with setupOpts

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/custom-plugins/configuring.md

Use `config.vim.lazy.plugins.*.setupOpts` for lazy-loading plugins that require a setup table. The `setupModule` and `setupOpt` can be used if the plugin follows a `require('module').setup(...)` pattern. The `after` hook can be used for custom logic.

```nix
{
  config.vim.lazy.plugins = {
    "aerial.nvim" = {
    # ^^^^^^^^^ this name should match the package.pname or package.name
      package = aerial-nvim;

      setupModule = "aerial";
      setupOpts = {option_name = false;};

      after = "print('aerial loaded')";
    };
  };
}
```

--------------------------------

### Non-Flake Installation of NVF

Source: https://context7.com/notashelf/nvf/llms.txt

Installs NVF using `builtins.fetchTarball` for traditional Nix configurations without flakes. Ensure to replace `<sha256-of-release-tarball>` with the actual hash.

```nix
let nvf = import (builtins.fetchTarball { url = "https://github.com/notashelf/nvf/archive/v0.9.tar.gz"; sha256 = "<sha256-of-release-tarball>"; }); in { imports = [ nvf.nixosModules.nvf ]; # or nvf.homeManagerModules.nvf programs.nvf = { enable = true; settings.vim = { lsp.enable = true; languages.nix.enable = true; }; }; } # Tip: use npins or niv to automatically track updates and manage sha256 hashes
```

--------------------------------

### Install npins

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Install the npins tool to manage Neovim plugins. Use `nix-shell` for traditional environments or `nix shell` with flakes.

```bash
nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
```

--------------------------------

### Basic Lua Configuration Example

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/tips/pure-lua-config.md

A simple Lua configuration snippet that sets a keymap and defines the mapleader. This can be placed in a file like ~/.config/nvf/lua/myconfig/init.lua.

```lua
-- init.lua
vim.keymap.set("n", " ", "<Nop>", { silent = true, remap = false })
vim.g.mapleader = " "
```

--------------------------------

### Testing Nix Configuration Changes

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Example of how to configure Neovim modules for testing within a Nix development environment. This allows for quick bootstrapping of specific configurations.

```nix
{
  # Let's assume you are adding a new module for the Nix language.
  # You will need to enable it here
  configuration = {
    vim.languages.nix.enable = true;

    # You can also enable other plugins that you wish to test with, for example
    # none-ls:
    vim.lsp.null-ls = {
      enable = true;
      setupOpts = { /* Your setup options here */ };
    };
  };
}
```

--------------------------------

### Install nvf without Flakes using fetchTarball

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/modules/nixos.md

Install nvf on a NixOS system without using flakes by fetching the repository archive directly. This requires manual updates for the URL and hash.

```nix
# configuration.nix
let
  nvf = import (builtins.fetchTarball {
    url = "https://github.com/notashelf/nvf/archive/<commit or tag>.tar.gz";
    # Optionally, you can add 'sha256' for verification and caching
    # sha256 = "<sha256>";
  });
in {
  imports = [
    # Import the NixOS module from your fetched input
    nvf.nixosModules.nvf
  ];

  # Once the module is imported, you may use `programs.nvf` as exposed by the
  # NixOS module.
  programs.nvf.enable = true;
}
```

--------------------------------

### Generated Lua plugin setup

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

This Lua script is generated from the Nix configuration, showing how the plugin is set up with its options.

```lua
require('plugin-name').setup({
  enable_feature_a = false,
  number_option = 3,
})
```

--------------------------------

### Configure Custom LSP Package with a List of Strings

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/languages/lsp.md

Use a list of strings to specify the command for launching a custom LSP server. This method allows the LSP API to discover servers from your PATH, bypassing automatic installation.

```nix
vim.languages.java = {
  lsp = {
    enable = true;

    # This expects 'jdt-language-server' to be in your PATH or in
    # 'vim.extraPackages.' There are no additional checks performed to see
    # if the command provided is valid.
    package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
  };
}
```

--------------------------------

### Configure Plugins with Standard API

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/custom-plugins/configuring.md

Utilize `vim.extraPlugins` to configure plugins using an attribute set. This allows specifying the plugin package, the setup code, and the order of execution relative to other plugins.

```nix
{pkgs, ...}:
{
  config.vim.extraPlugins = {
    aerial = {
      package = pkgs.vimPlugins.aerial-nvim;
      setup = "require('aerial').setup {}";
    };

    harpoon = {
      package = pkgs.vimPlugins.harpoon;
      setup = "require('harpoon').setup {}";
      after = ["aerial"]; # place harpoon configuration after aerial
    };
  };
}
```

--------------------------------

### Integrate Pure Lua Configuration

Source: https://context7.com/notashelf/nvf/llms.txt

Add custom directories to Neovim's runtime path for `require()` access to hand-written Lua modules. The path must be version-controlled for purity. This example adds a local `nvim` directory.

```nix
# Project layout:
#   flake.nix
#   nvim/
#     lua/
#       myconfig/
#         init.lua      ← vim.keymap, options, etc.
#         plugins.lua   ← manual plugin setup

{
  config.vim = {
    additionalRuntimePaths = [
      ./nvim   # added to &runtimepath; Lua in nvim/lua/ becomes require()-able
    ];

    startPlugins = [pkgs.vimPlugins.gitsigns-nvim];

    luaConfigRC.load-myconfig = /* lua */ ''
      -- Load hand-written Lua config
      require("myconfig")

      -- Plugin setup that depends on the Lua config above
      require("gitsigns").setup({ current_line_blame = true })
    '';
  };
}
# For impure usage: place files under ~/.config/nvf/lua/ (NVIM_APPNAME="nvf")
# then require them via vim.luaConfigRC without additionalRuntimePaths

```

--------------------------------

### Adding Custom Neovim Plugins with NVF

Source: https://context7.com/notashelf/nvf/llms.txt

Integrates third-party Neovim plugins not included by default in NVF. Plugins can be configured with setup functions and ordered using the `after` attribute.

```nix
{ config.vim.extraPlugins = { # Plugin loaded and configured unconditionally at startup aerial = { package = pkgs.vimPlugins.aerial-nvim; setup = "require('aerial').setup { layout = { max_width = { 40, 0.2 } } }"; }; # Plugin loaded after aerial (DAG ordering) harpoon = { package = pkgs.vimPlugins.harpoon; setup = '' local mark = require('harpoon.mark') local ui = require('harpoon.ui') require('harpoon').setup {} vim.keymap.set('n', '<leader>a', mark.add_file) vim.keymap.set('n', '<C-e>', ui.toggle_quick_menu) ''; after = ["aerial"]; # harpoon config runs after aerial config }; }; }
```

--------------------------------

### Lazy Loading an Arbitrary Plugin

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/custom-plugins/lazy-method.md

Configure a plugin to be lazy-loaded by setting `lazy = true` and defining triggers like commands, events, or keymaps. This example shows how to configure `aerial.nvim`.

```nix
{ config.vim.lazy.plugins = {
    "aerial.nvim" = {
      package = pkgs.vimPlugins.aerial-nvim;
      setupModule = "aerial";
      setupOpts = {
        option_name = true;
      };
      after = ''
        -- custom lua code to run after plugin is loaded
        print('aerial loaded')
      '';

      # Explicitly mark plugin as lazy. You don't need this if you define one of
      # the trigger "events" below
      lazy = true;

      # load on command
      cmd = ["AerialOpen"];

      # load on event
      event = ["BufEnter"];

      # load on keymap
      keys = [
        {
          key = "<leader>a";
          action = ":AerialToggle<CR>";
        }
      ];
    };
  };
}
```

--------------------------------

### Reference Pinned Plugin in Nix Module

Source: https://context7.com/notashelf/nvf/llms.txt

Reference a pinned plugin within a Nix module. This example shows how to add 'aerial-nvim' to the list of started plugins.

```nix
# modules/plugins/filetree/aerial/aerial.nix
# config.vim.startPlugins = ["aerial-nvim"];
```

--------------------------------

### Nix Flake for Standalone Neovim Installation

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/standalone/nixos.md

Define a Nix flake to package your Neovim configuration, making it available as a standalone output. This example enables the default theme and shows how to integrate custom configurations.

```nix
{ 
  inputs = { 
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    nvf.url = "github:notashelf/nvf";
  };

  outputs = { 
    nixpkgs, 
    nvf, 
    self, 
    ...
  }: { 
    # This will make the package available as a flake output under 'packages'
    packages.x86_64-linux.my-neovim = 
      (nvf.lib.neovimConfiguration { 
        pkgs = nixpkgs.legacyPackages.x86_64-linux;
        modules = [ 
          # Or move this to a separate file and add it's path here instead
          # IE: ./nvf_module.nix
          (
            {pkgs, ...}: { 
              # Add any custom options (and do feel free to upstream them!)
              # options = { ... };
              config.vim = { 
                theme.enable = true;
                # and more options as you see fit...
              };
            }
          )
        ];
      })
      .neovim;

    # Example nixosConfiguration using the configured Neovim package
    nixosConfigurations = { 
      yourHostName = nixpkgs.lib.nixosSystem { 
        # ...
        modules = [ 
          # This will make wrapped neovim available in your system packages
          # Can also move this to another config file if you pass your own
          # inputs/self around with specialArgs
          ({pkgs, ...}: { 
            environment.systemPackages = [self.packages.${pkgs.stdenv.hostPlatform.system}.my-neovim];
          })
        ];
        # ...
      };
    };
  };
}

```

--------------------------------

### Using mkMappingOption for Plugin Keymaps

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Demonstrates how to use the `mkMappingOption` helper function to define keymaps for a plugin. This abstracts the repetitive structure of mapping definitions.

```nix
# pluginDefinition.nix
{
  lib,
  config,
}: let
  inherit (lib.options) mkEnableOption;
  inherit (config.vim.lib) 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";
    };
  }
}
```

--------------------------------

### Run Prebuilt nvf Configurations

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/index.md

Run the 'nix' or 'maximal' prebuilt configurations of nvf.

```bash
$ nix run github:notashelf/nvf#nix
$ nix run github:notashelf/nvf#maximal
```

--------------------------------

### Run Maximal Configuration with Specific File

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/index.md

Open a file with the maximal configuration, which supports more languages and includes additional plugins. Be aware this downloads many dependencies.

```bash
$ nix run github:notashelf/nvf#maximal -- test.nix
# => This will open a file called `test.nix` with a variety of plugins available
```

--------------------------------

### Build nvf Documentation Locally

Source: https://context7.com/notashelf/nvf/llms.txt

Build the HTML documentation for nvf locally using `nix build`. After building, open the generated `index.html` to view the documentation.

```bash
# Build documentation locally
nix build github:notashelf/nvf#docs-html
xdg-open ./result/share/doc/index.html
```

--------------------------------

### Run Minimal nvf Configuration with Cache

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/index.md

Optional: Add the nvf cache to save CPU resources and time. Then, run the default minimal configuration.

```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
```

--------------------------------

### Reference an npins-added plugin

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

After adding a plugin with npins, reference it as a string in your nvf configuration to include it in your Neovim setup.

```nix
{ 
  config.vim.startPlugins = ["lazydev-nvim"];
}
```

--------------------------------

### Run Nix Configuration with Specific File

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/index.md

Open a file with the Nix configuration, which provides LSP/diagnostic support for Nix and utility plugins.

```bash
$ nix run github:notashelf/nvf#nix test.nix
# => This will open a file called `test.nix` with Nix LSP and syntax highlighting
```

--------------------------------

### Define Autocommands with Lua Callback

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/autocmds.md

Configure an autocommand to execute a Lua function after a Lua file is saved. This example uses `vim.notify` for feedback.

```nix
{
  vim.augroups = [ { name = "UserSetup"; } ];

  vim.autocmds = [
    # Example 1: Using a Lua callback
    {
      event = [ "BufWritePost" ];
      pattern = [ "*.lua" ];
      group = "UserSetup";
      desc = "Notify after saving Lua file";
      callback = lib.generators.mkLuaInline ''
        function()
          vim.notify("Lua file saved!", vim.log.levels.INFO)
        end
      '';
    }
  ];
}
```

--------------------------------

### Flake Configuration for NVF

Source: https://context7.com/notashelf/nvf/llms.txt

Integrates NVF into a Nix flake setup for Neovim. Ensures NVF's modules are available for Home Manager configuration.

```nix
{ inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; home-manager.url = "github:nix-community/home-manager"; nvf.url = "github:notashelf/nvf"; }; outputs = { nixpkgs, home-manager, nvf, ... }: { homeConfigurations."alice@workstation" = home-manager.lib.homeManagerConfiguration { pkgs = nixpkgs.legacyPackages.x86_64-linux; modules = [ nvf.homeManagerModules.default # provides programs.nvf.* ./home.nix ]; }; }; }
```

--------------------------------

### Add Plugin to Runtime with Legacy Method

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/custom-plugins/legacy-method.md

Use `vim.startPlugins` to add a Neovim plugin package to the runtime. This accepts strings for internal plugins or package inputs for external ones.

```nix
{pkgs, ...}:
{
  # Add a Neovim plugin from Nixpkgs to the runtime.
  # This does not need to come explicitly from packages. 'vim.startPlugins'
  # takes a list of *string* (to load internal plugins) or *package* to load
  # a Neovim package from any source.
  vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
}
```

--------------------------------

### Add Binary Cache with Cachix

Source: https://context7.com/notashelf/nvf/llms.txt

Add the nvf binary cache to your system using Cachix. This is recommended for faster installations, especially for the 'maximal' configuration.

```bash
# Add binary cache (optional but strongly recommended for maximal)
cachix use nvf
```

--------------------------------

### Configure nvf settings in NixOS

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/installation/modules/nixos.md

Configure nvf options using the `programs.nvf` attribute set in your NixOS configuration. This example enables aliases and LSP.

```nix
{
  programs.nvf = {
    enable = true;
    # Your settings need to go into the settings attribute set
    # most settings are documented in the appendix
    settings = {
      vim.viAlias = false;
      vim.vimAlias = true;
      vim.lsp = {
        enable = true;
      };
    };
  };
}
```

--------------------------------

### Defining Custom Keymaps with vim.keymaps

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Example of defining a custom keymap using the `vim.keymaps` option. This sets a specific key combination to execute a command silently.

```nix
{
  vim.keymaps = [
    {
      key = "<leader>wq";
      mode = ["n"];
      action = ":wq<CR>";
      silent = true;
      desc = "Save file and quit";
    }
  ];
}
```

--------------------------------

### Package a Rust-based Neovim plugin

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Create a Nix derivation for plugins like blink.cmp that require additional packages, such as a Rust fuzzy matcher. Use `buildRustPackage` and copy necessary files in `postInstall`.

```nix
{
  # ...
  
  postInstall = ''
    cp -r {lua,plugin} "$out"

    mkdir -p "$out/doc"
    cp 'doc/'*'.txt' "$out/doc/"

    mkdir -p "$out/target"
    mv "$out/lib" "$out/target/release"
  '';
  
  # ...
}
```

--------------------------------

### Build Plugin Directly Using fetchFromGitHub

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/tips/plugin-sources.md

Build a Vim plugin using `fetchFromGitHub` when not using flake inputs or npins. This method allows direct fetching from a repository.

```nix
regexplainer = buildVimPlugin {
  name = "nvim-regexplainer";
  src = fetchFromGitHub {
    owner = "bennypowers";
    repo = "nvim-regexplainer";
    rev = "4250c8f3c1307876384e70eeedde5149249e154f";
    hash = "sha256-15DLbKtOgUPq4DcF71jFYu31faDn52k3P1x47GL3+b0=";
  };

  # The 'buildVimPlugin' imposes some "require checks" on all plugins build from
  # source. Failing tests, if they are not relevant, can be disabled using the
  # 'nvimSkipModule' argument to the 'buildVimPlugin' function.
  nvimSkipModule = [
    "regexplainer"
    "regexplainer.buffers.init"
    "regexplainer.buffers.popup"
    "regexplainer.buffers.register"
    "regexplainer.buffers.shared"
    "regexplainer.buffers.split"
    "regexplainer.component.descriptions"
    "regexplainer.component.init"
    "regexplainer.renderers.narrative.init"
    "regexplainer.renderers.narrative.narrative"
    "regexplainer.renderers.init"
    "regexplainer.utils.defer"
    "regexplainer.utils.init"
    "regexplainer.utils.treesitter"
  ];
}
```

--------------------------------

### Configure Non-Lazy Vim Plugins with extraPlugins

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/custom-plugins/non-lazy-method.md

Use `vim.extraPlugins` to configure plugins that should not be loaded lazily. This API allows specifying the package, setup function, and dependencies for each plugin.

```nix
{
  pkgs, ...
}: {
  config.vim.extraPlugins = {
    aerial = {
      package = pkgs.vimPlugins.aerial-nvim;
      setup = ""
        require('aerial').setup {
          -- some lua configuration here
        }
      '';
    };

    harpoon = {
      package = pkgs.vimPlugins.harpoon;
      setup = "require('harpoon').setup {}";
      after = ["aerial"];
    };
  };
}
```

--------------------------------

### Generate Lua Configuration with Nix

Source: https://context7.com/notashelf/nvf/llms.txt

Generate Lua configuration for a Neovim plugin using Nix. This snippet shows how to conditionally enable the configuration and pass setup options to the plugin.

```nix
{ lib, config, ... }:
let
  cfg = config.vim.my-plugin;
in {
  config = lib.mkIf cfg.enable {
    vim.luaConfigRC.my-plugin = lib.nvim.dag.entryAnywhere ''
      require('my-plugin').setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
    '';
    # With setupOpts = { show_numbers = true; on_open = lib.generators.mkLuaInline "function() print('opened') end"; }
    # generates: require('my-plugin').setup({ show_numbers = true, on_open = function() print('opened') end })
  };
}
```

--------------------------------

### Define Autocommands with Vim Command

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/configuring/autocmds.md

Configure an autocommand to execute a Vimscript command when a Markdown file's type is set. This example enables spell checking for Markdown files.

```nix
{
  vim.augroups = [ { name = "UserSetup"; } ];

  vim.autocmds = [
    # Example 2: Using a Vim command
    {
      event = [ "FileType" ];
      pattern = [ "markdown" ];
      group = "UserSetup";
      desc = "Set spellcheck for Markdown";
      command = "setlocal spell";
    }
  ];
}
```

--------------------------------

### Home Manager Integration with `programs.nvf`

Source: https://context7.com/notashelf/nvf/llms.txt

Integrate nvf with Home Manager by importing `nvf.homeManagerModules.default`. The configuration options mirror the NixOS module under `programs.nvf.settings.vim.*`.

```nix
# flake.nix + home.nix — Home Manager integration

```

--------------------------------

### Run Minimal nvf Configuration

Source: https://context7.com/notashelf/nvf/llms.txt

Execute the minimal nvf configuration, which includes Nix LSP and utilities, using `nix run`. This is useful for testing the core Nix-focused editor.

```bash
# Try the minimal configuration (Nix LSP + utilities)
nix run github:notashelf/nvf#nix -- test.nix
```

--------------------------------

### Lazy-load Neovim plugins with vim.lazy.plugins

Source: https://context7.com/notashelf/nvf/llms.txt

Configure plugins to be lazy-loaded, triggering only on specific events, commands, or keymaps. Uses an extended `PluginSpec` interface supporting `setupModule` and `setupOpts` for common setup patterns.

```nix
{ pkgs,
  ... 
}: {
  config.vim.lazy.plugins = {
    # Plugin name must match package.pname or package.name
    "aerial.nvim" = {
      package = pkgs.vimPlugins.aerial-nvim;

      # Translates to: require('aerial').setup({ show_guides = true })
      setupModule = "aerial";
      setupOpts = { show_guides = true; };

      # Load triggers — plugin stays unloaded until one fires
      cmd   = ["AerialToggle" "AerialOpen"];
      event = ["BufReadPost"];
      keys  = [
        { key = "<leader>at"; mode = "n"; action = ":AerialToggle<CR>"; desc = "Toggle aerial"; }
      ];

      after = ''
        -- Lua to run once plugin is loaded
        vim.notify("aerial.nvim loaded", vim.log.levels.DEBUG)
      '';
    };

    # LazyFile event: load when any file is opened (BufReadPost + BufNewFile + BufWritePre)
    "gitsigns.nvim" = {
      package = pkgs.vimPlugins.gitsigns-nvim;
      setupModule = "gitsigns";
      setupOpts = { signs.add.text = "+"; signs.change.text = "~"; };
      event = [{ event = "User"; pattern = "LazyFile"; }];
    };
  };
}

```

--------------------------------

### Example Commit Message Structure

Source: https://github.com/notashelf/nvf/blob/main/docs/manual/hacking.md

Follow a structured commit message format: '{component}: {description}'. The component indicates the affected code module. A long description can be optionally included for more complex changes.

```gitcommit
{component}: {description}

{long description}
```

```gitcommit
starship: allow running in Emacs if vterm is used

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

```gitcommit
languages/ruby: init module

Adds a language module for Ruby, adds appropriate formatters and Treesitter
grammars
```

```gitcommit
plugin: init
```

```gitcommit
neotree: init

This adds the neo-tree plugin.
```

--------------------------------

### NixOS System Integration with `programs.nvf`

Source: https://context7.com/notashelf/nvf/llms.txt

Integrate nvf into NixOS by importing `nvf.nixosModules.default`. Configuration options are available under `programs.nvf.settings.vim.*`.

```nix
# flake.nix + configuration.nix — NixOS system integration
# --- flake.nix ---
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nvf = {
      url = "github:notashelf/nvf";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, nvf, ... }:
  {
    nixosConfigurations."my-host" = nixpkgs.lib.nixosSystem {
      modules = [
        nvf.nixosModules.default  # provides programs.nvf.*
        ./configuration.nix
      ];
    };
  };
}

# --- configuration.nix ---
{
  programs.nvf = {
    enable = true;
    # enableManpages = true;  # enables `man 5 nvf`
    settings = {
      vim = {
        viAlias = false;
        vimAlias = true;
        lsp = {
          enable = true;
          formatOnSave = true;
          trouble.enable = true;
          lightbulb.enable = true;
        };
        languages = {
          enableFormat = true;
          enableTreesitter = true;
          nix.enable = true;
          go.enable = true;
          typescript.enable = true;
        };
        statusline.lualine = { enable = true; theme = "catppuccin"; };
        git = { enable = true; gitsigns.enable = true; };
        terminal.toggleterm = { enable = true; lazygit.enable = true; };
      };
    };
  };
}

```