Grip -- GitHub Readme Instant Preview

[ Current version on PyPI ][pypi]

Render local readme files before sending off to GitHub.

Grip is a command-line server application written in Python that uses the [GitHub markdown API][markdown] to render a local readme file. The styles and rendering come directly from GitHub, so you'll know exactly how it will appear. Changes you make to the Readme will be instantly reflected in the browser without requiring a page refresh.

Motivation

Sometimes you just want to see the exact readme result before committing and pushing to GitHub.

Especially when doing [Readme-driven development][rdd].

Installation

To install grip, simply:

$ pip install grip

On OS X, you can also install with Homebrew:

$ brew install grip

Usage

To render the readme of a repository:

$ cd myrepo
$ grip
 * Running on http://localhost:6419/

Now open a browser and visit http://localhost:6419. Or run with -b and Grip will open a new browser tab for you.

You can also specify a port:

$ grip 80
 * Running on http://localhost:80/

Or an explicit file:

$ grip AUTHORS.md
 * Running on http://localhost:6419/

Alternatively, you could just run grip and visit [localhost:6419/AUTHORS.md][AUTHORS.md] since grip supports relative URLs.

You can combine the previous examples. Or specify a hostname instead of a port. Or provide both.

$ grip AUTHORS.md 80
 * Running on http://localhost:80/

$ grip CHANGES.md 0.0.0.0
 * Running on http://0.0.0.0:6419/

$ grip . 0.0.0.0:80
 * Running on http://0.0.0.0:80/

You can even bypass the server and export to a single HTML file, with all the styles and assets inlined:

$ grip --export
Exporting to README.html

Control the output name with the second argument:

$ grip README.md --export index.html
Exporting to index.html

If you're exporting a bunch of files, you can prevent styles from being inlining to save space with --no-inline:

$ grip README.md --export --no-inline introduction.html
Exporting to introduction.html

Reading and writing from stdin and stdout is also supported, allowing you to use Grip with other programs:

$ cat README.md | grip -
 * Running on http://localhost:6419/

$ grip AUTHORS.md --export - | bcat

$ cat README.md | grip --export - | less

This allows you to quickly test how things look by entering Markdown directly in your terminal:

$ grip -
Hello **world**!
^D
 * Running on http://localhost:6419/

Note: ^D means Ctrl+D, which works on Linux and OS X. On Windows you'll have to use Ctrl+Z.

Rendering as user-content like comments and issues is also supported, with an optional repository context for linking to issues:

$ grip --user-content --context=joeyespo/grip
 * Running on http://localhost:6419/

For more details and additional options, see the help:

$ grip -h

Access

Grip strives to be as close to GitHub as possible. To accomplish this, grip uses [GitHub's Markdown API][markdown] so that changes to their rendering engine are reflected immediately without requiring you to upgrade grip. However, because of this you may hit the API's hourly rate limit. If this happens, grip offers a way to access the API using your credentials to unlock a much higher rate limit.

$ grip --user <your-username> --pass <your-password>

Or use a [personal access token][] with an empty scope (note that a token is required if your GitHub account is set up with two-factor authentication):

$ grip --pass <token>

You can persist these options in your local configuration. For security purposes, it's highly recommended that you use an access token over a password. (You could also keep your password safe by configuring Grip to [grab your password from a password manager][keychain-access].)

There's also a [work-in-progress branch][offline-renderer] to provide offline rendering. Once this resembles GitHub more precisely, it'll be exposed in the CLI, and will ultimately be used as a seamless fallback engine for when the API can't be accessed.

Grip always accesses GitHub over HTTPS, so your README and credentials are protected.

Tips

Here's how others from the community are using Grip.

Want to share your own? [Say hello @joeyespo][twitter] or submit a pull request.

Create a local mirror of a Github Wiki

$ git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.wiki.git
$ cd YOUR_REPOSITORY.wiki
$ grip

By Joshua Gourneau.

Generate HTML documentation from a collection of linked README files

Enter the directory:
```
$ cd YOUR_DIR
$ export GRIPURL=$(pwd)
```

Include all assets by setting the CACHE_DIRECTORY config variable:

$ echo "CACHE_DIRECTORY = '$(pwd)/assets'" >> ~/.grip/settings.py

Export all your Markdown files with Grip and replace absolute asset paths with relative paths:

$ for f in *.md; do grip --export $f --no-inline; done
$ for f in *.html; do sed -i '' "s?$GRIPURL/??g" $f; done

You can optionally compress the set of HTML files to docs.tgz with:

$ tar -czvf docs.tgz `ls | grep [\.]html$` assets

Looking for a cross platform solution? Here's an equivalent Python script.

By Matthew R. Tanudjaja.

Configuration

To customize Grip, create ~/.grip/settings.py, then add one or more of the following variables:

HOST: The host to use when not provided as a CLI argument, localhost by default
PORT: The port to use when not provided as a CLI argument, 6419 by default
DEBUG: Whether to use Flask's debugger when an error happens, False by default
DEBUG_GRIP: Prints extended information when an error happens, False by default
API_URL: Base URL for the github API, for example that of a Github Enterprise instance. https://api.github.com by default
CACHE_DIRECTORY: The directory, relative to ~/.grip, to place cached assets (this gets run through the following filter: CACHE_DIRECTORY.format(version=__version__)), 'cache-{version}' by default
AUTOREFRESH: Whether to automatically refresh the Readme content when the file changes, True by default
QUIET: Do not print extended information, False by default
STYLE_URLS: Additional URLs that will be added to the rendered page, [] by default
USERNAME: The username to use when not provided as a CLI argument, None by default
PASSWORD: The password or [personal access token][] to use when not provided as a CLI argument (Please don't save your passwords here. Instead, use an access token or drop in this code [grab your password from a password manager][keychain-access]), None by default

Note that this is a Python file. If you see 'X' is not defined errors, you may have overlooked some quotes. For example:

USERNAME = 'your-username'
PASSWORD = 'your-personal-access-token'

Environment variables

GRIPHOME: Specify an alternative settings.py location, ~/.grip by default
GRIPURL: The URL of the Grip server, /__/grip by default

Advanced

This file is a normal Python script, so you can add more advanced configuration.

For example, to read a setting from the environment and provide a default value when it's not set:

PORT = os.environ.get('GRIP_PORT', 8080)

API

You can access the API directly with Python, using it in your own projects:

from grip import serve

serve(port=8080)
 * Running on http://localhost:8080/

Run main directly:

from grip import main

main(argv=['-b', '8080'])
 * Running on http://localhost:8080/

Or access the underlying Flask application for even more flexibility:

from grip import create_app

grip_app = create_app(user_content=True)
# Use in your own app

Documentation

serve

Runs a local server and renders the Readme file located at path when visited in the browser.

serve(path=None, host=None, port=None, user_content=False, context=None, username=None, password=None, render_offline=False, render_wide=False, render_inline=False, api_url=None, title=None, autorefresh=True, browser=False, grip_class=None)

path: The filename to render, or the directory containing your Readme file, defaulting to the current working directory
host: The host to listen on, defaulting to the HOST configuration variable
port: The port to listen on, defaulting to the PORT configuration variable
user_content: Whether to render a document as [user-content][] like user comments or issues
context: The project context to use when user_content is true, which takes the form of username/project
username: The user to authenticate with GitHub to extend the API limit
password: The password to authenticate with GitHub to extend the API limit
render_offline: Whether to render locally using [Python-Markdown][] (Note: this is a work in progress)
render_wide: Whether to render a wide page, False by default (this has no effect when used with user_content)
render_inline: Whether to inline the styles within the HTML file
api_url: A different base URL for the github API, for example that of a Github Enterprise instance. The default is the public API https://ap

Grip

Install / Use

README