vim As A Personal Wiki

vim is an extremely flexible and versatile editor and is one of those tools which have a cult-like following. Typically these tools are liked a lot by these followers and hated by others. So, this post is for those who like to use, or who are open to trying out, vim.

One thing I have learnt from experience is that the tool to collect and organize our information must be easily available and easy to use. And that is where vim scores higher than any other tool to build a wiki.

Some Background

vim inherently supports tags. These tags are more like bookmarks, and a tags file maintains an index of these tags. Using this, looking up a tag is extremely easy and fast. These tags have really been popular with the vim users, however, primarily for source code browsing. But there one more type of non-code tag that vim covers extremely well - the helptags. Whenever you use the command help zf to find help on the operator zf, it actually looks for the tag zf, which is indicated using the syntax *zf*. This acts as a bookmark for the section with help on zf. The index for these tags is created using the command helptags. Also, you can use the syntax |zf| to link to the tag from other files. Remember, the tag is more like a bookmark, so there are no restrictions on how it should be used, but its location should be indicative of start of the section it bookmarks. In fact, it can bookmark the entire file or a section or an individual line as well.

Here is the example:

							*zf* *E350*
zf{motion}  or
{Visual}zf	Operator to create a fold.
		This only works when 'foldmethod' is "manual" or "marker".
		The new fold will be closed for the "manual" method.
		'foldenable' will be set.
		Also see |fold-create-marker|.

We can use this to build a raw wiki system for ourselves. For example, we can have a file called ideas.txt, which has various entries with corresponding tags. Once the tags index is created, which we will look at shortly, you can jump to those tags using the command tag. As an aside, the command help, which we saw earlier, is in effect a special case of tag because it looks only at the tags index file in the vim documentation directory.

How to

I needed to do two things to start using this system:

1. Automatically create/update the tags index file, commonly referred to as the tags file, whenever I update any of my wiki files.
2. Ask the tag command to look at that tags file.

So we do the following.

1. Create a directory called wiki (name it as you want) in your home directory. In my case it is /home/anadgouda/wiki.
2. vim has a setting called tags which points to possible locations for the tags files. We prepend our wiki path through the vim settings file - either .vimrc or _vimrc depending on your platform. In my case it becomes set tags=/home/anadgouda/wiki/tags;./tags;tags;/.
3. Add autocmd BufWritePost /home/anadgouda/wiki/* :helptags /home/anadgouda/wiki in the vim settings file. This tells vim to execute the helptags command on files in the directory /home/anadgouda/wiki whenever a file is written to in that directory.

That is it. We now have a system where we can create text files, tag its various sections using *yourtag* syntax and then look it up using the command tag <yourtag>. Or you can link to the tag using the syntax |yourtag|. The only caveat is that we need to have the .txt extension to our filenames as helptags looks only that those.

Nowadays I use the vim as a combination of wiki and outliner to record my ideas and thoughts, documentation, tasks and even contacts. I believe you can go to any extent to customize vim. You can create your own commands, your own syntax and your own operations. This was an attempt at showing how we can efficiently use vim as more than a code editor, on multiple platforms, using its inbuilt capabilities.