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
• Cheat Sheet
• Colorschemes
• Configuration Structure
• Language Server Setup
• Customization
• Troubleshooting
• Configuration Check
• Resources
• Plugins
• Contributing
• Disclaimer
• Thanks

📸 Screenshots

Alpha Dashboard

🖼️ View More Screenshots

Colorschemes

🌙 One Dark Pro (Default)

🎨 View More Colorschemes

🐱 Catppuccin

🌸 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 (One Dark Pro, Catppuccin, Kanagawa, etc.)
• 🔄 Tmux integration for seamless navigation
• 📊 Status line with git integration
• 🌳 Treesitter for enhanced syntax highlighting
• 🎯 Auto-completion with nvim-cmp
• 🧭 Code outline powered by LSP and Treesitter
• 🚦 Structured diagnostics with Trouble
• 💬 Floating command line and message history with Noice
• ✨ External formatting with Conform and automatically managed formatter binaries
• 🛠️ External tools integration with Mason

📋 Requirements

Core Requirements

• Neovim >= 0.12.0 (uses the current Treesitter and native LSP APIs)
• 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)
• LazyGit (enables the :LazyGit floating Git UI inside Neovim)

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

📝 Cheat Sheet

Looking for key bindings or quick tips? Everything now lives in docs/cheatsheet.md.
That reference also reminds you that pressing g? inside NvimTree opens its built-in help overlay.

🎨 Colorschemes

Available colorschemes:

• One Dark Pro (default)
• Catppuccin
• Kanagawa
• Monokai Pro
• Rose Pine

Switch colorschemes by changing the colorscheme value in lua/core/colors.lua. Only the selected theme is loaded at startup.

🔧 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
│   │       ├── conform.lua     # External formatters
│   │       ├── 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)
• ESLint (eslint)
• Lua (lua_ls)
• Svelte (svelte)

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:

local 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

mason-tool-installer.nvim - Automatically installs configured formatters through Mason

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

mini.surround - Add, delete, and replace surrounding characters

lazydev.nvim - LuaLS support for editing Neovim Lua configurations

conform.nvim - Lightweight external formatter runner

aerial.nvim - LSP and Treesitter-powered code outline

trouble.nvim - Structured diagnostics, references, symbols, and quickfix views

noice.nvim - Floating command line, messages, and notification history

which-key.nvim - Discoverable keybinding hints

gitsigns.nvim - Git integration for buffers lazygit.nvim - Floating LazyGit terminal within Neovim

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

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

onedarkpro.nvim - One Dark Pro theme and the default colorscheme

catppuccin - Soothing pastel theme for Neovim

nvim-web-devicons - Filetype icons 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.