Skip to content

johnmathews/neovim

BranchesTags

Repository files navigation

Neovim Configuration

A robust, performant Neovim configuration optimized for Python, JavaScript/TypeScript, Lua, Bash, SQL, YAML, and Markdown development.

Version: 1.2.0
Last Updated: 2025-11-08
Repository: https://github.com/johnmathews/neovim

🎯 Features

  • Full LSP Support - Language servers for 10+ languages via Mason
  • Fuzzy Finding - Telescope with multiple search modes and extensions
  • Git Integration - Gitsigns for inline blame, diffs, and staging
  • Smart Completion - nvim-cmp with LuaSnip snippets
  • Syntax Highlighting - Treesitter with custom text objects
  • Fast Navigation - Leap motion, Harpoon marks, and project management
  • Performance - Lazy-loaded plugins, ~350ms startup time
  • Testing - Automated LSP testing and comprehensive test suite
  • Documentation - Detailed guides for LSP, keymaps, and performance

📋 Quick Start

Requirements

  • Neovim: v0.11.4+

  • Node.js: v18+ (for LSP servers)

  • CLI Tools:

    brew install luacheck stylua ripgrep fd glow

    glow powers the in-editor Markdown preview described below.

  • Optional: pynvim for Python support

Installation

# Backup existing config
mv ~/.config/nvim ~/.config/nvim.backup

# Clone this repository
git clone https://github.com/johnmathews/neovim.git ~/.config/nvim

# Launch Neovim (plugins will auto-install)
nvim

# Install LSP servers via Mason
:Mason

First Steps

  1. Install git hooks: Run ./scripts/install-hooks to enable automatic quality checks
  2. Check health: :checkhealth or run ./scripts/health-check
  3. View keymaps: <Tab>tk or see KEYMAPS.md
  4. Configure LSP: See LSP.md for language server setup
  5. Test LSP: Run ./test/test_lsp.sh to verify LSP attachment

🚀 Key Features Guide

1. Telescope (Fuzzy Finder)

Prefix: <Tab> (all Telescope commands start with Tab)

Keymap Function
<Tab>f Find files (respects .gitignore)
<Tab>a Find all files
<Tab>s Search text (ripgrep)
<Tab>x Search with ripgrep args
<Tab>r Recent buffers
<Tab>tk Search keymaps
<Tab>tc Command history
<Tab>gc Git commits
<Tab>gb Git branches
<Tab>z Resume last search

Telescope Extensions:

  • fzf-native - Better performance and FZF syntax support
  • live_grep_args - Pass arguments to ripgrep (e.g., --no-ignore, -tpy)
  • smart_history - Persistent search history
  • project - Project management

2. LSP (Language Server Protocol)

Available via Mason: Python (pyright), Lua (lua_ls), JavaScript/TypeScript (ts_ls), YAML (yamlls), Bash, JSON, SQL, Markdown, HTML, CSS

Keymap Function
K Hover documentation
gd Go to definition
gD Go to declaration
gr Go to references
gi Go to implementation
<leader>rn Rename symbol
<leader>ca Code actions
<leader>cf Format document
[d Previous diagnostic
]d Next diagnostic
<leader>q Diagnostic quickfix list

LSP Documentation: See LSP.md for detailed server configurations and troubleshooting.

3. Git Integration (Gitsigns)

Keymap Function
<leader>sb Blame current line
<leader>sS Stage buffer
<leader>su Undo stage hunk
<leader>sr Reset hunk
<leader>sp Preview hunk
]c Next git hunk
[c Previous git hunk

Visual Indicators:

  • | - Added or changed line
  • _ - Deleted line
  • ~ - Changed line number

4. Navigation & Motion

Leap Motion:

  • s - Jump forward by 2-character search
  • S - Jump backward by 2-character search
  • Type 2 characters → see labeled jump points → press label

Harpoon (Quick Marks):

  • <leader>ha - Add file to harpoon
  • <leader>hh - Toggle harpoon menu
  • <leader>h1-4 - Jump to harpooned file 1-4

Marks:

  • m, - Create next available mark
  • m; - Toggle mark at current line
  • dmx - Delete mark x
  • dm<space> - Delete all marks in buffer
  • m] - Next mark
  • m[ - Previous mark

5. Window (Split) Management

Prefix: <C-w> (Control+W, then see which-key options)

Keymap Function
<C-w>s Horizontal split
<C-w>v Vertical split
<C-w>H Rotate layout counterclockwise
<C-w>J/K/L Rotate layout other directions
<C-w>q Close window
<C-w>= Equalize window sizes

6. Markdown Authoring

Keymap/Command Function
<leader>mg Open a live Glow preview for the current Markdown buffer
:Glow Manually trigger the Glow preview command

Details:

  • Uses glow.nvim with a 120-column floating window, rounded border, and 85% screen height.
  • Automatically lazy-loads when editing Markdown, running :Glow, or pressing <leader>mg.
  • Requires the glow CLI (install via brew install glow).
  • Falls back with a warning if the CLI is missing so you know why the preview did not start.

📁 Configuration Structure

~/.config/nvim/
├── init.lua                    # Entry point
├── lua/
│   ├── options.lua             # Neovim options
│   ├── mappings.lua            # Keybindings
│   ├── autocmd.lua             # Autocommands
│   ├── functions.lua           # Custom functions
│   ├── colorscheme.lua         # Theme configuration
│   ├── plugins.lua             # Plugin declarations (lazy.nvim)
│   ├── plugins/                # Plugin configurations (45 files)
│   │   ├── lsp.lua             # LSP setup
│   │   ├── telescope.lua       # Telescope configuration
│   │   ├── treesitter.lua      # Treesitter setup
│   │   ├── cmp.lua             # Completion configuration
│   │   └── ...
│   └── snippets/               # LuaSnip snippets (6 languages)
├── ftplugin/                   # Filetype-specific settings (22 files)
├── scripts/
│   ├── health-check            # Configuration health check
│   ├── quality-gate            # Pre-commit validation
│   └── pre-commit              # Git pre-commit hook
├── test/                       # Test files for LSP/linter validation
│   ├── test_lsp.sh             # Automated LSP testing
│   ├── python/                 # Python test files
│   ├── lua/                    # Lua test files
│   ├── javascript/             # JavaScript test files
│   └── ...
└── docs/
    ├── AGENTS.md               # Architecture & conventions
    ├── CHANGELOG.md            # Version history
    ├── IMPROVEMENTS.md         # Enhancement tracking
    ├── KEYMAPS.md              # Complete keymap reference
    ├── LSP.md                  # LSP documentation
    ├── PERFORMANCE.md          # Performance analysis
    ├── TESTING.md              # Testing infrastructure
    ├── TEST_RESULTS.md         # Latest test results
    └── TESTING_CHANGELOG_GUIDE.md # Testing & changelog guide

🧪 Testing & Validation

Automated Tests

# Test LSP attachment (4 languages)
./test/test_lsp.sh

# Run health check
./scripts/health-check

# Run quality gate (linting + formatting)
./scripts/quality-gate

Test Results (2025-11-08)

  • ✅ Health Check: PASS
  • ✅ Code Quality: 0 warnings / 0 errors (58 Lua files)
  • ✅ LSP Attachment: 4/4 languages (100%)
  • ✅ Startup Performance: 350ms (excellent, <500ms threshold)

Detailed Results: See docs/TEST_RESULTS.md

⚡ Performance

Current Performance:

  • Headless startup: ~350ms (average of 5 runs)
  • Real-world startup: ~250-280ms (with lazy-loading)
  • Plugin count: 88 (8 plugins lazy-loaded)

Lazy-Loaded Plugins:

  • Telescope (loads on <Tab> keypress)
  • nvim-cmp (loads on InsertEnter)
  • LuaSnip (loads on InsertEnter)
  • Gitsigns (loads on BufReadPre)
  • Alpha dashboard (loads on VimEnter)
  • Lualine (loads on VeryLazy)
  • Mason (deferred with run_on_start = false)
  • Harpoon (loads on keypress)

Performance Guide: See docs/PERFORMANCE.md for detailed analysis and optimization tips.

📚 Documentation

Document Purpose
AGENTS.md Architecture, design principles, conventions
CHANGELOG.md Version history and change tracking
IMPROVEMENTS.md Enhancement implementation details
KEYMAPS.md Complete keymap reference (searchable via <Tab>tk)
LSP.md LSP servers, formatters, linters
PERFORMANCE.md Startup analysis and optimization
TESTING.md Testing infrastructure and CI/CD
TEST_RESULTS.md Latest test execution results
TESTING_CHANGELOG_GUIDE.md Testing & changelog workflows

🔧 Common Tasks

Update Plugins

# Inside Neovim
:Lazy update

# Check for issues
:Lazy health

Update LSP Servers

# Inside Neovim
:Mason

# Or update all
:MasonUpdateAll

Format Code

# Format current buffer
<leader>cf

# Or via command
:lua require('conform').format()

Lint Code

# Lint current buffer
<leader>cl

# Or via command
:lua require('lint').try_lint()

Run Tests

# Install git hooks (one-time setup)
./scripts/install-hooks

# Test LSP stack
./test/test_lsp.sh

# Full health check
./scripts/health-check

# Quality gate (linting + formatting)
./scripts/quality-gate

Git Hooks (Automatic Quality Assurance)

Pre-commit hook (runs before each commit):

  • Luacheck validation
  • Code formatting check
  • Neovim load test
  • Common issue detection

Pre-push hook (runs before push to remote):

  • Full quality gate
  • LSP attachment tests
  • Health check
  • Documentation validation

Bypass hooks (emergency only):

git commit --no-verify
git push --no-verify

🐛 Troubleshooting

LSP Not Attaching

  1. Check LSP status: :LspInfo
  2. Verify server installed: :Mason
  3. Check logs: :LspLog
  4. Run LSP test: ./test/test_lsp.sh
  5. See LSP.md for detailed troubleshooting

Slow Startup

  1. Check startup time: nvim --startuptime startup.log +qa
  2. Profile plugins: :Lazy profile
  3. See docs/PERFORMANCE.md for optimization tips

Linting/Formatting Issues

  1. Check conform status: :ConformInfo
  2. Verify formatter installed: :Mason
  3. Check configuration: See docs/LSP.md

Plugin Errors

  1. Check plugin health: :Lazy health
  2. Update plugins: :Lazy sync
  3. Check Lazy logs: :Lazy log

🤝 Contributing

This is a personal configuration, but suggestions are welcome!

Making Changes

  1. Create a feature branch
  2. Make changes
  3. Update CHANGELOG.md under [Unreleased]
  4. Run tests: ./scripts/quality-gate
  5. Commit with descriptive message

Commit Messages

Follow conventional commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • perf: - Performance improvements
  • refactor: - Code refactoring
  • test: - Test changes

📜 License

MIT License - Feel free to use and modify as needed.

🙏 Acknowledgments

Built with:

And 80+ other amazing plugins. See lua/plugins.lua for complete list.

📞 Support

Enjoy your Neovim experience! 🚀

About

neovim configuration including plugins and customizations

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages