seliaste/nvim-config
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

migration complete

Browse source
This commit is contained in:
Anup Sebastian 2025-11-01 03:01:29 -05:00
parent c0c1148fde
commit 88d84fee4c
34 changed files with 4641 additions and 281 deletions
Download patch file Download diff file Expand all files Collapse all files

316
docs/DOCUMENTATION-PLAN.md Normal file
View file

@ -0,0 +1,316 @@
# 📋 Documentation Plan & Status
## ✅ Completed
### 1. Changed <Space> to <Leader> in Cheatsheet
- Updated `lua/plugins/core/cheatsheet.lua`
- All 105 instances of `<Space>` changed to `<Leader>`
- Ensures consistency with which-key display
### 2. Created New Professional README.md
- Location: `README.new.md` (ready to replace README.md)
- Features: Badges, features list, requirements, quick start
- Links to comprehensive documentation structure
- Professional appearance with emojis and formatting
### 3. Created Documentation Structure
```
docs/
├── README.md # Main documentation index ✅
├── getting-started/
│ ├── README.md # Getting started overview ✅
│ ├── installation.md # Detailed install steps (TODO)
│ ├── first-steps.md # First hour tutorial (TODO)
│ ├── quick-reference.md # Essential commands (TODO)
│ └── philosophy.md # Design principles (TODO)
├── keymaps/
│ ├── README.md # Keymaps overview ✅
│ ├── core.md # Leader key bindings (TODO)
│ ├── lsp.md # LSP commands (TODO)
│ ├── plugins.md # Plugin-specific (TODO)
│ ├── debug.md # Debug keymaps (TODO)
│ ├── consistency.md # Cross-plugin patterns ✅ (copied)
│ └── duplicates.md # Duplicate keys guide ✅ (copied)
├── plugins/
│ ├── README.md # Plugins overview (TODO)
│ ├── core.md # Telescope, Neo-tree, which-key (TODO)
│ ├── editor.md # TreeSitter, mini.nvim, etc (TODO)
│ ├── lsp.md # LSP & completion (TODO)
│ ├── debug.md # nvim-dap (TODO)
│ ├── git.md # Git integration (TODO)
│ └── ui.md # UI enhancements (TODO)
├── languages/
│ ├── README.md # Languages overview (TODO)
│ ├── flutter.md # Flutter/Dart guide (TODO)
│ ├── rust.md # Rust guide (TODO)
│ ├── python.md # Python guide (TODO)
│ ├── svelte.md # Svelte guide (TODO)
│ ├── typescript.md # TypeScript guide (TODO)
│ ├── go.md # Go guide (TODO)
│ └── others.md # Other languages (TODO)
├── vim-mastery/
│ ├── README.md # Vim mastery overview ✅
│ ├── week-01-motions.md # Motion basics ✅
│ ├── week-02-text-objects.md # Text objects (TODO)
│ ├── week-03-advanced.md # Advanced editing (TODO)
│ ├── week-04-macros.md # Macros & registers (TODO)
│ ├── week-05-cmdline.md # Command line (TODO)
│ ├── week-06-windows.md # Windows & tabs (TODO)
│ ├── week-07-search.md # Search & replace (TODO)
│ ├── week-08-marks.md # Marks & jumps (TODO)
│ ├── tips-and-tricks.md # Productivity tips (TODO)
│ ├── workflows.md # Real-world patterns (TODO)
│ └── advanced.md # Advanced topics (TODO)
├── customization.md # Customization guide (TODO)
├── plugin-development.md # Plugin dev (TODO)
├── performance.md # Performance tuning (TODO)
├── troubleshooting.md # Troubleshooting (TODO)
├── migration.md # Migration guide (TODO)
└── faq.md # FAQ (TODO)
```
---
## 📝 Files to Remove/Consolidate
### Remove (Redundant)
- `NEO-TREE-CHEATSHEET.md` - Incorporated into docs/keymaps/plugins.md
- `ORGANIZATION.md` - Internal planning doc, not needed for users
### Move to Archive or Remove
- `TESTING.md` - Move to docs/development/ or remove
- `MIGRATION.md` - Move to docs/migration.md
- `SETUP-GUIDE.md` - Consolidate into docs/getting-started/installation.md
- `INSTALLATION.md` - Consolidate into docs/getting-started/installation.md
### Keep but Update
- `LICENSE.md` - Keep at root
- `README.md` - Replace with README.new.md
- `lazy-lock.json` - Keep (Lazy.nvim uses this)
---
## 🎯 Next Steps (Priority Order)
### Phase 1: Core Documentation (High Priority)
1. **Replace README.md** with README.new.md
2. **Complete getting-started/**
- installation.md (consolidate INSTALLATION.md + SETUP-GUIDE.md)
- first-steps.md (interactive tutorial)
- quick-reference.md (one-page cheat sheet)
- philosophy.md (design decisions)
3. **Complete keymaps/core.md**
- Consolidate KEYMAPS.md
- Organize by category
- Add examples
4. **Complete keymaps/lsp.md** and **keymaps/plugins.md**
- Document all LSP keymaps
- Document Telescope, Neo-tree, Git, etc.
### Phase 2: Plugin Documentation (Medium Priority)
5. **Create plugins/core.md**
- Telescope deep dive
- Neo-tree features
- which-key customization
6. **Create plugins/lsp.md** and **plugins/debug.md**
- LSP configuration
- Mason setup
- Debug adapter setup
### Phase 3: Language Guides (Medium Priority)
7. **Create language guides**
- flutter.md (full Flutter tools guide)
- rust.md (Crates.io integration)
- python.md (virtual envs, testing)
- Others as needed
### Phase 4: Vim Mastery (Ongoing)
8. **Complete Vim mastery weeks 2-8**
- week-02-text-objects.md
- week-03-advanced.md
- week-04-macros.md
- week-05-cmdline.md
- week-06-windows.md
- week-07-search.md
- week-08-marks.md
9. **Create supplementary guides**
- tips-and-tricks.md
- workflows.md
- advanced.md
### Phase 5: Advanced Topics (Low Priority)
10. **Create advanced guides**
- customization.md
- plugin-development.md
- performance.md
- troubleshooting.md
- faq.md
---
## 🎨 Documentation Style Guide
### Writing Principles
1. **Clear and Concise**: Get to the point quickly
2. **Example-Driven**: Show, don't just tell
3. **Progressive Disclosure**: Basic → Intermediate → Advanced
4. **Actionable**: Every guide includes exercises
5. **Searchable**: Good headers, keywords, cross-references
### Formatting Standards
- **Emojis for visual hierarchy**: 🎯 🔥 💡 ⚠️ 📚
- **Code blocks with language**: ```vim, ```lua, ```bash
- **Tables for comparisons**: Keymap tables, feature matrices
- **Callouts**: Tips, Warnings, Notes
- **Navigation**: Links at top and bottom of every page
### File Naming
- Use kebab-case: `week-01-motions.md`
- Be descriptive: `lsp-configuration.md` not `lsp.md`
- Group by prefix: `week-01-`, `week-02-`, etc.
---
## 📊 Estimated Completion Times
### Already Done (4 hours)
- ✅ Cheatsheet <Space> → <Leader>
- ✅ README.new.md
- ✅ docs/README.md
- ✅ docs/getting-started/README.md
- ✅ docs/keymaps/README.md
- ✅ docs/vim-mastery/README.md
- ✅ docs/vim-mastery/week-01-motions.md
- ✅ Copied consistency.md and duplicates.md
### Phase 1 (8 hours)
- getting-started/ guides (4 hours)
- keymaps/core.md (2 hours)
- keymaps/lsp.md (1 hour)
- keymaps/plugins.md (1 hour)
### Phase 2 (6 hours)
- plugins/ guides (6 hours total)
### Phase 3 (8 hours)
- language guides (8 hours total)
### Phase 4 (12 hours)
- Vim mastery weeks 2-8 (9 hours)
- tips/workflows/advanced (3 hours)
### Phase 5 (6 hours)
- Advanced topics (6 hours)
**Total Estimated**: ~44 hours of documentation writing
---
## 🎯 Immediate Action Items
### Right Now
1. **Backup old README.md**
```bash
mv README.md README.old.md
mv README.new.md README.md
```
2. **Remove redundant files**
```bash
rm NEO-TREE-CHEATSHEET.md
rm ORGANIZATION.md
```
3. **Clean up root directory**
```bash
mkdir archive
mv KEYMAPS.md archive/
mv CONSISTENCY.md archive/ # Now in docs/keymaps/
mv DUPLICATES.md archive/ # Now in docs/keymaps/
```
### Next Session
4. **Write getting-started/installation.md**
- Consolidate INSTALLATION.md and SETUP-GUIDE.md
- Add macOS, Linux, Windows sections
- Include troubleshooting
5. **Write getting-started/first-steps.md**
- Interactive 30-minute tutorial
- Essential keymaps only
- Real code examples
6. **Write getting-started/quick-reference.md**
- One-page PDF-printable guide
- 50 most-used commands
- Organized by category
---
## 💡 Content Sources
### From Existing Files
- KEYMAPS.md → docs/keymaps/core.md
- CONSISTENCY.md → docs/keymaps/consistency.md ✅
- DUPLICATES.md → docs/keymaps/duplicates.md ✅
- INSTALLATION.md + SETUP-GUIDE.md → docs/getting-started/installation.md
- lua/ plugin files → docs/plugins/ and docs/languages/
### From Configuration
- lua/config/keymaps.lua → keymap docs
- lua/plugins/ → plugin guides
- lua/plugins/lang/ → language guides
- Comments in code → feature documentation
### Original Content Needed
- Vim mastery guides (weeks 2-8)
- Tips and tricks
- Workflows
- Troubleshooting
- FAQ
- Customization guide
---
## 🔄 Maintenance Plan
### Weekly
- Update any changed keymaps
- Add new plugin documentation
- Review and improve based on feedback
### Monthly
- Check all links still work
- Update screenshots if needed
- Add new tips discovered
### Per Release
- Update version numbers
- Document new features
- Archive old migration guides
---
## 🎊 Success Criteria
Documentation is complete when:
- ✅ New users can install and be productive in 1 hour
- ✅ All keymaps are documented with examples
- ✅ All plugins have usage guides
- ✅ Complete Vim mastery path (8 weeks)
- ✅ Troubleshooting covers common issues
- ✅ Users say "I found it in the docs" instead of asking
---
<div align="center">
**Documentation is a journey, not a destination!**
This plan provides the structure. Now we execute, one file at a time.
</div>

256
docs/README.md Normal file
View file

@ -0,0 +1,256 @@
# 📚 Complete Documentation Guide
Welcome to the comprehensive documentation for this Neovim configuration. This guide is organized to help you progress from beginner to advanced user.
---
## 🗺️ Documentation Structure
### 🚀 Getting Started
**Start here if you're new or just installed the config**
- [**Installation**](getting-started/installation.md) - Step-by-step setup guide
- [**First Steps**](getting-started/first-steps.md) - Your first hour with this config
- [**Quick Reference**](getting-started/quick-reference.md) - Essential commands cheat sheet
- [**Philosophy**](getting-started/philosophy.md) - Design principles and organization
### ⌨️ Keymaps
**Complete keymap documentation with examples**
- [**Overview**](keymaps/README.md) - Keymap organization philosophy
- [**Core Keymaps**](keymaps/core.md) - Leader key bindings (buffer, window, search, etc.)
- [**LSP Keymaps**](keymaps/lsp.md) - Language Server Protocol commands
- [**Plugin Keymaps**](keymaps/plugins.md) - Telescope, Neo-tree, Git, etc.
- [**Debug Keymaps**](keymaps/debug.md) - Debugging commands
- [**Duplicates Guide**](keymaps/duplicates.md) - Understanding multiple keys for same action
- [**Consistency Guide**](keymaps/consistency.md) - Cross-plugin key patterns
### 🔌 Plugins
**Understanding each plugin and how to use it**
- [**Overview**](plugins/README.md) - All plugins explained
- [**Core Plugins**](plugins/core.md) - Telescope, Neo-tree, which-key, lazy.nvim
- [**Editor Plugins**](plugins/editor.md) - TreeSitter, mini.nvim, autopairs, etc.
- [**LSP & Completion**](plugins/lsp.md) - Language servers, nvim-cmp, snippets
- [**Debug Adapter**](plugins/debug.md) - nvim-dap setup and usage
- [**Git Integration**](plugins/git.md) - Gitsigns, LazyGit, fugitive
- [**UI Enhancements**](plugins/ui.md) - Colorscheme, statusline, bufferline
### 💻 Language Setup
**Language-specific configuration and features**
- [**Overview**](languages/README.md) - All supported languages
- [**Flutter/Dart**](languages/flutter-dart.md) - Flutter tools, device management, hot reload
- [**Rust**](languages/rust.md) - rust-analyzer, Crates.io integration
- [**Python**](languages/python.md) - Pyright, virtual environments, testing
- [**Svelte**](languages/svelte.md) - Svelte LSP, web development
- [**TypeScript/JavaScript**](languages/typescript.md) - tsserver, ESLint, Prettier
- [**Go**](languages/go.md) - gopls, testing, debugging
- [**Other Languages**](languages/others.md) - Lua, JSON, YAML, Markdown, etc.
### 🎓 Vim Mastery
**Progressive learning path to master Vim**
- [**Overview**](vim-mastery/README.md) - Learning philosophy and roadmap
- [**Week 1: Motion Basics**](vim-mastery/week-01-motions.md) - hjkl, word motions, searching
- [**Week 2: Text Objects**](vim-mastery/week-02-text-objects.md) - iw, ap, at, etc.
- [**Week 3: Advanced Editing**](vim-mastery/week-03-advanced.md) - Visual mode, macros intro
- [**Week 4: Macros & Registers**](vim-mastery/week-04-macros.md) - Recording and replay
- [**Week 5: Command Line**](vim-mastery/week-05-cmdline.md) - Ex commands, ranges, substitution
- [**Week 6: Windows & Tabs**](vim-mastery/week-06-windows.md) - Managing your workspace
- [**Tips & Tricks**](vim-mastery/tips-and-tricks.md) - Productivity boosters
- [**Workflows**](vim-mastery/workflows.md) - Real-world editing patterns
- [**Advanced Topics**](vim-mastery/advanced.md) - Vim script, Lua, custom commands
### 🛠️ Advanced Topics
- [**Customization**](customization.md) - Make this config your own
- [**Plugin Development**](plugin-development.md) - Create your own plugins
- [**Performance Tuning**](performance.md) - Optimize startup time
- [**Troubleshooting**](troubleshooting.md) - Common issues and solutions
- [**Migration Guide**](migration.md) - Coming from other configs
- [**FAQ**](faq.md) - Frequently asked questions
---
## 📖 How to Use This Documentation
### For Beginners
1. Start with [Getting Started](getting-started/README.md)
2. Learn [Quick Reference](getting-started/quick-reference.md) commands
3. Follow [Vim Mastery Week 1](vim-mastery/week-01-motions.md)
4. Use the [in-editor cheatsheet](#in-editor-help) constantly
### For Intermediate Users
1. Review [Keymaps documentation](keymaps/README.md) to discover new commands
2. Explore [Plugin guides](plugins/README.md) for advanced features
3. Continue [Vim Mastery](vim-mastery/README.md) progression
4. Learn language-specific features in [Languages](languages/README.md)
### For Advanced Users
1. Study [Customization](customization.md) to extend the config
2. Optimize with [Performance Tuning](performance.md)
3. Master [Advanced Topics](vim-mastery/advanced.md)
4. Contribute improvements back to the project
---
## 🎯 In-Editor Help
You don't need to leave Neovim to access help:
### Built-in Cheatsheet
- `<Leader>sc` - Comprehensive searchable cheatsheet (200+ keymaps)
- `<Leader>sk` - Telescope keymap search
- `<Leader>?` - Quick keymap fuzzy search
- `<Leader>sK` - Which-key command palette
### Context-Sensitive Help
- `K` - Hover documentation (LSP)
- `<Leader>k` - Signature help
- `?` (in Telescope/Neo-tree) - Show plugin-specific help
- `:help <topic>` - Vim's built-in help system
### Discovery Tools
- Press `<Leader>` and wait - which-key shows all available keymaps
- Press `g` and wait - see all "go to" commands
- Press `]` or `[` and wait - see all next/previous commands
---
## 💡 Learning Philosophy
This documentation follows a **progressive disclosure** approach:
1. **Start Simple**: Basic commands to be productive immediately
2. **Build Gradually**: Add one new technique per week
3. **Practice Deliberately**: Focus on mastering before moving on
4. **Apply Immediately**: Use new skills in real work
5. **Iterate**: Return to earlier topics with new understanding
### The One-Trick-Per-Week Method
Instead of trying to learn everything at once:
- Pick ONE new command/technique each week
- Use it consciously until it becomes muscle memory
- Track your progress in [Vim Mastery](vim-mastery/README.md)
- After a year, you'll have 52 new tricks!
---
## 🗺️ Learning Paths
### Path 1: Productive in One Day
*Goal: Get work done immediately*
1. [Installation](getting-started/installation.md) - 30 min
2. [Quick Reference](getting-started/quick-reference.md) - 15 min
3. [Core Keymaps](keymaps/core.md) - Learn `<Leader>sf`, `<Leader>sg`, `<Leader>bb`
4. Start coding with LSP features (K, gra, gd)
### Path 2: Vim Proficiency in 6 Weeks
*Goal: Become efficient with Vim motions*
1. Week 1: [Motion Basics](vim-mastery/week-01-motions.md)
2. Week 2: [Text Objects](vim-mastery/week-02-text-objects.md)
3. Week 3: [Advanced Editing](vim-mastery/week-03-advanced.md)
4. Week 4: [Macros & Registers](vim-mastery/week-04-macros.md)
5. Week 5: [Command Line](vim-mastery/week-05-cmdline.md)
6. Week 6: [Windows & Tabs](vim-mastery/week-06-windows.md)
### Path 3: Master All Features
*Goal: Unlock the full power of this config*
1. Complete Path 2 (Vim Proficiency)
2. Deep dive into [All Plugins](plugins/README.md)
3. Master your primary language setup
4. Learn [Advanced Workflows](vim-mastery/workflows.md)
5. Customize and extend ([Customization Guide](customization.md))
---
## 🎓 Recommended External Resources
### Books
- **Practical Vim** by Drew Neil - The best Vim book
- **Modern Vim** by Drew Neil - Neovim-specific features
- **Learning the Vi and Vim Editors** - Comprehensive reference
### Video Courses
- **ThePrimeagen's Vim Course** - Entertaining and informative
- **Vim Casts** - Short, focused video tutorials
- **TJ DeVries' Neovim YouTube** - Creator of kickstart.nvim
### Interactive Learning
- **vimtutor** - Run `:Tutor` in Neovim
- **Vim Adventures** - Game to learn Vim
- **OpenVim** - Interactive tutorial
### Community
- **r/neovim** - Reddit community
- **Neovim Discourse** - Official forum
- **Matrix/Discord** - Real-time chat
---
## 📝 Documentation Conventions
### Notation
- `<Leader>` - Your leader key (default: Space)
- `<C-x>` - Control + x
- `<M-x>` - Alt/Meta + x
- `<CR>` - Enter/Return key
- `{motion}` - Any motion command (w, e, $, etc.)
- `[count]` - Optional number prefix
### Visual Cues
- 💡 **Tip** - Helpful suggestion
- ⚠️ **Warning** - Important caution
- 📌 **Note** - Additional information
- 🎯 **Pro Tip** - Advanced technique
- 🔍 **Example** - Practical demonstration
---
## 🔄 Keeping Documentation Updated
This documentation evolves with the configuration:
- **Check for updates**: `git pull` in `~/.config/nvim`
- **Version**: Documentation matches config version
- **Feedback**: Open issues for unclear docs
- **Contribute**: Submit PRs for improvements
---
## 🎯 Quick Navigation
### By Topic
- **Need to find a file?** → [Telescope Guide](plugins/core.md#telescope)
- **Want to understand a keymap?** → [Keymaps Overview](keymaps/README.md)
- **LSP not working?** → [Troubleshooting LSP](troubleshooting.md#lsp-issues)
- **Adding a language?** → [Language Setup](languages/README.md)
- **Config too slow?** → [Performance Tuning](performance.md)
### By Skill Level
- **Beginner** → [Getting Started](getting-started/README.md)
- **Intermediate** → [Vim Mastery](vim-mastery/README.md)
- **Advanced** → [Customization](customization.md)
### By Plugin
- [Telescope](plugins/core.md#telescope)
- [Neo-tree](plugins/core.md#neo-tree)
- [which-key](plugins/core.md#which-key)
- [nvim-cmp](plugins/lsp.md#completion)
- [nvim-dap](plugins/debug.md)
- [Gitsigns](plugins/git.md)
---
<div align="center">
**Happy Coding! 🚀**
[Back to Main README](../README.md) | [Get Started →](getting-started/README.md)
</div>

195
docs/getting-started/README.md Normal file
View file

@ -0,0 +1,195 @@
# 🚀 Getting Started
Welcome! This guide will help you get up and running with this Neovim configuration.
---
## 📚 Guide Structure
1. **[Installation](installation.md)** - Set up Neovim and this configuration
2. **[First Steps](first-steps.md)** - Your first hour with the config
3. **[Quick Reference](quick-reference.md)** - Essential commands you'll use daily
4. **[Philosophy](philosophy.md)** - Understanding the design principles
---
## ⚡ Quick Start (5 Minutes)
### 1. Install Neovim 0.11.4+
```bash
# macOS
brew install neovim
# Ubuntu/Debian
sudo apt install neovim
# Arch Linux
sudo pacman -S neovim
```
### 2. Backup Old Config
```bash
mv ~/.config/nvim ~/.config/nvim.backup
mv ~/.local/share/nvim ~/.local/share/nvim.backup
```
### 3. Clone This Config
```bash
git clone https://github.com/anupjsebastian/kickstart.nvim.git ~/.config/nvim
```
### 4. Install Dependencies
```bash
# macOS
brew install ripgrep fd
# Ubuntu
sudo apt install ripgrep fd-find
# Arch
sudo pacman -S ripgrep fd
```
### 5. Launch Neovim
```bash
nvim
```
Wait for all plugins to install (watch bottom right corner).
### 6. Verify Everything Works
```vim
:checkhealth
```
---
## 🎯 What You'll Learn
### Immediate (Day 1)
- Opening and editing files
- Basic navigation with Telescope
- Using LSP features (autocomplete, go to definition)
- Essential keymaps you'll use every day
### Short Term (Week 1)
- Vim motion basics
- Using the file explorer (Neo-tree)
- Git integration
- Debugging basics
### Medium Term (Month 1)
- Advanced Vim motions and text objects
- Customizing keymaps
- Language-specific features
- Efficient workflows
### Long Term (Ongoing)
- Mastering Vim commands
- Building your own plugins
- Optimizing your workflow
- One new trick per week approach
---
## 🗺️ Learning Path
```
Installation (15 min)
↓
First Steps (30 min) - Learn the absolute basics
↓
Quick Reference (ongoing) - Your daily command sheet
↓
Week 1: Basic Motions - hjkl, word motions, searching
↓
Week 2: Text Objects - iw, ap, it, edit intelligently
↓
Week 3: Advanced Editing - Visual mode, macros
↓
Continue with Vim Mastery guides...
```
---
## 💡 Key Concepts
### Leader Key = Space
Almost all custom keymaps start with `<Leader>` (the Space key). Press Space and wait - you'll see a menu!
### Which-key is Your Friend
When you press a key prefix (like `<Leader>` or `g`), a menu appears showing all available commands.
### Everything is Searchable
- Files: `<Leader>sf`
- Text: `<Leader>sg`
- Keymaps: `<Leader>sc`
- Help: `<Leader>sh`
### LSP Powers Your Editing
- `K` - Documentation
- `gd` - Go to definition
- `gr` - Find references
- `gra` - Code actions
---
## 🆘 Getting Help
### In-Editor
- `<Leader>sc` - Comprehensive cheatsheet
- `<Leader>sk` - Search all keymaps
- `<Leader>` (wait) - Which-key menu
- `:help <topic>` - Vim help
### External
- [Full Documentation](../README.md)
- [Troubleshooting Guide](../troubleshooting.md)
- [FAQ](../faq.md)
- [GitHub Issues](https://github.com/anupjsebastian/kickstart.nvim/issues)
---
## ⚠️ Common First-Day Issues
### Plugins Not Installing
```vim
:Lazy sync
```
### LSP Not Working
```vim
:Mason
:LspInfo
:checkhealth
```
### Fonts Look Broken
Install a [Nerd Font](https://www.nerdfonts.com/) and set `vim.g.have_nerd_font = true` in `init.lua`.
### Keymaps Not Working
Check your terminal doesn't intercept keys:
```vim
:checkhealth which-key
```
---
## 🎓 Next Steps
1. Complete [Installation Guide](installation.md)
2. Follow [First Steps Tutorial](first-steps.md)
3. Bookmark [Quick Reference](quick-reference.md)
4. Start [Vim Mastery Week 1](../vim-mastery/week-01-motions.md)
---
<div align="center">
**Ready to dive in?**
[Installation Guide →](installation.md)
[Back to Documentation](../README.md) | [Back to Main README](../../README.md)
</div>

226
docs/keymaps/README.md Normal file
View file

@ -0,0 +1,226 @@
# ⌨️ Keymaps Reference
Complete guide to all keymaps in this configuration, organized by category.
---
## 📋 Quick Navigation
- **[Core Keymaps](core.md)** - Leader-key organization (buffer, window, search, git, etc.)
- **[LSP Keymaps](lsp.md)** - Language Server Protocol commands
- **[Plugin Keymaps](plugins.md)** - Telescope, Neo-tree, Git, Debug
- **[Duplicates Guide](duplicates.md)** - Understanding multiple keys for same action
- **[Consistency Guide](consistency.md)** - Cross-plugin key patterns
---
## 🎯 Keymap Philosophy
### 1. Leader-Based Organization
Almost all custom keymaps start with `<Leader>` (Space key):
- `<Leader>b` - **Buffer** operations
- `<Leader>s` - **Search** (Telescope)
- `<Leader>f` - **Flutter** (Dart files)
- `<Leader>r` - **Rust** operations
- `<Leader>d` - **Debug** commands
- `<Leader>g` - **Git** operations
- And more...
### 2. Mnemonic Design
Keys are chosen to be memorable:
- `<Leader>sf` = **S**earch **F**iles
- `<Leader>bb` = **B**uffer **B**rowse
- `<Leader>gg` = Open Lazy**G**it
- `<Leader>db` = **D**ebug **B**reakpoint
### 3. Which-key Discovery
Press `<Leader>` and wait - a menu shows all available commands!
### 4. Consistent Across Plugins
Same keys work the same way everywhere:
- `Ctrl-x` = Horizontal split (Telescope, Neo-tree)
- `Ctrl-v` = Vertical split (Telescope, Neo-tree)
- `Ctrl-t` = New tab (Telescope, Neo-tree)
- `?` = Show help (Telescope, Neo-tree)
---
## 🗺️ Keymap Categories
### Core Editor
| Prefix | Category | Example |
|--------|----------|---------|
| `<Leader>b` | Buffer operations | `<Leader>bd` = Delete buffer |
| `<Leader>w` | Window operations | `<Leader>wv` = Vertical split |
| `<Leader>u` | UI toggles | `<Leader>uw` = Toggle wrap |
| `<Leader>s` | Search/Telescope | `<Leader>sf` = Find files |
| `<Leader>g` | Git operations | `<Leader>gg` = LazyGit |
### LSP (Language Features)
| Prefix | Category | Example |
|--------|----------|---------|
| `gr*` | Go to... | `grd` = Go to definition |
| `K` | Hover | `K` = Show documentation |
| `<Leader>c` | Code | `<Leader>ca` = Code actions |
### Debug
| Prefix | Category | Example |
|--------|----------|---------|
| `<Leader>d` | Debug commands | `<Leader>db` = Breakpoint |
| `F5-F12` | Debug quick keys | `F5` = Continue |
### Language-Specific
| Prefix | Language | Example |
|--------|----------|---------|
| `<Leader>f` | Flutter/Dart | `<Leader>fr` = Run app |
| `<Leader>r` | Rust | `<Leader>ra` = Code actions |
| `<Leader>rc` | Rust Crates | `<Leader>rct` = Toggle |
| `<Leader>p` | Python | `<Leader>pr` = Run |
| `<Leader>v` | Svelte | `<Leader>vf` = Format |
---
## 📚 Detailed Documentation
### [Core Keymaps](core.md)
Complete reference for all leader-key bindings:
- Buffer management
- Window operations
- Search/Telescope
- Git integration
- UI toggles
- Session management
### [LSP Keymaps](lsp.md)
Language Server Protocol commands that work in all languages:
- Go to definition, references, implementation
- Hover documentation
- Rename symbol
- Code actions
- Signature help
- Diagnostics navigation
### [Plugin Keymaps](plugins.md)
Plugin-specific keymaps:
- **Telescope**: Fuzzy finding, live grep, file browser
- **Neo-tree**: File explorer navigation and operations
- **Git**: Gitsigns hunks, staging, blame
- **Debug**: nvim-dap debugging commands
- **Mini.nvim**: Surround, comments, pairs
### [Duplicates Guide](duplicates.md)
Understanding why some actions have multiple keymaps:
- Vim defaults + modern alternatives
- Function keys + leader keys for debugging
- Single keys + Ctrl combos for consistency
- Default plugin keys + consistent alternatives
### [Consistency Guide](consistency.md)
Cross-plugin key patterns:
- Same split/tab keys in Telescope and Neo-tree
- Consistent navigation patterns
- Unified help access
---
## 🎓 Learning Strategy
### Week 1: Essential Commands
Focus on these 10 keymaps:
1. `<Leader>sf` - Find files
2. `<Leader>sg` - Search text (grep)
3. `<Leader>bb` - Browse buffers
4. `\` - Toggle file explorer
5. `gd` - Go to definition
6. `K` - Show documentation
7. `<Leader>ca` - Code actions
8. `<Leader>gg` - Git interface
9. `<C-h/l>` - Switch windows
10. `<Leader>sc` - Open cheatsheet!
### Week 2: Expand Your Arsenal
Add these:
- `<Leader>s/` - Search in open files
- `<Leader>bd` - Delete buffer
- `<Leader>wv` - Split vertical
- `gr` - Find references
- `[d` / `]d` - Next/prev diagnostic
### Ongoing: One Per Week
Pick ONE new keymap each week from the [full documentation](core.md) and practice it until it's muscle memory.
---
## 🔍 Finding Keymaps
### In-Editor Tools
```vim
" Comprehensive searchable cheatsheet
<Leader>sc
" Search all keymaps with Telescope
<Leader>sk
" Which-key command palette
<Leader>sK
" Quick fuzzy search
<Leader>?
" Press any prefix and wait
<Leader> " Shows all leader keymaps
g " Shows all 'go to' commands
[ " Shows all 'next' commands
] " Shows all 'previous' commands
```
### By Category
- **Buffer commands**: `<Leader>b` (then wait for menu)
- **Search commands**: `<Leader>s` (then wait)
- **Git commands**: `<Leader>g` (then wait)
- **Debug commands**: `<Leader>d` (then wait)
### By Plugin
Inside a plugin (like Telescope or Neo-tree), press `?` for help.
---
## 💡 Tips
### Discovering Features
1. Press `<Leader>` and wait - explore the which-key menu
2. Open cheatsheet with `<Leader>sc` and search
3. Check plugin-specific help with `?`
### Customizing Keymaps
See [Customization Guide](../customization.md) to:
- Change existing keymaps
- Add your own keymaps
- Disable unwanted keymaps
### Resolving Conflicts
If a keymap doesn't work:
```vim
:verbose map <Leader>sf
:checkhealth which-key
```
---
## 📖 External Resources
- [Vim Cheat Sheet](https://vim.rtorr.com/)
- [Interactive Vim Tutorial](https://www.openvim.com/)
- [Practical Vim Book](https://pragprog.com/titles/dnvim2/practical-vim-second-edition/)
---
<div align="center">
**Master your keymaps, master your editor!**
[Core Keymaps →](core.md) | [LSP Keymaps →](lsp.md) | [Plugin Keymaps →](plugins.md)
[Back to Documentation](../README.md)
</div>

82
docs/keymaps/consistency.md Normal file
View file

@ -0,0 +1,82 @@
# Keymap Consistency Guide
> **Last Updated:** November 1, 2025
> **Purpose:** Document consistent keymaps across Telescope and Neo-tree
## 🎯 Consistent Actions
The following keymaps work **identically** in both Telescope and Neo-tree:
### File Opening Actions
| Key | Action | Telescope | Neo-tree |
|-----|--------|-----------|----------|
| `<CR>` or `o` | Open in current window | ✅ | ✅ |
| `<C-x>` | Open in horizontal split | ✅ | ✅ |
| `<C-v>` | Open in vertical split | ✅ | ✅ |
| `<C-t>` | Open in new tab | ✅ | ✅ |
### Navigation
| Key | Action | Telescope | Neo-tree |
|-----|--------|-----------|----------|
| `<C-j>` | Next item/source | ✅ | ✅ |
| `<C-k>` | Previous item/source | ✅ | ✅ |
| `j/k` (normal mode) | Down/Up | ✅ | ✅ |
| `gg/G` (normal mode) | First/Last | ✅ | ✅ |
### Utility
| Key | Action | Telescope | Neo-tree |
|-----|--------|-----------|----------|
| `?` | Show help | ✅ | ✅ |
| `<Esc>` or `q` | Close | ✅ | ✅ (`\\` for Neo-tree) |
### Cross-Plugin Integration
| Key | Action | Context |
|-----|--------|---------|
| `<leader>sf` | Telescope find files | Works in both editor and Neo-tree |
| `<leader>sg` | Telescope live grep | Works in both editor and Neo-tree |
When used in Neo-tree, these commands search from the currently selected directory!
## 📚 Complete Cheatsheet Access
Access the comprehensive cheatsheet with:
```
<leader>sc - Complete cheatsheet (vim, plugins, language-specific)
<leader>sk - Search keymaps (Telescope)
<leader>sK - All keymaps (which-key)
<leader>? - Quick keymap search
```
## 🎨 Visual Consistency
Both Telescope and Neo-tree now follow the same pattern:
- **Same keys** for same actions
- **Predictable behavior** across interfaces
- **Integrated workflows** (use Telescope from Neo-tree)
- **Help always available** with `?`
## 📝 Quick Reference
### In Telescope:
1. `<C-j/k>` to navigate
2. `<C-x/v/t>` to open in split/vsplit/tab
3. `<CR>` to open in current window
4. `?` for help
### In Neo-tree:
1. `<C-j/k>` to switch sources
2. `<C-x/v/t>` to open in split/vsplit/tab
3. `<CR>` or `o` to open file
4. `?` for help
5. `<leader>sf/sg` to launch Telescope from current directory
### Both Share:
- Consistent split/tab opening
- Same navigation philosophy
- Integrated search capabilities
- Help on demand

90
docs/keymaps/duplicates.md Normal file
View file

@ -0,0 +1,90 @@
# Duplicate Keymaps Reference
This document lists all keymaps where the same action can be performed using multiple key combinations.
## Philosophy
Having duplicate keymaps is **intentional and beneficial**:
- **Vim defaults + Modern alternatives**: Keep familiar vim keys while adding intuitive modern ones
- **Consistency across plugins**: Same keys work the same way in Telescope and Neo-tree
- **Ergonomics**: Function keys (F5-F12) AND leader keys for debugging
- **Context switching**: Use what feels natural in different workflows
## Debug Actions
| Action | Keys | Notes |
|--------|------|-------|
| Continue | `F5` or `<Space>dc` | F5 is standard in many IDEs |
| Step over | `F10` or `<Space>dO` | Uppercase O for over |
| Step into | `F11` or `<Space>di` | |
| Step out | `F12` or `<Space>do` | Lowercase o for out |
**Why duplicates?** Function keys are muscle memory from other IDEs. Leader keys are more discoverable via which-key and don't conflict with terminal function keys.
## Neo-tree vs Consistent Actions
| Action | Neo-tree Default | Consistent Alternative | Notes |
|--------|------------------|------------------------|-------|
| Vertical split | `s` | `Ctrl-v` | Matches Telescope |
| Horizontal split | `S` | `Ctrl-x` | Matches Telescope |
| New tab | `t` | `Ctrl-t` | Matches Telescope |
| Next source | `>` | `Ctrl-j` | Matches Telescope navigation |
| Previous source | `<` | `Ctrl-k` | Matches Telescope navigation |
| Close window | `q` | `\` or `Esc` | Backslash mirrors toggle |
| Open file | `<CR>` | `o` | Two ways to open |
**Why duplicates?** Neo-tree defaults are efficient single-key presses. Consistent alternatives (`Ctrl-x/v/t/j/k`) work the same way in Telescope, reducing cognitive load when switching between file finder and file tree.
## Flutter Code Actions
| Action | Keys | Notes |
|--------|------|-------|
| Code actions | `<Space>.` or `gra` | Period mimics Cmd+. in IDEs, gra is standard LSP |
**Why duplicates?** Flutter developers coming from IDEs expect `.` (like Cmd+.). `gra` is the standard LSP keymap used everywhere else.
## Telescope Navigation
| Action | Keys | Notes |
|--------|------|-------|
| Next/prev item | `Ctrl-j/k` or `j/k` (normal) | Insert mode uses Ctrl, normal mode uses plain |
| Close | `Ctrl-c` or `Esc` or `q` (normal) | Three ways to exit |
**Why duplicates?** `Ctrl-j/k` work in insert mode without switching modes. In normal mode, plain `j/k` are more natural.
## Vim Defaults
| Action | Keys | Notes |
|--------|------|-------|
| Save and quit | `:wq` or `ZZ` | ZZ is faster |
| Quit without save | `:q!` or `ZQ` | ZQ is faster |
**Why duplicates?** Both are vim defaults. ZZ/ZQ are faster but less discoverable.
## Summary of Duplicate Patterns
1. **Debug**: F-keys + Leader keys (muscle memory from IDEs + discoverability)
2. **Splits/Tabs**: Single keys + Ctrl combos (efficiency + consistency)
3. **Navigation**: Plain + Ctrl variants (context-dependent ergonomics)
4. **Close/Exit**: Multiple keys (q, Esc, Ctrl-c, \\) (different mental models)
## Design Principles
1. **Never remove defaults** unless they conflict
2. **Add consistent alternatives** that work across plugins
3. **Document all options** so users can choose their preferred style
4. **Optimize for discoverability** (leader keys show in which-key)
5. **Respect muscle memory** (keep vim and IDE conventions)
## Quick Reference: Cross-Plugin Consistency
These keys work the same way in **both Telescope and Neo-tree**:
- `Ctrl-x` → Horizontal split
- `Ctrl-v` → Vertical split
- `Ctrl-t` → New tab
- `Ctrl-j` → Next/down
- `Ctrl-k` → Previous/up
- `?` → Show help
This consistency means once you learn these in one plugin, they work the same everywhere.

295
docs/languages/flutter-dart.md Normal file
View file

@ -0,0 +1,295 @@
# Flutter & Dart Development
Complete reference for Flutter and Dart development in Neovim.
## Quick Start
1. Open any `.dart` file to activate Flutter tools
2. Select device: `<Space>fd`
3. Run app: `<Space>fr`
4. Hot reload during development: `<Space>fh`
## Essential Keymaps
### App Lifecycle
| Key | Command | Description |
|-----|---------|-------------|
| `<Space>fr` | FlutterRun | Run the app (auto-selects last used device) |
| `<Space>fh` | FlutterReload | Hot reload (faster, preserves state) |
| `<Space>fR` | FlutterRestart | Hot restart (full reload, resets state) |
| `<Space>fq` | FlutterQuit | Stop the running app |
**Workflow**: First time, use `<Space>fd` to select a device, then `<Space>fr` to run. Subsequent runs remember your device.
### Device Management
| Key | Command | Description |
|-----|---------|-------------|
| `<Space>fd` | FlutterDevices | List and select connected devices |
| `<Space>fe` | FlutterEmulators | Launch an emulator |
| `<Space>fa` | FlutterAttach | Attach to an already running app |
| `<Space>fD` | FlutterDetach | Detach from app (keeps it running) |
### Developer Tools
| Key | Command | Description |
|-----|---------|-------------|
| `<Space>ft` | FlutterDevTools | Start Dart DevTools server |
| `<Space>fc` | FlutterCopyProfilerUrl | Copy profiler URL to clipboard |
| `<Space>fo` | FlutterOutlineToggle | Toggle widget tree outline |
| `<Space>fL` | FlutterLogToggle | Show/hide application logs |
**DevTools Workflow**:
1. Run your app: `<Space>fr`
2. Start DevTools: `<Space>ft`
3. Copy profiler URL: `<Space>fc`
4. Open URL in browser for full DevTools experience
### Code Actions & Refactoring
| Key | Command | Description |
|-----|---------|-------------|
| `<Space>.` | Code Actions | Quick actions (like Cmd+. in VS Code) |
| `gra` | Code Actions | Alternative LSP keymap |
**Common Code Actions**:
- Wrap widget with Padding, Center, Column, etc.
- Remove widget (unwrap)
- Extract widget to new class
- Extract method
- Add import
- Organize imports
### LSP & Language Server
| Key | Command | Description |
|-----|---------|-------------|
| `<Space>fl` | FlutterLspRestart | Restart Dart language server |
| `K` | Hover | Show documentation |
| `grd` | Go to Definition | Jump to definition |
| `grr` | Go to References | Find all references |
| `grn` | Rename | Rename symbol |
## Flutter-Specific Features
### Widget Tree Outline
The outline window shows your widget tree structure:
```
<Space>fo # Toggle outline window
```
The outline updates as you edit and shows:
- Widget hierarchy
- Widget types
- Quick navigation to widgets
### Closing Tags
Automatically shows closing tags for deeply nested widgets:
```dart
Container( // Container
child: Column( // Column
children: [
Text('Hello'),
Text('World'),
],
), // Column
), // Container
```
### Color Preview
Material Design colors show inline preview:
```dart
Colors.red # Shows red color indicator
Color(0xFF42A5F5) # Shows the actual color
```
### Hot Reload vs Hot Restart
| Hot Reload (`<Space>fh`) | Hot Restart (`<Space>fR`) |
|---------------------------|---------------------------|
| Fast (< 1 second) | Slower (few seconds) |
| Preserves app state | Resets app state |
| UI changes only | Can handle code structure changes |
| Use during active development | Use after changing initState, constructors |
## Debugging
### Debug Keymaps
Available when debugging (after `<F5>` or breakpoint hit):
| Key | Description |
|-----|-------------|
| `F5` | Start/Continue |
| `F10` | Step over |
| `F11` | Step into |
| `F12` | Step out |
| `<Space>db` | Toggle breakpoint |
| `<Space>dB` | Conditional breakpoint |
| `<Space>dt` | Terminate debug session |
| `<Space>dr` | Toggle REPL |
| `<Space>du` | Toggle debug UI |
### Debug Workflow
1. Set breakpoints: Position cursor, press `<Space>db`
2. Start debugging: `F5` (launches app in debug mode)
3. App pauses at breakpoint
4. Inspect variables in debug UI panels
5. Step through code: `F10`, `F11`, `F12`
6. Continue execution: `F5`
### Debug UI Panels
When debugging starts, you get:
- **Scopes**: Local and global variables
- **Breakpoints**: All breakpoints in your project
- **Call Stack**: Function call hierarchy
- **Watches**: Custom expressions to monitor
- **REPL**: Evaluate Dart expressions live
- **Console**: Debug output and print statements
## Logs
```
<Space>fL # Toggle log buffer
```
The log buffer shows:
- `print()` statements
- Flutter framework messages
- Hot reload/restart confirmations
- Error messages and stack traces
## Tips & Tricks
### Fast Development Loop
```
1. Make UI changes
2. <Space>fh for instant hot reload
3. See changes immediately
4. Repeat
```
### When Hot Reload Fails
If hot reload shows unexpected behavior:
```
<Space>fR # Hot restart (full reload)
```
If issues persist:
```
<Space>fq # Quit app
<Space>fl # Restart LSP
<Space>fr # Run again
```
### Multiple Devices
Switch between devices without restarting:
```
<Space>fq # Quit current
<Space>fd # Select new device
<Space>fr # Run on new device
```
### Widget Extraction
To extract a widget to a new class:
1. Visual select the widget code
2. Press `<Space>.` or `gra`
3. Choose "Extract Widget"
4. Enter new widget name
### Attach to Running App
If your app is already running (started outside Neovim):
```
<Space>fa # Attach to running process
```
This enables hot reload and debugging for external apps.
## Configuration
Flutter tools are configured in `lua/custom/plugins/flutter.lua`.
Key settings:
- **Auto-start DevTools**: `dev_tools.autostart = false` (manual start)
- **Widget guides**: `widget_guides.enabled = true` (visual nesting guides)
- **Closing tags**: `closing_tags.enabled = true` (shows widget closing comments)
- **Color preview**: `lsp.color.enabled = true` (inline color indicators)
## Troubleshooting
### LSP Not Working
```
:FlutterLspRestart
# or
<Space>fl
```
### Can't Select Device
Ensure Flutter can see your devices:
```
:!flutter devices
```
If devices don't show, check:
- Android emulator is running
- iOS simulator is running
- Physical device is connected and authorized
- Chrome is installed (for web)
### Hot Reload Not Responding
```
<Space>fR # Force hot restart
```
If still not working:
```
<Space>fq # Quit
<Space>fr # Restart fresh
```
### Dart Analysis Errors
Force re-analysis:
```
:FlutterReanalyze
```
Or restart LSP: `<Space>fl`
## Resources
- [Flutter Documentation](https://flutter.dev/docs)
- [Dart Language Tour](https://dart.dev/guides/language/language-tour)
- [Widget Catalog](https://flutter.dev/docs/development/ui/widgets)
- [flutter-tools.nvim GitHub](https://github.com/akinsho/flutter-tools.nvim)
## See Also
- [Debug Keymaps](../keymaps/README.md#debugging) - Complete debugging reference
- [LSP Features](../plugins/lsp.md) - Language Server Protocol features
- [Code Actions](../keymaps/README.md#lsp) - All code action keymaps

272
docs/vim-mastery/README.md Normal file
View file

@ -0,0 +1,272 @@
# 🎓 Vim Mastery - Progressive Learning Path
Master Vim one technique at a time, building real skill over months instead of trying to learn everything at once.
---
## 🎯 Philosophy: The One-Trick-Per-Week Method
Instead of overwhelming yourself with hundreds of commands:
1. **Learn ONE new command/technique each week**
2. **Practice it consciously** in your daily work
3. **Use it until it becomes muscle memory**
4. **Move to the next technique**
After one year: **52 new powerful techniques!**
---
## 🗺️ Learning Roadmap
### Weeks 1-4: Foundation
Build essential motion and editing skills
- **[Week 1: Motion Basics](week-01-motions.md)** - Move efficiently
- **[Week 2: Text Objects](week-02-text-objects.md)** - Edit intelligently
- **[Week 3: Advanced Editing](week-03-advanced.md)** - Visual mode & macros intro
- **[Week 4: Macros & Registers](week-04-macros.md)** - Automate repetitive tasks
### Weeks 5-8: Power User
Master Vim's unique features
- **[Week 5: Command Line](week-05-cmdline.md)** - Ex commands & substitution
- **[Week 6: Windows & Tabs](week-06-windows.md)** - Workspace management
- **[Week 7: Search & Replace](week-07-search.md)** - Advanced patterns
- **[Week 8: Marks & Jumps](week-08-marks.md)** - Navigate large codebases
### Ongoing: Mastery
Continuous improvement
- **[Tips & Tricks](tips-and-tricks.md)** - Productivity boosters
- **[Workflows](workflows.md)** - Real-world patterns
- **[Advanced Topics](advanced.md)** - Vim script, Lua, custom commands
---
## 📊 Skill Progression
```
Week 0: hjkl, basic editing [Beginner]
↓
Week 2: Word motions, text objects [Functional]
↓
Week 4: Visual mode, basic macros [Comfortable]
↓
Week 6: Ex commands, window management [Efficient]
↓
Week 8: Advanced searching, marks [Proficient]
↓
Month 3: Custom workflows [Advanced]
↓
Month 6: Vim expert, teaching others [Master]
```
---
## 🎯 Learning Objectives
### By Week 4
You will be able to:
- Navigate code without arrow keys
- Edit text objects (change word, delete paragraph)
- Use visual mode for selections
- Record and replay simple macros
- Be MORE productive than with mouse + arrow keys
### By Week 8
You will be able to:
- Refactor code efficiently
- Use advanced search patterns
- Manage multiple windows and tabs
- Navigate large codebases with marks
- Automate repetitive tasks with macros
### By Month 6
You will be able to:
- Edit at the speed of thought
- Teach Vim to others
- Create custom workflows
- Write your own Vim scripts
- Never want to use another editor
---
## 📖 Weekly Structure
Each week follows this pattern:
### Monday: Learn
- Read the week's guide (15 minutes)
- Watch any linked videos
- Understand the concepts
### Tuesday-Friday: Practice
- Pick 2-3 commands from the week's list
- Use them consciously in real work
- Don't worry about speed yet
- Focus on correctness
### Weekend: Review
- What did you learn?
- What felt natural?
- What needs more practice?
- Pick next week's focus
---
## 💡 Learning Tips
### 1. Deliberate Practice
Don't just read - **use** the commands in real code.
### 2. Start Slow
Speed comes with muscle memory. Focus on correctness first.
### 3. One Thing at a Time
Master one command before adding another.
### 4. Keep a Cheat Sheet
Write down your current week's commands somewhere visible.
### 5. Use the In-Editor Cheatsheet
`<Leader>sc` is your friend!
### 6. Don't Rush
It's okay to spend 2 weeks on one topic if needed.
### 7. Apply Immediately
Learn Monday, use in real work Tuesday.
### 8. Embrace Mistakes
Undo (`u`) is your safety net. Experiment!
---
## 🎮 Practice Exercises
Each week includes:
- **Focused drills** - Specific command practice
- **Real-world scenarios** - Apply to actual code
- **Challenge tasks** - Test your skills
- **Cheat sheet** - Quick reference
---
## 📚 Recommended Schedule
### If You're New to Vim
- **Pace**: 1 week per topic
- **Time**: 30 minutes/day practice
- **Duration**: 8 weeks to proficiency
### If You Know Basic Vim
- **Pace**: 2-3 topics per week
- **Time**: 15 minutes/day practice
- **Duration**: 4 weeks to level up
### If You Want to Master Vim
- **Pace**: All topics + advanced
- **Time**: 1 hour/day practice
- **Duration**: 3-6 months to mastery
---
## 🗺️ Your Journey Starts Here
### Absolute Beginner?
Start with **[Week 1: Motion Basics](week-01-motions.md)**
### Know hjkl Already?
Jump to **[Week 2: Text Objects](week-02-text-objects.md)**
### Comfortable with Vim?
Explore **[Tips & Tricks](tips-and-tricks.md)** and **[Workflows](workflows.md)**
### Want to Master Everything?
Follow the full 8-week program, then **[Advanced Topics](advanced.md)**
---
## 📈 Track Your Progress
Create a file to track what you've learned:
```vim
:e ~/vim-mastery-log.md
```
Template:
```markdown
# My Vim Mastery Journey
## Week 1: Motion Basics
- Started: 2025-11-01
- Mastered: w, b, e, 0, $
- Still practicing: f/F, t/T
- Favorite new trick: dt, (delete till comma)
## Week 2: Text Objects
...
```
---
## 🎯 Success Metrics
You're making progress when:
- ✅ You reach for hjkl instead of arrow keys
- ✅ You think "change inner word" instead of selecting with mouse
- ✅ You prefer Vim commands over GUI operations
- ✅ You can edit without looking at keyboard
- ✅ You start teaching others
- ✅ You feel frustrated using non-Vim editors
---
## 💬 Community
Share your progress:
- **Reddit**: r/vim, r/neovim
- **Discord**: Neovim community server
- **GitHub**: Open issues with questions
---
## 📚 Additional Resources
### Books
- **Practical Vim** by Drew Neil (highly recommended!)
- **Modern Vim** by Drew Neil
- **Learning the Vi and Vim Editors**
### Videos
- **ThePrimeagen's Vim Course**
- **Vim Casts** (vimcasts.org)
- **TJ DeVries' Neovim streams**
### Interactive
- `:Tutor` - Built into Neovim
- **Vim Adventures** - Learn through gaming
- **OpenVim** - Interactive tutorial
### References
- `:help` - Vim's excellent documentation
- **vim.rtorr.com** - Quick reference
- **This config's cheatsheet** - `<Leader>sc`
---
## 🎊 Ready to Begin?
Remember: **Progress > Perfection**
Every expert was once a beginner. The only difference is they kept practicing.
---
<div align="center">
**Your journey to Vim mastery starts now!**
[Week 1: Motion Basics →](week-01-motions.md)
[Back to Documentation](../README.md) | [Tips & Tricks](tips-and-tricks.md)
</div>

380
docs/vim-mastery/week-01-motions.md Normal file
View file

@ -0,0 +1,380 @@
# 🎯 Week 1: Motion Basics
Master efficient navigation - the foundation of Vim proficiency.
---
## 🎓 Learning Objectives
By the end of this week, you will:
- Navigate without arrow keys
- Move by words, not characters
- Jump to specific characters on a line
- Understand the power of count + motion
- Be faster than mouse + arrow keys
---
## 📚 Core Commands
### Basic Directional Movement
```vim
h " Left ←
j " Down ↓
k " Up ↑
l " Right →
```
**Practice Goal**: Use only hjkl for one full day. Unmap arrow keys if needed!
### Word Movement (Most Important!)
```vim
w " Next word (start)
e " Next word (end)
b " Previous word (start)
ge " Previous word (end)
W " Next WORD (whitespace separated)
E " Next WORD (end)
B " Previous WORD
```
**Difference**:
- `word`: Stops at punctuation (my-function → 3 words)
- `WORD`: Whitespace only (my-function → 1 WORD)
### Line Movement
```vim
0 " Start of line
^ " First non-whitespace character
$ " End of line
g_ " Last non-whitespace character
```
### Character Search (Super Powerful!)
```vim
f{char} " Find next {char} on line →
F{char} " Find previous {char} on line ←
t{char} " Till next {char} (stop before)
T{char} " Till previous {char}
; " Repeat last f/F/t/T forward
, " Repeat last f/F/t/T backward
```
**Pro Tip**: `f` and `t` are game-changers for editing!
---
## 💪 Practice Exercises
### Exercise 1: Word Navigation (5 minutes)
Open any code file:
```vim
:e ~/.config/nvim/init.lua
```
Practice:
1. Use `w` to move forward 10 words
2. Use `b` to come back
3. Use `e` to jump to word ends
4. Compare speed: `wwwww` vs `5w` (count!)
### Exercise 2: Line Precision (5 minutes)
In the same file:
```vim
" Jump to line start
0
" Jump to first character
^
" Jump to line end
$
" Try this combo: Move to end, then back to start
$^
```
### Exercise 3: Character Hunting (10 minutes)
Find a line with multiple parentheses or quotes:
```lua
local function test(arg1, arg2, arg3)
```
Practice:
```vim
f( " Jump to first (
; " Jump to next (
; " Jump to next (
, " Go back one (
```
Try these scenarios:
- Jump to the closing quote: `f"`
- Delete till comma: `dt,`
- Change till closing paren: `ct)`
### Exercise 4: Combine Motions (10 minutes)
Real-world scenarios:
**Scenario 1**: Change the word "function" to "method"
```vim
" Position cursor on 'f' in function
cw " Change word
method<Esc>
```
**Scenario 2**: Delete from cursor to end of line
```vim
d$ " or D
```
**Scenario 3**: Change from here to next underscore
```vim
ct_
```
---
## 🎯 Daily Challenges
### Monday: Basic hjkl
- Disable arrow keys: Add to `init.lua`:
```lua
vim.keymap.set('n', '<Up>', '<Nop>')
vim.keymap.set('n', '<Down>', '<Nop>')
vim.keymap.set('n', '<Left>', '<Nop>')
vim.keymap.set('n', '<Right>', '<Nop>')
```
- Navigate only with hjkl for the entire day
### Tuesday: Word Motions
- Practice `w`, `b`, `e` every time you move
- Count your keystrokes: `www` = 3, `3w` = 2
- Use counts!
### Wednesday: Line Jumps
- Every time you need line start/end, use `^` or `$`
- Stop using `0` (except when you really need column 0)
### Thursday: Character Search
- Find 10 opportunities to use `f` or `t`
- Practice `;` and `,` for repeating
- Try `dt,` and `ct)` patterns
### Friday: Combinations
- Combine everything: `d3w`, `c$`, `vf)`, etc.
- Edit entire lines without arrow keys
- Feel the power!
---
## 🔥 Real-World Patterns
### Pattern 1: Change Till Character
```vim
" Change from cursor to next comma
ct,
```
**Use when**: Editing function arguments
### Pattern 2: Delete Word Forward
```vim
" Delete from cursor to end of word
dw
" Delete 3 words
d3w
```
**Use when**: Removing variable names
### Pattern 3: Jump and Edit
```vim
" Find opening paren, then change till closing
f(ct)
```
**Use when**: Changing function parameters
### Pattern 4: End of Line Operations
```vim
" Append at end of line
A
" Delete to end of line
D
" Change to end of line
C
```
**Use when**: Adding semicolons, removing trailing code
---
## 📊 Progress Checklist
Track your mastery:
```
Day 1:
[ ] Used hjkl instead of arrows at least 50% of time
[ ] Felt uncomfortable (this is good!)
Day 2:
[ ] Used w/b/e consciously 20+ times
[ ] Started thinking in "words" not "characters"
Day 3:
[ ] Used ^ and $ instead of Home/End
[ ] Comfortable with 0/^/$ distinction
Day 4:
[ ] Used f/t successfully 10+ times
[ ] Discovered one "aha!" moment with dt or ct
Day 5:
[ ] Combined motions (d3w, c$, etc.)
[ ] Hjkl feels natural
[ ] Ready for Week 2!
```
---
## 🎮 Speed Drills
### Drill 1: The Word Race (2 minutes)
```vim
" Open a file
" Start at top: gg
" Goal: Get to word "function" on line 50
" Slow way: jjjjjjjjwwwwwwww
" Fast way: 50G/function<CR>
" Week 1 way: 50G (jump to line) then use w/e
```
### Drill 2: Line Ninja (2 minutes)
```vim
" Create test line:
" the quick brown fox jumps over the lazy dog
" Tasks (as fast as possible):
0 " Line start
$ " Line end
^ " First char
fb " Find 'b'
; " Next 'b'
e " End of word
```
### Drill 3: Edit Marathon (5 minutes)
```lua
-- Start with:
local result = calculate(arg1, arg2, arg3, arg4)
-- Tasks:
-- 1. Change "calculate" to "compute"
-- Solution: /calc<CR>cw compute<Esc>
--
-- 2. Delete ", arg4"
-- Solution: f4 (on '4') then dF, (delete back to comma)
--
-- 3. Change "result" to "output"
-- Solution: 0 (start of line) cw output<Esc>
```
---
## 💡 Pro Tips
### Tip 1: Think in Motions
Don't think: "I need to move 5 characters right"
Think: "I need to move to the next word"
### Tip 2: Use Counts
`5w` is faster than `wwwww` and requires less thought.
### Tip 3: f/t Are Superpowers
Once you master `f` and `t`, you'll never want to use arrow keys for horizontal navigation.
### Tip 4: Learn the Difference
- `w` stops at punctuation: `my-word` = 3 stops
- `W` only stops at whitespace: `my-word` = 1 stop
### Tip 5: Combine with Operators
Motions are 10x powerful with operators (d, c, y):
- `dw` = delete word
- `ct.` = change till period
- `y$` = yank to end of line
---
## 🎯 Week 1 Goal
**By end of week, you should prefer hjkl + word motions over arrow keys.**
If you catch yourself reaching for arrows or mouse, that's your cue to practice more!
---
## 🔗 Quick Reference Card
Print this or keep it visible:
```
┌─────────────────────────────────────┐
│ Week 1: Motion Basics │
├─────────────────────────────────────┤
│ hjkl - Directions │
│ w/b/e - Word motions │
│ ^/$ - Line start/end │
│ f/F - Find character │
│ t/T - Till character │
│ ;/, - Repeat find │
│ │
│ Combos: │
│ dw - Delete word │
│ dt, - Delete till comma │
│ c$ - Change to end │
│ 5w - Move 5 words │
└─────────────────────────────────────┘
```
---
## ❓ Common Questions
**Q: Why not use arrow keys?**
A: They're far from home row. Hjkl is faster once trained.
**Q: When should I use w vs W?**
A: Use `w` for code (stops at punctuation). Use `W` for prose (whitespace only).
**Q: I'm slower with hjkl!**
A: Normal! Stick with it for 3 days. Speed comes after correctness.
**Q: Do I really need to learn f/t?**
A: YES! They're the secret weapon. Worth the practice.
---
## 🎊 Graduation Criteria
You're ready for Week 2 when:
- ✅ hjkl feels natural (no conscious thought)
- ✅ You use w/b/e more than arrow keys
- ✅ You've used f/t successfully in real work
- ✅ You can navigate without looking at keyboard
- ✅ You feel frustrated when using arrow keys
---
<div align="center">
**Congratulations on completing Week 1!**
Practice these daily, and they'll become second nature.
[← Back to Vim Mastery](README.md) | [Week 2: Text Objects →](week-02-text-objects.md)
</div>