If you work in tech, chances are that you’ve had to write some Markdown documents, and it is also reasonably likely that you’ve had to upload those Markdown documents to Github.

Github (and other git-hosting sites) provide quite a decent in-browser Markdown editor, but for anything other than the smallest of changes, it can be quicker to use your day-to-day code editor.

If you use vim, you might be wondering how you can preview the Markdown you’re writing to see exactly what it will look like once you’ve committed and pushed to Github.

Thankfully, Github exposes its Markdown rendering as an API…

…and there’s a vim plugin - vim-markdown-preview - that wraps the Github Markdown API* and allows you to preview your Markdown files in Github Flavored Markdown (GFM) right in your browser.

Installing requirements

Instead of interacting with the Github Markdown API directly, vim-markdown-preview uses grip to do the heavy lifting. To install grip, you can use pip:

$ pip install grip

or brew:

$ brew install grip

Since grip requires access to a Github API, it is subject to Gitub’s API request limits. Although it should be possible to use the API without authentication, you can quickly come up against the hourly rate limit if you are doing a lot of Markdown updates. To unlock a much higher rate limit, you can provide grip with authentication details for your Github account, by adding the following lines to ~/.grip/settings.py:

USERNAME = 'your-username'
PASSWORD = 'your-personal-access-token'

(You can generate a Github personal access token by visiting https://github.com/settings/tokens)

For more details on authenticating with Github in grip (and other grip) settings, see the project’s README.md.

Setting up vim-markdown-preview

Add the vim-markdown-preview plugin to your vim plugin manager. I use Vundle, so I’ve added the following to my .vimrc:

Plugin 'JamshedVesuna/vim-markdown-preview'

I also override some default settings to make it integrate better with my current setup:

# Change the default shortcut for triggering the preview
let vim_markdown_preview_hotkey='<leader>m'

# Change the browser used for the preview to Google Chrome
# (the default is Safari on OSX)
let vim_markdown_preview_browser='Google Chrome'

# Use grip and the Github Markdown API for rendering the preview
let vim_markdown_preview_github=1

Final result

To get a bit meta, here is this post, rendered using vim-markdown-preview:

* rather, vim-markdown-preview wraps grip, which wraps the Github Markdown API