Using Vim for writing Prose

Vim is a great text editor for writing code. Anyone who claims otherwise is either an Emacs user (and you should be OK with that, because Emacs is pretty neat) or a “casual” code wrangler who sometimes dabbles in programming but knows very little of it. You can recognize these guys because of the persistent Dunning–Kruger aura effect that surrounds them (+10 to Smug Ignorance). The smart people know that if you are writing code, you should be writing it in Vim (or maybe in Emacs if you were born with extra fingers on each hand). What about prose though?

The wise advice that is always thrown around by seasoned vimmers is that you should use it for everything. It doesn’t really make sense to fire up another text editor if you want to write a letter, a blog post or a short story. If it involves editing text, it should be done in Vim. That said, Vim can sometimes be less than perfect for that sort of thing. Or rather, there are more enticing alternatives out there: like Write Room for example.

With the default, out-of-the-box settings Vim can be less than perfect for editing text. For one, it is an editor designed to work with lines of text and when you write code, the last thing you want is for your editor to fuck with your lines. Thus most people opt to have no line wrapping or soft line wrapping by default to avoid headaches. When writing prose, you don’t really work with lines. You work with paragraphs.

What is a paragraph though? Well, in most editors it is a block of text composed out of lines that are wrapped to fit to screen/container width. For Vim however a paragraph is technically just a single line. If you have no wrapping enabled then your paragaph will simply scroll off the screen to the right forever. If you have soft wrap, then it will be nicely wrapped wot window width but still synonymous to line. All line based commands will affect the entire paragraph. So for example, d d can potentially blow away half a page or more, which is not technically what it was designed for.

Hard Wrap is Your Friend

The #1 problem of editing prose with Vim is not as much configuration as the approach people take to it. There is this notion that text files should be soft wrapped because that’s how other editors do it. This is however not necessarily true for all use cases. If you think about it logically, a lot of non-code text files you might be editing with Vim do not necessarily require soft wrapping. Readme files, for example, actually benefit from having lines hard wrapped around the column 80 as most text editors and viewers will open them in a window that is 80 characters wide or wider.

I submit that most of the time when you are writing prose in the form of plain text files, you are actually writing “source code” of sorts. By that I mean that the file you are writing is not the end product, but instead it will be run through some sort of conversion tool (like Pandoc) and end up as a PDF, HTML or maybe a Microsoft Word file later on. This of course means that the way you wrap your lines is inessential, as most tools that generate fancy, rich text out of plain text files are not particularly interested in white space unless it indicates end of paragraph.

This means that you can technically hard-wrap your text without ruining shit for everyone. And as soon as you do, life becomes easier. Scrolling stops being wonky, j and k work properly and all normal mode commands start to work properly.

These are the settings I typically recommend you set up when working with text documents:

setlocal formatoptions=ant
setlocal textwidth=80
setlocal wrapmargin=0

The t option ensures text gets wrapped on textwidth and the a turns on the real-time reformatting as you edit. In essence it means that your paragraphs will get re-wrapped automatically each time you insert or delete characters. It feels exactly as working in soft-wrap mode.

Typically when you open a new file that was soft-wrapped you may want to re-format it using the good old g g g q G sequence. Quick word of advice – it is usually a good idea to disable auto-indentation before you do this, since it sometimes will indent paragraphs in a weird way if you forget:

setlocal noautoindent
setlocal nocindent
setlocal nosmartindent
setlocal indentexpr=

Please note that hard-wrapping your text is mostly reversible. In most cases you can reset your file back to normal using two commands:

:set formatoptions=croql
:%norm vipJ

In case you are not fluent in Vim, the v i p key combo stands for “visual internal paragraph” – in other words, it selects current paragraph in visual mode. The J command “joins” lines. The command above simply runs this across the entire file, re-flowing every single paragraph.

This method is not perfect though, as sometimes short (one or two line) paragraphs get “swallowed” by their neighbors and I haven’t really figured out why that happens yet. It might actually be something unique to my setup.

Aesthetics

The other problem a lot of people have with Vim is that while it works well for code, it is not as aesthetically pleasing or fun to write in as some of the distraction free editors, or just about any plain text tool that was created for writing prose. I find this to be mostly a configuration issue. For example, when I write prose, my Vim looks more or less like this:

Vim in Prose Writing Mode

You note that it has wide margins on each side, the font size is slightly bigger than my code writing font and the line numbers are turned off because I find that I don’t actually need them as much. They tend to be incredibly useful when refactoring code or debugging but when writing prose I typically never actually need to edit more than the current line, and the lines directly above or below it.

How did I get the margins to work like that? Like this:

set foldcolumn=10
set columns=100

As you might remember, I set my textwidth to 80 characters and I have auto-wrapping on which means my text will never be wider than that. I set my window width to be exactly 100 columns which is how I get the right margin. The left margin is a little bit more tricky – to get it I’m abusing Vim’s folding engine by setting the foldcolumn value to 10 columns. This works well, because I don’t use any folds when I write prose and so I can abuse that feature to create margins to my heart’s content.

This is not necessarily as good as distraction-free full screen mode, but it works well enough for me.

To make switching to “prose” mode semi-automatic and easy, I wrapped all of the above into a function that toggles it on or off. As I’m still tweaking it and trying new things, I haven’t made it into a real stand-alone plugin yet (though that may happen at some point) but it is included along with my Vim files and accessible here.

Why not VimRoom?

I’m aware of VimRoom but it didn’t really work for me. For one, I find it a little bit invasive: it works by opening bunch of buffers, then hiding stuff by altering your color scheme. It doesn’t work nicely with vim-obviousmode and vim-neatstatus which I kinda like having around. Not to mention the fact that it doesn’t automatically detect and use your current color scheme. As you can probably see from my screenshots I use Solarized Light, and VimRoom defaults to a rather odd dark color scheme that is not even close to Solarized. Enablign it makes my editor window look weird – mostly black with patches of Solarized yellow and odd blotches of color where it attempts to hide stuff. To make it work you essentially have to feed it the solarized color-codes for just about everything by hand.

So I opted for something much simpler and much less finicky and prone to breaking all the time.

How About You?

This is how I solved the problem of writing prose in vim. How do you do it? How about Emacs users? Is your editor perfectly fit for writing blog posts and short stories out of the box, or do you need to tweak it a bit to work better? Share your tips and tricks in the comments. Maybe we can learn from each-other.