FreeBSD Manual Pages
nvimpager(1) General Commands Manual nvimpager(1) NAME nvimpager - using neovim as a pager SYNOPSIS nvimpager [-acp] [--] [nvim options and files] nvimpager -h nvimpager -v DESCRIPTION Nvimpager is a small program that can be used like most other pagers. In- ternally it uses neovim with the default TUI to display the text. This means it has all the fancy syntax highlighting, mouse support and other features of neovim available in the pager, possibly including plugins! COMMAND LINE OPTIONS Nvimpager itself interprets only very few options but all neovim options can also be specified. If options to neovim are specified before the first file name they must be preceded by "--" to prevent nvimpager from trying to interpret them. The following options are interpreted by nvimpager itself: -a Run in "auto mode" (default). Auto mode will detect the terminal size and switch to pager mode if the content to display would not fit on one screen. If the content will fit on one screen it will switch to cat mode. This overrides any previous -c and -p options. -c Run in "cat mode". Do not start the neovim TUI, only use neovim for syntax highlighting and print the result to stdout. This overrides any previous -a and -p options. -h Show the help screen and exit -p Run in "pager mode". Start the neovim TUI to display the given content. This overrides any previous -a and -c options. -v Show version information and exit CONFIGURATION Like neovim itself nvimpager will honour $XDG_CONFIG_HOME and $XDG_DATA_HOME, which default to ~/.config and ~/.local respectively. The main config directory is $XDG_CONFIG_HOME/nvimpager and the main user con- fig file is $XDG_CONFIG_HOME/nvimpager/init.lua or $XDG_CONFIG_HOME/nvim- pager/init.vim. It is an error if both files are present. The site direc- tory is $XDG_DATA_HOME/.local/share/nvimpager/site. The manifest for remote plugins is read from (and written to) $XDG_DATA_HOME/nvimpager/rplugin.vim. The rest of the &runtimepath is configured like for neovim. The -u option of nvim(1) itself can be used to change the main config file from the com- mand line. The default config files for neovim are not used by design as these poten- tially load many plugins and do a lot of configuration that is only rele- vant for editing. If one really wants to use the same config files for both nvimpager and nvim it is possible to do so by symlinking the config and site directories and the rplugin file. Environment variables The environment variable $NVIMPAGER_NVIM can be used to specify an nvim ex- ecutable to use. If unset it defaults to nvim. Configuration variables The script exposes a lua table called nvimpager to --cmd/-c options and the init file. It can be modified to change some options that are specific to nvimpager. The following fields (options) exist: +-----------------+--------+---------+------------------------------------+ | option | type | default | explanation | +-----------------+--------+---------+------------------------------------+ | follow | bool | false | start in follow mode, i.e. contin- | | | | | uously load changes to the opened | | | | | file and scroll to the bottom | | | | | (like less +F or tail -f) | +-----------------+--------+---------+------------------------------------+ | follow_interval | number | 500 | how often in ms the underlying | | | | | file should be checked in follow | | | | | mode | +-----------------+--------+---------+------------------------------------+ | git_colors | bool | false | use git command highlighting in- | | | | | stead of nvim syntax highlighting, | | | | | set this to true if you use an ex- | | | | | ternal diff | +-----------------+--------+---------+------------------------------------+ | maps | bool | true | if some default less like maps | | | | | should be defined inside pager | | | | | mode | +-----------------+--------+---------+------------------------------------+ So to start nvimpager and follow changes to the opened file the user can put lua nvimpager.follow = true in the init file (or on the command line). Default key mappings Nvimpager defines some mappings to make it feel more like a pager than an editor. These mappings are inspired by less(1) which are very close to the defaults in neovim. These mappings can be deactivated altogether by putting lua nvimpager.maps = false in the init file (or on the command line). The following mappings are defined by default: * q is mapped to quit nvimpager in normal and visual mode * <Space> and <S-Space> move down or up a page respectively * g goes to the top of the file * <Down> and j scroll the window down one line * <Up> and k scroll the window up one line * F toggles "follow mode" where nvimpager continuously loads changes to the underlying file and scrolls to the bottom. This is useful for watching log files. It is modeled after the F command in less(1) or the -f option of tail(1) You can remap the lua function `nvimpager.toggle_follow` if you disabled the default key mappings. EXAMPLES To use nvimpager to view a file (with neovim's syntax highlighting if the filetype is detected): nvimpager file Pipe text into nvimpager to view it: echo text | nvimpager Use nvimpager as your default $PAGER to view man pages or git diffs: export PAGER=nvimpager man nvimpager git diff Options for nvim(1) can be specified if they are separated from the options for nvimpager itself. Either by separating them with -- or by putting the nvim options after at least one non option argument: nvimpager -p -- -c 'echo "option for nvim"' file nvimpager -p file -u custom_init.vim Start nvimpager in "follow mode" to watch a growing log file: nvimpager log_file -c 'lua nvimpager.follow = true' LIMITATIONS If reading from stdin, nvimpager (like nvim(1)) waits for EOF until it starts up. This means that it can not be used to continuously watch output from a long running command even in follow mode. SEE ALSO nvim(1) https://github.com/neovim/neovim vimpager(1) https://github.com/rkitover/vimpager AUTHORS Lucas Hoffmann nvimpager 0.14.0 2026-07-30 nvimpager(1)
NAME | SYNOPSIS | DESCRIPTION | COMMAND LINE OPTIONS | CONFIGURATION | EXAMPLES | LIMITATIONS | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nvimpager&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>