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.

Installation

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

Homebrew

$ brew install grip

You can skip to the Usage section now.

Python

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

  1. List your virtualenvs

    $ lsvirtualenv
    myenv
    ====
    bar
    ====
  2. Activate one environment

    $ workon myenv
    (myenv) $
  3. Install grip

    (myenv) $ pip install grip

Usage

To render the readme of a repository:

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

To render a specific markdown file:

$ grip CONTRIBUTE.md
 * 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

Logo

I'm Carlos Roso. I'm a Software Engineer and digital nomad at Toptal. Previously Software Architect at 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.