Using Vim Wiki

The Problem

I’ve been a big fan of Vim ever since my old boss Josh introduced me to it somewhere around 2014. Before that I had used mostly Sublime, but with a bit of dabbling into Visual Studio and a couple of JetBrains IDEs. It of course took a while, but once I had the basics down to muscle memory I was absolutely sold on Vim. It’s become just how I type, and the little tricks that save a second or two here or there over the course of a day add up to a real productivity gain. The only downside is that any time I’m typing into something that doesn’t recognize vim keybindings I end up mashing escape too often and being frustrated that things just don’t work as well.

Long story short, I just couldn’t get into any of the popular note taking apps because they just weren’t Vim. I had a pretty short list of wants:

1. Some sort of syncing or backup. I take lots of notes on paper and I love that I can grab a notebook from five years ago and quickly get insight into whatever was happening at that time. I’ve got notebooks going all the way back to my very first internship, and they’ve actually come in handy more than once. I needed syncing or backup because it’s easy to see a scenario in which my computer accidentally drinks a cup of coffee and woosh there go a years worth of notes. No thank you.
2. Maybe open source? I wanted this for the same reason syncing and backup are important. I take notes because I want to remember something. If a company can go out of business and my notes are gone… well that’s just bad news for me. I wanted something that I felt had real lasting power. At some point I realized that it’s honestly hard to be just plain ole Markdown files.
3. Easy to access. If notes are painful to take, I’m not going to take them. Maybe I’m just lazy, but it’s the truth. I wanted something that was just a click or maybe two away from me opening it and using it anytime I’m at my computer. I don’t even care that much for taking notes from my phone or anything — I just want it to be super easy from my computer.

You’ve probably got several apps queued up in your head to recommend to me, right? Evernote was always a big suggestion, and I did enjoy using it for a long time. It did syncing so I wasn’t worried about my computer having the only copy. It wasn’t open source, but it was a paid app that I could at least try to help stay in business. It’s not like it was hard to access either — just start the app when I first start working and use Spotlight Search to quickly hop to it whenever I wanted to take a note.

But. It wasn’t Vim. It wasn’t Markdown either, so I knew that any note I took in it was only going to be really useful within Evernote. Plus I didn’t really make much use of any of the cooler features because I’m a simple man and typically take simple notes. So I plugged along with it, but I wasn’t necessarily happy about it, you know?

Enter VimWiki.

VimWiki is a “personal wiki for Vim — a number of linked text files that have their own syntax highlighting.” It’s easy to access (three keystrokes) while I’m already in Vim, which if I’m on my computer working I 100% am. It’s got an easy to use diary feature, which is something I’d been trying to do more often. It even supports Markdown, although I didn’t really use that at first.

Now that I’ve got several months of use under my belt, I feel like I’ve nailed down a few things that make it just about perfect for my needs.

How I Use It Now

Using Markdown

If you check out the project’s docs linked above, you’ll see that they’ve got their own syntax that’s not at all hard to use. I’ve never used orgmode enough before to really know for sure, but it at least seems similar. It’s a moot point though, because my very first suggestion is to use Markdown instead. I’m sure there are benefits to the default syntax, but I know Markdown well, I use it for just about everything else I write, and it renders well on Github and Gitlab, which will be important later.

Telling VimWiki to use Mardown is as simple as adding this to your vimrc (or init.vim):

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

Easy as pie. I didn’t do this at first so I had to do a fair amount of converting the default syntax to Markdown, but that wasn’t very hard.

Gitlab Backups

I knew that I wanted my notes to be backed up and I figured that keeping everything in a git repository couldn’t be a bad idea. At first I would manually commit and push things up whenever I thought about it, but that’s a bad plan because obviously I would never plan for my laptop to bite it and me lose my notes.

I figured it would be easy to set up a cron job to just commit and push every fifteen minutes, but it turns out MacOS deprecated the crontab command a long time ago. After I found this blog I ended up with this snippet located in /Users/linell/Library/LaunchAgents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.linell.vimwikibackup</string>

  <key>ProgramArguments</key>
  <array>
    <string>/Users/linell/vimwiki/backup.sh</string>
  </array>

  <key>Nice</key>
  <integer>1</integer>

  <key>StartInterval</key>
  <integer>300</integer>

  <key>RunAtLoad</key>
  <true/>

  <key>StandardErrorPath</key>
  <string>/tmp/vimwikibackup.err</string>

  <key>StandardOutPath</key>
  <string>/tmp/vimwikibackup.out</string>
</dict>
</plist>

The file that it’s calling out to is stored directly in ~/vimwiki and is as simple as this:

cd ~/vimwiki
git add .
git commit -a -m "updated on `date +'%Y%m%d_%H:%M'`"
git push origin master

With this set up, I don’t have to worry about remembering to manually do anything and I can guarentee that I won’t lose too much work if things ever go south. It’s also got the nice benefit of being displayed really well on Gitlab. The only downside I’ve encountered in this approach that I haven’t figured out yet is that links that VimWiki generates look like [Foo](Foo), which isn’t clickable in Gitlab. It’s been easy enough to just tack .md on the end of the link so that it’s [Foo](Foo.md) though, which lets me click around and view everything in a nice interface.

Easy Access

VimWiki is pretty darn easy to access from the jump. <Leader>ww opens the index file, which is honestly what I use for most things. In my index file I’ve got a bunch of links generated that will take me to the other pages that I use the vast majority of the time. There are a ton of built in shortcuts that you can check out in their documentation, and you can find cheatsheets like this one that make things pretty easy to learn.

The only things I’ve really added to make my life easier are a command to open the diary and another to open my scratch buffer. From the diary file you can see a list of all of your diary entries, which is pretty self explanatory. The scratch buffer is another trick that I picked up from Josh mentioned in the beginning of this post, and it’s simple but super effective: it’s a file I use to just store random stuff I need to type out. It’s mostly little snippets of code that I want to copy paste all at once, or things that don’t really need to be in my project’s source control but I do want a record of having done. His command is much cooler but overkill for what I needed. I just created a regular link to a new file from my wiki index and then a command to easily open it. The command probably sucks, but it works. Here are both of those:

command! Diary VimwikiDiaryIndex

"" Lame adaptation of Josh's buffer file here:
""  https://gist.github.com/dphase/1792d67b4ac06aea11a49ed801f18a7e
function! s:DScratch()
  exe 'edit ~/vimwiki/Scratch Buffer.md'
endfunction

command! Scratch call s:DScratch(<f-args>)

Conclusion

VimWiki works super well for everything I need for taking notes. It hits all of my criteria, it’s easy to set up and use, and honestly it’s neat to not need another app. I’m sure I’ll continue to refine and improve my setup over time, but I can’t suggest it highly enough overall.