You too can ace that coding interview
Get my guide for free
April 15, 2020

How to preview a README with GitHub styles

Use Python to preview markdowns as rendered in GitHub

After trying a lot of tools there’s only one that have worked flawlessly for me. It’s a Python module called grip.


You can either install it using Homebrew (recommended) or Python.


$ brew install grip

You can skip to the Usage section now.


I normally recommend using virtualenvs to install anything in Python. Install that along with virtualenvwrapper.

  1. List your virtualenvs
$ lsvirtualenv
  1. Activate one environment
$ workon myenv
(myenv) $
  1. Install grip
(myenv) $ pip install grip


To render the readme of a repository:

$ cd my-repo
$ grip
 * Running on http://localhost:6419/

To render a specific markdown file:

$ grip
 * Running on http://localhost:6419/

Open your browser at http://localhost:6419. Profit.

screenshot for reminders github readme

API Limits

Grip uses the Github API directly to render the markdown files. This is fine until you hit the 60 API requests / min limit. From there, you can use basic auth to increase the limit to 5000 requests / min:

$ grip --user johndoe --pass foobarbaz

Or, you can just use the VSCode markdown previewer for a while until you get access to Github again. Click on the top-right icon with the glass to preview the markdown.

Preview button in VSCode

And this how it looks like:

VSCode preview


I'm Carlos Roso. I'm a Software Engineer at Meta. Former SDE at Amazon. Ex digital nomad at Toptal and Crossover. In love with open source and design.

More about me
Join the newsletter

I write about remote work, software and personal growth. Subscribe to enjoy my articles every once in a while.