Description | Installation | Usage | Mapping | Commands | Customization | Notes

⚠️ STARTING FROM VERSION 2.2.0 ALL THE KEYS OF g:zv_file_types ARE CONSIDERED AS REGEX AND VIM MAGIC IS NOT APPLIED BY DEFAULT, SO PLEASE UPDATE YOUR CONFIGURATION:

e.g

" CHANGE THIS
let g:zv_file_types = {
    \	'(ft1|ft2)' : 'foobar',
    \ }

" TO THIS
let g:zv_file_types = {
    \	'\v(ft1|ft2)' : 'foobar',
    \ }
" OR THIS
let g:zv_file_types = {
    \	'\(ft1\|ft2\)' : 'foobar',
    \ }

Zeavim allows to use the offline documentation browser Zeal from Vim.

• Search for word under cursor, a text motion or a visual selection.
• Search without losing focus from Vim if Zeal is already opened (Need wmctrl on UNIX).
• Narrow search with a docset or a query.
• Allows using multiple docsets.
• Docset name completion.
• Define you own docsets using patterns.
• Works on GNU/Linux and Windows.

To use zeavim, you need of course to have Zeal installed. Grab it from here and install it .

Install the distributed files into Vim runtime directory which is usually ~/.vim/, or $HOME/vimfiles on Windows.

And this is the best way, use a vim plugin manager.
Here an example with Vim-plug and its lazy loading functionnality:

Plug 'KabbAmine/zeavim.vim', {'on': [
			\	'Zeavim', 'Docset',
			\	'<Plug>Zeavim',
			\	'<Plug>ZVVisSelection',
			\	'<Plug>ZVKeyDocset',
			\	'<Plug>ZVMotion'
			\ ]}

There are 3 ways of using zeavim:

1. <leader>z or :Zeavim

   Search for word under cursor (Or visual selection) with the docset defined automatically⁺.

2. gz{motion}

   Search for a motion with the docset defined automatically⁺.

3. <leader><leader>z or :Zeavim!

   Narrow search with a docset⁺ and a query (A default docset is provided).

   

   • Multiple docsets can be defined, just separate them by a comma.
   • The docset name can be completed using tab, see completion for that.

You can easily change the mapping keys of zeavim:

nmap gzz <Plug>Zeavim           " <leader>z (NORMAL mode)
vmap gzz <Plug>ZVVisSelection   " <leader>z (VISUAL mode)
nmap gz <Plug>ZVMotion          " gz{motion} (NORMAL mode)
nmap gZ <Plug>ZVKeyDocset       " <leader><leader>z

You can disable the default mappings, but this is useful only if you're not going to use all the <Plug>'s above.

A unique command Zeavim is provided.

:Zeavim     " NORMAL & VISUAL modes
:Zeavim!    " Ask for docset & query

N.B: The commands ZvV and ZVKeyDocset are still available to maintain compatibility with old versions.

If you need a lazy way to specify a docset, you can use:

Docset DOCSET_NAME

As an example, I'm working on a scss file but I want to get compass documentation when using Zeavim, so I just need to specify manually this docset:

Docset compass

Then Zeavim only for the current buffer will use compass as a docset. Note that you can define multiple docsets here.

The docset name can be completed, for that see completion.

To set back the initial docset, a simple Docset without argument is enough.

By default zeavim looks for an executable named zeal on your PATH for UNIX and in %ProgramFiles%/Zeal/zeal.exe for Windows. You can specify Zeal's location manually by adding in your vimrc:

let g:zv_zeal_executable = 'path/to/zeal'

Or if you're using both OS:

let g:zv_zeal_executable = has('win32') ?
			\ 'path/to/zeal.exe' :
			\ 'path/to/zeal'

You can add arguments/flags to zeal command using g:zv_zeal_args.

By default, the plugin defines a few docsets:

'cpp' : 'c++'
'scss': 'sass'
'sh'  : 'bash'
'tex' : 'latex'

Its up to you to add patterns (Or overwrite the default ones).
For that you can use g:zv_file_types variable.
It's a dictionary where:

• The keys are pattern(s) that can match file names, file types or file extensions.
• The values are the docset names.

" For the docset, not mandatory but you can use underscores instead of spaces
let g:zv_file_types = {
    \	'FILE_NAME' : 'DOCSET_NAME',
    \	'EXTENSION' : 'DOCSET NAME',
    \	'FILE_TYPE' : 'DOCSET_NAME',
    \ }

Here again you can define multiple docsets for a type, just separate them by a comma.

'TYPE': 'DOCSET1,DOCSET2'

Note that you are using regex, so it can be a more accurate pattern:

e.g

let g:zv_file_types = {
			\	'css'                      : 'css,foundation,bootstrap_4',
			\	'.htaccess'                : 'apache_http_server',
			\	'\v^(G|g)runt\.'           : 'gulp,javascript,nodejs',
			\	'\v^(G|g)ulpfile\.'        : 'grunt',
			\	'\v^(md|mdown|mkd|mkdn)$'  : 'markdown',
			\ }

You can disable the default mappings:

let g:zv_disable_mapping = 1

If you're using all the functionalities of the plugin (NORMAL, VISUAL, docset and query manual input), no need of setting this variable, just map the <Plug>'s normally.

To define the docset, the plugin uses by order:

• The value defined by :Docset command.
• The values defined in g:zv_get_docset_by.
• The current file type.

The default value of g:zv_get_docset_by is ['file', 'ext', 'ft'].
That means that the plugin will try to find a pattern matching:

1. The current file name
2. The current file extension
3. The current file type

You can set a specific order or remove a criteria:

" Find matching pattern to the file type only:
let g:zv_get_docset_by = ['ft']

" Find matching pattern to the extension first, then to the file name 
" and finally to the type.
let g:zv_get_docset_by = ['ext', 'file', 'ft']

When using <leader><leader>z or the command Docset, you can get a docset name completion with Tab. The docset names are taken from your zeal's docset directory (The one specified in Zeal's options).

By default zeavim assumes that Zeal docsets are located in %LOCALAPPDATA%\Local\Zeal\Zeal\docsets, which expands into something like C:\Users\you\AppData\Local\Zeal\Zeal\docsets for Windows and ~/.local/share/Zeal/Zeal/docsets for UNIX systems.

If you have them in a different folder, just set the correct path in g:zv_docsets_dir variable.

e.g

let g:zv_docsets_dir = has('win32') ?
			\ 'path/to/docsets/in/win' :
			\ 'path/to/docsets/in/unix'

nmap gzz <Plug>Zeavim
vmap gzz <Plug>ZVVisSelection
nmap gZ <Plug>ZVKeyDocset<CR>
nmap gz <Plug>ZVMotion
nmap <leader>z <Plug>ZVKeyDocset
let g:zv_file_types = {
			\	'help'               : 'vim',
			\	'.htaccess'          : 'apache http server',
			\	'javascript'         : 'javascript,nodejs',
			\	'python'             : 'python 3',
			\	'\v^(G|g)ulpfile\.'  : 'gulp,javascript,nodejs',
			\ }
let g:zv_zeal_args = g:hasUnix ? '--style=gtk+' : ''
let g:zv_docsets_dir = g:hasUnix ?
			\ '~/Important!/docsets_Zeal/' :
			\ 'Z:/username/Important!/docsets_Zeal/'

Zeavim was my first vim plugin and it was created in the beginning for a personal use, so please feel free to report issues and submit PR. I usually answer in 1-2 days.

Thanks to Jerzy Kozera for creating such wonderful open-source application.

Thanks to Bram Moolenaar for creating the best piece of software in the world ❤️

Thanks to you if you're using zeavim.