gh-preview

Run a specific preview command

$ gh preview [command]

gh preview <file> [<flags>]

<file>
    The path to the markdown file to be previewed.

-p, --port <port>
    Specifies the port for the local web server. Defaults to 8080.

-w, --watch
    Enables watching the file for changes and automatically re-rendering the preview in the terminal.

-b, --browser
    Opens the raw HTML rendering in a web browser. If no port is specified, an ephemeral port is used.

--theme <theme>
    Applies a specific GitHub theme to the rendering (e.g., light, dark, dark_dimmed, light_colorblind).

--jq <query>
    Applies a jq query to the JSON output generated from the rendered HTML.

--template <template>
    A Go template string used to format the JSON output. Implies --jq.

--web
    Renders the markdown file directly in a web browser instead of the terminal.

gh-preview is an official GitHub CLI extension designed to render local markdown files (e.g., README.md, pull request templates) exactly as they would appear on github.com, directly within your terminal.

It achieves this by utilizing GitHub's internal markdown rendering pipeline. The extension operates by launching a local web server, rendering the markdown in a headless browser, and then converting the generated HTML back into a terminal-friendly text format. This ensures an accurate representation, including proper styling for code blocks, tables, and images, mirroring the GitHub web interface. It's an invaluable tool for authors who want to ensure their markdown content looks perfect before pushing changes.

• Requires an internet connection to access GitHub's rendering services.
• The terminal rendering is a best-effort conversion from HTML; very complex markdown/HTML structures might not render perfectly in all terminals.
• Relies on gh (GitHub CLI) being installed and authenticated.

To use gh-preview, it must first be installed as a gh extension using the command:
gh extension install cli/gh-preview

gh-preview does not currently support offline rendering as it relies on GitHub's live web rendering pipeline for accurate previews.

gh-preview was developed as an official extension for the GitHub CLI (gh). It addresses a common need for developers to accurately preview how their markdown content will look on github.com, especially for README.md files, issue templates, and pull request descriptions.

Its development reflects GitHub's commitment to providing robust command-line tools that integrate seamlessly with its platform, enhancing developer workflows by bringing web-specific functionality directly to the terminal.

gh(1), markdown(7), less(1), bat(1)