Vim Recipes ‣ Other Uses of Vim ‣ Outlining a Document

Outlining a Document

Problem

You want to create an outline view of a document such that its structure can be treated as a hierarchy, the levels of which can be expanded or collapsed.

For example, if you were writing an essay you may begin by creating an outline. Initially that would consist of the main section headings. You may then decide to subdivide those headings further, or add explanatory text that explains the heading's scope. As you continue this iterative process, you can focus on a particular level by expanding that level of the hierarchy. This process enables long or complex documents to be planned and organised in a logical fashion.

Solution

Use the Vim Outliner plugin.

Vim Outliner satisfies all of the objectives above. It's completely integrated with Vim, so your existing Vim knowledge still applies, and there's little to learn.

Download the plugin from VimOutliner.org, then follow the installation instructions. (The Extending Vim with Scripts and Plugins recipe may be helpful here).

Debian/Ubuntu users can install Vim Outliner via their package manager. The installation process is slightly convoluted, however, so instructions follow:

$ sudo apt-get install vim-vimoutliner
  vim-addon-manager
  $ sudo vim-addons -w install vimoutliner

Add the following line to your vimrc if not already there:

filetype plugin indent on

Now open a new file with an .otl extension with Vim, e.g.

vim outline.otl

Each line of this file becomes an entry in the outline. Indentation is used to denote levels of hierarchy. For example:

In this example, Solar System is at the top level of the outline. Sun and Planets are the next level down. All of the planets are in the next level after that. Each level is automatically assigned a colour.

You can add body text to a heading by starting a new line with a colon followed by a space, i.e. : Body text.

In the example above, body text has been added to the Sun heading.

Vim Outliner uses Vim's folds feature, so the standard folds commands still work. Continuing the above example, if your cursor is over the body text and you hit the fold close command zc the text will be hidden.

Using zc on a heading collapses its child elements. So, with the cursor over Planets zc displays:

To expand a tree one level use zo; to expand it all the way down use zO.

To move a heading to a lower level in the hierarchy use >> in Normal mode; << reverses the process.

A shortcut for expanding the hierarchy to a certain level is \n, where n is the minimum level you want displayed. \0 expands every level. \1 collapses every level. Using \2 on our solar system outline displays only the first- and second-level headings:

For more information see :help vimoutliner.

A mature alternative to Vim Outliner is TVO (The Vim Outliner). Confusingly-similar name aside, it's worth considering if Vim Outliner doesn't suit you.

Discussion

A key strength of this form of organisation is that you can view a complex document at a glance with \1, then drill down to a specific heading to work on it.

I use one for my todo/ideas list by putting every item on a line of its own, then, as patterns emerge, grouping items under headings. For instance, I may add a heading for Book on HTML. Some time later I think of some chapters, so add them as subheadings to Book on HTML. When I want to start writing notes for a chapter I add body text to a heading, and start typing.

Vim Outliner comes with various scripts to convert outlines into other file formats. For instance, there is a script named otl2html which can be used to convert a .otl file into a .html. This lets you create semantically-correct webpages without writing HTML. There's also otl2docbook and otl2pdb, which target DocBook and AddressDB Palm, respectively. For more tools like this, see VimOutliner.org.