https://github.com/shahshlok/vim-coach.nvim
Your Personal Coach
https://github.com/shahshlok/vim-coach.nvim
Last synced: 8 months ago
JSON representation
Your Personal Coach
- Host: GitHub
- URL: https://github.com/shahshlok/vim-coach.nvim
- Owner: shahshlok
- License: mit
- Created: 2025-07-09T18:53:13.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-07-09T19:01:03.000Z (8 months ago)
- Last Synced: 2025-07-10T04:48:50.949Z (8 months ago)
- Language: Lua
- Homepage:
- Size: 20.5 KB
- Stars: 18
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- my-awesome-github-stars - shahshlok/vim-coach.nvim - Your Personal Coach for Neovim (Lua)
README
# 🎯 vim-coach.nvim
> **Your personal Vim coach - A comprehensive, beginner-friendly command reference for Neovim**
A Neovim plugin that provides an interactive, searchable reference for all Vim commands with detailed explanations, beginner tips, and context-aware guidance. Perfect for absolute beginners who want to master Vim efficiently.
## ✨ Features
- 🔍 **Fuzzy searchable** - Find any command instantly with modern snacks.picker interface
- 📚 **120+ commands** - Comprehensive coverage of Vim motions, editing, visual mode, and plugins
- 🎓 **Beginner-focused** - Detailed explanations with "when to use" guidance
- 🌐 **Context-aware** - Different explanations for file vs explorer vs git contexts
- 💡 **Coaching tips** - Learn WHY and WHEN to use each command
- 📋 **Copy keybinds** - Press Enter or Ctrl+Y to copy commands to clipboard
- 📱 **Modern UI** - Clean interface with text wrapping and enhanced preview
- 🎯 **Categorized** - Browse by command type (motions, editing, visual, plugins)
## 🎪 Demo
```
? → Opens comprehensive command search
hm → Motion commands (h,j,k,l,w,b,f,etc.)
he → Editing commands (i,a,d,c,y,p,etc.)
hv → Visual mode commands
hp → Plugin-specific commands
```
## 📦 Installation
### [lazy.nvim](https://github.com/folke/lazy.nvim) (Recommended)
```lua
{
"shahshlok/vim-coach.nvim",
dependencies = {
"folke/snacks.nvim",
},
config = function()
require("vim-coach").setup()
end,
keys = {
{ "?", "VimCoach", desc = "Vim Coach" },
},
}
```
### [packer.nvim](https://github.com/wbthomason/packer.nvim)
```lua
use {
"shahshlok/vim-coach.nvim",
requires = {
"folke/snacks.nvim",
},
config = function()
require("vim-coach").setup()
end
}
```
### [vim-plug](https://github.com/junegunn/vim-plug)
```vim
Plug 'folke/snacks.nvim'
Plug 'shahshlok/vim-coach.nvim'
" In your init.lua or init.vim:
lua require('vim-coach').setup()
```
## 🚀 Usage
### Commands
| Command | Description |
|---------|-------------|
| `:VimCoach` | Open all commands |
| `:VimCoach motions` | Motion commands only |
| `:VimCoach editing` | Editing commands only |
| `:VimCoach visual` | Visual mode commands |
| `:VimCoach plugins` | Plugin commands |
| `:Coach` | Alias for `:VimCoach` |
### Default Keybindings
| Key | Command | Description |
|-----|---------|-------------|
| `?` | `:VimCoach` | Open comprehensive help |
| `hm` | `:VimCoach motions` | Motion commands |
| `he` | `:VimCoach editing` | Editing commands |
| `hv` | `:VimCoach visual` | Visual mode commands |
| `hp` | `:VimCoach plugins` | Plugin commands |
| `hh` | `:VimCoach all` | All commands |
### In the Picker
| Key | Action |
|-----|--------|
| `Enter` | Copy keybind to clipboard |
| `Ctrl+Y` | Copy keybind to clipboard |
| `Esc` | Close picker |
## ⚙️ Configuration
```lua
require("vim-coach").setup({
-- Disable default keymaps
-- Set vim.g.vim_coach_no_default_keymaps = 1 before setup
window = {
border = "rounded",
title_pos = "center",
},
keymaps = {
copy_keymap = "",
close = "",
},
})
```
### Disable Default Keymaps
If you want to set your own keymaps:
```lua
vim.g.vim_coach_no_default_keymaps = 1
require("vim-coach").setup()
-- Set your own keymaps
vim.keymap.set('n', '', 'VimCoach', { desc = 'Vim Coach' })
```
## 🎯 What Makes This Different?
Unlike other cheatsheet plugins, vim-coach.nvim provides:
### 📖 Comprehensive Explanations
```
Delete Line (dd)
├─ What: Deletes entire current line
├─ When: Removing code lines, empty lines
├─ Tip: Cursor can be anywhere on the line
├─ Context: In file: removes code | In explorer: may delete files
└─ Examples: dd, 2dd (delete 2 lines)
```
### 🧠 Beginner Coaching
- **WHY** use each command
- **WHEN** it's most effective
- **WHERE** it works (file vs explorer context)
- **HOW** it differs from similar commands
### 🔍 Smart Search
- Search by command name: "delete line"
- Search by keybind: "dd"
- Search by purpose: "remove text"
- Fuzzy matching finds everything
## 📚 Command Categories
| Category | Count | Description |
|----------|-------|-------------|
| **Motions** | 20+ | Movement commands (h,j,k,l,w,b,f,etc.) |
| **Editing** | 30+ | Text manipulation (i,a,d,c,y,p,etc.) |
| **Visual** | 25+ | Selection and visual mode operations |
| **Plugins** | 25+ | Common plugin commands (telescope, git, etc.) |
## 🛠️ Requirements
- Neovim >= 0.7
- [snacks.nvim](https://github.com/folke/snacks.nvim) (with picker support)
## 🤝 Contributing
We welcome contributions! Here's how you can help:
### Adding New Commands
1. Edit the appropriate file in `lua/vim-coach/commands/`
2. Follow the existing format:
```lua
{
name = "Command Name",
keybind = "key",
modes = {"n", "v"},
explanation = "What the command does",
beginner_tip = "Helpful tip for beginners",
when_to_use = "When this command is most useful",
context_notes = {
file = "Behavior in files",
explorer = "Behavior in explorers",
},
examples = {"example1", "example2"}
}
```
### Reporting Issues
- 🐛 Found a bug? [Open an issue](https://github.com/your-username/vim-coach.nvim/issues)
- 💡 Have a suggestion? [Start a discussion](https://github.com/your-username/vim-coach.nvim/discussions)
- 📝 Missing a command? [Request it](https://github.com/your-username/vim-coach.nvim/issues)
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [snacks.nvim](https://github.com/folke/snacks.nvim)
- Inspired by the need for better Vim learning resources
- Created for the Neovim community
## ⭐ Show Your Support
If this plugin helps you learn Vim, please give it a star! ⭐
---
**Happy Vimming!** 🎉
*"The best way to learn Vim is with a good coach by your side."*