Configuring and Using GitHub Readme Instant Preview
Published: 2021-07-27 20:20:56

---
title: Configuring and Using GitHub Readme Instant Preview
published: true
date: 2021-07-27 00:00:00 UTC
tags: 
canonical_url: https://blog.hcf.dev//article/2021-07-27-grip
---

[GitHub](https://github.com/) will render project `README` and other markdown files to `HTML`when displaying projects on its website. Those files must be commited and pushed before the developer can see the results which can result in extraneous and unwanted commits. This post discusses installing and using the [GitHub Readme Instant Preview](https://github.com/joeyespo/grip) (GRIP) tool for previewing[GitHub-flavored Markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) locally.  It provides a GRIP-specific configuration file to enable authentication to GitHub to prevent the developer from bumping up against GitHub’s[throttles](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)for unauthenticated users.

## Installation

The [GRIP](https://github.com/joeyespo/grip) tool is available for installation from many popular package managers. To install on MacOS with Home Brew:

```
$ brew install grip

```

Or on Debian:

```
$ apt install grip

```

To name a few.

## Usage

Usage is straightforward: Change the working directory to the project directory containing the `README.md` or other markdown and invoke `grip`.

```
$ grip
 * Serving Flask app "grip.app" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://localhost:6419/ (Press CTRL+C to quit)

```

And browse to [http://localhost:6419/](http://localhost:6419/) (or the URL specified in the output). The output of [GRIP](https://github.com/joeyespo/grip) run in the local project is shown below for comparison to [https://github.com/allen-ball/spring-boot-web-server](https://github.com/allen-ball/spring-boot-web-server).

![](https://blog.hcf.dev/assets/article/2021-07-27-grip/screenshot-1.png)

As configured (albeit, without configuration), [GRIP](https://github.com/joeyespo/grip) will invoke the[GitHub](https://github.com/) API without authentication. GitHub will limit unauthenticated requests to as little as 60 per hour which could impact intensive read/review cycles (especially if the developer is sumltaneously using other GitHub resources in an unauthenticated manner). The next section discusses configuring authentication.

## Authentication

[GRIP](https://github.com/joeyespo/grip) invokes the `${HOME}/.grip/settings.py` script (if it exists) to determine the `USERNAME` and `PASSWORD` to use for authentication. The script below offers a more secure option than simply assigning those raw values in the script.

[GitHub](https://github.com/) currently recommends (and sometimes requires) the developer[create a personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)and also provides a process for[caching GitHub credentials in Git](https://docs.github.com/en/get-started/getting-started-with-git/caching-your-github-credentials-in-git)(for Mac, Windows, and Linux). After completing these two procedures, the developer’s credentials are available for GitHub `https` operations through the `git credential fill` command. The `${HOME}/.grip/settings.py` script below (and available as this[Gist](https://gist.github.com/allen-ball/fdc974e6e24e391ddcfad3d61b9a5230)) retrieves the cached credentials for [GRIP](https://github.com/joeyespo/grip).

```
# settings.py
# https://github.com/joeyespo/grip

# Uses "git credential fill" to populate USERNAME and PASSWORD

def git_credential_fill():
    import subprocess
    argv = ["git", "credential", "fill"]
    process = subprocess.Popen(argv, text = True, stdin = subprocess.PIPE, stdout = subprocess.PIPE, stderr = subprocess.PIPE)
    output = process.communicate(input = "protocol=https\nhost=github.com\n")[0].strip()
    map = dict(item.split("=") for item in output.splitlines())

    return (map["username"], map["password"])

(USERNAME, PASSWORD) = git_credential_fill()

```

Notice [GRIP](https://github.com/joeyespo/grip) prints `Using credentials` message when configured.

```
$ grip
 * Using credentials: allen-ball
 * Serving Flask app "grip.app" (lazy loading)
 * Environment: production
...

```