My Simple Solution for Outlining

I’ve had a couple of folks ask after my tools and process for writing based on mentions I’ve made in the podcast. I thought I’d take this opportunity to share a few thoughts as they may be of general interest.

What I use is pretty straightforward. I use vim, I have for years, so this is specific to that text editor.  vim is available for every operating system, many of you may already be familiar with the basics of how to use it.  I’ll recommend you to the project’s web site if you are not already familiar.  What I use isn’t a key binding but some buffer auto commands that I associate with a custom filename extension, “.notes”. I take advantage of vim’s fold support to tie folding to white space indentation.

autocmd BufEnter,BufNew *.notes set smartindent foldmethod=indent expandtab tw=0 ts=4 sw=4 spell

That line above should be all one line in a .vimrc file. smartindent preserves indent when starting new lines. I use ctrl-d and ctrl-t when in insert mode to outdent and indent respectively. You can also just hit tab when in insert mode to increase indent. In command mode you can use the shift commands, >> and << to indent and outdent respectively. You can combine those with vim’s various selection modes, too, which can be vary useful for re-organizing your outline’s structure. Those are all defaults in vim, no special config needed.

foldmethod=indent means that more than one line at the same level of indentation triggers a fold. A fold is just some number of lines hidden from view. vim colors a fold different when collapsed and by default shows the first line of the folded text as a summary and provides information on how much text is hidden in the fold. For moving, cutting and yanking, a closed fold behaves like a single line, making it far easier to work with text that you want to keep together and treat as one thing, like sections of an outline.

In command mode, the various z-* commands manipulate folds. In particular, I use z-O to open all the folds below a certain level of indentation and z-C to recursively close them back up again. Using simple outline organization with my indents means I can easily open and close main sections of a piece on which I am writing.

The rest of the line ensures indentation is driven by spaces, not tabs, is set consistently, and that text wrapping of lines doesn’t interfere with indentation. Oh, and that final command enables inline spell checking.

Here are the raw notes for one of my recent features by way of example. Feel free to download this file and experiment. With that autocmd line in place, when you open a *.notes file, it should be collapsed initially. Then you can navigate to the different folds and use the z-* commands to explore. Globally useful are z-r to reduce folding for an entire document by one level and z-m to fold more by one level.