Neovim config for a GUI text editor user. Welcome Geany Fans!!
  • Lua 95%
  • CSS 5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-06 12:57:58 -05:00
assets gem: a small config that works with no plugins 2026-10-03 20:47:48 -04:00
colors colours follow the terminal when there is no wallpaper palette 2026-10-04 15:16:22 -04:00
lua/butter fixed new session screen 2026-10-04 17:29:26 -04:00
.gitignore butter-nvim: editor keys on by default, sessions restore on a bare start 2026-10-04 14:30:06 -04:00
init.lua butter-nvim: editor keys on by default, sessions restore on a bare start 2026-10-04 14:30:06 -04:00
LICENSE Add GPL-2.0 license 2026-02-01 17:59:56 -05:00
nvim-pack-lock.json files: oil instead of nvim-tree. esc closes it, backspace goes up, names sort ignoring case 2026-10-04 12:55:47 -04:00
README.md consistent readme footer 2026-11-06 12:57:58 -05:00

🍿 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 = false here. The config this repo held before is tagged v1.

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

  • Esc gets you out of whatever you are in.
  • Ctrl+S saves. Space Q quits 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 i to type. Or set vim.g.butter_start_insert = true and 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: press s there to bring them back, or r for recent files. Close every file before you quit and the folder starts fresh next time.
  • F5 runs the file in a terminal split, F8 checks it into a clickable list: shellcheck for shell scripts, make for C beside a Makefile, and so on. One table in lua/butter/run.lua.
  • Snippets: bash, fn, if, for, case, die, here, then Tab.
  • Colour codes painted in their own colour: #rrggbb and 0xrrggbb.
  • Language servers through Neovim's own client, started only if the server is installed. Ten defined, including qmlls for QML. Completion as you type.
  • Treesitter highlighting for Markdown, Lua, C and Vim, built into Neovim; Vim's own syntax for everything else. .h files are treated as C.
  • Small things: trailing whitespace trimmed on save, cursor position remembered, missing folders created on save, rounded floats.

Markdown

  • Enter continues a list: bullets, numbers, checkboxes. Enter on an empty item ends it.
  • Space x ticks a checkbox.
  • Space t or F8 lists Takes: words and speaking time under each numbered heading, then the total. Built for video shooting orders.
  • Space p or F5 opens a browser preview that follows as you type (needs pandoc or cmark-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

Buy me a coffee

Connect

License

MIT. Drew Griffin, justaguylinux.


Made with 🧈 by JustAGuyLinux