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 previewingGitHub-flavored Markdown locally. It provides a GRIP-specific configuration file to enable authentication to GitHub to prevent the developer from bumping up against GitHub’sthrottlesfor 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 theGitHub 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 developercreate a personal access tokenand also provides a process forcaching 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 thisGist) 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
...
Top comments (0)