gfm_hotview

A lightweight, yet feature-rich offline GitHub-Flavored Markdown (GFM) file browser and viewer.

Features

• Supports all Gtihub markdown features:
  • Tables, task lists, footnotes, strikethrough, autolinks
  • GitHub-style alerts (> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION])
  • Heading anchors, emoji shortcodes (:rocket:)
  • Code blocks with syntax highlighting
  • Math ($…$, $$…$$) and Mermaid blocks
• Markdown file explorer with search
• Light and dark modes
• Live reload
• Automatic port selection
• Dependency-free and easy to deploy

Install

Use one of the installation methods below or download the latest release for your platform from the releases page.

macOS (Homebrew)

brew tap keathmilligan/tap
brew install keathmilligan/tap/gfm-hotview

Stay up-to-date with brew upgrade gfm-hotview.

See the macOS Install Guide for other ways to install on macOS.

Linux (shell installer)

curl -fsSL https://packages.keathmilligan.net/gfm-hotview/install.sh | sh

This will install gfm-hotview into ~/.local/bin.

See the Linux Install Guide for other ways to install on Linux.

Windows (PowerShell)

In an elevated powershell session, run:

irm https://packages.keathmilligan.net/gfm-hotview/install.ps1 | iex

See the Windows Install Guide for other ways to install on Windows.

Usage

gfm-hotview [options] [path...]

One or more path arguments may be given (default: the current directory). Each directory becomes a root shown in the sidebar tree; pass a file and its directory becomes a root with that file opened first. When multiple roots are given, paths in the tree (and --open-page) are prefixed with each root's basename, e.g. proj/README.md.

Options

Flag	Default	Description
-p, --port	6419	Port to bind (auto-selects next free if taken; 0 = OS-chosen)
-H, --host	localhost	Host/interface to bind
--no-open	off	Do not auto-open the browser
--no-reload	off	Disable live reload
-t, --theme	auto	auto | light | dark
--mode	gfm	gfm | markdown (plain CommonMark)
--show	*.md,*.markdown	Comma-separated globs shown in the tree
--ignore	—	Additional comma-separated ignore globs
--open-page	README-detect	Initial document (relative to root; for multiple roots, prefix with the root label)
-c, --config	auto	Path to config file (default .gfm-hotview/config.*)
--no-config	off	Ignore config file and .gfm-hotview overrides
-q, --quiet	off	Suppress non-error logs
-v, --verbose	off	Verbose logging
-d, --debug	off	Detailed server activity (file scanning, change events, requests)
--version		Print version

Configuration & theming (.gfm-hotview)

Create an optional .gfm-hotview directory at the root you serve:

<root>/.gfm-hotview/
  config.toml      # optional: override host/port (and future settings)
  css/             # optional: CSS overrides applied after built-in styles
    theme.css

config.toml (TOML primary; YAML/JSON also accepted):

[server]
host = "127.0.0.1"
port = 8080

Precedence: built-in defaults → config file → command-line flags. Any CSS files in .gfm-hotview/css are concatenated and served at /user.css, linked after the built-in stylesheets so they win by cascade. Both are ignored with --no-config. The .gfm-hotview directory is never shown in the tree or served as raw content.

Build from source

Requires Go 1.22+.

go build -o gfm-hotview .

Cross-compile (fully static, CGO_ENABLED=0):

CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o gfm-hotview.exe .
CGO_ENABLED=0 GOOS=darwin  GOARCH=arm64 go build -o gfm-hotview-macos .

Development

go test ./...      # unit tests
go vet ./...
gofmt -l .