mdview

README

mdview

Live-reloading Markdown viewer for the terminal. Point it at a .md file and see it re-render, styled, every time you save — without leaving the terminal or opening a browser. Real syntax highlighting in fenced code blocks.

mdview README.md          # live TUI, re-renders on save
mdview --print README.md  # render once to stdout
cat notes.md | mdview     # render piped stdin
mdview                    # opens ./README.md if present

Why

glow, mdcat, and bat all render Markdown in the terminal, but none nail the write-and-watch loop: keep mdview open in one pane, edit in another, and every save updates the rendered view instantly. A status bar flashes ⟳ reloaded so you know the change was picked up. Saves made through editors that write atomically (vim, VS Code, and most others) are detected correctly.

Features

• Live reload — re-renders on every save, preserving your scroll position.
• Real code fidelity — syntax-highlighted fenced code blocks (via glamour + chroma); code is never hard-wrapped.
• Full-screen TUI — scroll with familiar pager keys; quit with q.
• Print mode — --print, or automatically when piped, for use in scripts and pipelines (mdview --print doc.md | less -R).
• Themes — auto-detects light/dark terminals; override with --style.
• Single static binary — no runtime dependencies.

Install

Homebrew (macOS / Linux)

brew install vashuteotia123/tap/mdview

go install (Go 1.23+)

go install github.com/vashuteotia123/mdview@latest

The binary lands in $(go env GOPATH)/bin — make sure that's on your PATH.

Prebuilt binaries

Download the archive for your OS/arch from the Releases page, extract, and move the mdview binary onto your PATH:

tar -xzf mdview_Darwin_arm64.tar.gz
sudo mv mdview /usr/local/bin/

Build from source

git clone https://github.com/vashuteotia123/mdview.git
cd mdview
go build -o mdview .
./mdview README.md

Usage

mdview [flags] [FILE]

• mdview FILE — open FILE in the live-reloading TUI.
• mdview — with piped stdin, render it and exit; otherwise open ./README.md if present; otherwise show usage.
• mdview --print FILE — render once to stdout and exit. Print mode is selected automatically when stdout is not a terminal (pipes, redirects) or when input arrives on stdin.

Keys (TUI)

Key	Action
q / Ctrl-C	quit
j / k, ↑ / ↓	scroll line
Space / b	scroll page
g / G	top / bottom
r	manual reload
?	help

Flags

Flag	Description
--print	render once to stdout and exit (auto when stdout isn't a TTY)
--style NAME	glamour style: auto (default), dark, light, notty, …
--width N	prose wrap width (default: min(termWidth-gutter, 100))
--version	print version and exit

Environment

Variable	Description
MDVIEW_STYLE	default style when --style is not given

Configuration precedence: flag > environment > built-in default.

How it works

mdview watches the target file's parent directory (not the file inode) so that atomic-rename saves keep firing events. Filesystem events are debounced (~75 ms) and coalesced, the terminal background is detected once to pick a theme, and the file is re-rendered off the UI thread so scrolling stays responsive even on large documents. Unchanged saves are skipped, and if a read comes back empty or fails mid-write, the last good render is held on screen rather than flashing blank. The UI is a Bubble Tea program; rendering is powered by glamour.

Roadmap

Planned beyond the first release: directory browsing, multiple files / tabs, in-document search, follow-the-edit scrolling, horizontal scrolling for wide code, custom stylesheets, a config file, and viewport virtualization for very large documents.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for how to set up your environment, run the tests, and open a pull request. By participating you agree to abide by the Code of Conduct.

License

Licensed under the MIT License.

Third-party notices

mdview builds on the Charm and related libraries — glamour, Bubble Tea, Bubbles, Lip Gloss, chroma, termenv, and fsnotify — each under their own licenses. See the module dependencies in go.mod.

Documentation

Overview

Command mdview renders a Markdown file in the terminal with a live-reloading TUI, or prints it once to stdout.

Usage:

mdview FILE            live TUI, re-renders on save
mdview --print FILE    render once to stdout and exit
mdview                 pipe stdin -> print; else open ./README.md; else usage
cat x.md | mdview      auto print mode (stdin piped)

Flags:

--print          render once and exit (also auto when stdout is not a TTY)
--style NAME     glamour style: auto (default), dark, light, notty, ...
--width N        wrap width for prose (default: min(termWidth-gutter, 100))

Config precedence: flag > env (MDVIEW_STYLE) > built-in default.