A reproducible, offline-capable, fully documented Neovim development environment built directly on native Neovim mechanisms. Behaves like a small distribution — fast, quiet, modular, portable — while remaining 100% readable, hand-written configuration. No LazyVim, NvChad, AstroNvim, LunarVim or SpaceVim anywhere in this repository.
- Offline by default. Every plugin is vendored in-repo via
git subtree(pack/vendor/) — cloning this repo is enough, no plugin manager, no download step. Language tooling (LSP/formatter/linter/ debugger) is opt-in and installed explicitly; see Offline Usage. - Quiet by default. A missing optional tool never produces a startup
warning, error, or repeated notification — see
:NvimConfigHealth/:ToolsStatusinstead. Real configuration bugs stay loud. - Demand-driven. Language servers only start for filetypes whose
binary is installed; most plugins (Telescope, nvim-tree, Oil, Trouble,
the debugger UI, markdown/LaTeX/CSV support) load on first actual use, not
at startup. A plain
nvimloads zero optional plugins. - One source of truth per concept. A central language registry
(
lua/languages/*.lua) and tool registry (lua/tools/registry.lua) drive LSP setup, formatting, linting and debugging alike — no copy-pasted per-language configuration. Keymaps and commands are registered through two small registries that simultaneously power which-key,:NvimKeymaps/:NvimCommands, and the generated docs below. - Broad language coverage, from systems languages (C/C++/Rust/Go/Zig/ Assembly) through web (JS/TS/Vue/Svelte/HTML/CSS), JVM (Java/Kotlin), functional (Haskell/OCaml/Elixir/Erlang), scripting (Python/Ruby/Perl/ PowerShell/Bash), data/config formats (JSON/YAML/TOML/XML/SQL/...), and documentation (Markdown/LaTeX/reStructuredText). Full matrix: docs/_generated/languages.md.
- Real debugging, not just LSP —
nvim-dap+nvim-dap-ui, lazily loaded, with a documented keymap set and per-language adapter config. - Cross-platform architecture: macOS, Linux and Windows all go
through the same
lua/util/platform.luafacts andlua/config/platform.luasettings — no hardcoded paths anywhere.
- Neovim 0.12.0 or newer — a hard requirement, not a preference: this
config vendors nvim-treesitter's
mainbranch, which itself requires 0.12+../scripts/install.shrefuses to continue on anything older. git(for cloning and for the plugin-vendoring scripts).- Recommended, optional:
ripgrep,fd, a Nerd Font.
Nothing else is required for a working editor — see Offline Usage.
git clone https://github.com/MichaelWeissDEV/nvim-config.git ~/.config/nvim
nvimor, if you keep the repo elsewhere:
git clone https://github.com/MichaelWeissDEV/nvim-config.git ~/git/nvim-config
./scripts/install.sh # symlinks ~/.config/nvim -> the repo, generates :help tags(scripts/install.ps1 on Windows.) Full details: docs/installation.md.
<space>(leader) opens which-key's group popup.<leader>ff/<leader>fg— find files / live grep (Telescope, loads on first use).<leader>e— file explorer sidebar (nvim-tree, loads on first use);<leader>o/-for Oil's buffer-as-directory editing instead.gd,K,<leader>lr,<leader>la— LSP go-to-definition, hover, rename, code action (once a server has attached).<leader>lf— format the current buffer.<leader>db/<leader>dc— toggle breakpoint / start-or-continue debugging.:NvimConfigHealth— full report of what's vendored and what optional tooling is missing.:NvimKeymaps/:NvimCommands— this config's own keymaps/commands, grouped.:NvimDocs— open the local Sphinx docs (or:help nvim-configif not built yet).
Nothing above installs a single language server, formatter, linter or debugger. Install a profile for what you actually use:
./scripts/bootstrap.sh core # lua_ls, stylua, shellcheck, shfmt, bash-language-server, selene, taplo
./scripts/bootstrap.sh systems # clangd, rust-analyzer, gopls, codelldb, delve, zls, asm-lsp, ...
./scripts/bootstrap.sh python # basedpyright, ruff, debugpy
./scripts/bootstrap.sh web # TS/JS/Vue/Svelte LSPs, eslint, prettier, js-debug-adapter
./scripts/bootstrap.sh all # everything (slow, large download)Full profile list and every tool each one installs:
docs/_generated/tools.md. This
is also the only script (besides the equivalent in-editor
:ToolsInstall/:ToolsUpdate/:Mason*/:TSInstall) that touches the
network — see Offline Usage.
| Key | Action |
|---|---|
<leader>ff / <leader>fg / <leader>fb |
Find files / live grep / buffers |
<leader>e |
File explorer sidebar (nvim-tree) |
<leader>o / - |
File explorer as a buffer (Oil) |
gd / gr / K |
LSP definition / references / hover |
<leader>lr / <leader>la |
LSP rename / code action |
<leader>lf |
Format buffer |
[d / ]d / <leader>xx |
Prev/next diagnostic / diagnostics list (Trouble) |
<leader>db / <leader>dc |
Toggle breakpoint / start-continue debugging |
<leader>gb / ]h / [h |
Git blame line / next-prev hunk |
<C-h/j/k/l> |
Move between windows |
Full table, generated from the config's own keymap registry:
docs/_generated/keymaps.md.
Interactive: press <space> for which-key, or run :NvimKeymaps.
Full generated list: docs/_generated/commands.md,
or run :NvimCommands inside Neovim.
A normal session — editing, LSP, completion, formatting, linting,
debugging with whatever's already installed — never touches the network.
The only things that do, and only when run explicitly, are:
./scripts/bootstrap.sh/.ps1, :ToolsInstall/:ToolsUpdate, :Mason*,
:TSInstall/:TSUpdate, the scripts/plugin-*.sh vendoring scripts, and
the first run of ./scripts/docs-build.sh (to fetch Sphinx). Full
explanation, including a caveat found during real testing (missing
tree-sitter-cli): docs/offline.md.
This README is the entry point; everything else lives under docs/:
- Local Sphinx docs (architecture, per-subsystem pages, platform notes,
troubleshooting, development guide): build with
./scripts/docs-build.sh(.ps1on Windows), then opendocs/_build/html/index.htmlor run:NvimDocsinside Neovim. - Native
:help nvim-config— a fast, always-available subset, generated (like the files below) from the same registries the config itself reads. - docs/_generated/ — the reference tables
(keymaps, commands, plugins, tools, languages) generated by
scripts/generate-docs.luafrom the config's own registries, so these can't drift from what's actually configured. They render as plain Markdown on GitHub and are{include}'d by the Sphinx pages above, so there is exactly one copy of each table. Regenerate with./scripts/docs-build.sh(which also refreshes the Sphinx site and:helptags) after changing a language/tool/keymap/command.
All plugins are vendored via git subtree --squash. Manifest:
scripts/plugins.tsv; pinned commits: plugins.lock.
./scripts/plugin-status.sh # what's vendored, start vs. opt
./scripts/plugin-add.sh <name> # vendor a new plugin from the manifest
./scripts/plugin-update.sh <name> # update one plugin
./scripts/plugin-update-all.sh # update everything that's already vendoredDetails: docs/plugin-updates.md.
Lua, Python, Ruby, Go, Rust, C, C++, Java, Kotlin, Bash, Fish, PowerShell, Assembly, JavaScript, TypeScript, HTML, CSS/SCSS/Sass/Less, Vue, Svelte, JSON, YAML, TOML, XML, SQL, CSV/TSV, dotenv, INI, Dockerfile, Terraform, Nix, Ansible, Markdown, reStructuredText, LaTeX, AsciiDoc, C#, F#, Haskell, OCaml, Elixir, Erlang, PHP, Perl, Zig, CMake, Make, GraphQL, Protobuf. Full matrix with LSP/formatter/linter/debugger/Tree-sitter per language: docs/_generated/languages.md.
| Platform | Status |
|---|---|
| macOS | Primary development platform — real, interactive daily use |
| Linux | Full headless test suite runs on every push (ubuntu-latest) |
| Windows | Platform-independent tests run on every push (windows-latest); the POSIX-only missing-dependency sandbox test is skipped there |
See docs/platform.md for exactly what differs per OS.
Start with :NvimConfigHealth. Common issues and their fixes:
docs/troubleshooting.md.
Adding a language, tool, keymap or command; code style; how the registries fit together: docs/development.md and docs/architecture.md.