ifacethoughts

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.

Discussion [Participate or Link]

  1. Karim said:

    Very smart and simple indeed! Thanks for sharing :)

  2. Jitendra said:

    Hey Abhijit,

    Jitendra from SezWho here…Please let me know if you have any updates for us and once you have some time, please update your SezWho rev from

    http://sezwho.com/sezwho21.zip

    Thanks, Jitendra

  3. Task Management Using vim | iface thoughts said:

    […] also tag the projects so that they automatically become part of my wiki. Sometimes I also tag individual tasks, especially if I need to access some of them […]

  4. Anonymous said:

    The following addition is also useful to enable a little bit of syntax highlighting. Just put it into your .vimrc


    au BufRead,BufNewFile *.txt set filetype=text
    autocmd FileType text syn match TextTag "\*[a-zA-Z]*\*"
    autocmd FileType text syn match TextJump "|[a-zA-Z]*|"
    hi def link TextTag String
    hi def link TextJump Comment

  5. Misha said:

    vimwiki 0.5 could be used as personal wiki…
    http://www.vim.org/scripts/script.php?script_id=2226

  6. [M]etabrain [E]ntry [L]og » Blog Archive » Lunchtime: a good time to go through notes said:

    […] you can use vim as a wiki. (Translation: Do you also like keeping your notes in plaintext files? Now you can link them […]

  7. lou said:

    I personally very much like the viki plugin:
    http://www.vim.org/scripts/script.php?script_id=861

  8. Customizing vim For Dojo | iface thoughts said:

    […] you can extend and customize it for your purpose. I use vim for almost all my tasks, including my personal wiki and task management. And this has inspired me to customize it further to work […]

  9. Extending Bash Auto-Completion | iface thoughts said:

    […] and using them to auto complete command line arguments for your application. I use vim as a wiki, task managemer and contacts. The vim helptags system lets me index the content instead of […]

  10. Anonymous said:

    Here’s a very simple way to do syntax highlighting (the above didn’t work for me):

    au BufNewFile,BufRead /home/anandgouda/wiki/* set filetype=help

  11. anonymous said:

    Does anyone know of a script or utility to convert the help file to html?

  12. kevin said:

    i really wanted to do this but it seems to require that my files be named *.txt

  13. Using vim as a personal wiki | The Celsius1414 Journal said:

    […] Nadgouda over at iface thoughts describes a method of using vim as a simple wiki system, utilizing its built-in “tags” […]

  14. Ashish Jain said:

    Illuminating post. Thanks :).

  15. BestSeoSoftware said:

    Hey Web Entrepreneurs and Webmasters

    If you are interested in 100% automatic book-marking submission software, Bookmarking Demon is usually the choice. The software submits blog posts, content articles as well as other website pages to hundred+ most popular high PR social websites like digg, reddit, etc on total autopilot. But this famous software is actually not low priced, that’s why I’ve acquired greatest discount link for it plus included huge social bookmarking bonus available from this page:

    http://www.bookmarkingdemongiveaway.com/

    If you locate more attractive Bookmarking Demon offer anywhere else, write me, I’ll add more value and provide it to you free of charge!

    Regards,
    Mark

  16. wilsh said:

    This totally works! However, I’d be happier if I could g^] to tags that include a “-” (dash). This is not possible with the default settings (presumably because dashes are not allowed in C or perl identifiers). I hoped to find a variable with the regular expression for valid tags, but couldn’t. Any advice? Is that hardcoded into vim?

    Keep up the good work!

  17. Henry said:

    This is great! How can I extend it to follow subfolders of the wiki/ directory?

  18. http://tinyurl.com/naok-8154317875 said:

    “vim As A Personal Wiki | iface thoughts” was in fact a
    remarkable post. In case it owned much more photographs it would definitely
    be quite possibly even better. Cya -Arthur

Say your thought!

If you want to use HTML you can use these tags: <a>, <em>, <strong>, <abbr>, <code>, <blockquote>. Closing the tags will be appreciated as this site uses valid XHTML.

freshthoughts

contactme

Abhijit Nadgouda
iface Consulting
India
+91 9819820312
My bookmarks

badgesand...

This is the weblog of Abhijit Nadgouda where he writes down his thoughts on software development and related topics. You are invited to subscribe to the feed to stay updated or check out more subscription options. Or you can choose to browse by one of the topics.