This plugin allows to easily preview tags in a floating window close to the
cursor. It aims to work as a mostly invisible extension to the native preview
functionality. In fact it tries to fill the gap of a still missing
previewwindowfunc option. At
its core, it just opens a floating window before the native tag command gets
executed. Because the native commands search first for an already existing
preview window, they just pick up this window.
Additionally it provides some minor additions to improve the preview functionality. Such include to automatically close the window on cursor movement, open folds in the preview and apply highlight to the tag word. All features are quite generic, so they can be disabled individually but also can be also completely customized.
Use your favorite plugin manager to install the plugin or use it as plain package. The following example uses packer.nvim with some lazy loading:
lua require('packer').use({
\ 'weilbith/nvim-floating-tag-preview',
\ cmd = {'Ptag', 'Ptselect', 'Ptjump', 'Psearch', 'Pedit' },
\ })Unfortunately is is not possible to overwrite native commands. As a
compromise, this plugin clones all tag preview related commands with an upper
case P version (e.g. Ptag, Ptnext, Psearch, ...). Native mappings
(e.g. <C-W>}) get automatically overwritten to use the floating versions
(can be disabled). Commands or mappings to focus (<C-W>P) or close
(<C-W>z) the preview window manually just work as always. When the cursor
moves, the window closes automatically again. While continue to preview
different tags (or just see the different locations), the same window gets
re-used and remains the same.
To preview a simple tag just execute :Ptag <tag-name> or type <C-W>} to
preview the word under the cursor. To cycle through the different definitions,
use :Ptnext, Ptprevious and friends. But also :Psearch might be an
interesting entrypoint.
You can run the plugin's health check to verify that NeoVim version supports
all necessary features (:checkhealth floating_tag_preview). Mind that this
does not work if you load the plugin in a lazy manner.
Checkout the
docs
(:help floating_tag_preview.txt) to get further details on how to customize
each single part of the plugin.
Tags might be an ancient or event obsolete feature of Vim/NeoVim. If you prefer to use the data of a language server instead, consider to use nvim-lsp-smag. It makes LSP locations like definitions, declaration, implementation etc. just work as tags. Using both plugins in combination you can easily preview the definition of a code object (e.g. a function or class) under the cursor. Cycling through the previews will show you the definition, implementation etc. (depending on the configuration). In fact, the demo GIF at the top is using this plugin in background.
Thereby this is a minimal plugin which follows a traditional Vim/NeoVim approach, but combine it with the most recent advanced features.