NoetherVim

A Neovim distribution with a minimal abstraction layer. The name is after Emmy Noether (the name also contains nvim - noetherVim).

LaTeX, BibTeX, and VimTeX get the same level of support as LSP and treesitter. Everything else you'd expect is configured out of the box: completion (blink.cmp), DAP, diagnostics, formatters. Startup is fast by using lazy-loading.

The distro is opinionated, but anything and everything can be overridden through lua/user/; in fact the distro's architecture prioritizes easy overriding (see Configuration)

Note

NoetherVim is in alpha. The core is stable for daily use, but what counts as a "default" vs. an "overridable" option is still being refined. These choices grew out of my Neovim use and represent my best idea of good, agnostic defaults. If you think there are better choices, open an issue and we can address it there.

Why another distribution?

Many existing Neovim distributions introduce their own abstraction layers: framework APIs, custom event systems, declarative config DSLs, etc. These are powerful, but they sit between you and Neovim; your configuration ends up targeting the distribution, not the editor. I wanted an experience that is closer to Neovim's philosophy.

In NoetherVim, plugin specs are standard lazy.nvim, options are vim.o, keymaps are vim.keymap.set(), and so forth. Overriding a default means writing the same Lua you would write in a vanilla Neovim config, and the distro just makes sure your file loads after its own.

The same principle applies to keybindings. Keymaps build on Vim's own prefix conventions rather than funneling everything through <Leader> subgroups (though you can choose to funnel everything through a single prefix): <C-w> for anything window-related (panels, terminal, undo tree), [/] for directional navigation, [o/]o for option toggles, g for goto and LSP actions. <Leader> and <LocalLeader> stay separate (global actions vs. filetype-specific), following :help maplocalleader. Features use Neovim's built-in APIs directly (vim.lsp.config(), vim.diagnostic, vim.fn.setqflist()) and where Neovim 0.12 ships good defaults, the distro leaves them alone.

Neovim 0.12 ships a built-in package manager (vim.pack), but NoetherVim stays on lazy.nvim because the override model (deep-merged opts, auto-imported bundle directories, lazy-loading via event/keys/cmd/ft) depends on its spec system - vim.pack is a plain installer and doesn't provide that layer.

There's also a personal reason to build this distro. After using vim/nvim for ~10 years, my nvim dotfiles have grown to be ~10k lines of code. So this is partly a fun project to convert the core functionality of my personal setup into a distribution.

Requirements

• Neovim >= 0.12
• A Nerd Font for icons
• git, fd, ripgrep, a C compiler (for treesitter parsers)

Neovim: Platform install commands

macOS

brew install neovim ripgrep fd

Ubuntu / Debian

apt install neovim ships an outdated version on most releases. Use the Neovim PPA, an AppImage, or bob to get Neovim >= 0.12.

sudo apt install ripgrep fd-find

Arch

sudo pacman -S neovim ripgrep fd

Fedora

sudo dnf install neovim ripgrep fd-find

Some bundles have their own dependencies:

• latex needs latexmk and a TeX distribution
• debug needs Python 3 with debugpy for Python debugging
• ai needs an API key (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)

Installation

Important

If you have an existing Neovim config, back it up first:

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

Copy the starter config and open Neovim:

mkdir -p ~/.config/nvim
curl -fLo ~/.config/nvim/init.lua \
  https://raw.githubusercontent.com/Chiarandini/NoetherVim/main/init.lua.example
nvim

On first launch, lazy.nvim bootstraps itself, pulls all plugins, and runs noethervim.setup().

Tip

Want to try NoetherVim without replacing your config? Neovim's NVIM_APPNAME feature lets you run multiple configs side by side:

mkdir -p ~/.config/noethervim
curl -fLo ~/.config/noethervim/init.lua \
  https://raw.githubusercontent.com/Chiarandini/NoetherVim/main/init.lua.example
NVIM_APPNAME=noethervim nvim

Your existing ~/.config/nvim/ stays untouched. Add alias nv='NVIM_APPNAME=noethervim nvim' to your shell profile for convenience.

Tip

New to Neovim-as-a-distribution, or coming in primarily for LaTeX / Typst work? See the onboarding guide for mathematicians, a walkthrough of the install, the math bundles, snippets, citations, and how to extend the setup.

Updating

Run :Lazy update inside Neovim. This updates the distro and all plugins.

Migrating from an existing config

Back up your current ~/.config/nvim/ before installing. NoetherVim replaces init.lua, so anything there will be overwritten.

Once you're running, you can bring over your personal settings:

• Plugins - add lazy.nvim specs to lua/user/plugins/ (see Configuration)
• Options/keymaps/autocmds - check what the distro defaults to before re-adding (type :NoetherVim diff keymaps to check out the distro's keymaps)
• LSP configs - NoetherVim configures servers through lua/noethervim/lsp/; if you had custom server settings, look there first

Uninstalling

Quick crash course: the following are important files/locations for any Neovim setup

Path	Contents
~/.config/nvim/init.lua	Your leaders and bundle selection
~/.config/nvim/lua/user/	Your plugin specs, option/keymap/autocmd overrides
~/.config/nvim/lazy-lock.json	Your pinned plugin versions
~/.local/state/nvim/	Shada (command/search history, marks, registers), undo history, sessions, views
~/.local/share/nvim/site/spell/	Custom spell additions

Everything else under ~/.local/share/nvim/ and ~/.cache/nvim/ is installed or generated by the distro and can be regenerated by relaunching Neovim.

To reset the distribution and keep personal data, run

rm -rf ~/.local/share/nvim ~/.cache/nvim

This wipes installed plugins (lazy.nvim, NoetherVim, everything else), Mason-managed LSP servers and formatters, and all caches. Your init.lua, lua/user/, and editing state (history, undo, sessions) stay intact. Next launch re-bootstraps and reinstalls everything from scratch.

To reset the distribution and editing state

rm -rf ~/.local/share/nvim ~/.local/state/nvim ~/.cache/nvim

Same as above but also drops shada, undo history, sessions, and views. Config is still preserved.

To fully uninstall

rm -rf ~/.config/nvim ~/.local/share/nvim ~/.local/state/nvim ~/.cache/nvim

Removes the config, data, state, and cache directories. Restore your backup if you made one.

Tip

If you installed with NVIM_APPNAME=noethervim, substitute noethervim for nvim in every path above.

Configuration

Enabling bundles

Open ~/.config/nvim/init.lua and uncomment the bundles you want in the spec table. Each import path is noethervim.bundles.<category>.<name>:

-- inside require("lazy").setup({ spec = { ... } })
{ import = "noethervim.bundles.languages.latex" },
{ import = "noethervim.bundles.tools.debug" },
{ import = "noethervim.bundles.tools.git" },

All bundles are opt-in - the core is fully functional with none enabled. See Bundles for the full list.

Adding your own plugins

Drop plugin specs in ~/.config/nvim/lua/user/plugins/. Any .lua file there is auto-imported by lazy.nvim:

-- ~/.config/nvim/lua/user/plugins/my-plugins.lua
return {
    { "some/plugin", event = "VeryLazy", opts = {} },
    { "my-local-plugin", dir = "~/programming/my-plugin" },
}

To override an existing plugin's settings, use the same repository string - lazy.nvim deep-merges opts automatically:

-- ~/.config/nvim/lua/user/plugins/snacks.lua
return {
    { "folke/snacks.nvim",
      opts = { picker = { layout = { preset = "vertical" } } },
    },
}

See templates/user/plugins/example.lua in the installed distro for more patterns, or docs/user-config-examples.md for drop-in snippets.

Overriding options, keymaps, and more

NoetherVim loads user override files after each core module. Create any of these in ~/.config/nvim/lua/user/:

File	What it overrides
options.lua	vim.o / vim.g settings
keymaps.lua	Keymaps (add, change, or remove)
autocmds.lua	Autocommands
highlights.lua	Highlight groups (runs after colorscheme)
lsp/<server>.lua	Per-server LSP settings
config.lua	Bundle data table -- vault paths, feature flags (:help noethervim-user-config-data)

Template files are provided in templates/user/ in the installed distro - copy the ones you want and uncomment the relevant lines.

For the full override system reference, see :help noethervim-user-config.

---

Bundles

Bundles are optional feature groups. Enable them in init.lua (see Enabling bundles).

Bundle	Contents
Languages
rust	rustaceanvim - macro expansion, runnables, crate graph, hover actions
go	go.nvim - test generation, struct tags, interface impl, fill struct
java	nvim-jdtls - proper Java LSP support (jdtls requires special setup)
python	venv-selector.nvim - virtual environment switching
latex	VimTeX, noethervim-tex (snippets, textobjects, math spell dictionary)
latex-zotero	Zotero citation picker - needs Zotero
web-dev	Template-string auto-conversion + inline color preview
Tools
debug	nvim-dap + UI (Python, Lua, JS/TS, Go adapters)
test	neotest test runner framework
repl	iron.nvim interactive REPL
task-runner	overseer.nvim task runner + compiler.nvim
database	vim-dadbod + UI + SQL completion via blink.cmp
http	kulala.nvim HTTP/REST/gRPC/GraphQL client
git	Fugitive, Flog, Fugit2 TUI, diffview, git-conflict, gitignore
ai	CodeCompanion - Anthropic, OpenAI, Gemini, Ollama, and more
refactoring	Extract function, variable, block
Navigation & editing
harpoon	Per-project file marks (harpoon v2)
flash	Enhanced f/t and / motions with labels
projects	Project switcher
editing-extras	Argument marking (argmark) + decorative ASCII comment boxes
Writing & notes
markdown	render-markdown, preview, tables, math, image paste
obsidian	Obsidian vault integration (pair with markdown bundle)
neorg	.norg wiki and note-taking system
Terminal & environment
better-term	Named/numbered terminal windows
tmux	Automatic tmux window naming
remote-dev	Edit files on remote machines over SSH (distant.nvim)
UI & appearance
colorscheme	10 popular themes, persistence, highlight tweaks
eye-candy	Animations (drop.nvim, cellular-automaton), scrollbar, block display
minimap	Sidebar minimap with git/diagnostic markers
helpview	Rendered :help pages
tableaux	noethervim-tableaux -- animated mathematical dashboard scenes
Practice & utilities
training	Vim motion and typing practice (vim-be-good, speedtyper, typr)
dev-tools	Startup profiling (:StartupTime), Lua scratchpad (:Luapad)
presentation	Slide presentations (presenting.nvim) + keypress display (showkeys)
hardtime	Motion habit trainer

---

Keybinding Philosophy

Prefix	Purpose
<Space> (configurable)	Fuzzy navigation and search -- set vim.g.mapsearchleader to change
<Leader> (\)	Global actions (format, open tools)
<LocalLeader> (,)	Filetype-specific actions (compile LaTeX, run script)
<C-w>	All window navigation and manipulation
[ / ]	Previous / next (diagnostics, hunks, buffers, …)
[o / ]o	Toggle options on / off (wrap, spell, …)

q closes non-editing windows (help, quickfix, Oil, notify, man, …)

Discovering distro keymaps: press any prefix key and wait for which-key to show available actions. Use SearchLeader+fk (default: <Space>ck) to search all keymaps by description, or run :NoetherVim diff keymaps to see what you've changed.

---

Structure

Distro config (installed by lazy.nvim to ~/.local/share/nvim/lazy/NoetherVim/):

init.lua.example            ← starter template (copy to ~/.config/nvim/init.lua)
lua/
├── noethervim/
│   ├── init.lua            ← noethervim.setup() - runs after all plugins load
│   ├── plugins/            ← core plugin specs (always loaded)
│   ├── bundles/            ← optional feature bundles, grouped by category
│   │   ├── languages/      ← rust, go, java, python, latex, …
│   │   ├── tools/          ← debug, test, git, ai, database, …
│   │   ├── navigation/     ← harpoon, flash, projects, …
│   │   ├── writing/        ← markdown, obsidian, neorg
│   │   ├── terminal/       ← better-term, tmux, remote-dev
│   │   ├── ui/             ← colorscheme, eye-candy, minimap, tableaux, …
│   │   └── practice/       ← training, dev-tools, presentation, hardtime
│   ├── lsp/                ← per-server LSP configurations
│   ├── util/               ← shared utilities and icons
│   └── …                   ← options, keymaps, autocmds, …
│   └── sources/            ← custom blink.cmp completion sources

Your config (~/.config/nvim/):

init.lua                    ← lazy.setup() entry - enable bundles here
lua/
└── user/
    ├── plugins/            ← your personal plugins and opts overrides
    ├── options.lua         ← vim.o overrides
    ├── keymaps.lua         ← keymap overrides and additions
    ├── autocmds.lua        ← autocommand additions
    ├── highlights.lua      ← highlight overrides (after colorscheme)
    ├── lsp/                ← per-server LSP overrides
    └── config.lua          ← data table for bundles

---

Health Check

:checkhealth noethervim

Reports on required and optional dependencies.

---

Documentation

For the full reference - configuration system, keymap namespaces, commands, bundle details, and FAQ - run inside Neovim:

:help noethervim

Browse NoetherVim source with :NoetherVim files, bundles with :NoetherVim bundles, and installed plugins with :NoetherVim plugins. When viewing a source file, run :NoetherVim override (or SearchLeader+ce) to open the corresponding user override file in a split - the file is created if it doesn't exist.

Note

If muscle memory makes you type :NeotherVim, that works too.