Use Neovim as your man pager

This post originally appeared on Chris DeLuca's blog

You may know that you can open man pages in a Neovim buffer with :Man. However, you can also configure your shell to open manual pages in a Neovim buffer when called from the command line.

First, if you’re unfamiliar, Neovim ships with the great :Mancommand, which opens man pages in a nicely formatted buffer. These buffers are normal Vim buffers, so come equipped with syntax highlighting, can be easily searched, and links to other manual pages can be followed with C-].

" Open the git manual page.
:Man git

You can also open man pages invoked inside Neovim’s terminal emulator using this same man buffer with a little configuration.

# This opens a man buffer?
man git

The man command can be configured to render pages with any program, controlled by the $MANPAGER environment variable.

We could set $MANPAGER to nvim, but that would cause nesting Neovim instances if called from inside a Neovim :terminal.

To work around this, we’ll need help from the neovim-remoteproject (at least until Neovim core adds --remoteback). With that installed, we can call nvr inside a Neovim terminal buffer to open the given file in the same Neovim instance.

I personally would rather not launch a whole Neovim instance just to render a man page if I’m not already inside Neovim, so for this tip we’ll add some detection code to only set the $MANPAGERvalue inside Neovim. We can do this by checking the value of the$NVIM_LISTEN_ADDRESS environment variable, which will only be set inside an instance of Neovim.

We’ll use the -o flag to open the man page in a new split, to help retain the context of what you’re working on.

In your bash/zsh config file:

if [-n "${NVIM_LISTEN_ADDRESS+x}"]; then
 export MANPAGER="/usr/local/bin/nvr -c 'Man!' -o -"
fi

Or for the fish shell:

if test -n "$NVIM_LISTEN_ADDRESS"
 set -x MANPAGER "/usr/local/bin/nvr -c 'Man!' -o -"
end

And that’s it. Happy RTFM!