Neovim Configuration with Lua and LSP

A modern, fully-featured Neovim configuration with LSP support, tmux integration, and a beautiful UI.

---

Table of Contents

• Features
• Requirements
• Installation
• Tmux Integration Setup
• Key Bindings
• Colorschemes
• Configuration Structure
• Language Server Setup
• Customization
• Troubleshooting
• Configuration Check
• Resources
• Plugins
• Contributing
• Disclaimer
• Thanks

📸 Screenshots

Alpha Dashboard

🖼️ View More Screenshots

Colorschemes

🐱 Catppuccin (Default)

🎨 View More Colorschemes

🌙 OneDark

🌸 Kanagawa

🔥 Monokai Pro

🌹 Rose Pine

✨ Features

• 🚀 Fast startup with lazy loading via lazy.nvim
• 🔍 LSP support with auto-completion, diagnostics, and code actions
• 📁 File explorer with nvim-tree
• 🔭 Fuzzy finder with telescope.nvim
• 🎨 Multiple colorschemes (Catppuccin, OneDark, Kanagawa, etc.)
• 🔄 Tmux integration for seamless navigation
• 📊 Status line with git integration
• 🌳 Treesitter for enhanced syntax highlighting
• 🎯 Auto-completion with nvim-cmp
• 🛠️ External tools integration with Mason

📋 Requirements

Core Requirements

• Neovim >= 0.11.0 (uses the native vim.lsp configuration API)
• Git (for plugin management)
• Node.js (for LSP servers)
• Python (for LSP servers)

Optional but Recommended

• tmux (for tmux integration)
• ripgrep (for telescope live grep functionality)
• fd (for faster telescope file finding)
• wget (for Mason package downloads)

Installation Commands

macOS (Homebrew):

# Core tools
brew install neovim git node python3

# Optional tools
brew install tmux ripgrep fd wget

Ubuntu/Debian:

# Core tools
sudo apt update
sudo apt install neovim git nodejs npm python3 python3-pip

# Optional tools
sudo apt install tmux ripgrep fd-find wget

Arch Linux:

# Core tools
sudo pacman -S neovim git nodejs npm python python-pip

# Optional tools
sudo pacman -S tmux ripgrep fd wget

🚀 Installation

1. Backup your existing configuration (if any):

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

2. Clone this repository:

   git clone https://github.com/CollatzConjecture/neovim-lua ~/neovim-config

3. Copy the nvim configuration:

   cp -r ~/neovim-config/nvim ~/.config/nvim

4. Start Neovim:

   nvim

   The configuration will automatically:

   • Install the plugin manager (lazy.nvim)
   • Download and install all plugins
   • Set up LSP servers via Mason

🔧 Tmux Integration Setup

This configuration includes a beautiful oh-my-tmux setup with colorful status bar, powerline separators, and vim integration.

Complete Tmux Setup

1. Copy both tmux configuration files:

   # Main oh-my-tmux configuration
   cp ~/neovim-config/nvim/tmux.conf ~/.config/tmux/tmux.conf
   
   # Custom local configuration with colorful theme
   cp ~/neovim-config/nvim/tmux.conf.local ~/.config/tmux/tmux.conf.local

   Or if you've already copied the nvim folder:

   mkdir -p ~/.config/tmux
   cp ~/.config/nvim/tmux.conf ~/.config/tmux/tmux.conf
   cp ~/.config/nvim/tmux.conf.local ~/.config/tmux/tmux.conf.local

2. Reload tmux configuration:

   tmux source-file ~/.config/tmux/tmux.conf

Features

• 🎨 Colorful status bar with oh-my-tmux theming
• ⚡ Battery indicator with colorful gradient bar
• 📡 Powerline separators with angled shapes
• 🚀 Vim integration with vim-tmux-navigator
• ⌨️ Vi mode keys in copy mode
• 🖱️ Mouse support enabled

Key Bindings

Prefix Key: Ctrl + a (changed from default Ctrl + b)

Window Management:

• Ctrl + a + c - Create new window
• Ctrl + a + | - Split window horizontally
• Ctrl + a + - - Split window vertically
• Ctrl + a + Ctrl + h - Previous window
• Ctrl + a + Ctrl + l - Next window
• Alt + 1-9 - Jump directly to window 1-9

Pane Navigation (works seamlessly with Neovim):

• Ctrl + h - Move left (pane/vim split)
• Ctrl + j - Move down (pane/vim split)
• Ctrl + k - Move up (pane/vim split)
• Ctrl + l - Move right (pane/vim split)

Copy Mode (vim-style):

• Ctrl + a + [ - Enter copy mode
• h/j/k/l - Navigate with vim motions
• v - Start visual selection
• y - Copy selection
• / and ? - Search

Session Management:

• Ctrl + a + N - Create new session
• Ctrl + a + X - Kill current session

The integration automatically detects whether you're in Neovim or tmux and navigates accordingly.

⌨️ Key Bindings

Leader Keys

• Leader: Space
• Local Leader: \

Core Navigation

• kk - Exit insert mode
• <leader>c - Clear search highlighting
• <leader>r - Reload configuration
• <leader>s - Save file
• <leader>q - Quit all

File Management

• <leader>e - Toggle file explorer
• <leader>f - Refresh file explorer
• <leader>n - Find current file in explorer

Fuzzy Finding (Telescope)

• <leader>ff - Find files
• <leader>fg - Live grep
• <leader>fb - List buffers
• <leader>fh - Help tags

LSP Features

• gd - Go to definition
• gD - Go to declaration
• gi - Go to implementation
• gr - Find references
• K - Show hover documentation
• <leader>rn - Rename symbol
• <leader>ca - Code actions
• <leader>f - Format code
• gl - Show line diagnostics
• [d - Previous diagnostic
• ]d - Next diagnostic

Terminal

• Ctrl + t - Open terminal
• Esc - Exit terminal mode (in terminal)

🎨 Colorschemes

Available colorschemes:

• Catppuccin (default)
• OneDark
• Kanagawa
• Monokai Pro
• Rose Pine

Switch colorschemes by editing lua/core/colors.lua.

🔧 Configuration Structure

Repository Structure:
├── img/                    # Documentation images
├── nvim/                   # Neovim configuration folder
│   ├── lua/
│   │   ├── core/
│   │   │   ├── autocmds.lua    # Auto-commands
│   │   │   ├── colors.lua      # Colorscheme configuration
│   │   │   ├── keymaps.lua     # Key mappings
│   │   │   ├── lazy.lua        # Plugin manager setup
│   │   │   ├── options.lua     # Neovim options
│   │   │   └── statusline.lua  # Status line configuration
│   │   ├── lsp/
│   │   │   └── lspconfig.lua   # LSP configuration
│   │   └── plugins/
│   │       ├── alpha-nvim.lua  # Dashboard
│   │       ├── indent-blankline.lua
│   │       ├── none-ls.lua     # External formatters/linters
│   │       ├── nvim-cmp.lua    # Auto-completion
│   │       ├── nvim-tree.lua   # File explorer
│   │       ├── nvim-treesitter.lua
│   │       ├── telescope.lua   # Fuzzy finder
│   │       └── tmux.lua        # Tmux integration
│   ├── init.lua            # Entry point
│   └── tmux.conf           # Tmux configuration template
├── .gitignore
├── LICENSE
└── README.md

After Installation (~/.config/nvim/):
├── lua/
│   ├── core/              # Core configuration files
│   ├── lsp/               # LSP configuration
│   └── plugins/           # Plugin configurations
├── init.lua                # Entry point
└── tmux.conf              # Tmux configuration template

🛠️ Language Server Setup

The configuration automatically installs LSP servers for:

• Bash (bashls)
• Python (pyright)
• C/C++ (clangd)
• HTML (html)
• CSS (cssls)
• TypeScript/JavaScript (ts_ls)
• Lua (lua_ls)

Additional servers can be added in lua/lsp/lspconfig.lua.

🎯 Customization

Adding New Plugins

1. Add plugin specification to ~/.config/nvim/lua/core/lazy.lua
2. Create configuration file in ~/.config/nvim/lua/plugins/
3. Add plugin-specific keymaps to the config file

Changing Colorscheme

Edit ~/.config/nvim/lua/core/colors.lua and change:

vim.cmd.colorscheme("your-colorscheme")

Adding LSP Servers

Edit ~/.config/nvim/lua/lsp/lspconfig.lua and add to the servers table:

local servers = {
  'bashls',
  'pyright',
  'your-new-server',  -- Add here
}

🐛 Troubleshooting

Plugin Installation Issues

# Clear plugin cache
rm -rf ~/.local/share/nvim/lazy/
nvim --headless "+Lazy! sync" +qa

LSP Server Issues

# Check Mason installation
:Mason
# Reinstall server
:MasonUninstall server-name
:MasonInstall server-name

Tmux Navigation Not Working

1. Verify tmux configuration is loaded: tmux source-file ~/.tmux.conf
2. Check if bc is installed: which bc
3. Restart tmux session

✅ Configuration Check

• Health Check: Open nvim and run :checkhealth to verify everything is working correctly:

  :checkhealth

• Startup Time: Check nvim startup performance:

  nvim --startuptime startup.log
  nvim startup.log

• Plugin Status: Check plugins configuration and startup time:

  :checkhealth lazy
  :Lazy profile

• LSP Status: Open a source file and verify LSP is working:

  :LspInfo

📚 Resources

• Neovim Documentation
• Lazy.nvim Documentation
• vim-tmux-navigator
• LSP Configuration
• Oh My Tmux - Beautiful tmux configuration
• Vim Cheat Sheet - Learn vim commands and motions
• Lua - Neovim docs
• Lua-guide - Neovim docs
• Everything you need to know to configure neovim using lua

Plugins

lazy.nvim - A modern plugin manager for Neovim

lualine.nvim - A blazing fast and easy to configure neovim statusline plugin written in pure lua

nvim-lspconfig - A collection of common configurations for Neovim's built-in language server client

mason.nvim - Portable package manager for Neovim that runs everywhere Neovim runs

nvim-cmp - A completion plugin for neovim coded in Lua

LuaSnip - Snippet Engine for Neovim written in Lua

telescope.nvim - Find, Filter, Preview, Pick. All lua, all the time

nvim-tree.lua - A file explorer tree for neovim written in lua

nvim-treesitter - Treesitter configurations and abstraction layer for Neovim

indent-blankline.nvim - Indent guides for Neovim

nvim-autopairs - Autopairs for neovim written by lua

gitsigns.nvim - Git integration for buffers

alpha-nvim - A lua powered greeter like vim-startify / dashboard-nvim

vim-tmux-navigator - Seamless navigation between tmux panes and vim splits

catppuccin - Soothing pastel theme for Neovim

nvim-web-devicons - lua fork of vim-web-devicons for neovim

🤝 Contributing

Feel free to submit issues and enhancement requests!

---

Disclaimer

This setup is based on the KISS principle, probably some concepts may not be valid for everyone. Then feel free to take what you need but don't install anything without checking first!

This setup is not a Framework but it is a configuration that can be used by default as it can be a starting point to understand how Neovim is structured and maybe improve this config. It tries to stay as simple as possible, with each addition weighted along these lines.

Less is more

🙏 Thanks

• brainfucksec for the amazing neovim-lua project that served as inspiration for this configuration
• folke for the incredible lazy.nvim plugin manager
• christoomey for vim-tmux-navigator that makes tmux + vim integration seamless
• All the amazing plugin authors who make Neovim extensible and powerful
• All contributors who help improve this setup with their reports and advice

📄 License

This configuration is open source and available under the GPL-3.0 License.