Neovim Configuration

July 28, 2026 · View on GitHub

A minimal, fast Neovim configuration for Neovim 0.12+ with lazy-loading, LSP support, and intuitive keybindings.

Installation

1. System Dependencies (Required)

# Core requirements
brew install neovim    # v0.12+ required
brew install git
brew install ripgrep   # Fast grep (used by picker)
brew install fd        # Fast find (used by picker)
brew install lazygit   # Git TUI
brew install node      # Required for some LSPs and tools
brew install npm       # Required for markdown-preview

2. Fonts (Required)

Install a Nerd Font for icons:

brew install --cask font-jetbrains-mono-nerd-font
# or
brew install --cask font-fira-code-nerd-font

Then set your terminal to use the installed font.

3. Language Toolchains (Install what you need)

# Go
brew install go
# After install, run :GoInstallBinaries in nvim

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# After install, run :CargoInstallTools in nvim

# Zig
brew install zig

# Python
brew install python
pip install pynvim  # Optional: for some plugins

# PHP
brew install php composer

# Laravel LSP (optional, for Laravel projects — see "Language Servers" below)
composer global require laravel/lsp

# Swift / iOS (macOS only)
# Xcode + Command Line Tools provide sourcekit-lsp and xcodebuild

# Lua (for luarocks, optional)
brew install lua luarocks

4. Optional Dependencies

# Markdown preview (browser-based)
# markdown-preview.nvim will auto-install, but needs npm

# Image rendering (optional)
brew install imagemagick ghostscript

# Mermaid diagrams (optional)
npm install -g @mermaid-js/mermaid-cli

# LaTeX rendering (optional)
brew install tectonic

5. Clone and Start

# Backup existing config
mv ~/.config/nvim ~/.config/nvim.bak
mv ~/.local/share/nvim ~/.local/share/nvim.bak
mv ~/.local/state/nvim ~/.local/state/nvim.bak
mv ~/.cache/nvim ~/.cache/nvim.bak

# Clone this config
git clone <your-repo> ~/.config/nvim

# Start Neovim - plugins will auto-install on first launch
nvim

6. Post-Install Steps

Run these commands in Neovim after first launch:

" Wait for lazy.nvim to finish installing plugins, then:

" Generate help tags
:helptags ALL

" Install treesitter parsers (auto-installs, but can force)
:TSUpdate

" Check health
:checkhealth

" For Go development
:GoInstallBinaries

" For Rust development  
:CargoInstallTools

" Build markdown-preview (if not auto-built)
:Lazy build markdown-preview.nvim

Verify Installation

:checkhealth

All checks should pass. Common fixes:

Missing CLI tools: brew install <tool>
Treesitter errors: :TSUpdate
LSP not working: :LspInfo and :Mason

What Gets Auto-Installed

Via Mason (LSP/Linters/Formatters)

Category	Tools
LSP Servers	lua_ls, gopls, zls, ts_ls, rust-analyzer, intelephense, bashls, pyright, cssls, html, jsonls, yamlls, sourcekit-lsp¹
Linters	eslint_d, luacheck, golangci-lint, shellcheck, markdownlint, yamllint, jsonlint, htmlhint, stylelint, phpstan, ruff, mypy
Formatters	stylua, goimports, prettier, black, isort, shfmt, pint

¹ sourcekit-lsp ships with Xcode (not managed by Mason).

Via Treesitter

Parsers for: bash, c, css, go, html, javascript, json, latex, lua, markdown, php, python, rust, scss, svelte, swift, terraform, tsx, typescript, vim, vue, yaml, zig

Structure

~/.config/nvim/
├── init.lua                 # Entry point
├── lua/
│   ├── core/
│   │   ├── init.lua         # Loads all core modules
│   │   ├── options.lua      # Neovim options + filetype detection
│   │   ├── keymaps.lua      # Core keybindings
│   │   ├── autocmds.lua     # Auto commands
│   │   ├── lazy.lua         # Plugin manager bootstrap
│   │   └── utils.lua        # Utility functions
│   └── plugins/
│       ├── coding.lua       # Completion, treesitter
│       ├── colorschemes.lua # Themes
│       ├── editor.lua       # Flash, mini.nvim, persistence
│       ├── formatting.lua   # Conform.nvim (format on save)
│       ├── git.lua          # Gitsigns, fugitive, diffview
│       ├── linting.lua      # nvim-lint
│       ├── lsp.lua          # Mason + LSP keymaps + diagnostic config
│       ├── snacks.lua       # Picker, explorer, notifications
│       ├── swift.lua        # xcodebuild.nvim (Swift/iOS)
│       ├── tools.lua        # Misc tools
│       └── ui.lua           # Which-key, trouble, markdown
├── lsp/                     # Per-server configs (vim.lsp.config / 0.11+ API)
│   ├── bashls.lua
│   ├── cssls.lua
│   ├── gopls.lua
│   ├── html.lua
│   ├── intelephense.lua
│   ├── jsonls.lua
│   ├── lua_ls.lua
│   ├── pyright.lua
│   ├── rust_analyzer.lua
│   ├── sourcekit.lua
│   ├── ts_ls.lua
│   ├── yamlls.lua
│   └── zls.lua
├── ftplugin/
│   ├── go.lua               # Go commands (:GoTest, :GoBuild, etc.)
│   ├── rust.lua             # Rust commands (:CargoRun, :CargoTest, etc.)
│   ├── swift.lua            # Swift indentation/comment settings
│   └── zig.lua              # Zig commands (:ZigBuild, :ZigTest, etc.)
└── doc/
    ├── go.txt               # :help go.txt
    ├── rust.txt             # :help rust.txt
    └── zig.txt              # :help zig.txt

Keybindings

Leader key: <Space>

Essential (No Prefix)

Key	Action
`<C-s>`	Save file
`<C-h/j/k/l>`	Navigate windows
`<C-Up/Down/Left/Right>`	Resize windows
`<Esc>`	Clear search highlight
`jj` / `jk`	Exit insert mode
`H` / `L`	Start/End of line
`<S-h>` / `<S-l>`	Prev/Next buffer
`Q`	Delete buffer
`K`	Hover documentation
`s`	Flash jump
`S`	Flash treesitter

Quick Access (Leader)

Key	Action
`<leader><space>`	Find files
`<leader>/`	Grep
`<leader>,`	Switch buffer
`<leader>.`	Scratch buffer
`<leader>e`	File explorer
`<leader>q`	Quit
`<leader>Q`	Quit all
`<leader>?`	Buffer keymaps
`<leader>K`	All keymaps
`<C-/>`	Terminal

Buffers (`<leader>b`)

Key	Action
`<leader>bb`	Switch buffer
`<leader>bd`	Delete buffer
`<leader>bo`	Delete other buffers

Code (`<leader>c`)

Key	Action
`<leader>ca`	Code action
`<leader>cr`	Rename symbol
`<leader>cd`	Line diagnostic
`<leader>cf`	Format
`<leader>cv`	Definition in vsplit

Diagnostics (`<leader>d`)

Key	Action
`<leader>dd`	Workspace diagnostics
`<leader>db`	Buffer diagnostics
`<leader>dt`	Trouble (workspace)
`<leader>dT`	Trouble (buffer)
`<leader>dq`	Quickfix list
`<leader>dl`	Location list

Files (`<leader>f`)

Key	Action
`<leader>ff`	Find files
`<leader>fr`	Recent files
`<leader>fc`	Config files
`<leader>fg`	Git files
`<leader>fp`	Projects
`<leader>fR`	Rename file

Git (`<leader>g`)

Key	Action
`<leader>gg`	Lazygit
`<leader>gs`	Status
`<leader>gl`	Log
`<leader>gL`	Log (line)
`<leader>gf`	Log (file)
`<leader>gd`	Diff (picker)
`<leader>gD`	Diff HEAD
`<leader>gc`	Checkout branch
`<leader>go`	Open in browser
`<leader>gb`	Blame line
`<leader>gB`	Blame buffer
`<leader>gR`	Reset buffer
`<leader>gS`	Stage buffer
`<leader>gi`	GitHub issues
`<leader>gp`	GitHub PRs

Git Hunks (`<leader>gh`)

Key	Action
`<leader>ghp`	Preview hunk
`<leader>ghP`	Preview hunk inline
`<leader>ghs`	Stage hunk
`<leader>ghu`	Undo stage hunk
`<leader>ghr`	Reset hunk
`]h` / `[h`	Next/Prev hunk

LSP (`<leader>l`)

Key	Action
`<leader>ls`	Document symbols
`<leader>lS`	Workspace symbols
`<leader>li`	LSP info
`<leader>lr`	LSP restart
`<leader>lh`	Toggle inlay hints
`<leader>lt`	References (Trouble)
`<leader>lT`	Symbols (Trouble)

Markdown (`<leader>m`)

Key	Action
`<leader>mp`	Preview in browser
`<leader>mr`	Toggle render in buffer

Notifications (`<leader>n`)

Key	Action
`<leader>nn`	Notification history
`<leader>nd`	Dismiss all

Search (`<leader>s`)

Key	Action
`<leader>sg`	Grep
`<leader>sw`	Word under cursor
`<leader>sb`	Buffer lines
`<leader>sB`	Grep buffers
`<leader>sh`	Help
`<leader>sm`	Marks
`<leader>sj`	Jumps
`<leader>sk`	Keymaps
`<leader>sc`	Commands
`<leader>s:`	Command history
`<leader>s/`	Search history
`<leader>sr`	Registers
`<leader>sR`	Resume last
`<leader>su`	Undo history

UI/Toggles (`<leader>u`)

Key	Action
`<leader>us`	Toggle spelling
`<leader>uw`	Toggle wrap
`<leader>ur`	Toggle relative numbers
`<leader>ul`	Toggle line numbers
`<leader>uD`	Toggle diagnostics
`<leader>uc`	Toggle conceal
`<leader>uT`	Toggle treesitter
`<leader>ub`	Toggle background
`<leader>uh`	Toggle inlay hints
`<leader>ui`	Toggle indent guides
`<leader>ud`	Toggle dim
`<leader>uC`	Colorschemes
`<leader>uz`	Zen mode
`<leader>uZ`	Zoom

Windows (`<leader>w`)

Key	Action
`<leader>wd`	Close window
`<leader>ws`	Split horizontal
`<leader>wv`	Split vertical
`<leader>ww`	Other window
`<leader>w=`	Equal size
`<leader>wm`	Maximize

Goto (`g`)

Key	Action
`gd`	Definition
`gD`	Declaration
`gr`	References
`gi`	Implementation
`gy`	Type definition

Key	Action
`[d` / `]d`	Prev/Next diagnostic
`[h` / `]h`	Prev/Next hunk
`[b` / `]b`	Prev/Next buffer
`[[` / `]]`	Prev/Next reference

Editing

Key	Mode	Action
`J` / `K`	Visual	Move lines down/up
`<` / `>`	Visual	Indent (stay selected)
`p`	Visual	Paste (no yank)
`X`	Normal	Split line
`YY`	Normal	Yank block {}
`n` / `N`	Normal	Next/Prev match (centered)

Surround (mini.surround)

Key	Action
`gsa`	Add surrounding
`gsd`	Delete surrounding
`gsr`	Replace surrounding
`gsf`	Find surrounding (right)
`gsF`	Find surrounding (left)

Language-Specific Commands

Go (`:help go.txt`)

Command	Action
`:GoBuild`	go build
`:GoRun`	go run
`:GoTest`	go test
`:GoTestFunc`	Test function under cursor
`:GoTestFile`	Test current package
`:GoCoverage`	Test with coverage
`:GoModTidy`	go mod tidy
`:GoGet <pkg>`	go get
`:GoVet`	go vet
`:GoLint`	golangci-lint
`:GoDoc <sym>`	go doc
`:GoImpl`	Generate interface stubs
`:GoIfErr`	Insert if err != nil
`:GoAddTags`	Add struct tags
`:GoAlt`	Switch test/source
`:GoInstallBinaries`	Install all Go tools

Rust (`:help rust.txt`)

Command	Action
`:CargoBuild`	cargo build
`:CargoBuildRelease`	cargo build --release
`:CargoRun`	cargo run
`:CargoTest`	cargo test
`:CargoTestFunc`	Test function under cursor
`:CargoCheck`	cargo check
`:CargoClippy`	cargo clippy
`:CargoFmt`	cargo fmt
`:CargoAdd <crate>`	cargo add
`:CargoDoc`	cargo doc
`:RustDoc <crate>`	Open docs.rs
`:CargoInstallTools`	Install cargo subcommands

Zig (`:help zig.txt`)

Command	Action
`:ZigBuild`	zig build
`:ZigBuildRelease`	zig build -Doptimize=ReleaseFast
`:ZigRun`	zig build run
`:ZigRunFile`	zig run
`:ZigTest`	zig build test
`:ZigTestFile`	zig test
`:ZigFmt`	zig fmt
`:ZigDoc`	Open Zig docs
`:ZigAlt`	Switch test/source

Swift / iOS (`<leader>x`)

Key / Command	Action
`<leader>xs`	Setup project
`<leader>xb` / `xr`	Build / Build & Run
`<leader>xt`	Run tests
`<leader>xT` / `xf`	Test current class / function
`<leader>xS` / `xd`	Select scheme / device
`<leader>xo`	Boot simulator
`<leader>xl`	Toggle build logs
`:XcodebuildPicker`	All commands menu

Language Servers

Server configs live under lsp/ and are activated via vim.lsp.enable() in lua/plugins/lsp.lua.

Auto-installed via Mason:

Go: gopls
Rust: rust-analyzer
Zig: zls
Lua: lua_ls
TypeScript: ts_ls
Python: pyright
PHP: intelephense
Bash: bashls
CSS/HTML/JSON/YAML: vscode servers

Not managed by Mason:

Swift / Objective-C: sourcekit-lsp (ships with Xcode)
Laravel: laravel-lsp (installed via Composer, see below)

Laravel LSP

laravel/lsp is Laravel's official language server. It is not available through Mason — install it globally with Composer:

composer global require laravel/lsp

Make sure Composer's global bin directory is on your PATH, otherwise Neovim cannot find the laravel-lsp binary:

# Add to ~/.zshrc (macOS default location)
export PATH="$HOME/.config/composer/vendor/bin:$PATH"

# Verify
which laravel-lsp

Config lives in lsp/laravel_lsp.lua. The filename must match the name passed to vim.lsp.enable() in lua/plugins/lsp.lua — laravel_lsp resolves to lsp/laravel_lsp.lua, so a hyphenated filename silently fails to load.

It runs alongside intelephense rather than replacing it. intelephense handles general PHP intelligence (classes, methods, properties); laravel-lsp adds Laravel-aware completion for strings such as config('…'), route('…'), view('…') and env('…'), plus Blade directives. It boots the Laravel application, so it only works in a real Laravel project (one containing artisan).

To verify: open a PHP file in a Laravel project, type config(' in insert mode, and the config keys should appear. :checkhealth vim.lsp lists it as attached.

Formatters (Conform)

Language	Formatter
Go	goimports, gofmt
Rust	rustfmt
Zig	zigfmt
Lua	stylua
JS/TS/JSON/YAML/HTML/CSS	prettier
Python	isort, black
PHP	pint
Shell	shfmt

Format on save is enabled by default.

Linters (nvim-lint)

Language	Linter
Go	golangci-lint
JS/TS	eslint_d
Lua	luacheck
Python	ruff, mypy
PHP	phpstan
Shell	shellcheck

Health Check

:checkhealth

Common fixes:

Missing tools: brew install <tool>
Treesitter errors: :TSUpdate
Go tools: :GoInstallBinaries
Rust tools: :CargoInstallTools

Colorscheme

Default: yukinord

Switch with <leader>uC

Always a WIP.