Neovim Configuration

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

Navigation ([ / ])

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)

Powered by xcodebuild.nvim. Requires Xcode + Command Line Tools.

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.