Configuring and Using GitHub Readme Instant Preview

Jul 27, 2021

GitHub 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 (GRIP) tool for previewing 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 for unauthenticated users.

Installation

The 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/ (or the URL specified in the output). The output of GRIP run in the local project is shown below for comparison to https://github.com/allen-ball/spring-boot-web-server.

As configured (albeit, without configuration), GRIP will invoke the GitHub 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 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 currently recommends (and sometimes requires) the developer create a personal access token and also provides a process for caching 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) retrieves the cached credentials for 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 prints Using credentials message when configured.

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