writing vim

An awesome-ish list of vim for writers. Geared towards beginners, but hopefully useful for others too.

Items with 👍 are recommended.

Items with 👀 are new (in latest commit)

1. why
2. getting started
3. writing with vim
4. a note on markup languages
5. plugins for writing
6. colorschemes
7. general vim resources
8. other resources
9. contributing

why

So... why use a text editor for writing over a word processor like Microsoft Word, Apple Pages or Google Docs?

There are many reasons, but the most important/obvious are:

• The separation of text and styling and the productivity boost that comes with that—essentially they force you to focus on the text instead of faffing about with fonts and headings.
• They use an open, non-proprietary, plain text file format, meaning you can rely on your files being usable fifty years from now.
• Text editors are faster, lighter, and appear less prone to bugs and/or crashes.

You could say the same thing about Notepad, why use vim?

Yes, and if you want to use Notepad or TextEdit or the like, you should. Whatever is most comfortable for you. In the case of vim, the positives of plain text files also apply to the editor itself. It’s reliable, tested, lightweight and cross platform—it’s available across all operating systems including iOS and Android—and your can use the same config across all your devices. More than that though is the powerful and unrivalled editing language (described in detail in some of the links below) that strives to increase editing effects. Add to that the deep customisability and you can shape vim into a productive and personal tool.

The elephant in the room is Vim’s steep learning curve. And yeah there is no getting around that. However, for the purpose of prose that curve is steep but not high, a two or three runs through vimtutor, the first step on the vim highway, and reading some of the links in general vim, is enough to start. Anyway, I recommend at least reading both Coming home to vim and Everyone Who Tried to Convince Me to use Vim was Wrong before deciding in vim is for you.

getting started

The below links show vim can be a powerful and flexible editor of prose, with near endless configuration options. Perhaps too many options. But you don’t need to learn it all at once, especially if your focus is writing prose. Here’s a some simple steps to get started:

Install the GUI version. Either gVim or MacVim. Vim has different shortcuts to other editors, you’ll want the menus as backup when starting out.

Bookmark a quality cheat-sheet and the official documentation. You can access the docs with :h <topic> but I find the online copy is easier to browse. Check the links below.

As we have seen, one of the main benefits of vim is its configurability. However, for prose, there’s only a few settings you need. For convenience you download a super minimal vimrc here:

minimal vimrc for writing

This will set up backspacing and word wrapping to work as you would expect in traditional editors.

ALSO use the mouse if you want!

writing with vim

Here is collection of links on using vim for prose. The criteria for this section is that I think the link is interesting (with the usual disclaimer that I do not necessarily endorse the opinions expressed or their authors).

• 3 shell scripts: Kill weasel words, avoid the passive, eliminate duplicates - Matt Might 👀
• Configuring Vim as a Writing Tool - Its FOSS
• English Words Completion inside Neovim/Vim - jdhao
• How I'm writing my book using Vim, Git and Ruby - Chris Parsons
• Real-time LaTeX using Vim/Neovim, VimTeX, and snippets - ejmastnak
• The Woodnotes Guide to Vim for Writers
• Using Vim for writing Prose - terminally incoherent
• Vim for Writers - NaperWriMo Wiki
• Vim for Writing - Vivek
• WRITING PROSE IN VIM - ultralight
• Writing Markdown in Vim - David Winterbottom
• Writing a Book with Pandoc, Make, and Vim - Vladimir Keleshev
• Writing with Vim - Jamie Todd Rubin
• Writing, Editing and World-Building at the speed of thought with Vim - Theena Kumaragurunathan
• You (probably) don’t need Vimwiki - Joe Reynolds
• take notes using LaTeX and Vim - Gilles Castel
• using vim to write prose - n3wjack
• writing prose in vim - Jonathan Hodgson

a note on markup languages

While not essential, when writing in plain text you may want to markup your er... text to indicate emphasis and the like. You’ve heard of Markdown but there’s a number of light markup languages to choose from:

• AsciiDoc is both older and a bit more complex than Markdown. It does have some nice features of its own.
• Commonmark. There are so many flavours of Markdown. To avoid confusion I suggest just using this.
• Djot is a new attempt at refining Markdown.
• Fountain is a markup language for writing screenplays.
• LaTex is the grandma of markup languages. Big and intimidating. Used in academia. A little beyond the scope for us.
• Typst Typst is a new markup-based typesetting system that is designed to be “as powerful as LaTeX while being much easier to learn and use”
• txt2tags super minimal markup language
• reStructuredText perhaps markdown’s main rival

plugins for writing

Vanilla Vim is more than capable. However, you may want to customise it to make it fit better into your workflow. Check the documentation for options you may want to enable, and then check out Vim’s vast plugin ecosystem. This second step is optional.

For information on installing plugins see this video

• abolish. Fancy find and replace 👍
• ditto. Stop repeating yourself.
• fountain4vim is a modern plugin for working with Fountain
• goyo. Distraction-free writing in Vim. Also limelight by the same author
• gundo. Visual undo tree
• litecorrect is a small autocorrect plugin for the ~400 most common typos
• nrrwrgn. Focus on small region of text
• org.vim. Org mode syntax highlighting and folding for Vim
• targets.vim. Vim plugin that provides additional text objects
• vim-exchange. Swap words when they’re in the order wrong. Vimcasts has a tutorial 👍
• vim-fountain
• vim-lengthy. Colorize sentences by word count
• vim-lexical. Build on Vim’s spell/thes/dict completion
• vim-markdown-toc. An easy way to generate a table of contents for your markdown file
• vim-online-thesaurus. Thesaurus look up
• vim-pandoc. Pandoc integration and utilities for vim
• vim-pencil. Rethinking Vim as a tool for writing
• vim-textobj-quote. Use ‘curly’ quote characters in Vim
• vim-textobj-sentence. Improving on Vim's native sentence text object and motion
• vim-wordchipper. Power tool for shredding text in Insert mode
• vim-wordy. Uncover usage problems in your writing
• vimtex. A modern Vim and neovim filetype plugin for LaTeX files
• vimwiki. Personal Wiki for Vim
• visual-split.vim. Vim plugin to control splits with visual selections or text objects
• writegood. Highlight ‘weasel words’ etc
• focus.vim Make a split temporarily full screen 👀

colorschemes

There are thousands of colorschemes available for vim, but there are surprisingly few decent ones for light mode (which I find better for writing). Here are some good light themes:

• Lucius
• Pencil
• Solarized8
• Paramount
• Paige 👀
• Bruin 👀
• vim-no-color-collection Collection of Vim themes with barely any colors 👀

general vim resources

• A Vim Cheatsheet
• And another one
• Idiomatic Vimrc: Advice on writing your own config - romainl
• Learn Vimscript the Hard Way - Steve Losh 👍
• Let Vim do the typing
• My vim config. You shouldn’t copy it. Check out the above instead.
• Practical Vim - Drew Neil 👍
• Recommendations from #vim
• Seven habits of effective text editing - Bram Moolenaar
• The Documentation
• Vimcasts - Drew Neil 👍
• vim galore/

other resources

The if you liked that you'll like this section:

• Using Git Version Control as a Writer
• Write plain text files
• Vale: enforcing style guidelines for text

contributing

Suggestions are welcome! Please create an issue.