Vim Setup for Markdown

I’ve been struggling with the Vim setup I use to write for a while now. For a geek, I have a pretty standard work flow. iTerm is my terminal emulator. Inside that I run tmux. Inside that I run vim. I write my text in Markdown and commit my work to a Git repository. For ages I’ve been using my regular coding setup with a few hacks to the ftplugin for Markdown. It worked but it didn’t work well. I’ve since decided that it’s time to set about fixing it.

How my coding environment looks

I had what felt like a fairly simple ambition. I wanted a distraction-free writing environment within Vim. Discovering how to reach my ambition was rather more complicated and annoying than I anticipated. The trouble I kept running into was I that most of the plugins to clean up the Vim interface for writing prose didn’t work well within the console Vim and MacVim didn’t work very well with my Git tools.

Eventually after much experimentation I found a working combination of plugins that works how I hoped.

What my editor looks like right now


Goyo is the plugin I’m using for full-screen writing. It is based off the idea of WriteRoom. If you are unfamiliar, the intention is to create an environment void of all visual distractions to help you remain focused on what you are writing.

Goyo works perfectly at the console and should also work perfectly in a GUI (though I haven’t tested). After trying out lots of WriteRoom-like plugins, I liked this one the most.


This plugin gives you syntax highlights and folding for Markdown files.

By using ftdetect you can create auto commands for setting the correct filetype based on a files extension.

As my markdown files rarely have the .mkd extension, I needed to configure .md and .markdown extensions to use the filetype of .mkd.

The trick is to throw these couple of lines into your ~/.vim/ftdetect/mkd.vim file.

au! BufRead,BufNewFile *.markdown set filetype=mkd
au! BufRead,BufNewFile *.md       set filetype=mkd


I’m pretty new to writing so I took a look up at the patterns and styles that other authors use; specifically writers who commit their changes to a Git repository. I couldn’t work out whether soft (one paragraph per line) or hard (less than 80 characters per line) wrapping was better. The Pro Git Book use soft wrapping so without a strong opinion of my own, I decided to follow their example.

After using soft-wrapping for all of a couple of minutes, I realised that the up and down movement key bindings were pretty unintuitive. The ‘j’ and ‘k’ movements were jumping all over the place. I could fix it up by re-mapping ‘j’ to ‘gj’ and ‘k’ to gk’ but vim-pencil does all that and probably more for you.

:PencilSoft is the command to enable pencil for soft-wrapping.


vim-surround is a tool that helps you wrap words and sentences up in quotes or brackets or tags. It’s a super cool plugin but I still really need to put it into practice more. I’m including it in this document because we should use it even if I don’t.


I wrote little plugin called MacDict.vim that would allow me to search the OSX system dictionary from within Vim.

I usually keep the system dictionary open on my second screen. If I press F11 then the definition for the word under my cursor is brought up in the dictionary and cursor focus is given back to Vim.


My mkd ftplugin file has these settings.

setlocal autoindent
setlocal colorcolumn=0
setlocal linebreak
setlocal nonumber
setlocal shiftwidth=4
setlocal spell
setlocal tabstop=4
setlocal wrap


I use a Curses Git client called Tig which allows me to quickly make commits from within Vim. It does fork a process but it’s pretty seamless.

function! s:tig_status()
  cd `driller --scm-root %`
  !tig status

map <C-G> :TigStatus<CR><CR>
command! TigStatus call s:tig_status()

Driller is a tool I wrote a while ago. One of it’s features is to find the root directory of a repository. I’m using it to change into the root of the Git repository before starting Tig. For some reason Tig struggles to find all the uncommitted files unless you are in the root.

I also use GitGutter to present which lines of the open file have been modified. This needed to be enabled again after Goyo has been turned on.

map <F12> :Goyo<CR>:GitGutterEnable<CR>


I created a new profile for writing that has a nice large font. I open the profile in a new iterm tab. Everything is set to full screen and I’m good to go.

Jekyll Integration.

Part of the vim-markdown syntax file is the ability to style your initial Jekyll document settings in YAML instead of markdown. By default the syntax highlighter treats that a bit funky. That can be fixed up by dropping this into your ~/.vim/ftplugin/mkd.vim

let g:vim_markdown_frontmatter=1

Better Error Detection

I don’t have it yet but I think it would be nice to highlight accidental double-spaces.

A New Way To Move

Most of my writing in the past has been in the form of code. As such, I’d not really been constantly hurt from not knowing some of the mappings that are especially useful when writing in sentences.

Usually I’d jump to line numbers or search for something unique, (or relatively unique) like a method name or variable. That doesn’t really translate to this form of writing. Movement was something I quickly became better at.

  • Use ‘{‘ and ‘}’ to jump between paragraphs.
  • Use ‘[s’ and ‘]s’ to jump between typos.


As of today, I’ve been using this setup for, err, about 9 months. I started writing this in December last year but never got around to finishing the post. But I guess the added testing makes the conclusion far more accurate.

As I’m still using this setup with very minor changes (if any) I think that I’ve achieved what I set out to do. I’ve got a distraction free writing environment that I’m actually using and enjoying.

If you are interested, you can grab my Vim config files out of GitHub.