README
¶
mdview
A beautiful markdown viewer for the browser. Point it at a directory or file and get a world-class reading experience with live reload, three design themes, and zero configuration.
go install github.com/jsurdilla/mdview@latest
mdview ~/docs
Install
Go
go install github.com/jsurdilla/mdview@latest
From source
git clone https://github.com/jsurdilla/mdview.git
cd mdview
make install
Binary releases
Download from GitHub Releases.
Usage
mdview [flags] [path]
| Flag | Default | Description |
|---|---|---|
-p |
auto | Port to serve on |
-t |
paper | Initial theme (paper, mono, swiss) |
-d |
Start in dark mode | |
-no-open |
Don't auto-open browser | |
-no-watch |
Disable live reload | |
-v |
Show version |
Examples
# Serve current directory
mdview
# Serve a specific folder
mdview ~/docs/project
# Open a single file
mdview README.md
# Dark theme, mono style, specific port
mdview -t mono -d -p 3000 /path/to/docs
Themes
Three themes, each with light and dark variants:
| Theme | Feel | Best for |
|---|---|---|
| Paper | Warm serif, Crimson Pro | Long-form reading |
| Mono | Technical, IBM Plex Mono | Code-heavy docs |
| Swiss | Bold modernist, minimal | Clean presentation |
Features
- File sidebar — collapsible tree with directory grouping
- Full-text search — instant fuzzy file search
- Table of contents — auto-generated from headings with scroll spy
- Syntax highlighting — 150+ languages via Chroma
- YAML frontmatter — displayed as metadata fields
- Mermaid diagrams — rendered inline
- KaTeX math — LaTeX equation support
- Code copy — one-click copy button on code blocks
- Live reload — SSE-based, updates on file save
- Keyboard navigation — full keyboard control (see below)
- Mobile responsive — works on phones and tablets
- Print friendly — clean print styles
- Zero dependencies — single static binary, no npm, no frameworks
Keyboard Shortcuts
| Key | Action |
|---|---|
/ |
Focus search |
j |
Next file |
k |
Previous file |
t |
Cycle themes |
d |
Toggle dark mode |
[ |
Toggle sidebar |
Esc |
Clear search |
Experimental Features
mdview includes three experimental features, toggled from the ⚗ menu in the footer:
| Feature | Description |
|---|---|
| Buddy | A friendly pixel pet that lives in the corner. Feed it, pet it, track your reading stats. State persists in localStorage with import/export support. |
| Reading Progress | Tracks scroll progress per file. Shows completion indicators (✓) next to files in the sidebar. |
| Quick Notes | Per-file annotations saved to your browser. Jot notes while reading, they persist across sessions. |
Development
make fmt # Format (gofumpt)
make lint # Lint (golangci-lint)
make vet # Go vet
make test # Run tests with race detector
make cover # Coverage report
make dev # Build and serve current directory
make all # lint + vet + test + build
Architecture
Single-binary Go server with embedded web assets:
main.go CLI, flags, signal handling
server.go HTTP server, routing, template rendering
render.go Markdown → HTML (goldmark + chroma)
scanner.go Directory tree builder
watcher.go fsnotify file watcher + SSE broadcast
embed.go go:embed directives
web/ HTML template, CSS themes, JS client
License
Documentation
Source Files
Click to show internal directories.
Click to hide internal directories.