Grip is a live markdown document renderer and server, it’s like how ‘npm start’ runs a development server for React but grip runs a development server for GitHub markdown.
If you have a grip server running, you can view your .md files in a repository in all their rendered glory (including working links, headers, and images), this is good for two reasons: i) it encourages you to write documentation, ii) it makes your documentation immediately avaiable to you.
Basically you need to run grip and pass a directory, the best way to do this is to cd into a repository root directory and run grip ..
This of course assumes you have grip installed. Grip is a python package so pip install grip is all you need. You can either install grip into any virtual environment that requires it, or you can install grip to one particular virtual environment and always use that version.
Example of having one grip per repository
Example of having one grip that all projects use.
# Make a 'base' virtual env in its own directory, and have it install grip
cd ~
mkdir ~/virtualenv
cd ~/virtualenv
python -m venv base
~/virtualenv/base/bin/pip install grip
# Go to your project root directory and run 'grip' from the 'base' virtual environment.
cd ~/projects/myproject
~/virtualenv/base/bin/grip .Grip actually uses GitHub’s API hosted for by its servers, so if you use it a lot you quickly hit a rate limit. To avoid this you just need to tell grip your GitHub details.
To do this you make a file called ~/.grip/settings.py
Mine looks like this.
You will of course have to use your own password value, to find the value you should use, go to GitHub.com > settings > Developer settings > Personal access tokens > generate new token. Ignore all the options, and just give it a good name like “grip”. You’ll then see your token password. Copy/paste it to the PASSWORD value in ~/.grip/settings.py.
You’re done.
I recommend adding a bookmark on your browser called “grip localhost” that points to the URL http://localhost:6419/, then you don’t have to remember port 6419 and can just type “grip” into your browser.
Please send questions or comments to andrew@aomartin.co.uk.