gh-markdown-preview

To preview a specific Markdown file, pass the filename as an argument. The extension starts a local web server (defaulting to http://localhost:3333) and automatically opens your default browser. It uses GitHub's official markdown API and CSS to ensure the preview looks identical to GitHub.

gh markdown-preview README.md

Install the extension using the GitHub CLI (gh) command. This extension requires the gh command to be already installed on your system.

gh extension install yusukebe/gh-markdown-preview

To update the extension to the latest version, use the gh extension upgrade command.

gh extension upgrade markdown-preview

When running the tool, you can specify a file or a directory:

1. File: If you provide a path to a specific file, the tool will process that file.
2. Directory: If you provide a directory, the tool searches for a file matching the pattern (?i)^readme (case-insensitive, e.g., README.md, readme.txt). If no such file is found, it returns an error.
3. Default: If no filename is provided, it defaults to the current directory (.) and attempts to find a README file there.

The project implements live reloading by establishing a WebSocket connection between the server and the client. It uses an fsnotify.Watcher to monitor file system changes. When a change is detected, a reload signal is sent through a channel, triggering the server to write a websocket.TextMessage containing the string "reload" to the client.

To maintain a stable connection, the server implements a heartbeat mechanism:

• Ping/Pong: The server sends periodic websocket.PingMessage packets based on a pingPeriod (calculated as 90% of the pongWait interval).
• Deadlines: The server sets a read deadline (pongWait of 60 seconds) and updates it whenever a pong is received to ensure the connection remains active.

// Conceptual flow of the reload signal:
case <-reload:
    err := socket.WriteMessage(websocket.TextMessage, []byte("reload"))

The previewer automatically renders several advanced markdown elements:

• Math (LaTeX): Uses MathJax to render mathematical notation. Supports inline math with $ or \( and block math with $$ or \[.
• Diagrams (Mermaid): Renders Mermaid diagrams. It includes a built-in copy button to retrieve the original Mermaid source code.
• Code Blocks: All <pre> blocks include a copy button to quickly copy the code content to the clipboard.
• GitHub-style Links: Automatically cleans up GitHub-specific anchor IDs (removing the user-content- prefix) to ensure standard link behavior.

The markdown preview supports three visual modes that determine the CSS stylesheet and background colors used in the browser:

• dark: Uses github-markdown-dark.min.css and a dark background (#0d1117).
• light: Uses github-markdown-light.min.css.
• auto (default/unspecified): Uses github-markdown.min.css and respects the user's system color scheme via @media (prefers-color-scheme: ...) queries.

The gh-markdown-preview tool is a GitHub CLI extension. The entrypoint executes the command logic defined in the cmd package via cmd.Execute(). As a GitHub CLI extension, it is intended to be invoked through the gh command line interface.

# Typical usage as a GitHub CLI extension
gh extension install yusukebe/gh-markdown-preview
gh markdown-preview

The gh-markdown-preview command is a GitHub CLI extension used to preview Markdown files in a local web server. It can preview a specific file, or read content from stdin to allow piping markdown content directly into the previewer.

Basic Usage:

gh-markdown-preview [filename]

Using stdin: You can pipe content into the tool by using - as the filename or by piping directly to the command:

cat README.md | gh-markdown-preview -
# OR
echo '# Hello' | gh-markdown-preview

You can pipe Markdown content into the command or use the - flag to read from standard input. This is useful for previewing content generated by other commands without saving a file first.

echo "# Hello" | gh markdown-preview
cat README.md | gh markdown-preview
gh markdown-preview - < README.md