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.


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

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.

This entry was posted in programming and tagged . Bookmark the permalink.

9 Responses to Using Vim for writing Prose

  1. J. Alan Atherton UNITED STATES Google Chrome Linux says:

    As a graduate student, I use LaTeX for writing “prose”. To separate paragraphs, you must have a blank line between them, and it doesn’t matter how you organize your sentences. Because I also use vim, I just put each sentence on its own line. This makes it dead simple to change the order of sentences in a paragraph.

    Reply  |  Quote
  2. The main problem with writing prose (besides the talent for,) is a typography. One has two options for making the result perfect: either to remember all the rules and apply them as she’s typing or to use the proper formatting tool which is none but TeX.
    Hard wrap brings a lot of problems during hardly stropping the text. The ability of dd-ing (and operating in general) lines of code looks very important to me because the line of code is an entity. The hard-wrapped piece of plain text is not, though. What’s to force me to want to cut several random words, having actually neither a clear begin nor an end? Who the hell needs to delete a part of the sentense above, starting right after a definite article and containing 80-or-a-bit-less symbols?
    Writing a prose is likely a process which let’s me to concentrate on it for a long time; I do not need to switch a context often, so I may to give an editor window it’s own personal desktop. That’s why I personally prefer to resize a window so that it has ≈80-letters width and use the old good not-wrapping environment in my Vim.

    Reply  |  Quote
  3. Luke Maciak UNITED STATES Google Chrome Linux Terminalist says:

    @ J. Alan Atherton:

    Wow, the one sentence per line is actually a very good tip. d d p to swap sentences is indeed quicker and easier to remember than d a s ) p. TIL :)

    @ Alexei Matyushkin:

    Very good points. That said “sentences” are valid vim text objects and it recognizes them and can operate on them in hard wrapped mode just as easily as in soft wrapped. The semantics of, say deleting current sentence are the same: d i s (delete inner sentence). It doesn’t stop at the end of the line but continues till a full stop followed by a space is encountered in text.

    But yeah, I can see what you are saying about lines of code being logical entities whereas lines in “prose” are typically jumbles of incomplete sentence fragments. I think Alan’s suggestion of using soft wrap and keeping one sentence per vim line is a good compromise between the two “problematic” extremes. :)

    Reply  |  Quote
  4. @ Luke Maciak:
    Everybody finds the best way for her, but Leo Tolstoy would never use the “one-sentence-per-vim-line” idiom.
    Just kidding.

    Reply  |  Quote
  5. Maxime Safari Mac OS says:

    I’ve been trying a lot of things to have Vim center prose when I write in fullscreen. Using foldcolumn is absolutely brilliant. I’ve set it to 12 because you can’t go higher (and it happens to look nice), and then I’ve subtracted that twice from 116, which is my total number of columns when in fullscreen, which gave me a textwidth of 92. Put simply I now have 12+92+12 when in fullscreen. And I now finally have a distraction-free code/prose editor with all Vim shortcuts (and not the incomplete emulation you get in Sublime Text)! Thank you so much! And the rest of the article was very helpful, too!

    Reply  |  Quote
  6. Scott UNITED STATES Mozilla Firefox Linux says:

    I find it easier to keep paragraphs on one line and use screen wrapping. This works for more use cases, such as blog posts, blog comments, and for reading into a word processor document. These environments treat hard returns as either line breaks or paragraph breaks. Unfortunately, to distinguish paragraphs within plain text editors, you must have two hard returns. Vim makes dealing with this very easy: :%s/\n\n/\n/ replaces all doubled new lines with one. Run this command just before copying into a word processor and paragraphs will have no extra breaks between them.

    Vim has the gj and gk commands for navigating by screen lines, and these can be mapped to j and k respectively with: noremap j gj and noremap k gk. They are just as effective with screen wrapping turned off. Navigating by paragraph still works with { and } and by sentence with ( and ). Deleting, changing, and yanking iw (inner word), is (inner sentence), and ip (inner paragraph) or their aw, as, and ap (around) counterparts also still work as expected.

    It may not be as pretty as some distraction-free environments, but more than makes up for it with superior editing features.

    Reply  |  Quote
  7. Pingback: the Norman Crane UNITED STATES PHP

  8. Leon UNITED STATES Google Chrome Windows says:

    Hey Luke,

    This is self-promotional, but my big scripting project for vim has just reached a mostly mature state. It is a pannable, zoomable ‘infinite plane’ for organizing massive amounts prose called “textabyss”. Check it out at:



    Reply  |  Quote
  9. emacsowiec POLAND Google Chrome Windows says:

    uzywalem dlugo Emacsa, ale mnie wkurzył z kilkoma rzeczami.

    Od około tygodnia używam ViMa.
    Kilka refleksji, takich początkowych:

    1. ViM script jest znacznie prostszy od Emacs Lispa, ale przez to również trochę bardziej ograniczony
    2. ViM wydaje mi się jednak prostszy od Emacsa, ogólnie jako całość
    3. Po tygodniu niregularnej nauki *.vim uczę się pisać funkcje, a mój vimrc ma już 225 linijek kodu, a ledwo zacząłem w się w to bawić, mógłbym już sporo pluginów całkowicie zmienić
    4. najprawdopodobniej przerzucę się na Emacsa, ale za jakieś 2-3 lata, muszę się lepiej wyrobić w programowaniu (Lisp jest trudny), narazie zostaję przy ViM
    5. Wiele rzeczy w ViM jest od razu dostępnych, nie musialem grzebać tak głęboko w Googlach jak w przypadku Emacsa
    6. Nie ma się co oszukiwać, Emacs momentami jest znacznie potęzniejszym edytorem. np: –>tego mi najbardziej brakuje w VIM i chyba napiszę skrypt który to poprawi, bo aktualnie jest tragedia

    w VIM znalazłem rzeczy których nie znalazłem w Emacs. Emacs ma strasznie rozbudowanych kilka pluginów, których nie ma ViM.
    Ja zostaję narazie przy ViM, bo Emacs jest zbyt trudny, ale za kilka lat jak się wyrobie z funkcjami i logiką informatyczną to raczej wrócę do Lispa.

    Reply  |  Quote

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>