mirror
/
kickstart.nvim
mirror of https://github.com/nvim-lua/kickstart.nvim.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity
kickstart.nvim/CLAUDE.md

234 lines
8.9 KiB
Markdown
Raw Blame History

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Overview
This is a Neovim configuration based on kickstart.nvim, refactored into a modular structure for better organization and maintainability. The configuration separates core settings, keymaps, and plugins into logical modules.
## Architecture
### Modular Configuration Structure
The configuration is organized into three main directories:
```
~/.config/nvim/
├── init.lua # Bootstrap file that loads everything
├── lua/
│ ├── config/ # Core Neovim configuration
│ │ ├── options.lua # Vim settings (leader, numbering, clipboard, etc.)
│ │ ├── keymaps.lua # Global key mappings
│ │ └── autocommands.lua # Autocommands (highlight on yank, etc.)
│ ├── plugins/ # Plugin specifications (auto-loaded by lazy.nvim)
│ │ ├── autopairs.lua # Auto-close brackets and quotes
│ │ ├── claude-code.lua # Claude Code integration
│ │ ├── colorscheme.lua # Color scheme (kanso.nvim + alternatives)
│ │ ├── completion.lua # blink.cmp & LuaSnip
│ │ ├── flash.lua # Rapid cursor movement
│ │ ├── formatting.lua # conform.nvim for code formatting
│ │ ├── gitsigns.lua # Git signs and operations
│ │ ├── harpoon.lua # File bookmarking
│ │ ├── lsp.lua # LSP configuration & Mason
│ │ ├── lualine.lua # Status line
│ │ ├── oil.lua # File browser
│ │ ├── snacks.lua # Utility plugin
│ │ ├── telescope.lua # Fuzzy finder
│ │ ├── treesitter.lua # Syntax highlighting & parsing
│ │ ├── vim-sleuth.lua # Auto-detect indentation
│ │ ├── vim-tmux-navigator.lua # Tmux/Vim navigation
│ │ ├── which-key.lua # Keybinding hints
│ │ └── optional/ # Optional plugins (not loaded by default)
│ │ ├── README.md # Instructions for enabling optional plugins
│ │ ├── debug.lua # DAP debugger for Go
│ │ ├── indent-blankline.lua # Indentation guides
│ │ └── lint.lua # Linting with nvim-lint
│ └── custom/
│ └── plugins/
│ └── init.lua # User-added custom plugins
```
### Plugin Management
- **Plugin Manager**: lazy.nvim (bootstrapped in init.lua)
- **Auto-Loading**: All files in `lua/plugins/*.lua` are automatically loaded
- **Custom Plugins**: Add your own in `lua/custom/plugins/init.lua` or create new files there
### Key Plugins
Each plugin is in its own file for easy management:
- **lsp.lua** - LSP configuration with Mason, servers: `pyright`, `zls`, `rust_analyzer`, `ts_ls`, `lua_ls`
- **completion.lua** - blink.cmp autocompletion with LuaSnip snippets
- **telescope.lua** - Fuzzy finder with vertical layout, fzf and ui-select extensions
- **harpoon.lua** - Quick file bookmarking and navigation
- **flash.lua** - Rapid cursor movement with `s`, `S`, `r`, `R` keys
- **oil.lua** - File browser with `-` key binding
- **vim-tmux-navigator.lua** - Seamless tmux/vim split navigation
- **formatting.lua** - conform.nvim with format-on-save (stylua, prettier)
- **gitsigns.lua** - Git signs in gutter with staging/diffing keymaps
- **which-key.lua** - Keybinding hints popup
- **lualine.lua** - Status line with base16 theme
- **treesitter.lua** - Syntax highlighting for multiple languages
- **autopairs.lua** - Auto-close brackets and quotes
- **vim-sleuth.lua** - Auto-detect indentation
- **snacks.lua** - Utility plugin collection
- **colorscheme.lua** - Multiple color schemes (kanso active)
## Common Commands
### Plugin Management
```
:Lazy " View plugin status
:Lazy update " Update all plugins
:Mason " Manage LSP servers and tools (press g? for help)
```
### LSP & Diagnostics
```
:LspInfo " Show LSP client status
:ConformInfo " Show formatter status
<leader>q " Open diagnostic quickfix list
```
### File Navigation
```
<leader>sf " Search files
<leader>sg " Live grep
<leader><leader> " Find buffers
<leader>sn " Search Neovim config files
- " Open Oil file browser (parent directory)
```
### Harpoon (File Bookmarking)
```
<leader>a " Add file to Harpoon
<leader>e " Toggle Harpoon menu
<leader>1-4 " Jump to Harpoon mark 1-4
<leader>n/<leader>p " Next/Previous Harpoon mark
```
### Code Operations
```
grn " LSP rename
gra " Code action
grr " Find references (Telescope)
grd " Go to definition (Telescope)
gri " Go to implementation (Telescope)
grt " Go to type definition (Telescope)
gO " Document symbols (Telescope)
gW " Workspace symbols (Telescope)
<leader>m " Format buffer
```
### Git Operations (gitsigns)
```
]c / [c " Next/previous git change
<leader>hs " Stage hunk
<leader>hr " Reset hunk
<leader>hS " Stage buffer
<leader>hu " Undo stage hunk
<leader>hR " Reset buffer
<leader>hp " Preview hunk
<leader>hb " Blame line
<leader>hd " Diff against index
<leader>hD " Diff against last commit
<leader>tb " Toggle git blame line
<leader>tD " Toggle git show deleted
```
## Configuration Details
### Settings (lua/config/options.lua)
- Leader key: `<space>`
- Line numbers: relative + absolute
- No line wrapping
- Clipboard: synced with OS
- Undo history: persisted
- Scrolloff: 10 lines
- Cursor: blinking block in normal mode, vertical bar in insert
### Treesitter Languages (lua/plugins/treesitter.lua)
Auto-installed parsers for: zig, python, typescript, rust, htmldjango, bash, c, html, lua, markdown, vim
### Color Scheme (lua/plugins/colorscheme.lua)
Currently using kanso.nvim. Several commented-out alternatives available (gruvbox-material, catppuccin, kanagawa, zenbones, vague).
### Custom Keymaps (lua/config/keymaps.lua)
- `<C-d>/<C-u>`: Page down/up with recentering
- `<C-h/j/k/l>`: Window navigation
- `<Esc>`: Clear search highlights
## Development Notes
### Modifying Configuration
**Core Settings**: Edit files in `lua/config/`
- `options.lua` - Vim options and settings
- `keymaps.lua` - Global key mappings
- `autocommands.lua` - Autocommands
**Plugins**: Edit corresponding files in `lua/plugins/`
- Each plugin category has its own file
- Changes take effect after `:source $MYVIMRC` or restarting Neovim
- Run `:Lazy sync` if plugins were added/removed
### Adding New Plugins
1. **Create a new file** in `lua/plugins/` (e.g., `my-plugin.lua`)
2. **Return a table** with plugin specs:
```lua
return {
{
'author/plugin-name',
config = function()
-- plugin configuration
end,
},
}
```
3. **Restart Neovim** - lazy.nvim will auto-discover and load it
### Adding New LSP Servers
1. Edit `lua/plugins/lsp.lua`
2. Add server to the `servers` table
3. Optionally add to `ensure_installed`
4. Restart Neovim - mason-tool-installer will auto-install
### Adding Formatters
1. Edit `lua/plugins/formatting.lua`
2. Add to `formatters_by_ft` table
3. Install via `:Mason` or ensure it's in PATH
4. Optionally add to `ensure_installed` in `lua/plugins/lsp.lua`
### Plugin Organization Philosophy
- **One Plugin Per File**: Each plugin has its own dedicated file in `lua/plugins/` (except colorscheme.lua which contains theme options)
- **Easy Discovery**: Plugin files are named after the plugin they configure
- **Modular**: Add/remove individual plugins by managing single files
- **Custom Additions**: Use `lua/custom/plugins/` for your personal plugins without modifying core structure
### Optional Plugins
The `lua/plugins/optional/` directory contains plugins that are not enabled by default but may be useful:
- **debug.lua** - DAP debugger primarily configured for Go (extensible to other languages)
- **indent-blankline.lua** - Adds indentation guides on blank lines
- **lint.lua** - Linting with nvim-lint (includes markdown example)
**To enable an optional plugin**, move it from `lua/plugins/optional/` to `lua/plugins/`:
```bash
mv lua/plugins/optional/debug.lua lua/plugins/debug.lua
```
Or import it directly in your `init.lua`:
```lua
require('lazy').setup({
{ import = 'plugins' },
{ import = 'plugins.optional.debug' }, -- Enable debug plugin
})
```
See `lua/plugins/optional/README.md` for more details.
Reference in New Issue View Git Blame Copy Permalink