vim/config/default.nix

{ config, pkgs, ... }:
{
  # Skip generating the nixvim options manpage. It renders the *entire* nixvim
  # option reference on every build (options.json + nixos-render-docs + a Python
  # env) and is pure build-time cost — `:help nixvim` is the only thing lost.
  enableMan = false;

  # Extra packages available in Neovim's PATH
  extraPackages = with pkgs; [
    ripgrep     # Required by Telescope and fzf-lua for fast file content searching (grep)
    tree-sitter # Needed for treesitter parser compilation and grammar updates
  ];

  # Use the system clipboard so yanking/pasting works seamlessly with other apps
  clipboard.register = "unnamedplus";

  # Nord: a calm, low-contrast arctic color scheme that reduces eye strain during long sessions
  colorschemes.nord.enable = true;

  opts = {
    number = true;         # Show absolute line numbers for quick go-to-line navigation
    relativenumber = true; # Relative numbers make counted motions (e.g. 5j, 12k) easy to estimate
    shiftwidth = 2;        # 2-space indentation keeps Nix and web code compact and readable
  };

  plugins = {
    # Provides file-type icons used by nvim-tree, lualine, bufferline, and Telescope
    web-devicons.enable = true;

    # Lightweight and fast statusline showing mode, branch, file info, and diagnostics
    lualine.enable = true;

    # Edit the filesystem like a buffer — rename, move, and delete files without leaving Neovim
    oil.enable = true;

    # Toggle comments with gc/gcc — simple, reliable, and supports every filetype via treesitter
    commentary.enable = true;

    # Sidebar file explorer for visual project navigation and file management
    nvim-tree.enable = true;

    # Syntax-aware highlighting, indentation, and code folding via incremental parsing.
    # grammarPackages defaults to *every* grammar nvim-treesitter ships (~350),
    # which forces ~340 query derivations to be built locally and pulls hundreds
    # of MiB of parsers. Pin an explicit list instead — add languages as needed.
    treesitter = {
      enable = true;
      grammarPackages = with config.plugins.treesitter.package.builtGrammars; [
        bash
        c
        css
        diff
        dockerfile
        git_rebase
        gitcommit
        html
        javascript
        json
        lua
        make
        markdown
        markdown_inline
        nix
        python
        query
        regex
        toml
        typescript
        vim
        vimdoc
        yaml
      ];
    };

    # Git integration directly in the command line (:Git blame, :Git diff, :Git log, etc.)
    fugitive.enable = true;

    # Quickly add, change, or delete surrounding characters (quotes, brackets, tags)
    vim-surround.enable = true;

    # Popup that shows available keybindings as you type — great for discovering and remembering mappings
    which-key.enable = true;

    # Full-featured git UI inside a floating terminal — staging, committing, branching made visual
    lazygit.enable = true;

    # Persistent terminal that toggles in/out with a keypress — avoids leaving Neovim for shell tasks
    toggleterm.enable = true;

    # Visual indentation guides that make nested code structure easy to follow at a glance
    indent-blankline.enable = true;

    # Highlights all occurrences of the word under the cursor — helps spot usages instantly
    illuminate.enable = true;

    # Tab-style buffer bar at the top for fast switching between open files
    bufferline.enable = true;

    # Auto-loads .envrc variables so Neovim always has the correct nix-shell / devShell environment
    direnv.enable = true;

    # Blazing-fast fuzzy finder alternative to Telescope — useful for very large projects
    fzf-lua.enable = true;

    # EasyMotion-style jump-to-anywhere — type a hint and land on any visible position instantly
    hop.enable = true;

    # AI-powered code assistant providing inline suggestions and chat inside the editor
    codecompanion = { enable = true; };

    # Autocompletion engine with all sources enabled for a batteries-included completion experience
    cmp.enable = true;
    cmp.autoEnableSources = true;

    # Fuzzy file/buffer/grep picker — the Swiss-army knife for navigating any project
    telescope = {
      enable = true;
      extensions = {
        # Native C fzf algorithm makes Telescope filtering significantly faster on large result sets
        fzf-native = {
          enable = true;
        };
      };
    };

    # Nix language support — syntax highlighting, error checking, and formatting for .nix files
    nix.enable = true;

  };

  keymaps = [
    {
      # Remap 's' to hop's two-character search — faster than f/F for reaching distant targets
      key = "s";
      action.__raw = ''
        function()
          -- type two letters and jump to that bigram anywhere
          require("hop").hint_char2({
            current_line_only = false,
            multi_windows    = false,  -- set true if you want to hop across all windows
          })
        end
      '';
      options = { remap = true; };
    }
  ];

}