Jeromy Anglim's Blog: Psychology and Statistics

Saturday, April 16, 2011

Using Vim and VimOutliner as a Brainstorming and Outlining Tool

This post discuses using Vim as an outlining tool. It focuses particularly on VimOutliner. In particular the post (a) discusses reasons why I like outlining tools, (b) presents some links for getting started and installing VimOutliner, (c) presents my verdict on the personal utility of VimOutliner, and (d) presents an assortment of little issues that I encountered and resolved while learning to use VimOutliner.


I've been a huge fan of outlining tools for more than ten years. It all started when I stumbled on Outline View in MS Word. I tweaked the settings a little bit, reducing the tab width to zero, and adding a few additional shortcut keys and macros.

I used Outline View to do much of my project-related brainstorming. For example, if I had a yes/no decision to make, I'd type the name of the problem with subheadings: description, yes, no, and decision. The description would articulate the nature of the decision. I'd then put reasons for yes, and reasons for no under their respective headings. This facilitated taking both perspectives. Once I'd reached the decision, I could fold up the decision and move it from a pending section to a resolved section.

On a typical project there might 20, 30, or more decisions to be made.
Using the hierarchical structure of Outline View allowed me to zoom in and out of problems. And this is but one example. I used outlines for brainstorming, articulating problems, recording a log of events, organising notes, and more.

Of course, I'm not the first to discover the power of outlining. Outlining is part of many people's brainstorming and thinking toolkit (see Free Mind for an open source mind mapping tool), this post on essay writing strategies, etc.).

The beauty of a tool like Outline View is:

  • the ability to quickly manipulate the outline, promoting and demoting elements, moving elements or whole trees up and down, and so on
  • the ability to quickly navigate the outline
  • the ability to selectively show elements of the outline
  • Outline View also had benefits in that it had all the standard tools of MS Word available.

However, Outline View also had problems:

  • It was limited to 9 heading levels.
  • Large files over about 200,000 words were often sluggish, and sometimes crashed.
  • It was difficult to convert the file into other formats.
  • It lacked some fold navigation and viewing options, such as collapsing up a fold or just showing the folds required to view the current line.
  • Many of the keyboard shortcuts for Outline navigation and viewing required movement of the hands from the home key position.


I previously posted about my transition to using Vim. As part of this transition, I was keen to bring as many tasks as possible into Vim. I saw the appeal of plain text. I wanted to use cross-platform, open source tools. I wanted to take advantage of the power of the text editing keys in Vim. Thus, I wanted to switch from MS Word Outline View to an outliner in Vim.

VimOutliner is a major outlining tool for Vim. Raymon Li wrote instructions for installing VimOutliner on Windows.

Here are some additional links relevant to Vim, VimOutliner, and outlining more broadly.

Evaluation of VimOutliner after 3 months

At the time of posting I've been using Vim for around three months. However, for the last month and half I have settled into a workflow that does not involve VimOutliner. Instead, I've switched to using Markdown in Vim with custom folding for my brainstorming.

I'll talk more about my Markdown brainstorming setup at a later date (for an overview of Markdown in Vim, see this video on Vim and Markdown if you're curious). However, in general my preference for using Markdown has largely flowed from the benefits provided by Vim when working with text file formats. Specifically in MS Word, Outline View relative to Normal View had the advantage of being able to quickly hide and show the relevant text in a hierarchical document. However, Vim's folding tools can facilitate hiding and showing of text in a variety of text formats. Thus, with Markdown I can write text in a more structured format. The content can more readily be used in other sources, such as blog posts. Yet using Vim I can still hide and show relevant sections of text and move sections around fluidly.

Assorted problems and solutions

The remainder of this post records a few challenges that I encountered when getting oriented with VimOutliner. I've recorded them here in case they might be useful to others. Bear in mind that they are effectively the working notes of someone new both to Vim and VimOutliner.

1. Promote or demote multiple lines

  • How can multiple lines be promoted or demoted?

Visual line selection approach: 1. V to enter visual line mode * select lines to be promoted or demoted * > or < to demote or promote * . to repeat, u to undo

Collapsed fold approach: 1. collapse a fold (e.g., zc) 2. >> or << to demote or promote

2. Tab width for outline files

  • What is the best tab width for outlines?
  • If this is different to the default setting, how can such a change be limited to Vim Outlines?

Tab width of 2 might be better.

I added the following commands to my Vimrc

au BufEnter *.otl setlocal tabstop = 2
au BufEnter *.otl setlocal shiftwidth=2

3. Using virtualedit

  • Should virtualedit be turned off when working with outline mode?
  • Enter in insert mode at the end of a heading line starts a new line with proper indentation
  • o and O in normal mode add new lines below and above the current heading at the same heading level

Thus, vitualedit can be the source of formatting problems. However, with care, this can be prevented, and I like virtualedit enough to not turn it off for this file type.

4. Opening just subheadings

  • How can a collapsed heading only be opened to show the first set of headings?

The documentation for VimOutliner does not mention this. General Vim help on folding (h folding) is relevant. zx and zv are the two relevant key combinations.

5. Add heading below fold at same level as fold


I often edit a fold, fold it up and then want to add another level as a fold. For example, take the following:


I might want to fold up text1 to hide text2.1 to text2.4 and then want to add a new heading at the same level as text1 below test2.4. Pressing o adds a line below text2.4 at the same level as text2.4. How do I add a heading below test2.4?

  • Assume in insert mode
  • Ensure cursor is actually on fold: kj
  • Move cursor to start of text ^
  • Copy preceding tabs y0
  • Collapse headings again zc
  • Add line o
  • Exit mode <ESC>
  • Paste tabs P
  • Enter insert mode at end of line A

And optionally

  • Collapse unnecessary folds <ESC>zx
  • Return to insert mode A

Taken together and with some seemingly necessary tweaking, this makes:

au FileType vo_base  map <leader>o kjzO^y0zco<Esc>0DPA<Esc>zxA
  • It does not work when body text is at the bottom
    • it adds an extra body text line
  • It sometimes does not work when the outline is corrupted
    • it displays various error messages
  • It does not work when the heading is not folded
    • it leaves a blank line

6. Preventing outline file format corruption

  • What kinds of corruption of the outline file format can occur?
  • How can this be prevented?

Spaces where tabs should be is a major source of problems.

Outline format uses tabs for indentation. In general, if spaces precede the first printed character, the file format becomes corrupted.

The following are common causes of this

  • spaces can be inserted by using space instead of tab
  • spaces can be inserted when virtual edit is on

Potential Resolutions:

  • Prevent
    • Disable virtualedit (i.e., set virtualedit=""). However, I like virtualedit and disabling it for one file type makes my editing experience less consistent. So I chose not to do this.
    • Follow the rule of always starting a new heading using a limited set of keys: Enter, o, O.
    • Always change heading level using standard keys:
      • Tab, Ctrl+D, Ctrl+T (insert mode)
      • >> << (normal mode)
    • Avoid leaving blank lines
      • If a new heading is created, but no text is entered, delete it before moving the cursor.
      • The above behaviour could be automated with a substitution command.
  • Diagnose Problem
    • set list shows whether the characters preceding headings are all ^I (set nolist) turns this off.
  • Fix
    • Manually replace spaces with tabs with assistance from set list
    • Use substitution to replace all problematic lines. This could also be linked to an autocommand that automatically checks and fixes problems
  • General Advice