A personal wiki? Is this not an oxymoron?

I learned about that personal wiki thing in Andy Hunt’s Refactor your Wetware: Pragmatic Thinking and Learning. The idea is that the brain is great, but it has this tendancy to forget. In order to better nurture one’s good ideas, one should therefore use an exocortex, a nice sci-fi term to designate a cybernetic augmentation to one’s brain. Which is a nice sci-fi sentence to designate just a place to write them ideas up and link them to one another.

Until now, I have used Notational Velocity for this purpose. It is a very good tool for this, facilitating the redaction and interlinking of multiple miscellaneous articles. I also has a few features for text styling, and even for strongly encrypting one’s notes, which is handy and precious (although it precludes searching with Spotlight). However, for better or for worse, my editing reflexes are now hardwired to Vi-style dual-mode typing, after all these years of happy Vim usage. Silly me! I should have known this was the way to addiction. Although Notational Velocity supports my preference by allowing the editing to happen in MacVim, this is a bit cumbersome. Also, it makes the whole thing hard to transport to Windows or Linux, that I use occasionally.

A personal wiki in Vim

So here’s my requirements for a good personal wiki:

• Tight integration to Vim for editing.
• Text composed of multiple entries, each called a topic. Each such topic corresponds to an idea or reference or thing.
• Possible to easily link between topics in order to articulate their relationships and to navigate easily from one related topic to another.

I implemented these requirements in a couple of hacking hours using Vim and Exuberant ctags. While the former requires no introduction on this blog, the latter is a nifty utility that can parse through files of code or structured text and extract its salient features, called tags, such as class, type and function definitions. Vim can load the tag databases output by ctags and permit easy navigation between the occurrence of a tag and its definition, using Ctrl+], as well as commands tag, pop, and some others.

A very nice feature of Exuberant ctags, which makes it deserving of installation over the BSD equivalent that lurked on my Mac, is that the set of languages it can parse through is extensible. This is done by editing the .ctags file, which lives at the root directory of the user account: tag-worthy bits of code are described using regular expressions and the files that contain such code are identified using file name patterns or extensions. I used this feature to design a simple description language for my personal wiki: topic are started with a heading, which consists of the symbol => followed by the topic descriptor, a single word in CamelCase (digits allowed). Links to these topics correspond to this single word prepended with a colon. Putting these together, you end up with files looking like

…

=> SomeNewTopic

Blah blah blah. :LinkToOtherTopic
...
:SomeNewTopic

Depending on how ctags is configured, the tag database it produces can contain tags from multiple files, making it easy to divide one’s personal wiki among many subject-specific files.

Working with even such minimal markup is much more interesting if we can do it with syntax highlighting, which could better reveal links and emphasize topic separation through automatic styling. I thus whipped out a Vim syntax file for the format above, which comes along a small file detection plug-in. Personal wiki files are identified by both Vim and ctags as any file with the vln or vimlinknotes extension, as well as files named [Vv]im[Ll]ink[Nn]otes.

Installation and usage

The configuration files and scripts can be downloaded from https://github.com/hamelin/vimlinknotes, either as a ZIP archive or by Git cloning. People who know their way around Vim and ctags should have no problem setting everything up themselves, but I slapped together a small installation bash script. As usual, you use this software at your own risk. You may drop me a line if you have trouble making it work.

One issue that users must overcome while using VimLinkNotes is that the tags database must be updated regularly so that new topics can be navigated to. As proposed in conclusion of the installation script, it is advisable to set up an easy Vim shortcut to invoke ctags, such as a keymapping or a custom command. For instance, for wiki kept over multiple .vln files in a directory named PersonalWiki in one’s Dropbox, one could add the following line to his .vimrc:

nnoremap <ESC>t :ctags -f ~/tags -R ~/Dropbox/PersonalWiki<CR>

This will make the key sequence of [Esc] and [T] run ctags and update the database with whatever new topics were added since the last run.