2026-02-13T15:32:44+01:00

README.md

@@ -1,17 +1,177 @@
-# Nixvim template
+# Nixvim Configuration
 
-This template gives you a good starting point for configuring nixvim standalone.
+A standalone Neovim configuration built with [nixvim](https://github.com/nix-community/nixvim) and Nix flakes.
+
+## Installation
+
+```bash
+# First time — install to your Nix profile
+./install.sh
+
+# Update an existing installation
+./update.sh
+```
+
+## Testing your configuration
+
+```bash
+# Try the config without installing
+nix run .
+
+# Verify nothing is broken
+nix flake check .
+```
 
 ## Configuring
 
-To start configuring, just add or modify the nix files in `./config`.
+Add or modify nix files in `./config`. The main entry point is [`config/default.nix`](./config/default.nix).
-If you add a new configuration file, remember to add it to the
-[`config/default.nix`](./config/default.nix) file
 
-## Testing your new configuration
+## Plugin Usage Guide
 
-To test your configuration simply run the following command
+This configuration comes with a curated set of plugins. Here's how to get the most out of each one.
 
-```
+### Navigation
-nix run .
+
-```
+#### Telescope — fuzzy finder for everything
+| Keymap | Action |
+|---|---|
+| `<leader>ff` | Find files in the project |
+| `<leader>fg` | Live grep across all files (uses ripgrep) |
+| `<leader>fb` | Browse open buffers |
+| `<leader>fh` | Search help tags |
+
+Type to filter results, `<CR>` to open, `<C-x>` to open in a split, `<C-v>` for a vertical split.
+
+#### Hop — jump to any visible position
+| Keymap | Action |
+|---|---|
+| `s` + two characters | Jump to any matching two-character sequence on screen |
+
+Press `s`, type two characters, then press the hint letter to jump there instantly. Much faster than `f`/`F` or `/search` for medium-distance jumps.
+
+#### fzf-lua — alternative fuzzy finder
+| Command | Action |
+|---|---|
+| `:FzfLua files` | Find files |
+| `:FzfLua grep` | Grep project |
+| `:FzfLua buffers` | Switch buffers |
+
+Faster than Telescope on very large codebases thanks to the native fzf algorithm.
+
+### File Management
+
+#### nvim-tree — sidebar file explorer
+| Keymap | Action |
+|---|---|
+| `<C-n>` or `:NvimTreeToggle` | Toggle the file tree sidebar |
+| `a` | Create a new file or directory (inside the tree) |
+| `d` | Delete file (inside the tree) |
+| `r` | Rename file (inside the tree) |
+| `<CR>` | Open file or expand folder |
+
+#### Oil — edit the filesystem like a buffer
+| Command | Action |
+|---|---|
+| `:Oil` | Open the parent directory as an editable buffer |
+
+Rename files by editing their names, delete by removing lines, create by adding new lines. Save the buffer (`:w`) to apply changes.
+
+#### Bufferline — tab-style buffer bar
+| Keymap | Action |
+|---|---|
+| `:bnext` / `:bprev` | Cycle through open buffers |
+| `:bdelete` | Close the current buffer |
+
+Click on tabs with the mouse or use buffer commands to switch between open files.
+
+### Git
+
+#### Fugitive — Git commands inside Neovim
+| Command | Action |
+|---|---|
+| `:Git` | Open interactive git status (stage with `s`, commit with `cc`) |
+| `:Git blame` | Inline blame annotations for the current file |
+| `:Git diff` | View diff of current file |
+| `:Git log` | Browse commit history |
+| `:Gwrite` | Stage the current file |
+
+#### Lazygit — full git UI in a floating terminal
+| Command | Action |
+|---|---|
+| `:LazyGit` | Open the lazygit terminal UI |
+
+A visual interface for staging, committing, branching, rebasing, and more. Navigate with arrow keys, press `?` inside lazygit for help.
+
+### Editing
+
+#### Commentary — toggle comments
+| Keymap | Action |
+|---|---|
+| `gcc` | Toggle comment on the current line |
+| `gc` + motion | Toggle comments over a motion (e.g. `gcap` for a paragraph) |
+| `gc` in visual mode | Toggle comments on selected lines |
+
+#### vim-surround — manage surrounding characters
+| Keymap | Action |
+|---|---|
+| `cs"'` | Change surrounding `"` to `'` |
+| `ds"` | Delete surrounding `"` |
+| `ysiw]` | Surround the word with `[]` |
+| `S"` in visual mode | Surround selection with `"` |
+
+#### cmp — autocompletion
+Completion popups appear automatically as you type. Use:
+| Keymap | Action |
+|---|---|
+| `<C-n>` / `<C-p>` | Navigate completion items |
+| `<CR>` | Accept the selected completion |
+| `<C-e>` | Dismiss the completion menu |
+
+Sources include buffer words, file paths, LSP, and more (all enabled automatically).
+
+### UI & Visual Aids
+
+#### which-key — keybinding discovery
+Press `<leader>` (or any prefix key) and **wait** — a popup shows all available continuations. Great for learning and remembering mappings you don't use often.
+
+#### indent-blankline — indentation guides
+Visible automatically. Vertical lines show indentation levels so you can quickly see code structure and nesting depth.
+
+#### illuminate — highlight word under cursor
+Automatic — all occurrences of the word under your cursor are highlighted. Helps you quickly spot where a variable or function is used.
+
+#### lualine — statusline
+Always visible at the bottom. Shows the current mode, git branch, filename, file type, cursor position, and diagnostics.
+
+### Terminal & Environment
+
+#### toggleterm — embedded terminal
+| Command | Action |
+|---|---|
+| `:ToggleTerm` | Toggle a persistent terminal at the bottom |
+
+The terminal persists its state between toggles, so running processes stay alive.
+
+#### direnv — automatic environment loading
+Automatic — when you open a project with a `.envrc`, Neovim loads the environment variables and nix shell automatically. No action needed.
+
+### Language Support
+
+#### Treesitter — syntax-aware highlighting
+Automatic — provides accurate syntax highlighting, indentation, and code folding for all supported languages. Much better than regex-based highlighting.
+
+#### Nix — Nix language support
+Automatic — syntax highlighting, error checking, and formatting for `.nix` files.
+
+#### OpenSCAD — 3D modeling language support
+Automatic — syntax highlighting for `.scad` files.
+
+### AI
+
+#### CodeCompanion — AI assistant
+| Command | Action |
+|---|---|
+| `:CodeCompanionChat` | Open an AI chat buffer |
+| `:CodeCompanionActions` | Browse available AI actions |
+
+Use it for inline code suggestions, explanations, and refactoring help directly inside the editor.

config/bufferline.nix

@@ -1,6 +0,0 @@
-{
-  plugins = {
-    bufferline.enable = true;
-    web-devicons.enable = true;
-  };
-}

config/default.nix

@@ -1,66 +1,105 @@
 
 { pkgs, ... }:
 {
-  # Import all your configuration modules here
-  # imports = [ ./bufferline.nix ];
-
   # Extra packages available in Neovim's PATH
   extraPackages = with pkgs; [
-    ripgrep
+    ripgrep     # Required by Telescope and fzf-lua for fast file content searching (grep)
-    tree-sitter
+    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 line numbers
+    number = true;         # Show absolute line numbers for quick go-to-line navigation
-    relativenumber = true; # Show relative line numbers
+    relativenumber = true; # Relative numbers make counted motions (e.g. 5j, 12k) easy to estimate
-    shiftwidth = 2;        # Tab width should be 2
+    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
     treesitter.enable = true;
+
+    # 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;
+
+    # Syntax highlighting and preview support for OpenSCAD 3D modeling files
     openscad.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; };
 
-    # enable all auto completion
+    # Autocompletion engine with all sources enabled for a batteries-included completion experience
     cmp.enable = true;
     cmp.autoEnableSources = true;
 
-    # Good old Telescope
+    # 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 expressions in Neovim
+    # 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()