Vim Keybindings for Markdown Readers: A Keyboard Shortcuts Guide

You already use j and k. In your terminal. In less. In man pages. In every tool that respects the way your fingers have worked for years.

So when you open a markdown file in a viewer and have to reach for the mouse to scroll, something feels off. It’s not just preference — it’s a break in flow. You were reading, and now you’re pointing and clicking. The right vim keybindings turn any markdown viewer into a keyboard-driven markdown reader.

MDHero supports Vim keybindings natively — no config files, no plugins, no flags. It’s effectively a markdown viewer Vim users can pick up in seconds: open a markdown file and start navigating the way you already know how. The full set of markdown reader keyboard shortcuts is a small, deliberate subset focused on reading — j/k, gg/G, n/N — and it works the same on Mac and Windows. For a broader comparison of markdown viewers and which ones support keyboard-first workflows, see our 2026 roundup.

Vim keybindings: navigation keys

These are the markdown viewer keyboard shortcuts you’ll use 90% of the time. They work exactly as you’d expect from Vim or less:

The d/u shortcuts are a convenience — they do the same thing as Ctrl+d/Ctrl+u but without the modifier key. Since MDHero is a viewer (not an editor), there’s no conflict. The d key doesn’t need to mean “delete” when there’s nothing to delete.

gg requires two keypresses in quick succession, just like Vim. Tap g once and nothing happens until the second keypress arrives or a short timeout passes.

Tab management

If you work with multiple markdown files at once — a README, an API spec, a changelog — tabs keep them a keypress apart. These shortcuts aren’t Vim, but they complement the keyboard-driven workflow:

On Windows substitute Ctrl for Cmd. On Mac, Cmd is the standard modifier.

Search

Finding a specific section in a long document is where keyboard navigation really pays off. MDHero’s search works in two steps:

Once the search bar is open, type your query and press Enter. The first match highlights and the document scrolls to it. From there, n and N cycle through matches — the same keys Vim uses for / search navigation.

When you close the search bar with Escape, focus returns to the document and your j/k keys work again immediately. No clicking required to “re-focus” the content area.

View modes and file operations

A handful of other shortcuts round out the keyboard-driven experience:

Cmd+U is worth highlighting. It toggles between the rendered view and the raw markdown source. Useful when you want to see the actual syntax — what heading level something is, whether a link is inline or reference-style, or how a table is structured. Press it again to go back to the rendered view.

Why only navigation keys

A reasonable question: why not support the full Vim keybinding set? Where’s visual mode? Where are marks? Where’s :wq?

The answer is that MDHero is a viewer. It renders markdown files. You can’t edit text, so insert mode doesn’t exist. You can’t select and yank, so visual mode doesn’t exist. You can’t run Ex commands, so command mode doesn’t exist.

What remains is the part of Vim that matters for reading: moving through a document quickly and precisely. j/k for line-by-line. d/u for page-by-page. gg/G for endpoints. n/N for search results.

This isn’t a limitation — it’s a deliberate choice. Full Vim emulation in a read-only context would mean supporting dozens of keybindings that do nothing, and creating confusion about why dd doesn’t delete a line. By implementing only the navigation subset, every supported key actually does something useful, and there’s nothing to accidentally trigger.

If you’ve ever used less with its Vim-like defaults, you already know the mental model. MDHero works the same way: a focused set of keyboard shortcuts for moving through content, with nothing else in the way.

Quick reference: markdown viewer keyboard shortcuts

Here’s the full list of keyboard shortcuts in one place for bookmarking. The same keys are also documented on our shortcuts grid on the homepage:

Your fingers already know these keys. MDHero just makes sure they work — the markdown viewer with Vim keybindings that don’t fight you.