vimwiki cheat sheet

installation

Vimwiki requires a couple options to be configured for it to work

set nocompatible
filetype plugin on
syntax on

Install the plugin, in this case using Vim-Plug

Plug 'vimwiki/vimwiki'

configuration

Vimwiki uses a list of dictionaries to store configuration options for each wiki. These are referred to as local options in the help. This is the g:vimwiki_list global variable.

Here is mine so far.

let g:vimwiki_list = [{'name': 'main',
                     \ 'path': '~/vimwiki/',
                     \ 'path_html': '~/vimwiki/html/main',
                     \ 'links_space_char': '_',
                     \ 'syntax': 'markdown',
                     \ 'ext': '.md'},
                     \{'name': 'zettelkasten',
                     \ 'path': '~/vimwiki/zettelkasten',
                     \ 'path_html': '~/vimwiki/html/zettelkasten',
                     \ 'links_space_char': '_',
                     \ 'syntax': 'markdown',
                     \ 'ext': '.md'},
                     \{'name': 'writings',
                     \ 'path': '~/vimwiki/writings',
                     \ 'path_html': '~/vimwiki/html/writings',
                     \ 'links_space_char': '_',
                     \ 'syntax': 'markdown',
                     \ 'ext': '.md'},
                     \{'name': 'books',
                     \ 'path': '~/vimwiki/books',
                     \ 'path_html': '~/vimwiki/html/books',
                     \ 'links_space_char': '_',
                     \ 'syntax': 'markdown',
                     \ 'ext': '.md'},
                     \{'name': 'recipes',
                     \ 'path': '~/vimwiki/recipes',
                     \ 'path_html': '~/vimwiki/html/recipes',
                     \ 'links_space_char': '_',
                     \ 'syntax': 'markdown',
                     \ 'ext': '.md'}]

name is the human-readable name for the wiki. This is used to select a wiki from the list with the command or make inter-wiki links.

path is the path of the wiki. This is where the root index will reside.

path_html is the path where html files will be generated.

links_space_char is how spaces are handled in link titles when the wiki files are generated. Default keeps the spaces in the filename, but a much more sensible option is to replace them with underscores.

syntax is the syntax to use. AFAIK this only controls what the mappings do (e.g. pressing + will create a markdown link instead of default wiki syntax). I prefer to use markdown. I don’t think this option effects syntax highlighting.

ext is the file extension used when creating new files. I force .md since I’m using markdown syntax.

I also set some global options in my vimrc

let g:vimwiki_global_ext = 0
let g:vimwiki_listsyms = ' ◴↻x'
let g:vimwiki_filetypes = ['markdown', 'pandoc']
let g:vimwiki_dir_link = 'index'
let g:vimwiki_auto_chdir = 1
let g:vimwiki_auto_header = 1
let g:vimwiki_auto_nested_syntaxes = 1
" let g:vimwiki_conceal_pre = 1

g:vimwiki_global_ext is for controlling the behavior of creating temporary wikis. By default vimwiki tries to create temporary wikis if it sees the file extension when opening a file outside an established wiki folder. Since I use .md files for other things, I turn this off.

g:vimwiki_listsysm changes the progression of todo list characters when completing a task. Docs suggest this feature is to notate the extent to which a task has been completed. I change that to use other symbols that have different meaning to me.

let g:vimwiki_listsyms = ' ◴↻x'

- [x] this item is complete
- [◴] this item is waiting on something
- [↻] this item needs to be done again
- [ ] this item is incomplete

g:vimwiki_filetypes is for changing the default filetype of vimwiki files. I set this to:

let g:vimwiki_filetypes = ['markdown', 'pandoc']

So that the filetype changes to vimwiki.markdown.pandoc. This helps with syntax highlighting and can be used to enable other plugins and functions if you have something set up with an autoload command in your .vimrc

g:vimwiki_dir_link is for changing behavior of how vimwiki handles links to directories. By default directories are opened with Netrw. Changing it to ‘index’ creates a file called index.md.

g:vimwiki_auto_chdir changes the behavior of vim to automatically cd into any directories as you pop in and out of new notes folders.

g:vimwiki_auto_header automatically generates a level 1 header from the given title when creating a new link

g:vimwiki_auto_nested_syntaxes enable nested syntax highlighting automatically. With pandoc you can use it like this. Note that it can be slow for really big documents, so you might instead want to whitelist syntax checking with the g:vimwiki_nested_syntaxes option. See this document for an example.

g:vimwiki_conceal_pre allows hiding of the code block syntax, but I prefer leaving it in at the moment.

global commands

local