Vimwiki

June 6, 2012

Vim is the greatest thing ever. My second favorite thing is Vimwiki. Half my day is coding in Vim or bringing things in and out of Vimwiki.

What is it?

It's a personal wiki. Now, I don't really know what a wiki is. From my understanding, a wiki is a collection of text files that are linked to each other. It's amazing how powerful that is.

There are no folders, although you can link to many files from one. But from one of those files, you can link right back, so there is no rigid hierarchy that comes with a filesystem and folders.

What can you do with a personal wiki? I keep coming up with more. For example, for a couple years now, I kept all my notes on books I've read in a wiki. I have one file that lists the category of books. It's just three lines, for the three categories I have. I press enter on one line and it brings me to another file with a list of all the books. I press enter on any of the books and it brings me to the file with my notes on that book. I press escape anywhere on any of these files to go back. It's intuitive and fast. But it's the ability to link to any file in your wiki that's powerful.

Say I have book that fits in two categories. I can link to the same book from my two wiki files and it will link to the same file. This suddenly makes it so much better than a folder system. I also keep notes referencing different books in this same system. So I have a category about writing, and I have a great piece of advice that I've read in multiple books. I write this note down as its own file, and I reference all the relevant books. It's a revelation.

I think I stumbled on Vimwiki when I was reading something from Cal Newport and his method for collecting research for his books. He uses a similar system above of taking resources and identifying patterns among them using a wiki. He used pbwiki.com, which actually isn't bad, but I was intrigued by Vimwiki because I had already fallen in love with Vim at that point.

And that is its strongest point. You can fly with Vim around your wiki. Vim doesn't just make it fast, it makes it a joy to work with text, which is exclusively what you're working with in Vimwiki. If you need images or something else, you might need to look elsewhere, although I wouldn't be surprised if there was some sort of workaround.

Anyway, I use it for so many things. I use it to store any piece of writing. I'm allergic to word processors. I keep all my personal todo lists in it. This isn't so bad because the majority of my work requires collaborative todo lists so for just my own things it's perfectly manageable. Vimwiki actually has a built in todo list function, which means others must use it as their todo list tracker too. Honestly, it is already so much better than everything else I've tried (and I think I've tried most of them). The closest I've gotten to one I'd stick with is that one by the guy who wrote Writeroom but Vimwiki is the real deal.

I use it to store any kind of list. And I have a lot of lists. I have a list of all the books I want to read, and have read. Ditto for movies, games, and music. I have a list of all the great quotes I find on the internet. This might actually be my favorite list. I wouldn't even think of keeping a list like that if I didn't understand how powerful a personal wiki could be. I keep all the stuff I want to post here on this site. I keep a list of interesting things I find that I can tweet out. I have a long list of everything I want to write about but haven't yet. That one might be my most important one. Lists already rule our lives, but if you can take advantage of it like this, you might turn the tables into making it into something useful (and maybe even manageable).

I keep checklists in it too. Like, all the crap you have to remember when setting up a new server or something on Amazon. Things you don't do often but are still important.

There is one particular file in there I'm quite fond of. I call it my scratchpad. There are so many times in the day where I need to make a quick calculation and jot down some numbers, or someone is relaying something to me and I need to jot it down but not necessarily somewhere permanent. I used to use Textedit or that sticky note thing but now I have a permanent scratchpad right in my wiki. I love it because I can use Vim (do you see a recurring theme here?).

I'm convinced everyone should have a wiki. It's brought sanity in my life in a way I never imagined (although in some other ways, its brought to life a whole new layer of chaos, mainly about coming to grips with all the stuff I want and can do, which is exciting and scary).

What I used to use, or alternatives

I didn't have a direct alternative to Vimwiki before I started using it. I imagine something like pbwiki.com could have gotten me pretty far. Instead, I used to take a liberal amount of notes with Simplenote and its Mac equivalent Notational Velocity.

Now, more important than a wiki, is having something always ready at hand to jot something down the moment it comes to your head, assuming its worthy and necssary to jot down of course. Every great idea you have will evaporate if you don't note it somewhere. So a little notebook and pen is just fine, but it's even easier with an iPhone and Simplenote. Ditto with NV if you're on a mac. But after a couple years of doing this, it was getting out of control. I've been keeping those lists I mentioned above going for quite a while, way before Vimwiki, but I would save each item in the list as its own note. It worked fine, but having everything just... around, jumbled in a mess until you enter something in the search box or clicking a tag didn't scale as well as I would have liked.

Imagine using Vim to scroll and navigate one list with all your items versus using your mouse or finger to open each item one at a time. That's the big advantage over these note taking programs, I think.

So I had to make a choice of where to keep all this stuff, and although Vimwiki loses out on the ease of input, it totally kills my old system on everything else (and mostly on the strength of being able to use Vim). So how do I get around it not being able to jot and forget? I just email things to myself if I'm using an iPhone, otherwise a notebook works fine. I process everything later into my wiki. I email links, notes, quotes, etc., unless I'm already on my computer in which case it's just as easy to put in to my Vimwiki as it is to put it into NV. Unfortunately I kind of hate email but for now it works fine.

How to use it

I use Vimwiki in a particular way so take all of this as an introduction and make it your own.

To get to your Vimwiki at all, press leader + ww. This opens a index.wiki file in your default Vimwiki directory. You can change this to any other directory in your .vimrc with a simple line. I store mine in my Dropbox folder (more on that later). Your entire wiki will be files in this one directory so keep it safe, and back it up.

The key action is creating and linking to files. There are two ways to create a link. The first is to type any word that is capitalized and has another uppercase letter in it. (Example: ExampleLink) If I press enter when my cursor is on that word, it will create a new buffer with that file name. It won't exist until I save it like any other buffer, at which point it will create a new .wiki file in your wiki directory. Now press delete to go back. If you saved it, the link will be a different color, signifying that it exists.

Now, I don't like camelCase and this is hardly any better. The second option is to wrap your link in two brackets, like [[Example link]]. Much better.

If I'm on another page of my wiki, and I type [[Example link]] again, the color will show that it already exists and I can click right into it.

There are two keyboard actions available on any page except the index. leader + wr will prompt you to rename the file. If I change it to [[Example page]], it will change the name of the file as well as anywhere the link appears in your wiki. So say I link to one file named [[On Writing]] from three different pages in my wiki. If I change that to [[On Writing by Stephen King]], it will update the link in all three locations as well as the filename. Very convenient.

You can also press leader + wd to delete the file. This changes the color of the links in your wiki to when you didn't have the file saved.

So right here, you have something extremely powerful that you can link text files together with to an infinite depth using the ultimate convenience of Vim.

The only other big feature I use is its todo list features. To create a list item, start a line with a - or an *. Hitting return on that line will automatically create another bullet, on the same tab indent as the one you are pressing return from. Pretty standard. Now, to turn it into a todo, press CTRL + SPACE. Two brackets should show at the beginning of the line. Now press CTRL + SPACE again to toggle it checked. If you nest todos, it will automatically check the top level item as you finish the ones under it. You can also fold lists although I havent figured out how to do that yet.

I don't use Vimwiki's other formatting options like headers. I much prefer Markdown. But it doesn't get in your way if you don't like it. I also don't use the output to HTML function that might actually be fun to play around with later.

There you have it. I think this is the ultimate note taking, text gathering thing. The possibilities are endless. You can take all your notes in class with this. Store all your recipes. All your notes for your next novel. All without having to deal with any sort of file system or having to touch your mouse.

My setup

My Vimwiki is very important to me. So for ease of mind, I put it in a folder in my Dropbox. Im pretty sure that ensures I will never lose it no matter how fiery a death my computer comes to. I also use the same wiki on different computers but I only keep it on Dropbox on one computer. To keep it in sync with the other machines I don't use as much, I use Github.

Github is pretty much perfect. It's a backup to Dropbox, plus it keeps every version of every file you check in which can be convrnient in case you need to look up something that isn't there anymore. But the main reason is that I like to write on my iPad, so I ssh to my Linode and pull the latest version and fire up Vim. On my iPad. It's awesome and dorky. Otherwise I'm pretty sure you're perfectly fine with just syncing it with Dropbox among your different computers if you have them.

I could go on and on about how Vim on iPad is a revelation but I want to save that for later. With screen, I have one window constantly in the wiki, so I sometimes even ssh in with my iPhone. Pretty ridiculous, I know.

The diary

There's another bonus feature that I actually didn't discover until I was rummaging around the documentation looking for something else. I'm talking about Vimwiki's diary feature. I write a daily journal and Vimwiki is perfectly suited to it.

If you press leader w leader w, it will create a new file with the current date as the file name. This wiki file is actually in another directory called diary (also configurable) in your default wiki directory. This diary directory has an index.wiki that generates links to these daily files. If press leader w leader w tomorrow, it will automatically create a new blank file for you with tomorrow's date.

The obvious thing to do is to write a journal, but it's surprisingly useful in other ways. I use it as a scratchpad for the day, jotting down any notes or things I need to keep track of for the day, knowing it's going to be wiped clean the next (not really, but that's what it feels like).

I've been using it daily for a few months now. It's crazy to see how much I've put into this little feature. Imagine a month from now, this weird little scrapbook of myself with random thoughts and notes from each day. It makes me love writing things down I wouldn't think to normally, all organised in a way that I don't have to think or worry about at all. Is there anything more perfect?

Like I said, if I'm on my computer and I'm not coding or otherwise wasting time, I'm in Vimwiki, writing, thinking, jotting, organizing, and storing. It goes infinitely deep but doesn't feel overwhelming, and it takes advantage of everything Vim has to offer. It's fantastic.