Compare commits

...

2 commits

Author SHA1 Message Date
ac16609e1f
docs: add CLAUDE.md with project documentation
Add comprehensive documentation for AI assistants working with this
codebase. Documents the new keymap organization structure, semantic
namespacing patterns, and cross-application consistency philosophy.

Includes:
- Repository overview and development commands
- Keymap organization and namespace structure
- Plugin architecture and file locations
- Keybinding philosophy (navigation vs management)
- Container consistency patterns with WezTerm/XMonad
2025-10-03 16:43:12 +08:00
f6f92ec15e
refactor: reorganize keymaps into semantic namespaces
Restructure keybindings for improved discoverability and consistency
with WezTerm/XMonad configurations. Separate keymaps from plugin
configurations following single responsibility principle.

Changes:
- Create keymaps/ directory with semantic grouping:
  - general.nix: leader setup, page navigation
  - buffers.nix: buffer operations (bq, bQ, bl)
  - windows.nix: window operations (ws, wv, wq, wQ, wm)
  - find.nix: telescope find operations (ff, fg, fh, fc)
  - git.nix: unified git operations from gitsigns/fugitive/telescope

- Adopt consistent q/Q pattern across containers:
  - bq/bQ for buffer quit (current/all others)
  - wq/wQ for window quit (current/all others)
  - Mirrors WezTerm's LEADER+p q / LEADER+t q pattern

- Extract keymaps from plugin files:
  - telescope.nix: config only, keymaps moved to find.nix
  - fugitive.nix: config only, keymaps moved to git.nix
  - gitsigns.nix: config only, keymaps moved to git.nix
  - snacks.nix: config only, keymaps moved to buffers.nix
  - maximize.nix: config only, keymap moved to windows.nix

- Remove smart-splits.nix (functionality replaced by native window ops)

- Maintain navigation on dedicated modifiers (Ctrl+arrows/PageUp/PageDown)
  for consistency with WezTerm (ALT) and XMonad (Super)
2025-10-03 16:39:39 +08:00
13 changed files with 570 additions and 324 deletions

132
CLAUDE.md Normal file
View file

@ -0,0 +1,132 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Repository Overview
This is a personal Neovim configuration built with nixvim, a Nix-based configuration system for Neovim. The configuration is structured as a Nix flake with modular plugin organization and supports multiple platforms (Linux and macOS, both x86_64 and aarch64).
## Development Commands
### Building and Running
- `nix run .` - Build and run nixvim with current configuration
- `nix run git+https://git.sajenim.dev/jasmine/nvim.nix.git` - Run from remote repository
- `nix flake check` - Verify configuration is valid and not broken
- `nix flake show` - Display available packages and checks for all systems
- `nix build` - Build the nixvim package without running it
### Development Workflow
- `nix develop` - Enter development shell (if devShell is available)
- `nix flake update` - Update flake inputs (nixpkgs, nixvim, flake-parts)
- `git log --oneline -10` - View recent configuration changes
## Architecture and Structure
### Core Configuration Files
- `flake.nix` - Main flake definition with inputs, outputs, and build configuration
- `config/default.nix` - Central module imports file that orchestrates all configuration pieces
- `config/options.nix` - Global Neovim options (number, tabstop, clipboard, etc.)
- `config/autocmds.nix` - Autocommands for automatic behaviors (window balancing on resize)
### Keymap Organization
The configuration separates keybindings into semantic namespaces under `config/keymaps/`:
- `general.nix` - Leader setup, page navigation, global keybindings
- `buffers.nix` - Buffer management operations (bq, bQ, bl)
- `windows.nix` - Window management operations (ws, wv, wq, wQ, wm)
- `find.nix` - Telescope find operations (ff, fg, fh, fc)
- `git.nix` - Unified git operations from gitsigns, fugitive, and telescope
### Plugin Organization
The configuration uses a hierarchical plugin structure under `config/plugins/`:
**Themes & Appearance** (`plugins/themes/`)
- Uses gruvbox-material theme with medium background and italic support
**Language Server Protocol** (`plugins/lsp/`)
- `lsp.nix` - Comprehensive LSP setup with servers for: C/C++ (clangd), Clojure, Haskell (hls), Lua, Nix (nil_ls), YAML, Python (pyright), Rust (rust_analyzer)
- `conform.nix` - Code formatting configuration
- Extensive LSP keybindings: `gd` (definition), `gr` (references), `K` (hover), `<leader>r` (rename)
**Plugin Collections** (`plugins/collections/`)
- `mini.nix` - Mini.nvim plugin suite
- `snacks.nix` - Snacks.nvim plugin collection (bufdelete functionality)
**Editor Enhancements** (`plugins/editor/`)
- `treesitter.nix` - Syntax highlighting and parsing
- `harpoon.nix` - Quick file navigation
- `sessions.nix` - Session management
- `maximize.nix` - Window maximization/zoom functionality
- `surround.nix` - Text object surrounding
- `commentary.nix` - Code commenting
**User Interface** (`plugins/ui/`)
- `lualine.nix` - Status line configuration
- `web-devicons.nix` - File type icons
- `whichkey.nix` - Keybinding hints and discovery
**Git Integration** (`plugins/git/`)
- `fugitive.nix` - Git commands within Neovim (plugin config only, keymaps in keymaps/git.nix)
- `gitsigns.nix` - Git change indicators in gutter (plugin config only, keymaps in keymaps/git.nix)
**Completion** (`plugins/cmp/`)
- `cmp.nix` - Autocompletion engine configuration
**Utilities** (`plugins/utils/`)
- `telescope.nix` - Fuzzy finder and picker (plugin config only, keymaps in keymaps/find.nix and keymaps/git.nix)
- `oil.nix` - File manager replacement for netrw
- `vimtex.nix` - LaTeX support
**Notes and Productivity** (`plugins/notes/`)
- `neorg.nix` - Org-mode like note taking (requires conceallevel=2, foldlevel=99)
- `markdown-preview.nix` - Live markdown preview
- `render-markdown.nix` - Enhanced markdown rendering
- `todo-comments.nix` - Highlight and manage TODO comments
### Key Configuration Patterns
**Leader Keys**
- Primary leader: `<Space>`
- Local leader: `<Backspace>` (using raw vim API call)
- Namespace prefixes:
- `<leader>b` - Buffer operations (bq, bQ, bl)
- `<leader>w` - Window operations (ws, wv, wq, wQ, wm)
- `<leader>f` - Find operations (ff, fg, fh, fc)
- `<leader>g` - Git operations (gs, gr, gb, gc, gd, gu, gp)
- `<leader>gl` - Git list operations (glc, glb, gld, gls)
- `<leader>l` - LSP operations
**Navigation Keybindings**
- Uses dedicated modifiers for fast navigation (muscle memory):
- `Ctrl+Left/Right` - Cycle buffers
- `Ctrl+Up/Down` - Cycle windows
- `Ctrl+PageUp/PageDown` - Rotate windows
- `Ctrl+Del` - Equalize window sizes
- Mirrors WezTerm (ALT) and XMonad (Super) for cross-application consistency
**Keybinding Philosophy**
- **Navigation**: Optimized for speed using dedicated modifiers
- **Management**: Optimized for clarity using leader + semantic namespaces
- **Separation of concerns**: Keymaps separated from plugin configurations
- **Container consistency**: Matches WezTerm's LEADER+p/t namespace pattern
**Platform Support**
- Multi-platform flake supporting x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin
- Uses `pkgsWithUnfree` to allow unfree packages when needed
- Each system gets its own package and check derivation
**Module Import Strategy**
- Central `default.nix` imports all configuration modules
- Keymaps organized by domain (buffers, windows, find, git) not by plugin
- Plugin files contain only configuration, keymaps are extracted to `keymaps/`
- Logical grouping by functionality (themes, LSP, editor, UI, etc.)
- Each plugin typically gets its own dedicated file for maintainability
### Development Settings
- Uses 2-space indentation with tab expansion
- Clipboard integration with system (`unnamedplus`)
- Persistent undo files enabled
- Split windows open to the right
- Update time set to 100ms for responsive interactions
- Session options configured for proper session restoration
When working on this configuration, always test changes with `nix flake check` before committing, and consider the modular structure when adding new plugins or features.

View file

@ -2,9 +2,15 @@
imports = [
# General Configuration
./autocmds.nix
./keymaps.nix
./options.nix
# Keymaps
./keymaps/general.nix
./keymaps/buffers.nix
./keymaps/windows.nix
./keymaps/find.nix
./keymaps/git.nix
# Themes & Appearance
./plugins/themes/default.nix
@ -22,8 +28,8 @@
# Editor Enhancements
./plugins/editor/commentary.nix
./plugins/editor/harpoon.nix
./plugins/editor/maximize.nix
./plugins/editor/sessions.nix
./plugins/editor/smart-splits.nix
./plugins/editor/surround.nix
./plugins/editor/treesitter.nix

View file

@ -0,0 +1,70 @@
{...}: {
keymaps = [
# Buffer namespace indicator for whichkey
{
mode = ["n"];
key = "<leader>b";
action = "<NOP>";
options = {
desc = "+buffer";
};
}
# Buffer deletion
{
mode = ["n"];
key = "<leader>bq";
action = {
__raw = "function() require('snacks').bufdelete() end";
};
options = {
desc = "Quit current buffer";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>bQ";
action = {
__raw = "function() require('snacks').bufdelete.other() end";
};
options = {
desc = "Quit all other buffers";
silent = true;
};
}
# Buffer navigation (moved from keymaps.nix)
{
mode = ["n"];
key = "<C-Left>";
action = ":bprevious<CR>";
options = {
desc = "Previous buffer";
silent = true;
};
}
{
mode = ["n"];
key = "<C-Right>";
action = ":bnext<CR>";
options = {
desc = "Next buffer";
silent = true;
};
}
# Buffer listing
{
mode = ["n"];
key = "<leader>bl";
action = "<cmd>Telescope buffers<CR>";
options = {
desc = "List buffers";
silent = true;
};
}
];
}

54
config/keymaps/find.nix Normal file
View file

@ -0,0 +1,54 @@
{...}: {
keymaps = [
# Find namespace indicator for whichkey
{
mode = ["n"];
key = "<leader>f";
action = "<NOP>";
options = {
desc = "+find";
};
}
# Find files and content
{
mode = ["n"];
key = "<leader>ff";
action = "<cmd>Telescope find_files<CR>";
options = {
desc = "Find project files";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>fg";
action = "<cmd>Telescope live_grep<CR>";
options = {
desc = "Find pattern";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>fh";
action = "<cmd>Telescope help_tags<CR>";
options = {
desc = "Find help tags";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>fc";
action = "<cmd>Telescope commands<CR>";
options = {
desc = "Find commands";
silent = true;
};
}
];
}

View file

@ -14,15 +14,6 @@
};
}
{
mode = ["n"];
key = "<leader>f";
action = "<NOP>";
options = {
desc = "+find";
};
}
{
mode = ["n"];
key = "<PageUp>";

181
config/keymaps/git.nix Normal file
View file

@ -0,0 +1,181 @@
{...}: {
keymaps = [
# Git namespace indicator for whichkey
{
mode = ["n"];
key = "<leader>g";
action = "<NOP>";
options = {
desc = "+git";
};
}
# Git list namespace indicator for whichkey
{
mode = ["n"];
key = "<leader>gl";
action = "<NOP>";
options = {
desc = "+list";
};
}
# Git staging (from gitsigns)
{
mode = ["n" "v"];
key = "<leader>gs";
action = "<cmd>Gitsigns stage_hunk<CR>";
options = {
desc = "Stage hunk";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>gS";
action = "<cmd>Gitsigns stage_buffer<CR>";
options = {
desc = "Stage buffer";
silent = true;
};
}
# Git reset (from gitsigns)
{
mode = ["n" "v"];
key = "<leader>gr";
action = "<cmd>Gitsigns reset_hunk<CR>";
options = {
desc = "Reset hunk";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>gR";
action = "<cmd>Gitsigns reset_buffer<CR>";
options = {
desc = "Reset buffer";
silent = true;
};
}
# Git blame (from gitsigns)
{
mode = ["n"];
key = "<leader>gb";
action = "<cmd>Gitsigns toggle_current_line_blame<CR>";
options = {
desc = "Toggle blame";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>gB";
action = "<cmd>Gitsigns blame<CR>";
options = {
desc = "View blame";
silent = true;
};
}
# Git commit (from fugitive)
{
mode = ["n"];
key = "<leader>gc";
action = "<cmd>Git commit<CR>";
options = {
desc = "Commit changes";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>gC";
action = "<cmd>Git commit --amend<CR>";
options = {
desc = "Amend changes";
silent = true;
};
}
# Git diff (from fugitive)
{
mode = ["n"];
key = "<leader>gd";
action = "<cmd>Git diff<CR>";
options = {
desc = "View diff";
silent = true;
};
}
# Git unstage (from fugitive)
{
mode = ["n"];
key = "<leader>gu";
action = "<cmd>Git restore --staged .<CR>";
options = {
desc = "Unstage all changes";
silent = true;
};
}
# Git push (from fugitive)
{
mode = ["n"];
key = "<leader>gp";
action = "<cmd>Git push<CR>";
options = {
desc = "Push changes to remote";
silent = true;
};
}
# Git list operations (from telescope)
{
mode = ["n"];
key = "<leader>glc";
action = "<cmd>Telescope git_commits<CR>";
options = {
desc = "List git commits";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>glb";
action = "<cmd>Telescope git_branches<CR>";
options = {
desc = "List git branches";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>gld";
action = "<cmd>Telescope git_status<CR>";
options = {
desc = "List git diff";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>gls";
action = "<cmd>Telescope git_stash<CR>";
options = {
desc = "List git stash";
silent = true;
};
}
];
}

110
config/keymaps/windows.nix Normal file
View file

@ -0,0 +1,110 @@
{...}: {
keymaps = [
# Window namespace indicator for whichkey
{
mode = ["n"];
key = "<leader>w";
action = "<NOP>";
options = {
desc = "+window";
};
}
# Window splits
{
mode = ["n"];
key = "<leader>ws";
action = "<C-w>s";
options = {
desc = "Split window horizontally";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>wv";
action = "<C-w>v";
options = {
desc = "Split window vertically";
silent = true;
};
}
# Window closing
{
mode = ["n"];
key = "<leader>wq";
action = "<C-w>q";
options = {
desc = "Quit window";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>wQ";
action = "<C-w>o";
options = {
desc = "Quit all other windows";
silent = true;
};
}
# Window maximize
{
mode = ["n"];
key = "<leader>wm";
action = {
__raw = "require('maximize').toggle";
};
options = {
desc = "Toggle maximize window";
silent = true;
};
}
# Cycle through splits
{
mode = ["n"];
key = "<C-Up>";
action = "<C-w>W";
options = {
desc = "Cycle to previous split";
silent = true;
};
}
{
mode = ["n"];
key = "<C-Down>";
action = "<C-w>w";
options = {
desc = "Cycle to next split";
silent = true;
};
}
# Rotate split layout
{
mode = ["n"];
key = "<C-PageUp>";
action = "<C-w>R";
options = {
desc = "Rotate splits counter-clockwise";
silent = true;
};
}
{
mode = ["n"];
key = "<C-PageDown>";
action = "<C-w>r";
options = {
desc = "Rotate splits clockwise";
silent = true;
};
}
];
}

View file

@ -1,4 +1,4 @@
{...}:{
{...}: {
plugins.snacks = {
enable = true;
@ -12,30 +12,4 @@
};
};
};
keymaps = [
{
mode = ["n"];
key = "<leader>q";
action = {
__raw = "function() require('snacks').bufdelete() end";
};
options = {
desc = "Close current buffer";
silent = true;
};
}
{
mode = ["n"];
key = "<leader>Q";
action = {
__raw = "function() require('snacks').bufdelete.other() end";
};
options = {
desc = "Close other buffers";
silent = true;
};
}
];
}

View file

@ -0,0 +1,13 @@
{pkgs, ...}: {
extraPlugins = [
(pkgs.vimUtils.buildVimPlugin {
name = "maximize.nvim";
src = pkgs.fetchFromGitHub {
owner = "declancm";
repo = "maximize.nvim";
rev = "d688b66344b03ee6e5a32a0a40af85d174490af8";
hash = "sha256-rwnvX+Sul+bwESZtpqbvaDJuk49SV9tLUnvgiAH4VMs=";
};
})
];
}

View file

@ -1,110 +0,0 @@
{...}: {
plugins.smart-splits = {
enable = true;
settings = {
multiplexer_integration = "wezterm";
};
};
keymaps = [
# moving between splits
{
mode = ["n"];
key = "<A-Left>";
action = {
__raw = "require('smart-splits').move_cursor_left";
};
}
{
mode = ["n"];
key = "<A-Down>";
action = {
__raw = "require('smart-splits').move_cursor_down";
};
}
{
mode = ["n"];
key = "<A-Up>";
action = {
__raw = "require('smart-splits').move_cursor_up";
};
}
{
mode = ["n"];
key = "<A-Right>";
action = {
__raw = "require('smart-splits').move_cursor_right";
};
}
# swapping buffers between windows
{
mode = ["n"];
key = "<A-S-Left>";
action = {
__raw = "require('smart-splits').swap_buf_left";
};
}
{
mode = ["n"];
key = "<A-S-Down>";
action = {
__raw = "require('smart-splits').swap_buf_down";
};
}
{
mode = ["n"];
key = "<A-S-Up>";
action = {
__raw = "require('smart-splits').swap_buf_up";
};
}
{
mode = ["n"];
key = "<A-S-Right>";
action = {
__raw = "require('smart-splits').swap_buf_right";
};
}
# resizing splits
{
mode = ["n"];
key = "<A-C-Left>";
action = {
__raw = "require('smart-splits').resize_left";
};
}
{
mode = ["n"];
key = "<A-C-Down>";
action = {
__raw = "require('smart-splits').resize_down";
};
}
{
mode = ["n"];
key = "<A-C-Up>";
action = {
__raw = "require('smart-splits').resize_up";
};
}
{
mode = ["n"];
key = "<A-C-Right>";
action = {
__raw = "require('smart-splits').resize_right";
};
}
];
}

View file

@ -2,56 +2,4 @@
plugins.fugitive = {
enable = true;
};
keymaps = [
{
mode = ["n"];
key = "<leader>gc";
action = "<cmd>Git commit<cr>";
options = {
silent = true;
desc = "Commit Changes";
};
}
{
mode = ["n"];
key = "<leader>gC";
action = "<cmd>Git commit --amend<cr>";
options = {
silent = true;
desc = "Ammend Changes";
};
}
{
mode = ["n"];
key = "<leader>gd";
action = "<cmd>Git diff<cr>";
options = {
silent = true;
desc = "View diff";
};
}
{
mode = ["n"];
key = "<leader>gu";
action = "<cmd>Git restore --staged .<cr>";
options = {
silent = true;
desc = "Unstage all changes";
};
}
{
mode = ["n"];
key = "<leader>gp";
action = "<cmd>Git push<cr>";
options = {
silent = true;
desc = "Push changes to remote";
};
}
];
}

View file

@ -2,66 +2,4 @@
plugins.gitsigns = {
enable = true;
};
keymaps = [
{
mode = ["n" "v"];
key = "<leader>gs";
action = "<cmd>Gitsigns stage_hunk<cr>";
options = {
silent = true;
desc = "Stage Hunk";
};
}
{
mode = ["n"];
key = "<leader>gS";
action = "<cmd>Gitsigns stage_buffer<cr>";
options = {
silent = true;
desc = "Stage Buffer";
};
}
{
mode = ["n" "v"];
key = "<leader>gr";
action = "<cmd>Gitsigns reset_hunk<cr>";
options = {
silent = true;
desc = "Reset Hunk";
};
}
{
mode = ["n"];
key = "<leader>gR";
action = "<cmd>Gitsigns reset_buffer<cr>";
options = {
silent = true;
desc = "Reset Buffer";
};
}
{
mode = ["n"];
key = "<leader>gb";
action = "<cmd>Gitsigns toggle_current_line_blame<cr>";
options = {
silent = true;
desc = "Toggle Blame";
};
}
{
mode = ["n"];
key = "<leader>gB";
action = "<cmd>Gitsigns blame<cr>";
options = {
silent = true;
desc = "View Blame";
};
}
];
}

View file

@ -18,73 +18,12 @@
settings = {
defaults = {
layout_strategy = "horizontal";
# Reduce height / width of picker
# Reduce height / width of picker
layout_config = {
height = 0.8;
width = 0.8;
};
};
};
# Configure our telescope keymaps.
keymaps = {
# Find
"<leader>ff" = {
action = "find_files";
options = {
desc = "Find project files";
};
};
"<leader>fg" = {
action = "live_grep";
options = {
desc = "Find pattern";
};
};
"<leader>fb" = {
action = "buffers";
options = {
desc = "Find open buffers";
};
};
"<leader>fh" = {
action = "help_tags";
options = {
desc = "Find help tags";
};
};
"<leader>fc" = {
action = "commands";
options = {
desc = "Find commands";
};
};
# Git List
"<leader>glc" = {
action = "git_commits";
options = {
desc = "List git commits";
};
};
"<leader>glb" = {
action = "git_branches";
options = {
desc = "List git branches";
};
};
"<leader>gld" = {
action = "git_status";
options = {
desc = "List git diff";
};
};
"<leader>gls" = {
action = "git_stash";
options = {
desc = "List git stash";
};
};
};
};
}