Introduction to VimWiki

VimWiki is a way to create wikis (collections of notes) from right inside of Vim. It works a lot like Obsidian, in that it is modifiable and extendible and works well for taking notes as flat Markdown files. But you have the benefit of never having to leave Vim!

I’ve been playing around with VimWiki for my own knowledge management and it’s been working well. Something it makes easier that no other knowledge management solution seems to do well is taking notes and learning from a codebase. It’s not that this is particularly difficult in other tools, like Roam or Obsidian. Just that VimWiki means I can read and take notes on code without having to leave the editor where I’m reading it.

It also integrates seamlessly into coding sessions. So I don’t have to interrupt my workflow or switch contexts to go and check my notes on something. It’s right there in Vim.

Installation and Setup

Before installing VimWiki, you need to have the following set in your .vimrc:

set nocompatible
filetype plugin on
syntax on

Installing VimWiki with VimPlug is very straightforward. Just add the following to your .vimrc file and run :PlugInstall:

Plug 'vimwiki/vimwiki'

I use neovim, so I put the above in my init.vim file and then created a vimwiki.vim file in my plugin/ directory. This file is where I can further configure VimWiki.

All I’ve configured so far is the following:

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

Here I’ve configured VimWiki to set the slipbox/ directory as my VimWiki directory and to use traditional Markdown for all my wiki files. VimWiki uses Vim’s mark up style by default, but you can set it to use Markdown (as I have done) or to use MediaWiki-style mark up.

There is additional configuration you can do, like control how VimWiki generates an HTML version of your wiki. For that, read the man page at :help vimwiki.

Working with VimWiki

Next I’ll cover the basics of working with VimWiki.

Navigating VimWiki

When you’re working on a project in Vim, you can open your wiki by executing <Leader>ww. This will take you to your wiki’s root (or index) file, which for me is just index.md.

Once you’re in your wiki, there are a couple of things you can do: create a new note or navigate around your existing notes.

To create a new note, hit <Leader>wn. You’ll be prompted for the note’s path (minus the file extension) and then dropped into an empty markdown file. Something I want to experiment with here is using Vim’s built-in skeleton (i.e. file template) feature. This would make it so when I created a new note, it was pre-populated with things like frontmatter and any other formatting I wanted.

Aside from just creating new notes, it’s easy to navigate around VimWiki. Two commands in particular are important here: <CR> and <S-CR>: the first follows a link, opening a VimWiki page under your cursor, and the second does the same thing but in a new split. This two commands will help you navigate forward through your wiki. To navigate backwards, hit <Backspace>.

VimWiki also gives you commands for navigating within a file. These commands will help you navigate either by link or by header and serve as compliments to Vim’s existing movement commands (i.e. <C>u and <C>d to page up and down).

To navigate between links in a document, use <Tab> and <S-Tab>. This makes navigating around your wiki really fast, because you can traverse your notes with <Tab> and <CR>.

To navigate between headings in your document, use the [ and ] to navigate forward and backwards. You combine this with one of the following objects: [ or ] will navigate you to the next/previous heading while = will send you to the next/previous heading of the same level. The combinations then are:

Command	Description
[[ | Navigate to the previous header |
| ]]	Navigate to the next header
[=	Navigate to the previous header with the same level (i.e. the previous h2)
]=	Navigate to the next header with the same level (i.e. the next h2)

Editing Notes

VimWiki comes with a couple of commands that make working with pages of text even easier, especially in the context of creating a wiki.

To start, VimWiki comes with two commands for quickly creating links in your text. To do so you can hit + or just hit <CR> (both in normal or visual mode). For markdown files this will automatically insert brackets around the selected object and add parenthesis afterwards. If you hit <CR> again on the text, it’ll take you to the note with that title or create a new one if it doesn’t exist. This makes linking notes very easy.

You can use - and = to increase the heading level of some text. Each press will either add or remove a # to your markdown file, thereby increasing or decreasing the heading level.

Finally, VimWiki adds the h/H object for working with sections of text. What this means practically is that changing, deleting, and selecting entire sections of text is quick and easy. Hitting vah will visually select (v) outside (a) the current heading section (h), meaning it will select all the text in the current section, including the heading. If your section has subsections you would like to select too, swap h for H. As with other selections, a is to select outside (so including the heading) while i is to select inside.

Together, these commands make working with entire sections of text really easy:

Command	Description
cih	Change the contents of the current section
dah	Delete the current section (including the heading)
viH	Select the text under the current heading (including subsections)

Conclusion

That covers the basic setup of VimWiki as well as navigating around your new wiki. There are a couple of additional features that make VimWiki really powerful that I’ll cover in a future article. Namely:

1. VimWiki’s built in diary, which lets you create daily notes, similar to the daily note in Roam or Obsidian
2. Converting your wiki to html, including using templates to generate different types of pages.
3. Backlinks. VimWiki will search through your database and create a list of notes that link to your current note (either to navigate to them or to append them to the current note).

The above are three major features of VimWiki that I’m excited to explore. But VimWiki includes some additional minor features that make it really great. For instance, it includes a set of commands for quickly working with tables, lists, and tasks. It also has built in search with Ag, so you can quickly find text in your database of notes.

programming