nix-config/programs/nixvim/README.md

Nixvim Configuration

This directory contains a modular Neovim configuration managed through nixvim.

Directory Structure

nixvim/
├── default.nix           # Main entry point
├── options.nix           # Core Neovim options (line numbers, tabs, etc.)
├── keymappings.nix       # Global key mappings
├── autocommands.nix      # Auto commands for various events
├── completion.nix        # Completion configuration (nvim-cmp)
└── plugins/              # Plugin configurations
    ├── default.nix       # Plugin imports
    ├── ui.nix            # UI enhancements (colorscheme, icons, etc.)
    ├── git.nix           # Git integration
    ├── editing.nix       # Editing enhancements
    ├── utility.nix       # Utility plugins
    ├── ai.nix            # AI assistants (Copilot, Avante)
    ├── lsp/              # Language Server Protocol
    │   ├── default.nix   # LSP imports
    │   ├── servers.nix   # Language server configurations
    │   ├── keymaps.nix   # LSP-specific key mappings
    │   └── formatting.nix # Auto-formatting settings
    ├── avante.nix        # Avante AI configuration
    ├── conform.nix       # Code formatting
    ├── floaterm.nix      # Floating terminal
    ├── lualine.nix       # Status line
    ├── neo-tree.nix      # File explorer
    ├── telescope.nix     # Fuzzy finder
    └── treesitter.nix    # Syntax highlighting

Configuration Categories

Core Settings (options.nix)

• Editor options (line numbers, indentation, etc.)
• Update time and performance settings
• Clipboard configuration
• Leader key mappings

Key Mappings (keymappings.nix)

• Window navigation
• Buffer management
• Text manipulation
• Custom shortcuts

Auto Commands (autocommands.nix)

• FileType-specific settings
• Auto-formatting rules
• UI behavior modifications

Completion (completion.nix)

• nvim-cmp configuration
• Snippet support
• LSP integration
• Multiple completion sources

Plugins

UI Enhancements (ui.nix)

• Colorscheme: Tokyo Night theme with custom background
• Icons: File type icons via web-devicons
• Visual aids: Indent guides, color highlighting, markdown preview

Git Integration (git.nix)

• Gitsigns: Shows git changes in the gutter

Editing (editing.nix)

• Auto-pairs: Automatic bracket/quote closing
• Flash: Enhanced jump/search
• Trim: Whitespace management
• Image support: Clipboard image pasting

Utilities (utility.nix)

• Oil: File manager
• Todo-comments: Highlight TODO/FIXME comments
• Trouble: Diagnostics list
• Which-key: Show available keybindings

AI Assistants (ai.nix)

• Copilot: GitHub Copilot integration
• Avante: Advanced AI assistant

LSP (lsp/)

• Language Servers: Support for 15+ languages
• Key mappings: Go-to-definition, references, hover docs
• Auto-formatting: Format on save for all supported languages

Adding New Configurations

Adding a New Plugin

1. Create a new file in plugins/ or add to an existing category file
2. Add the import to plugins/default.nix
3. Configure the plugin following nixvim documentation

Example:

# plugins/my-plugin.nix
{ ... }:
{
  programs.nixvim.plugins.my-plugin = {
    enable = true;
    settings = {
      # Plugin-specific settings
    };
  };
}

Adding a New Language Server

Edit plugins/lsp/servers.nix and add your server configuration:

my_language_ls = {
  enable = true;
  settings = {
    # Server-specific settings
  };
};

Adding Key Mappings

• Global mappings: Add to keymappings.nix
• LSP mappings: Add to plugins/lsp/keymaps.nix
• Plugin-specific: Add to the plugin's configuration file

Applying Changes

After making changes, rebuild your nix configuration:

nixre  # Alias for darwin-rebuild switch --flake ~/.config/nixpkgs#salarm3max

Performance Tuning

Key performance settings:

• updatetime: Controls LSP/diagnostic update speed (currently 100ms)
• performance.debounce: Completion debounce time (60ms)
• performance.throttle: Completion throttle time (30ms)

Adjust these in options.nix and completion.nix respectively.

Troubleshooting

LSP Not Working

1. Check if language server is installed: :LspInfo
2. Verify keymaps are loaded: :map gd
3. Check for errors: :messages

Slow Performance

1. Increase updatetime in options.nix
2. Adjust completion performance settings in completion.nix
3. Disable unused language servers in lsp/servers.nix

Keyboard Shortcuts Cheatsheet

Leader Key

Leader: Space

General Keybindings

Key	Mode	Action
Esc	Normal	Clear search highlighting
Y	Normal	Yank to end of line
H	Normal	Go to beginning of line
L	Normal	Go to end of line
Ctrl-c	Normal	Switch to alternate buffer
Ctrl-x	Normal	Close window
Ctrl-s or <leader>s	Normal	Save file

Window Navigation

Key	Mode	Action
<leader>h	Normal	Move to left window
<leader>l	Normal	Move to right window
Ctrl-Up	Normal	Decrease window height
Ctrl-Down	Normal	Increase window height
Ctrl-Left	Normal	Increase window width
Ctrl-Right	Normal	Decrease window width

Text Manipulation

Key	Mode	Action
Alt-k	Normal	Move line up
Alt-j	Normal	Move line down
>	Visual	Indent (dot-repeatable)
<	Visual	Unindent (dot-repeatable)
Tab	Visual	Indent and keep selection
Shift-Tab	Visual	Unindent and keep selection
J	Visual	Move selected lines down
K	Visual	Move selected lines up

File Explorer (Neo-tree)

Key	Mode	Action
<leader>m	Normal	Toggle file explorer

Fuzzy Finder (Telescope)

Key	Mode	Action
<leader>ff	Normal	Find files
<leader>fg	Normal	Live grep (search text)
<leader>b	Normal	List buffers
<leader>fh	Normal	Help tags
<leader>fd	Normal	Diagnostics
Ctrl-p	Normal	Git files
<leader>?	Normal	Recently opened files
Ctrl-t	Normal	Search for TODOs
<leader>t	Normal	TODO comments (Telescope)

LSP (Language Server)

Key	Mode	Action
gd	Normal	Go to definition
gD	Normal	Go to references
gt	Normal	Go to type definition
gi	Normal	Go to implementation
K	Normal	Hover documentation
F2	Normal	Rename symbol
<leader>j	Normal	Next diagnostic
<leader>k	Normal	Previous diagnostic

Metals (Scala Development)

Key	Mode	Action
<leader>ws	Normal	Hover Metals Worksheet
<leader>sm	Normal	Telescope Metals Commands
<leader>tt	Normal	Toggle tree view
<leader>tr	Normal	Reveal in tree

Terminal (Floaterm)

Key	Mode	Action
<leader>,	Normal	Toggle floating terminal

AI Assistants

Avante

• Enabled with Claude Sonnet 4.5 model
• Default Avante keybindings apply (check :help avante for full list)

GitHub Copilot

• Enabled with default keybindings
• Check :help copilot for keybinding details

Other Utilities

Feature	Command/Key
Which-key	Automatically shows available keybindings when you pause
Oil file manager	:Oil command
Trouble diagnostics	:Trouble command

Resources

• Nixvim Documentation
• Neovim Documentation
• LSP Specification