🚀 Modular Neovim Configuration

A clean, fast, and fully-featured Neovim configuration with perfect separation of concerns. Built on modern plugins with LSP, TreeSitter, and Copilot integration. Originally forked from kickstart.nvim and transformed into a maintainable modular structure.

✨ Features

🎯 Core Features

• Modular Architecture - Clean separation between core settings, plugin specs, and configurations
• LSP Support - Full language server integration for C/C++, Python, Nix, LaTeX, and more
• Intelligent Completion - Blink.cmp with Copilot integration
• Fuzzy Finding - Telescope with FZF for lightning-fast file and text search
• Git Integration - Fugitive + Gitsigns for complete git workflow
• Syntax Highlighting - TreeSitter-based highlighting with automatic parser installation
• Debugging - Full DAP (Debug Adapter Protocol) support

🔧 Language Support

• C/C++ - clangd with automatic compile_commands.json detection
• Python - Pyright + Ruff for type checking and linting
• Nix - Full nixd integration
• LaTeX - TeXLab for document preparation
• CMake - CMake language server
• Lua - Optimized for Neovim config development

📁 Project Structure

nvim/
├── init.lua                    # Minimal bootstrapper
├── lua/
│   ├── core/                   # Core Neovim settings
│   │   ├── bootstrap.lua       # Lazy.nvim installation
│   │   ├── options.lua         # Editor options
│   │   ├── keymaps.lua         # Core keybindings
│   │   ├── autocmds.lua        # Auto commands
│   │   └── health.lua          # Health checks
│   └── plugins/
│       ├── spec/               # Plugin declarations
│       │   ├── lsp.lua         # Language servers
│       │   ├── blink.lua       # Completion
│       │   ├── telescope.lua   # Fuzzy finder
│       │   ├── treesitter.lua  # Syntax highlighting
│       │   ├── git.lua         # Git integration
│       │   └── ...             # Other plugins
│       └── config/             # Plugin configurations
│           ├── lsp/            # LSP setup
│           ├── blink.lua       # Completion config
│           ├── telescope.lua   # Telescope config
│           └── ...             # Other configs

🚀 Installation

Prerequisites

System Requirements

• Neovim >= 0.10
• Git - Version control
• Make - Build tool
• C Compiler - For native extensions
• ripgrep - Fast text search
• fd - Fast file finder

Language Servers (Install via Nix/Homebrew/Package Manager)

# Example with Nix
nix-env -iA nixpkgs.clang-tools    # clangd
nix-env -iA nixpkgs.pyright        # Python LSP
nix-env -iA nixpkgs.ruff           # Python linter
nix-env -iA nixpkgs.nixd           # Nix LSP
nix-env -iA nixpkgs.texlab         # LaTeX LSP

Install Configuration

Backup Existing Config

mv ~/.config/nvim ~/.config/nvim.backup

Clone This Repository

git clone https://github.com/yourusername/nvim.git ~/.config/nvim

Launch Neovim

nvim

The first launch will automatically:

1. Install lazy.nvim plugin manager
2. Download and install all plugins
3. Set up TreeSitter parsers

Health Check

After installation, run :checkhealth core to verify:

• Neovim version
• Required executables
• LSP servers
• Formatters

🔄 Syncing with Kickstart.nvim

This configuration maintains compatibility with upstream kickstart.nvim while keeping all customizations in a modular structure. Here's how to sync with kickstart updates:

Initial Setup (One Time)

# Add kickstart as a remote
git remote add kickstart https://github.com/nvim-lua/kickstart.nvim
git fetch kickstart

Checking for Updates

# See what changed in kickstart
git fetch kickstart
git log kickstart/master --oneline

# Review specific changes
git diff HEAD kickstart/master -- init.lua

Cherry-Picking Updates

# Option 1: Cherry-pick specific commits
git cherry-pick <commit-hash>

# Option 2: Manually review and integrate changes
git diff kickstart/master -- init.lua | less

# Option 3: Check for specific feature updates (e.g., telescope)
git diff kickstart/master -- init.lua | grep -A5 -B5 telescope

Update Workflow

1. Review Changes: Check kickstart's commit history for interesting updates
2. Test Locally: Apply changes in a test branch first
3. Adapt to Modular Structure: Move any new plugins/configs to appropriate lua/plugins/ files
4. Document: Update relevant documentation for new features

Example: Adding a New Plugin from Kickstart

If kickstart adds a new plugin in their init.lua:

1. Create a new spec file: lua/plugins/spec/newplugin.lua
2. Add configuration to: lua/plugins/config/newplugin.lua (if needed)
3. Update: lua/plugins/spec/init.lua to import the new spec

⌨️ Key Mappings

Leader Key

The leader key is set to <Space>.

Essential Keybindings

File Navigation

Key	Description
<leader>sf	Search Files
<leader>sg	Search by Grep
<leader>sh	Search Help
<leader><leader>	Switch buffers
<leader>/	Fuzzy search in current buffer

LSP Features

Key	Description
gd	Goto Definition
gr	Goto References
gI	Goto Implementation
<leader>rn	Rename symbol
<leader>ca	Code Action
K	Hover documentation
<space>f	Format buffer

Git Operations

Key	Description
<leader>gs	Git status (Fugitive)
<leader>gd	Git diff
<leader>gc	Git commit
<leader>gb	Git blame
]c	Next git change
[c	Previous git change
<leader>hs	Stage hunk
<leader>hr	Reset hunk

Debugging

Key	Description
<F5>	Start/Continue debugging
<F10>	Step over
<F11>	Step into
<F12>	Step out
<leader>db	Toggle breakpoint
<F7>	Toggle debug UI

Window Navigation (Tmux-aware)

Key	Description
<C-h>	Navigate left
<C-j>	Navigate down
<C-k>	Navigate up
<C-l>	Navigate right

Completion Keybindings

Key	Description
<C-Space>	Trigger completion
<C-y>	Accept completion
<C-e>	Cancel completion
<Tab>	Next snippet placeholder
<S-Tab>	Previous snippet placeholder

🔌 Installed Plugins

Core

• lazy.nvim - Plugin manager
• plenary.nvim - Lua utilities

Editor Enhancement

• mini.nvim - Collection of minimal plugins
• Comment.nvim - Smart commenting
• vim-sleuth - Auto-detect indentation
• nvim-autopairs - Auto-close brackets
• indent-blankline.nvim - Indent guides
• vim-illuminate - Highlight word under cursor

UI/Theme

• tokyonight.nvim - Color scheme
• which-key.nvim - Keybinding hints
• todo-comments.nvim - Highlight TODO comments

Navigation

• telescope.nvim - Fuzzy finder
• telescope-fzf-native.nvim - FZF sorter
• vim-tmux-navigator - Seamless tmux navigation

Git

• vim-fugitive - Git commands
• gitsigns.nvim - Git gutter signs

LSP & Completion

• nvim-lspconfig - LSP configurations
• blink.cmp - Completion engine
• lazydev.nvim - Lua development
• fidget.nvim - LSP progress

Development

• nvim-treesitter - Syntax highlighting
• nvim-treesitter-textobjects - Syntax-aware text objects
• copilot.lua - GitHub Copilot
• conform.nvim - Formatting
• nvim-dap - Debug Adapter Protocol
• nvim-dap-ui - Debug UI

🛠️ Configuration

Customization

All configuration files are designed to be easily customizable:

1. Core Settings: Edit files in lua/core/

   • options.lua - Vim options
   • keymaps.lua - Core keybindings

2. Add Plugins: Create new spec files in lua/plugins/spec/

   -- lua/plugins/spec/myplugin.lua
   return {
     'username/plugin-name',
     opts = {
       -- plugin options
     }
   }

3. Complex Plugin Config: Add config files to lua/plugins/config/

LSP Server Configuration

LSP servers are configured in lua/plugins/config/lsp/init.lua. Add new servers to the servers table:

servers = {
  myserver = {
    settings = {
      -- server-specific settings
    }
  }
}

Formatter Configuration

Formatters are configured in lua/plugins/spec/formatting.lua:

formatters_by_ft = {
  javascript = { "prettier" },
  -- add your formatters here
}

🔧 Commands

Custom Commands

• :ReloadLSP - Restart all LSP servers

Health Check

• :checkhealth core - Run configuration health check

Plugin Management

• :Lazy - Open plugin manager UI
• :Lazy sync - Update all plugins
• :Lazy profile - Profile startup time

🐛 Troubleshooting

First Steps

1. Run :checkhealth core to verify installation
2. Check :messages for error messages
3. Ensure all prerequisites are installed

Common Issues

Plugins not loading

• Run :Lazy sync to ensure all plugins are installed
• Check for errors in :messages

LSP not working

• Verify language servers are installed (check with :checkhealth core)
• Run :LspInfo to see active servers
• Try :ReloadLSP to restart servers

Telescope not finding files

• Ensure ripgrep and fd are installed
• Check you're not in a git-ignored directory

📝 License

This configuration is based on kickstart.nvim and is available under the MIT License.

🙏 Acknowledgments

• kickstart.nvim - Initial configuration structure
• Neovim - The best text editor
• All plugin authors for their amazing work

🤝 Contributing

Contributions are welcome! Feel free to:

• Report issues
• Suggest new features
• Submit pull requests

---

Happy Coding! 🎉