A terminal markdown viewer with vim keybindings, built with OpenTUI and shiki for syntax highlighting.

• Bun v1.0 or later

Download the latest binary for your platform from Releases:

# macOS (Apple Silicon)
curl -LO https://github.com/pders01/mdv/releases/latest/download/mdv-darwin-arm64.tar.gz
tar xzf mdv-darwin-arm64.tar.gz && sudo mv mdv-darwin-arm64 /usr/local/bin/mdv

# macOS (Intel)
curl -LO https://github.com/pders01/mdv/releases/latest/download/mdv-darwin-x64.tar.gz
tar xzf mdv-darwin-x64.tar.gz && sudo mv mdv-darwin-x64 /usr/local/bin/mdv

# Linux (x64)
curl -LO https://github.com/pders01/mdv/releases/latest/download/mdv-linux-x64.tar.gz
tar xzf mdv-linux-x64.tar.gz && sudo mv mdv-linux-x64 /usr/local/bin/mdv

git clone https://github.com/pders01/mdv.git
cd mdv
bun install

# Build for current platform
bun run build
sudo mv mdv /usr/local/bin/

# Or use the install script
bun run install-global

bun run src/index.ts README.md

# View a markdown file
mdv README.md

# Browse a directory of markdown files
mdv ./docs
mdv .

# Read from stdin (pipe)
cat README.md | mdv
curl -s https://example.com/doc.md | mdv

# Watch a file for live reload
mdv -w README.md

# Watch a directory (reloads active file, marks changed files in sidebar)
mdv -w ./docs

# With a specific theme
mdv -t dracula README.md

# Exclude directories when browsing
mdv -e drafts -e tmp ./docs

# List available themes
mdv --list-themes

Pass a directory instead of a file to open a sidebar file browser:

mdv ./docs

This recursively scans for .md files and displays them in a navigable sidebar. The following directories are excluded by default: node_modules, .git, vendor, dist, build, .next, .nuxt, __pycache__, .venv, target, .hg, .svn.

Use -e/--exclude to add custom exclusions (repeatable).

All navigation keys (j/k, Ctrl-d/u, etc.) work in both panes.

Search works in both the reader pane and the sidebar file list. Matches are highlighted inline with exact position awareness (accounts for markdown conceal).

• Full markdown rendering with proper styling
• Syntax highlighting for code blocks (50+ languages)
• Theme support via shiki (github-dark default, 30+ themes available)
• Live reload with --watch (single file and directory mode)
• Directory browsing with sidebar file tree
• Pager-style search (/, n/N) with inline match highlighting
• Vim-style navigation (works in both sidebar and reader panes)
• Supports:
  • Headings (ATX and Setext style)
  • Bold, italic, strikethrough
  • Links (with URL display)
  • Images (shows alt text)
  • Code blocks with syntax highlighting
  • Inline code
  • Ordered and unordered lists (nested)
  • Blockquotes (nested)
  • Tables
  • Horizontal rules
  • HTML blocks and inline HTML
  • Subscript/superscript (via Unicode)
  • Reference-style links
  • Escape sequences

-t, --theme <name>    Set syntax highlighting theme (default: github-dark)
-T, --list-themes     List available themes
-w, --watch           Live reload on file changes
-e, --exclude <dir>   Exclude directory from scan (repeatable)
    --no-mouse        Disable mouse input
    --debug           Enable debug logging
-v, --version         Show version
-h, --help            Show help

# Run with hot reload
bun dev

# Run directly
bun run src/index.ts <file.md>

• OpenTUI - Terminal UI framework
• shiki - Syntax highlighting
• marked - Markdown parsing
• Bun - JavaScript runtime

MIT