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] [PATH]
grip [OPTIONS] --export [PATH] -o OUTPUT_FILE
grip --help
grip --version

--help
    Show program's help message and exit.

--version
    Show program's version number and exit.

--port PORT
    The port to listen on (default: 6419).

--host HOST
    The host to listen on (default: 127.0.0.1).

--no-open
    Do not open a browser tab automatically.

--browser BROWSER
    Specify the browser to open (e.g., chrome, firefox).

--title TITLE
    Set the title of the HTML page.

--asset-path PATH
    Specify a path to serve assets from.

--export
    Instead of serving, export the rendered HTML to a file.

--output FILE, -o FILE
    Specify the output file for export mode.

--keep-html
    Do not remove the HTML file after serving.

--user USERNAME
    GitHub username for API authentication (for higher rate limits).

--pass PASSWORD
    GitHub password for API authentication.

--token TOKEN
    GitHub personal access token for API authentication.

--api-url URL
    Specify a custom GitHub API URL.

--offline
    Render Markdown completely offline without GitHub API.

--style CSS_URL
    Custom stylesheet URL or path.

--quiet
    Suppress output except for errors.

--clear-cache
    Clear GitHub API cache.

--skip-math
    Skip rendering math equations.

--skip-emoji
    Skip rendering emoji shortcodes.

grip is a powerful command-line utility designed to render GitHub Flavored Markdown (GFM) files locally. It accomplishes this by starting a lightweight web server that serves the rendered Markdown content, allowing you to preview your `README.md` files, Wiki pages, or any other Markdown document in your web browser exactly as it would appear on GitHub. This eliminates the need to commit and push changes to GitHub just to see how the Markdown is rendered, significantly speeding up the documentation workflow. It leverages GitHub's own Markdown API by default for accurate rendering, but also offers an offline mode for basic GFM display. Key features include live reloading on file changes, customizable port and host settings, and the ability to export rendered HTML to a file. grip is an indispensable tool for developers and technical writers who frequently work with Markdown for GitHub repositories, ensuring consistency and accuracy in their documentation.

grip requires Python to be installed on your system. By default, it relies on GitHub's Markdown API for accurate rendering, which means an active internet connection is typically needed. Without authentication (via username/password or personal access token), you might encounter GitHub API rate limits. While the `--offline` mode allows rendering without an internet connection, it may not perfectly replicate all GitHub-specific styles or extensions as it uses a local Markdown parser.

grip is typically installed via pip, Python's package installer. You can install it using the command:
`pip install grip`.
It's recommended to install it in a virtual environment to avoid conflicts with system-wide Python packages.

• To preview a `README.md` file:
  `grip README.md`
• To preview content from standard input:
  `cat my_notes.md | grip`
• To export a Markdown file to HTML:
  `grip --export documentation.md -o documentation.html`
• To preview a file on a specific port without opening a browser:
  `grip --port 8000 --no-open my_doc.md`

grip was created by Joe Esposito to fill a specific niche: providing an accurate, local preview of GitHub Flavored Markdown documents. Before grip, developers often had to commit and push changes to GitHub just to see the final rendered output, or rely on less accurate browser extensions. Written in Python, grip quickly became a popular choice for streamlining the Markdown documentation workflow due to its simplicity, live-reloading capabilities, and reliance on GitHub's own API for rendering accuracy. It continues to be maintained and updated by its community.

pandoc(1), markdown(1), lowdown(1), cat(1)