Tips and Snips

Vimwiki cannot be all things to all users so here are some tips and code snippets you may find useful for customizing Vimwiki to your liking.

There are several cheat sheets for Vimwiki:

• The Darnedest Thing - Vimwiki Cheatsheet
• Short Cheatsheet
• PDF Cheatsheet incl. Syntax

Vimwiki has simple folding folding methods built in but lets you easily customize folds with the g:vimwiki_folding option. For example, if you prefer that the last blank line before a heading not get folded, add this to your .vimrc file:

let g:vimwiki_folding = 'custom'

Then add the following to the ftplugin/vimwiki.vim plugin in your .vim configuration folder (create this file if it doesn't already exist):

let l:vimwiki_fold_blank_lines = 0  " set to 1 to fold blank lines
let l:vimwiki_header_type = '#'     " set to '=' for wiki syntax
setlocal foldlevel=1
setlocal foldenable
setlocal foldmethod=expr
setlocal foldexpr=Fold(v:lnum)

 function! Fold(lnum)
   let fold_level = strlen(matchstr(getline(a:lnum), '^' . l:vimwiki_header_type . '\+'))
   if (fold_level)
     return '>' . fold_level  " start a fold level
   endif
   if getline(a:lnum) =~? '\v^\s*$'
     if (strlen(matchstr(getline(a:lnum + 1), '^' . l:vimwiki_header_type . '\+')) > 0 && !g:vimwiki_fold_blank_lines)
       return '-1' " don't fold last blank line before header
     endif
   endif
   return '=' " return previous fold level
 endfunction

Vimwiki makes it effortless to add tasks to any wiki page. Unfortunately, this means that your tasks get dispersed rather widely, especially if you're tracking action items from meeting notes in your diary. The snippets below make it easier to manage tasks in vimwiki without adding any additional plugins or relying on external task management tools.

The following will open a QuickFix window with incomplete tasks, but only those which are in a hyphenated (-) list. This is a simple way to filter only on tasks which are ready to be performed.

function! VimwikiFindIncompleteTasks()
  lvimgrep /- \[ \]/ %:p
  lopen
endfunction

function! VimwikiFindAllIncompleteTasks()
  VimwikiSearch /- \[ \]/
  lopen
endfunction

nmap <Leader>wa :call VimwikiFindAllIncompleteTasks()<CR>
nmap <Leader>wx :call VimwikiFindIncompleteTasks()<CR>

If you want to encrypt singe pages of your wiki you can use vim gnupg in conjunction with vimwiki. Add the following to your vimrc:

let g:GPGFilePattern = '*.\(gpg\|asc\|pgp\)\(.wiki\)\='

Then you can create a link to a page in the following form: [[link.asc]], the resulting file "link.asc.wiki" will be transparently encrypted by vim-gnupg. vim-gnupg will ask you to choose a key and gpg-agent will ask you to unlock the chosen key.

Note: If you use a different file-extension for your wikipages make sure to change the code above accordingly.

Vimwiki has no support built in yet, but see this issue for workarounds.

You have to configure your wiki(s) in your vimrc, then you can configure among other the folder.

let g:vimwiki_list = [{'path': '~/mywiki/',
                      \ 'path_html': '~/mywiki_html'}]

Yes:

$ vim -c VimwikiIndex

Opening the file of a wikipage also does the trick, that way you can open it with another than your main page. Example:

$ alias importantpage='vim vimwiki/importantpage.wiki'
$ importantpage

If you init your vimwiki directory as a git repo, and add the following function to your .bashrc or .zshrc, you can interact with the repo using the command vimwiki git [commands] from any directory:

vimwiki () {
    if [[ $# == 0 ]]
    then
        nvim +'VimwikiIndex'
    elif [[ $1 == 'git' ]]
    then
        git -C ~/vimwiki/ ${@:2}
    else
        echo 'Usage: vimwiki [git] [args ...]'
    fi
}

For Fish, add the following function to your config.fish:

function vimwiki 
    if test (count $argv) -eq 0
        vim +"VimwikiIndex"
    else if test $argv[1] = "git"
        git -C ~/vimwiki/ $argv[2..-1]
    else
        echo "Usage: vimwiki [git] [args ...]"
    end
end

In addition, calling vimwiki without a git subcommand will automatically open the index.

You have to configure your wiki(s) in your vimrc, then you can configure syntax and file extension. To set them to markdown and .md add the following configuration to you vimrc:

let g:vimwiki_list = [{'path': '~/vimwiki/',
                      \ 'syntax': 'markdown', 'ext': '.md'}]

Vimwiki has a feature called "Temporary Wikis", that will treat every file with configured file-extension as a wiki. To disable this feature add this to your vimrc:

let g:vimwiki_global_ext = 0

Alternative you can set vimwiki to use markdown syntax but a different file-extension, like the default .wiki.

If you have other snippets you find useful, please share them here on the wiki.