mdview

Zero-latency, terminal-native Markdown previewer optimized for tmux and Vim/Neovim workflows.

mdview is a high-performance terminal markdown viewer built in Rust. It monitors your markdown files with sub-10ms response times, renders styled text directly in your terminal using Ratatui, and preserves your viewport scroll position across saves—even through Vim's atomic inode-swapping save mechanics.

---

Features

• ⚡ Zero-Latency Rendering: Decoupled async architecture delivers sub-10ms disk-to-screen response times.
• 🔄 Vim/Neovim Inode Resilience: Monitors parent directory to seamlessly survive atomic write-and-rename inode swaps (rename(2)).
• ⏱️ 75ms Event Debouncing: Batches rapid editor saves and formatter passes (Prettier, Conform, format-on-save) to eliminate screen flicker.
• 🛡️ Guaranteed Terminal Hygiene: Dual-layer RAII drop guards and custom panic hooks ensure your terminal raw mode and alternate screen are unconditionally restored on exit, error, or crash—zero orphaned terminals.
• 🎨 Rich Markdown AST Rendering:
  • Headings: Depth-colored with bold styling (H1 cyan, H2 magenta, H3 blue, H4 yellow, H5 green, H6 red).
  • Inline Code: High-contrast text with dark background tinting.
  • Code Blocks: Indented with language header frames (┌─ rust ─ and └────).
  • Lists: Cleanly indented unordered (•) and ordered (1., 2.) lists with depth indentation.
  • Task Lists & Quotes: Styled checkbox markers ([x], [ ]), blockquote bars (│), and tables.
• 📜 Intelligent Scroll Preservation: Preserves vertical scroll offset on reload; automatically follows expanding file bottoms if anchored at the end.
• ⌨️ Vim-Style Navigation: Native keybindings (j, k, d, u, g, G, q, Esc).

---

Keybindings

Key	Action
j / Down	Scroll down 1 line
k / Up	Scroll up 1 line
d / Ctrl-d	Half page down
u / Ctrl-u	Half page up
PageDown	Full page down
PageUp	Full page up
g / Home	Jump to top of file
G / End	Jump to bottom of file
q / Esc / Ctrl-c	Clean exit

---

Installation

Via Cargo

Install directly from source:

cargo install --path .

Manual Installation (From Source)

Ensure you have Rust 1.85+ installed:

git clone https://github.com/luke4211/mdview.git
cd mdview
cargo build --release

The optimized binary will be located at target/release/mdview. Copy it to any directory in your $PATH:

# User-local install (recommended)
mkdir -p ~/.local/bin
cp target/release/mdview ~/.local/bin/

# System-wide install
sudo cp target/release/mdview /usr/local/bin/

---

Usage & Workflows

Basic Usage

# Preview a file
mdview README.md

# Start without arguments (awaiting file)
mdview

tmux + Vim Workflow

Open your markdown document in Vim in one pane, and launch mdview in an adjacent pane:

# In your tmux session:
# 1. Open your markdown file in Neovim/Vim
nvim notes.md

# 2. Split pane horizontally or vertically and launch mdview
tmux split-window -h "mdview notes.md"

Whenever you save in Vim (:w), mdview instantly re-renders the document in the adjacent pane without changing your scroll position or interrupting your editing flow.

---

Architecture

• src/tui.rs: Crossterm backend wrapper providing raw mode, alternate screen buffers, panic hook guards, and RAII restoration.
• src/watcher.rs: Debounced filesystem watcher powered by notify-debouncer-mini, designed to handle atomic file swaps.
• src/markdown.rs: Infallible Markdown AST parser mapping CommonMark events to styled ratatui::text::Text.
• src/app.rs: Application state machine, scroll offset calculations, viewport clamping, and rendering.
• src/main.rs: CLI parser and asynchronous tokio::select! event loop.

---

License

Dual-licensed under either of:

• MIT License (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.