Making a Vim or Neovim tutorial where viewers see each keystroke

27 October 2026 · 6 min read

In a Vim or Neovim tutorial, show every key you press, not only shortcuts: in Normal mode, a command like ciw or dd is plain letters that change the text without ever appearing on screen. Turn on Vim’s own showmode and showcmd, add an on-screen key display set to show all keys, including Escape and Control combinations, and slow your pacing so each command has a moment on screen before the next one.

Why Vim is hard to follow on video

Vim is modal. The same letters type text in Insert mode and edit it in Normal mode, so viewers cannot tell from the screen alone which one just happened. In Insert mode, dd types two letters. In Normal mode, it deletes a line, and all the viewer sees is a line disappearing.

That is the whole problem with Vim videos: viewers see effects without causes. Some common ones:

Keys	What viewers see without a key display
dd	A line disappears
ciw	A word disappears and the cursor waits
.	The last change happens again somewhere else
u, then ⌃R	Text jumps back, then forward again
qa … q, then @a	“recording @a” at the bottom, then a burst of edits
gg, G	The view jumps to the top or the bottom
%	The cursor jumps to a matching bracket

An experienced Vim user does all of this fast, often with counts in front (3j, 2dd), and that speed is the thing beginners came to learn. If they cannot see the keys, they have to stop the video and guess.

Turn on what Vim already offers

Vim has two options that help, and both are worth setting before you record:

showmode puts the mode, such as – INSERT – or – VISUAL –, in the last line of the screen. It is on by default in Vim and Neovim, but some configurations turn it off, often because a status line plugin shows the mode instead. Make sure one or the other is visible.
showcmd shows a command you are partway through typing, toward the right of the last line. Neovim turns it on by default. The Vim that comes with macOS does not: its system vimrc skips Vim’s defaults.vim, so showcmd stays off until you add set showcmd to your own vimrc.

showcmd helps, but it does not do the job alone. It shows a command only while it is unfinished, so dd shows as d for an instant and then nothing. It is also small and tucked into a corner.

While you are in your config, make the text bigger for the recording. If Vim runs in Terminal, View > Bigger (Command-Plus) enlarges the font, and View > Default Font Size (Command-0) puts it back. A color scheme with strong contrast survives video compression better than a soft one.

Set up a key display for modal editing

A key display set to show only shortcuts, meaning keys pressed with Command, Control or Option, drops almost everything in Vim, because most commands are plain letters. Change it:

Show everything. In Typebar, set the pill to show everything, including Return and Tab. Typing gathers into one chip, and Control combinations such as ⌃R, ⌃V and ⌃O show as their keys.
Use the full keyboard for where, the pill for what. On the full keyboard, every key you press lights up, Escape included, which helps with a step beginners easily lose track of. The pill shows the sequence. Keyboard and Pill together, from the Show submenu in the menu bar menu, gives viewers both.
Put arrows on H, J, K and L for a first lesson. Typebar can put a layer of symbols on the keys from a link, for example:

open -g "typebar://layer/show?h=s:arrow.left&j=s:arrow.down&k=s:arrow.up&l=s:arrow.right&fill=blank"

Showing arrows or symbols on the keys covers layers like this in more detail.

Be clear about what the overlay does not do here. Typebar’s cheatsheets come from app menus, its hand-made packs and the settings files of eleven editors and terminals, and Vim is not one of them. For a Vim lesson, the key display’s job is showing what you pressed. Explaining what it means is still yours.

Say what your own setup changes

Viewers copy the keys they see, so anything personal in your setup needs saying out loud once:

Your leader key. Vim’s default leader is the backslash. Many people change it to Space or a comma, and viewers will press the wrong key if you do not tell them.
Your Escape. Control-[ does the same as Escape in Vim, so a viewer will see ⌃[ on screen. If you have mapped jk to leave Insert mode, they will see j and k typed. If you remapped Caps Lock to Escape in System Settings > Keyboard > Keyboard Shortcuts > Modifier Keys, say so too.
Plugins and mappings. If a command only works because of a plugin, say which one, or leave it out of a beginner lesson.

Pace each command for the viewer

The key display shows what you pressed, but viewers still need time to read it. A few habits make the difference:

One command, a beat, then the next. Press it, let the result land, then move on. Saying it aloud helps: “c, i, w: change inner word.”
Do not stop in the middle of a mapping to talk. If you pause partway through a mapped sequence, Vim waits for the time set by timeoutlen (1000 milliseconds by default) and then treats the keys typed so far on their own. Explain first, then type the whole thing.
Say counts as numbers. “Three j” is easier to follow than watching 3j flash by.
Slow down for macros. Record with qa, make the edits slowly, stop with q, then play it back with @a. Playing it again with @@ is a good moment to point out the repeat.

Why viewers pause tutorials goes into what makes people reach for the pause button, and most of it applies doubly to Vim.

Record it

Record with Command-Shift-5 (⇧⌘5) and Record Selected Portion, with the box around the editor and the key display, or record the whole screen. The key display appears in recordings like any other window, so a recorder set to capture only the terminal’s window will leave it out.

If your terminal has Secure Keyboard Entry turned on, no key display can see what you type there, and the keys will be missing from the take. Recording a terminal session that shows every key covers that and the other terminal-specific traps.

Questions

Is showcmd enough on its own?

Not for a video. It shows a command only while it is unfinished, in a small spot in the corner, and finished commands vanish. It is worth turning on, alongside a key display that shows every key.

Should I use a full keyboard or a pill for Vim?

For a first lesson on movement, the full keyboard, because where H, J, K and L sit is the point. For editing commands, the pill, because the order of the keys is the point. Showing both works well when the frame has room.

Does this work with Neovim in a GUI or with MacVim?

Yes. A key display shows what you press whatever app is in front, so the setup is the same; only where you change the font size differs.

Typebar is $9 once for up to 5 Macs, and free for 24 hours with everything on.