- Lua 95%
- CSS 5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| assets | ||
| colors | ||
| lua/butter | ||
| .gitignore | ||
| init.lua | ||
| LICENSE | ||
| nvim-pack-lock.json | ||
| README.md | ||
🍿 butter-nvim
Neovim for people arriving from a GUI editor.
The keys you already know work from the first minute: Ctrl+S saves,
Ctrl+Z undoes, Ctrl+C and Ctrl+V copy and paste, Shift+arrows select.
Vim is all still there underneath, for the day you want it.
It is small, about 860 lines of Lua, and it runs with no plugins at all. Five optional ones add polish.
| Startup | 13 ms bare, 21 ms on a script, 33 ms on markdown |
| Plugins | 0 required, 5 optional, each loaded on first use |
| Needs | Neovim 0.12 (ButterRepo keeps Debian current) |
If you already think in Vim and want its keys untouched, use nvim instead, or set
vim.g.butter_gui = falsehere. The config this repo held before is taggedv1.
Install
git clone https://justaguy.dev/drew/butter-nvim ~/.config/nvim
nvim
That is the whole install. For the optional plugins run :ButterInstall once
and restart; :ButterUpdate updates them. Neovim's built-in vim.pack does
the work, so there is no plugin manager to bootstrap.
To try it beside an existing config:
git clone https://justaguy.dev/drew/butter-nvim ~/.config/butter-nvim
NVIM_APPNAME=butter-nvim nvim
If you panic
Escgets you out of whatever you are in.Ctrl+Ssaves.Space Qquits and asks about unsaved files.Space ?lists every key.- You are in normal mode when the bottom-left says NORMAL: keys are
commands, not text. Press
ito type. Or setvim.g.butter_start_insert = trueand files open ready to type.
The keys you already know
| Key | Does |
|---|---|
Ctrl+S |
save |
Ctrl+Z / Ctrl+Y |
undo / redo, in every mode; while typing, a sentence or a line at a time |
Ctrl+C / Ctrl+X / Ctrl+V |
copy, cut, paste, on any selection including one made with the mouse |
Shift+arrows |
select by character and line |
Ctrl+Shift+Left/Right |
select by word |
Ctrl+Shift+Up/Down |
select whole lines |
Backspace / Delete |
remove the selection; typing replaces it |
Each of these replaces something Vim does with the same key. Block visual
mode moves to Ctrl+Q; suspending Neovim is :suspend.
kitty takes Ctrl+Shift+arrows for its own tabs and scrolling. To let them
reach the editor, add to kitty.conf:
map ctrl+shift+left no_op
map ctrl+shift+right no_op
map ctrl+shift+up no_op
map ctrl+shift+down no_op
The rest of the keys
Leader is Space. Space ? shows this list in the editor.
| Key | Does |
|---|---|
Space ff fw fr fb fh |
find file, word, recent, buffer, help |
Space e |
browse files (Enter opens, Backspace up, Esc closes) |
Space q / Space Q |
close file / quit |
]b / [b |
next / previous file |
Space v / Space s |
split right / below |
Ctrl+H/J/K/L |
move between windows |
Alt+j / Alt+k |
move the line or selection down / up |
Space r |
replace the word under the cursor |
Space z |
toggle spell check |
F5 / F8 |
run / check this file |
]h [h Space gp gr gb |
next / previous change, preview, undo, blame |
gd K grn gra grr ]d [d |
definition, docs, rename, fix, references, diagnostics |
What you get
With no plugins
- A statusline with a mode pill, git branch, diagnostics, a macro-recording marker, and word count in prose. A tab row that appears with the second file: click a tab to switch, click its × to close it. Both take their colours from the active colourscheme.
- A start screen on a bare
nvim: a short list of keys and nothing else. Each folder remembers the files you had open in it: presssthere to bring them back, orrfor recent files. Close every file before you quit and the folder starts fresh next time. F5runs the file in a terminal split,F8checks it into a clickable list: shellcheck for shell scripts,makefor C beside a Makefile, and so on. One table inlua/butter/run.lua.- Snippets:
bash,fn,if,for,case,die,here, thenTab. - Colour codes painted in their own colour:
#rrggbband0xrrggbb. - Language servers through Neovim's own client, started only if the server
is installed. Ten defined, including
qmllsfor QML. Completion as you type. - Treesitter highlighting for Markdown, Lua, C and Vim, built into Neovim;
Vim's own syntax for everything else.
.hfiles are treated as C. - Small things: trailing whitespace trimmed on save, cursor position remembered, missing folders created on save, rounded floats.
Markdown
Entercontinues a list: bullets, numbers, checkboxes.Enteron an empty item ends it.Space xticks a checkbox.Space torF8lists Takes: words and speaking time under each numbered heading, then the total. Built for video shooting orders.Space porF5opens a browser preview that follows as you type (needspandocorcmark-gfm).- Word count and speaking time in the statusline. Spell check on.
With the optional plugins
| Plugin | Adds | Without it |
|---|---|---|
| fzf-lua | fuzzy find files, words, recent, buffers, help | :find, :grep, :browse oldfiles |
| gitsigns | changes in the margin, branch in the statusline | nothing shown |
| render-markdown | headings, lists, checkboxes and tables drawn in the buffer | plain markdown |
| oil + devicons | a folder as editable text on Space e: rename by editing |
netrw on Space e |
Switches
lua/butter/local.lua is yours and is not tracked. It runs first, so it can
set these; define Butter.after() in it for anything that must run last.
| Switch | Does |
|---|---|
vim.g.butter_gui = false |
Vim's own keys instead of the editor-style ones |
vim.g.butter_start_insert = true |
open files ready to type |
vim.g.butter_session_auto = true |
reopen the folder's files on a bare nvim instead of showing the start screen |
vim.g.butter_colorscheme = "habamax" |
a fixed colourscheme instead of following the wallpaper or terminal |
vim.g.butter_wpm = 160 |
words per minute for Takes and the word count |
vim.g.butter_hex = false |
do not paint colour codes |
vim.g.butter_preview_cmd = "firefox --new-window" |
the command that shows the markdown preview |
vim.g.butter_ascii = true |
no Nerd Font glyphs in the statusline and signs |
vim.g.butter_extra_plugins = { "https://…" } |
more plugins through vim.pack |
Colours
The editor takes its colours from its surroundings, two ways:
- On a Butter desktop the wallpaper picker writes a palette to
~/.cache/wallpaper-theme/nvim-palette.lua, and the editor follows the wallpaper along with the bar and the terminal (colors/wallpaper.lua). - Everywhere else it asks the terminal for its foreground, background and
sixteen colours and builds the scheme from the answers
(
colors/terminal.lua). Change the terminal's theme and the editor follows when its window next gets focus. A terminal that will not answer, tmux for one, gets its sixteen colours used by number instead.
Checked in kitty, foot, alacritty, st, xterm, wezterm, ghostty and tmux.
vim.g.butter_colorscheme picks a fixed scheme instead.
Layout
init.lua loads local.lua, then the modules below, in order
lua/butter/
options.lua options and a few open/save conveniences
plugins.lua the five optional plugins, via vim.pack
ui.lua colours, statusline, tab row, quickfix look
termcolors.lua asks the terminal for its colours
hex.lua colour codes shown in their colour
keys.lua the Space keys, the close-file helper, the Space ? list
gui.lua the editor-style keys
lsp.lua ten server definitions, enabled if installed
run.lua F5 run, F8 check
markdown.lua Takes, preview, lists, checkboxes, prose settings
snippets.lua the snippets
session.lua per-folder sessions and the start screen
health.lua :checkhealth butter
colors/wallpaper.lua the wallpaper palette colourscheme
colors/terminal.lua the colourscheme built from the terminal's own colours
assets/preview.css stylesheet for the markdown preview
Support
Connect
- YouTube — tutorials and guides
- Butterforge — source code and projects
- Butter desktops — ready-to-use window manager desktops for Debian
- The Butter Lab — Discourse forum
- The Churn — community chat (Fluxer)
- Wiki — documentation and guides
- Mastodon — @justaguylinux@fosstodon.org
- Butterbian — a maintained Debian derivative built on Debian stable
License
MIT. Drew Griffin, justaguylinux.
Made with 🧈 by JustAGuyLinux
