Neovim Configuration Template

A standardized Neovim configuration template with best practices and modern plugins

Features • Requirements • Installation • Customization • Plugins • Key Mappings • Contributing • License

Features

• 📦 Plugin Management - Modern plugin system with lazy.nvim
• ⚡ Performance - Fast startup time with lazy loading
• 🧠 Completion - Powerful completion with blink.cmp
• 🔍 Diagnostics - Advanced diagnostics with Trouble
• 🎨 Beautiful UI - Modern look with Catppuccin and Noice
• 📂 File Explorer - Integrated explorer with Snacks
• 🔭 Fuzzy Finding - Telescope for searching files, text, and much more
• 📊 Performance - Profiling tools built-in for optimization
• ⌨️ Keymaps - Comprehensive mappings with which-key integration
• 🧩 Modular - Well-structured and modular configuration

Requirements

• Neovim 0.8 or higher (0.9+ recommended)
• Git 2.19.0 or higher
• A Nerd Font (optional but recommended)
• ripgrep for Telescope (optional)
• fd for faster file finding (optional)
• lazygit for Git integration (optional)

Installation

Quick Install

# Backup your existing config if needed
mv ~/.config/nvim ~/.config/nvim.bak

# Clone the template
git clone https://github.com/greggh/neovim-config-template.git ~/.config/nvim

# Start Neovim - plugins will be installed automatically
nvim

Manual Exploration

If you want to understand the template before installing:

# Clone to a temporary location
git clone https://github.com/greggh/neovim-config-template.git /tmp/nvim-template

# Look through the files
cd /tmp/nvim-template

Customization

Using User Config

The easiest way to customize is by creating a lua/user/init.lua file:

-- In lua/user/init.lua
return {
  -- Override options
  options = {
    tabstop = 4,
    background = "light",
  },
  
  -- Add your own plugins
  plugins = {
    "YOUR_USERNAME/custom-plugin",
    { "another/plugin", config = true },
  },
  
  -- Execute custom code
  setup = function()
    -- Any custom code you want to run
    vim.g.my_custom_var = "value"
  end,
}

Directory Structure

~/.config/nvim/
├── init.lua                 # Entry point
├── lua/
│   ├── config/              # Core configuration
│   │   ├── autocmd.lua      # Auto commands
│   │   ├── keymaps.lua      # Key mappings
│   │   ├── lazy.lua         # Plugin manager setup
│   │   └── options.lua      # Vim options
│   ├── plugins/             # Plugin configurations
│   │   ├── coding/          # Coding plugins (treesitter, completion)
│   │   ├── colorscheme/     # Themes and colors
│   │   ├── diagnostics/     # Linting and diagnostics
│   │   ├── lsp/             # LSP configurations
│   │   └── ui/              # UI enhancements
│   └── utils/               # Utility functions
└── tests/                   # Tests for your config

Plugins

This template includes a carefully selected set of plugins:

Core Plugins

• lazy.nvim - Modern plugin manager
• plenary.nvim - Lua functions library
• blink.cmp - Advanced completion (placeholder)

Editor Features

• nvim-treesitter - Syntax highlighting
• telescope.nvim - Fuzzy finder
• which-key.nvim - Keybinding helper
• todo-comments.nvim - Highlight TODOs
• trouble.nvim - Diagnostics list

UI Enhancements

• catppuccin - Modern colorscheme
• lualine.nvim - Status line
• noice.nvim - UI enhancements
• snacks.nvim - File explorer (placeholder)

See the lua/plugins directory for the complete list and configurations.

Key Mappings

This template uses Space as the leader key. Here are some important mappings:

Mapping	Description
<leader>e	Toggle file explorer
<leader>ff	Find files
<leader>fg	Live grep
<leader>fb	Find buffers
<leader>gg	Open LazyGit
<leader>xx	Open diagnostics list
<leader>pp	Generate profile report
<leader>nn	Open notifications panel

For a complete list, press <leader> to see a which-key popup, or check lua/config/keymaps.lua.

Profiling

Built-in profiling tools help you optimize your configuration:

Mapping	Description
<leader>pp	Generate profile report
<leader>ps	Show profile summary
<leader>pL	List all profile logs
<leader>pa	Analyze plugin performance
<leader>pc	Clean up profile logs

Enable profiling by starting Neovim with:

NVIM_PROFILE=1 nvim

Discussions

Have questions or ideas? Join the conversation in GitHub Discussions.

• Questions: For help with configuration or troubleshooting
• Ideas: Suggest new features or improvements
• Show and Tell: Share your customizations and setups
• General: For any other topics related to this configuration

Contributing

Contributions are welcome! Check out CONTRIBUTING.md for guidelines.

Development Setup

1. Clone the repository:

   git clone https://github.com/greggh/neovim-config-template.git
   cd neovim-config-template

2. Install development dependencies:

   • Neovim 0.8+
   • Luacheck for linting
   • StyLua for formatting

3. Set up pre-commit hooks (important first step!):

   ./scripts/setup-hooks.sh

   This will enable automatic formatting, linting, and testing before each commit. Make sure to run this before making any changes to ensure code quality.

Project Structure

.
├── lua/               # Lua configuration files
│   ├── config/        # Core configuration modules
│   ├── plugins/       # Plugin configurations
│   └── utils/         # Utility functions
├── plugin/            # Plugin files that are always loaded
├── tests/             # Test suite
├── .github/           # GitHub workflows and templates
├── .githooks/         # Git hooks for development
├── scripts/           # Development and utility scripts
├── .stylua.toml       # StyLua configuration
├── .luacheckrc        # Luacheck configuration
└── init.lua           # Main entry point

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• lazy.nvim - The plugin manager that makes this configuration possible
• Kickstart.nvim - Inspiration for some aspects of this template
• Neovim - The foundation of modern text editing
• hooks-util - Git hooks framework used in this project

---

Made with ❤️ by greggh