grip

Start the server and serve the rendered README file of a current directory

$ grip

$ grip [path/to/file.md]

$ grip [[-b|--browser]]

$ grip [port]

grip [OPTIONS] [FILE]

-b, --line-numbering
    Toggle display of line numbers.

-r, --render-inline
    Render images inline instead of as links.

-w WIDTH, --width WIDTH
    Set browser preview width (default: 100).

--title TITLE
    Custom page title.

-s, --show
    Open preview in browser (default).

-o FILENAME, --export FILENAME
    Export rendered HTML to file.

-p, --preserve-newlines
    Preserve newlines in rendered output.

--user USER
    GitHub username for context.

--repo REPO
    Repository name for rendering context.

--path PATH
    File path within the repo.

--token TOKEN
    GitHub API token for authentication.

Grip is a Python-based command-line tool designed to render Markdown files precisely as they appear on GitHub. It leverages the GitHub API to convert Markdown to HTML and applies GitHub's official CSS stylesheets, providing an authentic local preview.

Run grip file.md to launch a local HTTP server (typically on port 6419) and automatically open the rendered page in your default browser. This eliminates the need to push changes to GitHub for previews. Grip supports specifying a GitHub user, repo, and file path for context-aware rendering, ensuring code blocks, tables, and features like task lists display correctly.

Key features include browser-based previews, HTML export, customizable widths, line numbering, and inline image rendering. It's invaluable for developers writing READMEs, documentation, or any GitHub-flavored Markdown. Install via pip install grip; no GitHub account needed for public content, but a token enhances API access.

Relies on GitHub API (rate-limited to 60 req/hour unauthenticated). Requires Python 3 and pip install grip. Local server binds to localhost:6419 by default; use --norefresh or env vars for tweaks. Private repos need token.

pip install grip or pipx install grip for isolated env.

Set GITHUB_TOKEN env var or use --token for higher limits/private access.
Get token at github.com/settings/tokens.

grip README.md --export preview.html
Preview and save as HTML.

Created by Joel Berger (jcbertsch) in 2016 as a Python tool for local GitHub Markdown previews. First PyPI release 2016-10; active maintenance with v4+ supporting modern GitHub features like diagrams. Widely used in dev workflows (~1M downloads).

pandoc(1), glow(1), mdless(1)