A Better Man Page Viewer

We open up man pages for all kinds of CLI commands everyday. We should have a frictionless man page viewer that stands up to the task.

After recently reading Man pages are great, man readers are the problem ↗, I was curious what a better viewer would be and why we put up with the one that is built-in. Chief among the issues with the default viewer, as the article points out, is that there is no way to follow the links between man pages. Instead, you have to close the one you're viewing and issue another man command for another page.

That's when I remembered. I already have a better man page viewer. One that is right at my fingertips, in the right context. That context being while I already have a Vim/Neovim session open.

Usually when I'm writing a bash script or shelling-out a one-off command, I'll try to remember "that one flag". Is it -a or -s? I want to be sure, so right from my (Neo)vim session I use the man page plugin to check (:Man pg_dump).

Can I have it all the time?

We're not limited to only using this when we have a (Neo)vim session already running. We can override what man uses by exporting a different MANPAGER command.

Right from the Neovim Man plugin help page:

export MANPAGER='nvim +Man!'

This tells our system to use nvim whenever we issue a man <cmd>. The nvim +Man! part is instructing Neovim to activate the Man page viewer at startup (+), forcing the command to execute (!).

If you're already sold, go ahead and add this export to your shell profile (e.g. .zshrc) and enjoy. But if you want to stick around for a moment longer, let me explain why using nvim instead of the default pager is much better.

Why this is better

This means that every time I open a man page (e.g. man git-rebase), it opens in a Neovim session using the man plugin. I get the benefits of muscle memory, motions, search, and overall navigation that I'm used to working in (Neo)vim session.

I also get a few nice Man page-specific adjustments to the config.

• Quick Quit — Hitting q will quit out of man page, just like we're used to with the built-in man page viewer.
• Following Links — K or Ctrl-] will follow any man page link that you put your cursor on. This is the biggest selling point because now I can frictionlessly navigate back and forth between different man pages.
• Contextual "What is a word" Default — The iskeyword option has been tailored to what is usefully considered a keyword in the context of CLI tool documentation. In a standard Neovim session, I could yiw (yank inner word) or * (search) the word under cursor with, say, pg_restore, but it wouldn't work with, say, --data-only. The adjustments to the iskeyword for a man page (iskeyword=@-@,:,a-z,A-Z,48-57,_,.,-,(,)) mean that words containing dashes, such as a CLI flag, will be treated as a whole word.

Conclusion

This is one of the best changes I've made to my local setup in a while. I hope you enjoy it too.

If you just want to give it a try, export the MANPAGER like described above in your current shell. And try it with a couple man commands.

Are you using something else to view man pages? I'd be curious to hear what it is. Drop me a note on Bluesky ↗ or LinkedIn ↗.