gh-preview

Run a specific preview command

$ gh preview [command]

gh-preview [<repo>] [options]

-h, --help
    Show help message

-p, --port <PORT>
    Port to listen on (default: 3080)

--hostname <HOSTNAME>
    Hostname to bind to (default: 127.0.0.1)

--user <USERNAME>
    GitHub username (if repo format is user/repo)

--repo <REPO>
    Repository name (used with --user)

gh-preview is a Node.js-based command-line tool designed to locally preview the gh-pages branch of a GitHub repository. It automatically clones the specified repository's gh-pages branch (or uses the current directory's git repo if none specified) and starts a lightweight HTTP server to serve the static content.

This is particularly useful for developers deploying static websites or documentation to GitHub Pages, allowing quick local testing without pushing changes or using a full web server setup. The tool fetches the latest gh-pages content via GitHub's public clone URLs, making it ideal for public repositories.

Key features include customizable port and hostname binding, support for specifying username/repo combinations, and automatic handling of the current git repository context. It renders the site at http://localhost:3080 by default, mimicking the GitHub Pages environment closely for HTML, CSS, JS, and other static assets.

While simple and fast, it focuses solely on serving files and does not support server-side rendering or dynamic content. It's a popular choice in the Node.js ecosystem for quick previews during development workflows involving GitHub Pages.

Requires Node.js, npm, and git installed. Only supports public repositories out-of-the-box (private repos may need git config tweaks or tokens). Clones gh-pages branch to ~/.gh-preview/<repo>; deletes prior clones. Serves static files only—no dynamic backend support. Binds to localhost by default for security.

npm install -g gh-preview
Requires Node.js (≥10) and git.

gh-preview user/repo
or in repo dir: gh-preview (uses current git remote)

Created by Max Ogden (@maxogden) around 2013 as an npm package to streamline GitHub Pages workflows. Maintained sporadically with updates for Node.js compatibility; widely used in static site generation pipelines like Jekyll on GitHub Pages.

http-server(1), live-server(1), serve(1), git(1)