Thursday, September 20, 2007

Get Organized with VIM....yes, VIM.

I've recently discovered and have become addicted to vim-outliner. If you've never used a note taker or outliner before then it's time to get organized. Outliners are great for organizing projects, planning events, meetings, presentations, talks, note taking and satisfying many other organizational needs. I wish I knew about vim-outliner when I was in college, it would have been the perfect tool for managing lecture note and class projects. I now use vim-outliner for organizing work tools and open source projects.

To install vim-outliner in Ubuntu is as easy as opening a terminal and typing:
sudo apt-get install vim-vimoutliner

Now you will need to edit the /etc/vim/vimoutlinerrc file to enable necessary features, so in a terminal type:
sudo vim /etc/vim/vimoutlinerrc

Press 'i' to enter insert mode then make sure the following 2 lines are uncommented:

let g:vo_modules_load = "checkbox:hoist"
let maplocalleader = ",,"

Also make sure that the following line ends with a zero, not a 1:

let g:use_space_colon=0

Now save the file by pressing the 'esc' key to exit insert mode and type:

Now, let's get outlining!
To open a vim-outliner file type:
vim filename.otl

You must have the '.otl' extension to your filename for vim to act as an outliner. To use the outline just start typing, remembering to press 'i' first to enter vim insert mode. Create categories and sub-categories by tabbing. Here is an example:

How to Back up Your Data

   USB Drive

The above is an example of a 3 level outline, vim will automatically color code each level. To add text or notes to a category, start a new line under a heading and begin the new with a :(sp) (That's colon followed by a space). Here is an example:

How to Back up Your Data

         :  Make sure you store your CD's in fairly cool conditions
         :  Don't storage your CD's in direct sunlight
Your text will automatically wrap as needed. Now comes the fun part....folding.
Exit vim's insert mode my pressing 'esc' and move your cursor to one of the newly
entered text lines and press the 'z' and 'a' keys (z-a) and you should get
something like the following:

How to Back up Your Data
         [TEXT] ------------------------- (2 lines)
Pretty neat! There are some built-in keyboard shortcuts that unleashed the real
power of folding. Here are some of those handy commands:


collapse a tree within command mode


expand one level


expand all the way down


Demote headline, collapse the tree to demote all children


Promote headline, collapse the tree to promote all children


Fold at level #, all set foldlevel=# (i.e. ,,3 will foldset at level 3)


Draw dashed line


Directory listing of the current directory


Sort sub-tree under cursor ascending


Sort sub-tree under cursor descending


Append timestamp (HH:MM:SS) to heading

There are several other commands. To learn more commands and other outliner
features you can access vim-outliner documentation while in vim, by typing:

:h vimoutliner

I know...... I know..... You are well impressed, but wait there's MORE!!!!!

You can add checkboxes and percentages of completion to each of your categories.
You do this by moving the cursor to the heading of choice and pressing the following
keys ",,c%" (that's "comma comma the letter 'c' and the percentage symbol")
This will create something like this:

[_] %How to Back up Your Data
[_] %CD-RW
[_] Storage
[TEXT] ------------------------- (2 lines)
[_] Lifespan

You can toggle a checkbox as checked or unchecked by pressing the following
keys ",,cx" (comma comma the letter 'c' and the letter 'x'). Here is a
screeenshot of a partially complete oultine with checkboxes and percentages:

Here is a list of checkbox commands:


Insert a check box on the current line or each line

of the currently selected range (including lines in

selected but closed folds).


Toggle check box state (percentage aware)


Delete check boxes


Create a check box with percentage placeholder


Create a check box with % placeholder on all headings


Compute % completion for the tree below the current heading.

Of course vim-outliner also has all the vim features and commands that
you've come to expect and love. So all vi controls and keyboard entries
work with outliner. You can find more information about vim-outliner at
At the vim-outliner site you'll find some neat scripts to convert .otl files
to .html and .sxi ( Presentation format).

Now go get organized!


Anonymous said...

Thanks for the great intro. I use vim outliner but had no idea it had some of the features you mentioned.

Kyle said...

OK, so it was a year or so after your original post, but boy did this nail it. I got vim-outliner running in a way I didn't expect. One tip for Debian-based systems; use the, don't use the apt-get install vim-outliner; it doesn't work as well.

Jared said...

Thanks Kyle. I appreciate the tip.

YC said...

Thanks, that was helpful - now I just wonder, why are those options commented out in the rc-file in the first place? Half of the functionality of the addon is unavailable without them!

verysimple said...

In case someone stumbles upon your post and, like me, is looking for some instructions on how to install this plugin, I'm documenting here the steps that I followed. At the time of writing my pc is running Ubuntu Intrepid.

- I installed via apt-get and configured the /etc/vim/vimoutlinerrc file as indicated. It still wasn't working.

- I installed the vim-addon-manager.
~$ sudo apt-get install vim-addon-manager

- if after that you run the command
~$ vim-addons
you should see a list of addons, including vimoutliner. I ran

Now to install the VO plugin issue the vim-addons command.

Either locally:
~$ vim-addons install vimoutliner

or system wide:
~$ sudo vim-addons -w install vimoutliner

Note that I typed the word 'vimoutliner' one letter at a time, since the shell autocomplete couldn't find it.

Those steps seemed to do the trick for me. On a side note I don't understand why this project isn't trying to make it more obvious and clear what to do to install and configure the plugin. I had already tried to install this a few months ago, but up gave out of annoyance with not finding the info.

Engineers Without Borders at Northern Arizona University said...

I recently installed vim-outliner on a new install of Ubuntu Karmic via apt-get, and didn't need to tweak the rc file at all--worked from the get go.

Engineers Without Borders at Northern Arizona University said...

I recently installed vim-outliner on a new install of Ubuntu Karmic via apt-get, and didn't need to tweak the rc file at all--worked from the get go.

THK said...

Thank you for the post. I've just followed it and almost everything have been running as expected.