Grip

Python command-line server that renders local Markdown readme files through the GitHub Markdown API, with live refresh and HTML export.

install

Grip is a command-line server written in Python that renders a local readme or other Markdown file using the GitHub Markdown API. It uses GitHub rendering and styles to preview the file before pushing. Running grip in a repository starts a server on http://localhost:6419/, and the browser view updates when the file changes, without a manual refresh. The -b flag opens a browser tab automatically.

The CLI accepts a file, a port, a host, or combinations of these (e.g. grip AUTHORS.md 80, grip . 0.0.0.0:80). Relative URLs are supported, so other files in the directory can be viewed by path. grip --export bypasses the server and writes a single HTML file with styles and assets inlined, and --no-inline keeps styles external. Grip can read from stdin and write to stdout (cat README.md | grip -, grip --export - | less), and --user-content with --context=user/repo renders content as GitHub comments or issues.

Since rendering uses the GitHub API, unauthenticated use is subject to its hourly rate limit. Grip supports authenticating API requests with a personal access token. Settings such as HOST, PORT, API_URL (for GitHub Enterprise), AUTOREFRESH, CACHE_DIRECTORY and STYLE_URLS go in ~/.grip/settings.py. A Python API (serve, export, create_app, which returns a Flask app) allows embedding it in other projects. It suits developers and documentation authors who want to check Markdown output before committing, or generate HTML from Markdown files or GitHub wikis.

Installation

# via pip
pip install grip
# via Homebrew
brew install grip

Alternatives & related tools

add a badge to your README

Maintain Grip? Show that it's featured on trmn. The badge links back to this page.

Featured on trmn
Markdown
[![Featured on trmn](https://www.trmn.sh/badge/grip.svg)](https://www.trmn.sh/tools/grip?utm_source=badge)
HTML
<a href="https://www.trmn.sh/tools/grip?utm_source=badge"><img src="https://www.trmn.sh/badge/grip.svg" alt="Featured on trmn" height="20"></a>