Neovim Config Tutorial
Up: Neovim Down: bootstrap, platforms, options, settings keymaps autocmds, plugins, LSP, completion, snippets, filetype detection
This Neovim setup is not a plugin shopping list. It is a small workshop that wakes up differently depending on the project you open.
The editor provides the bench, drawers, lights, gauges, and habits. The project provides the tools. On NixOS, that distinction matters: Neovim should not use Mason as the package manager for language servers and debuggers. The language servers, formatters, linters, debuggers, and CLIs should come from devShell, devenv, or another project environment.
The Shape
The config has five layers:
| Layer | Source | Job |
|---|---|---|
| Doorway | init.lua | Load defaults, helpers, user settings, plugins, autocmds, and colors. |
| Mood board | user-defaults.lua and user-settings.lua | Decide which rooms are open today: LSP, Git, DAP, notes, AI, databases, notebooks. |
| Furniture | settings.lua, keymappings.lua, autocommands.lua | Make editing feel stable before plugins join the party. |
| Tool wall | lua/plugins/*.lua | Install and configure plugin families through Lazy.nvim. |
| Project air | devenv.nix, shell.nix, .envrc | Put external tools on $PATH for the editor to discover. |
Why This Is Nix-Aware
On ordinary Linux, Mason can be a convenience drawer for installing LSP servers. On NixOS, Mason fights the operating system. It downloads mutable binaries into Neovim state, while Nix wants reproducible packages in a declared environment.
This config notices NixOS with /etc/NIXOS and disables Mason there. The editor then expects tools like nixd, nil, lua-language-server, ruff, basedpyright, eslint, or js-debug-adapter to be present because the project shell provided them.
{ pkgs, ... }:
{
packages = with pkgs; [
nixd
nil
lua-language-server
stylua
];
}That is the central contract: Neovim asks, the project answers.
Reading Order
Start with bootstrap to see how the config wakes up.
Then read platforms before touching LSPs or debuggers, especially on NixOS.
Use plugins as the full atlas. Every plugin is named there with why it exists.
Use the category notes when you want the story rather than the inventory.
Public Notes Rule
These notes are public. Private paths, workspaces, forge hosts, and credentials are intentionally described with placeholders such as ~/notes/vault, ~/projects/flakes, gitlab.example.com, and /path/to/project.
Related: NixOS flakes, text editor