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:
Or on Debian:
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
.
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.
Notice GRIP prints Using credentials
message when configured.