Vim for Code

I use vim to write code every day. There’s an established and sensible convention that lines of code should be no more than 80 characters wide. Many people adhere to this convention, and I particularly like it because I can have vim vertically-split on my monitor and see two full-width files right next to one another. This is particularly helpful when working on a spec and its implementation.

Vim for Prose

But what about using vim to write prose? Lately, I’ve been writing some documentation for a feature I’m developing. The documentation is written in Markdown, processed by Jekyll, and in a git repository. With vim’s support of Markdown syntax highlighting, it makes sense to use it as an editor for this documentation.

(You can try vim’s Markdown syntax highlighting with :set filetype=markdown. I’m using MacVim and tried this on a hunch. I was surprised to find it actually worked!)

Code vs Documentation

One main difference between code and documentation though, is that documentation is written sentence by sentence, paragraph by paragraph, where code is generally written line by line, block by block. Normally, I navigate source code with hjkl. In fact, I have my arrow keys disabled. Vim also wraps long lines by inserting soft breaks so I can see all the text on the screen, even if it’s wider than the window.

Navigating

j and k

But these soft breaks don’t work when navigating with j and k. j and k both work on the hard line, which may be several soft lines. Particularly if you’re writing a paragraph that is all one hard line. Today, I’ve come across two options for solving this issue.

gj and gk

The first option: using gj and gk will move you up and down a line, respectively, while completely respecting soft lines. That’s awesome!

It’s nice because it just works, nothing to add to the .vimrc. The disadvantage here is that it’s now double the number of keys to simply navigate. But at least it’s possible!

textwidth

The second option: setting textwidth in the .vimrc.

I already had this chunk of code in my .vimrc, but I tweaked it to add markdown.

if has("autocmd")
  " For all text files set 'textwidth' to 78 characters.
  autocmd FileType text,markdown setlocal textwidth=78
endif " has("autocmd")

This forces all lines to break on whitespace so they are no more than 78 characters wide. This actually works as you’re typing, so you don’t have to manually do it. This is nice because it allows you to use j and k normally because the paragraph you end up typing is made up of hard lines. The downside is that going back and editing a paragraph can be annoying, since it doesn't always seem to reformat things as one might expect. The hard lines become apparent.

Update: Once you go back and edit the paragraph, the formatting might get out of wack. You can use gq{motion} to do format the text to match textwidth again. gq} will format the entire paragraph forward. gggqG will take you to the top and format the entire document. (Thanks @jasonkarns for the tip!)

Conclusion

I came across these two options earlier when looking into how to use vim for writing markdown. Hopefully they help you get a bit more out of vim. I’m hoping I’ll discover some better ways to use vim for prose as I go along. When I do, I’ll be sure to share. Let me know if you’ve got some tricks that would help here. Thanks for taking the time to read!