Stop Previewing Markdown in VS Code: mdr Is the Rust Tool You Need
You're staring at another wall of raw Markdown. Your AI assistant just generated a 500-line technical specification—complete with Mermaid flowcharts, nested tables, and code blocks—and you're supposed to review it. So you do what every developer does: you open VS Code, find the preview tab, wait for Electron to wheeze to life, and pray the diagrams render correctly. Spoiler: they won't. Mermaid diagrams? Broken. Live updates? Manual refresh. Speed? Glacial.
What if I told you there's a tool that launches in milliseconds, renders Mermaid diagrams natively without headless Chrome, and updates instantly as your file changes? No npm install. No 200MB of Node_modules. Just a single, static Rust binary that works everywhere—GUI, webview, or even over SSH in your terminal.
Meet mdr, the Markdown viewer that makes every other preview tool feel like a relic from 2015. Built by the engineering team at Clever Cloud, this "vibe coded" Rust project is secretly becoming the weapon of choice for developers drowning in AI-generated documentation. And once you try it, you'll wonder why you ever tolerated anything else.
What Is mdr? The Markdown Reader Built for the LLM Era
mdr (short for "Markdown Reader") is an open-source Markdown viewer developed by Clever Cloud, a French platform-as-a-service company known for serious infrastructure tooling. Don't let the playful "vibe coded" description fool you—this is production-grade software that solves a genuinely painful problem.
The repository lives at github.com/CleverCloud/mdr, and it's gaining traction for one simple reason: developers are generating more Markdown than ever before. ChatGPT, Claude, GitHub Copilot, and countless other AI tools output Markdown by default. Technical specs, API documentation, architecture decision records, incident postmortems—they all arrive as .md files packed with diagrams and structured content.
Traditional workflows fail here. Browser-based Markdown editors choke on Mermaid syntax. VS Code's preview is fine for basic files but stumbles on complex diagrams and requires manual refresh. Terminal-based tools like glow or mdcat are fast but can't render diagrams at all.
mdr occupies the sweet spot: native speed, diagram support, and live reload in one tool. Written in Rust, it compiles to a single binary with no runtime dependencies. The project embraces Rust's ecosystem strengths—comrak for GitHub-Flavored Markdown parsing, egui for immediate-mode GUI rendering, ratatui for terminal interfaces, and wry for native webview integration.
What's particularly clever is the multi-backend architecture. Unlike tools that force you into one rendering paradigm, mdr lets you choose: GPU-accelerated pure Rust GUI, OS-native webview for pixel-perfect HTML, or a keyboard-driven TUI for remote servers. This flexibility, combined with sub-second startup times, makes mdr genuinely versatile across development environments.
Key Features That Destroy the Competition
Let's dissect what makes mdr technically superior to every Markdown preview tool you've used:
Native Rust Binary — Zero Runtime Bloat
No Electron. No Node.js. No Chromium embedded somewhere eating 400MB of RAM. mdr compiles to a single static binary that starts in milliseconds. The egui backend produces entirely self-contained executables; the webview backend leverages OS-native WebKit (macOS/Linux) or WebView2 (Windows) that already exist on your system.
Mermaid Diagram Rendering Without Headless Browsers
This is the killer feature. mdr uses mermaid-rs-renderer to convert Mermaid syntax directly to SVG—no Puppeteer, no Playwright, no Chrome. Flowcharts, sequence diagrams, pie charts, class diagrams, state diagrams, ER diagrams, and Gantt charts all render natively. The only current limitation: diamond/decision nodes ({text}) aren't yet supported, but square brackets work as a workaround.
Three Backends, One Binary
| Backend | Technology | Best For |
|---|---|---|
| egui (default) | Pure Rust GPU rendering | Speed demons, minimal dependencies, cross-platform consistency |
| webview | Native WebKit/WebView2 | Pixel-perfect CSS, complex HTML, OS theme integration |
| tui | ratatui + crossterm | SSH sessions, servers, keyboard-only workflows |
Runtime backend selection means you don't commit to one paradigm. Writing docs locally? Use egui. Need exact GitHub rendering? Switch to webview. SSH'd into a production server? tui has you covered.
Live Reload With Intelligent Debouncing
File watching via the notify crate with 300ms debounce means changes appear instantly without thrashing. Edit in your preferred editor, save, and mdr updates. Let your AI tool regenerate the entire document—mdr catches it immediately.
Full GFM + Search + TOC
Tables, task lists, strikethrough, footnotes, autolinks—all supported via comrak. Syntax highlighting uses syntect for accurate language detection. In-document search (Ctrl+F or /) works across all backends. Auto-generated table of contents with click-to-navigate makes long documents manageable.
Real-World Use Cases Where mdr Dominates
1. Reviewing AI-Generated Technical Specifications
You prompt Claude to design a microservices architecture. It returns a 300-line Markdown file with Mermaid sequence diagrams, deployment tables, and API schemas. With mdr: mdr spec.md and you're analyzing rendered diagrams in under a second. Edit the prompt, regenerate, watch updates flow in real-time.
2. Remote Server Documentation Over SSH
You're debugging a production issue. Documentation lives on the server, not your laptop. Instead of downloading files or struggling with cat and less, SSH in and run mdr --backend tui docs/runbook.md. Full keyboard navigation, search, and readable formatting—no X11 forwarding required.
3. Documentation-Driven Development Workflows
You maintain API docs in Markdown with embedded architecture diagrams. Traditional preview requires a browser tab or VS Code instance. mdr's live reload lets you keep docs in one monitor, editor in another, and see instant feedback on every save. The egui backend's minimal resource usage means it stays out of your way.
4. Conference Talks & Live Coding Demos
Presenting from Markdown notes with embedded diagrams? mdr's clean rendering and instant startup beat waiting for browser tabs to load. The tui backend even works in stripped-down terminal environments where projectors only show console output.
5. CI/CD Pipeline Artifact Review
Generated reports in Markdown—test outputs, security scans, dependency analyses—often contain Mermaid visualizations. mdr lets operators quickly inspect these without setting up complex rendering pipelines. A single binary in your deployment image handles all review needs.
Step-by-Step Installation & Setup Guide
Getting mdr running takes under two minutes. Choose your path:
From Source (All Platforms)
Requires Rust 1.75+. Install Rust via rustup if needed.
# Clone the repository
git clone https://github.com/CleverCloud/mdr.git
cd mdr
# Install with all backends
cargo install --path .
Linux users: Install system dependencies first:
sudo apt-get install libgtk-3-dev libwebkit2gtk-4.1-dev libxdo-dev libgl1-mesa-dev
Minimal Build (Specific Backends Only)
Reduce binary size and dependencies by selecting only what you need:
# egui only — smallest binary, no WebView dependency
cargo install --path . --no-default-features --features egui-backend
# webview only — best HTML/CSS fidelity
cargo install --path . --no-default-features --features webview-backend
Package Managers
macOS / Linux (Homebrew):
brew install CleverCloud/misc/mdr
Linux (Snap):
sudo snap install --edge mdr-markdown-renderer
# Create convenient alias
sudo snap alias mdr-markdown-renderer mdr
Windows (Scoop):
scoop bucket add clevercloud https://github.com/CleverCloud/scoop-bucket
scoop install mdr
Windows (Chocolatey):
choco install mdr
Windows (WinGet):
winget install CleverCloud.mdr
Nix (any platform):
nix run github:CleverCloud/mdr
Pre-built Binaries
Download directly from GitHub Releases for macOS (Apple Silicon + Intel), Linux x86_64, and Windows x86_64.
REAL Code Examples From the Repository
Let's examine actual usage patterns from mdr's documentation, with detailed explanations:
Basic Usage: Open Any Markdown File
# Open with default egui backend — fastest startup, pure Rust
mdr README.md
# Explicitly select webview for GitHub-quality rendering
mdr --backend webview README.md
# Terminal UI for SSH sessions or minimal environments
mdr --backend tui README.md
# Display full help and available options
mdr --help
What's happening here: The mdr binary accepts a file path and optional --backend flag. Without the flag, it defaults to egui—the pure Rust GPU renderer. The webview backend delegates to OS-native WebKit/WebView2, while tui initializes a terminal interface using ratatui and crossterm. This single CLI entrypoint with runtime dispatch is elegant; you install once, choose per-invocation.
Mermaid Diagram Rendering
```mermaid
graph TD
A[Input] --> B[Process]
B --> C[Output]
When mdr encounters this code fence with `mermaid` language identifier, it passes the content through `mermaid-rs-renderer`—a Rust-native Mermaid implementation. The output is embedded SVG, rendered directly without any browser automation. **Supported diagram types**: flowchart, sequence, pie, class, state, ER, and gantt.
**Critical workaround note:** Diamond nodes using `{text}` syntax aren't yet supported. Use square bracket nodes `[text]` instead:
```markdown
```mermaid
graph TD
A[Start] --> B{Decision?} # ❌ Won't render
A[Start] --> C[Check Condition] # ✅ Works correctly
### **TUI Keyboard Navigation**
The terminal backend provides vim-inspired navigation:
```bash
mdr --backend tui documentation.md
| Key | Action |
|---|---|
q / Esc |
Quit the application |
j / ↓ |
Scroll down one line |
k / ↑ |
Scroll up one line |
Space / PgDn |
Page down |
PgUp |
Page up |
g / Home |
Jump to document start |
G / End |
Jump to document end |
Tab |
Toggle focus between TOC sidebar and main content |
Enter |
Navigate to selected heading from TOC |
/ or Ctrl+F |
Open search prompt |
n |
Next search match |
N |
Previous search match |
This keymap design shows thoughtful UX: j/k for vim users, arrow keys for everyone else, and Tab/Enter for TOC interaction. The search implementation (/, n, N) mirrors less/pager conventions, making it instantly familiar to systems programmers.
Build Configuration for Contributors
# Standard release build with all backends
cargo build --release
# Run the test suite
cargo test
# Lint with Clippy for code quality
cargo clippy
The Cargo.toml uses feature flags for backend selection, enabling the --no-default-features pattern shown in installation. This keeps the codebase modular—each backend lives in src/backend/ with minimal coupling to core parsing logic.
Advanced Usage & Best Practices
Optimize Binary Size for Distribution
Building for a specific use case? Strip unused backends:
# Smallest possible binary — egui only
cargo install --path . --no-default-features --features egui-backend
# Strip debug symbols for production builds
RUSTFLAGS="-C strip=symbols" cargo build --release
Integrate With Editor Workflows
Configure your editor to launch mdr on file save. For Vim/Neovim:
" Preview current file with mdr on leader-p
nnoremap <leader>p :!mdr %<CR>
For VS Code, create a task that runs mdr --backend webview ${file} for maximum fidelity when needed.
SSH-First Remote Development
When working on remote machines, the TUI backend shines. Combine with tmux for persistent sessions:
ssh server
tmux new -s docs
mdr --backend tui /var/log/documentation.md
# Detach with Ctrl+B, D — reattach later with tmux attach -t docs
Theme Consistency
The webview backend automatically follows OS dark/light theme settings. For consistent theming across backends, consider setting your terminal color scheme to match your OS preference when using TUI mode.
Comparison With Alternatives
| Tool | Speed | Mermaid | Live Reload | Binary Size | SSH/TUI | Native |
|---|---|---|---|---|---|---|
| mdr | ⚡ Instant | ✅ Native SVG | ✅ 300ms debounce | ~5-15MB | ✅ Full TUI | ✅ Single binary |
| VS Code Preview | 🐢 Slow | ❌ Broken/Extension | ❌ Manual | ~300MB+ | ❌ No | ❌ Electron |
glow / mdcat |
⚡ Fast | ❌ None | ❌ None | ~5MB | ✅ Terminal | ✅ Single binary |
| Marked 2 (macOS) | 🐢 Moderate | ✅ Via browser | ✅ Yes | ~50MB | ❌ No | ❌ App bundle |
| Obsidian | 🐢 Moderate | ✅ Plugin | ✅ Yes | ~200MB | ❌ No | ❌ Electron |
| Browser + Extension | 🐢 Slow | ✅ Via MermaidJS | ❌ Manual | N/A | ❌ No | ❌ Browser |
Why mdr wins: It's the only tool combining native-speed startup, native Mermaid rendering (no browser automation), live reload, and a true terminal backend. Glow is fast and terminal-native but can't touch diagrams. VS Code handles diagrams poorly and demands heavy resources. Obsidian and Marked are fine for note-taking but overkill and slow for quick document review.
FAQ: Common Developer Concerns
Is mdr stable enough for daily use?
Yes. Clever Cloud uses Rust in production infrastructure; mdr follows standard practices with cargo test, clippy linting, and semantic versioning. Pre-built binaries are available for major platforms.
Why Rust instead of Electron like other Markdown tools?
Rust enables true native performance with single-binary distribution. No runtime dependencies, no security surface from bundled Chromium, and startup times measured in milliseconds rather than seconds.
Can I use mdr with Markdown files generated by AI tools?
Absolutely—this is mdr's primary design target. The LLM era produces Markdown constantly; mdr's live reload and Mermaid support handle AI-generated technical documentation seamlessly.
Does mdr support custom CSS themes?
The webview backend renders with full CSS support. The egui backend uses built-in styling optimized for readability. Custom theme support for egui is on the roadmap; contribute at github.com/CleverCloud/mdr.
How do I report bugs or request features?
Open issues and pull requests on the GitHub repository. The "vibe coded" description suggests an approachable, community-friendly project.
Can I embed mdr in my own application?
Currently mdr is a standalone CLI tool. The underlying crates (mermaid-rs-renderer, comrak) are reusable. Library extraction is a potential future direction based on community interest.
What's the release process for new versions?
Tag-based: git tag v0.1.0 && git push origin v0.1.0 triggers automated builds. Pre-built binaries appear on the Releases page for macOS, Linux, and Windows.
Conclusion: Your Markdown Workflow Deserves Better
We've tolerated slow, bloated Markdown previews for too long. VS Code's preview tab was never designed for the LLM era's volume of diagram-rich documentation. Browser-based tools demand too much context-switching. Terminal renderers leave visual information on the table.
mdr fixes all of this. A Rust-native binary that starts instantly, renders Mermaid diagrams without browser automation, updates live as you edit, and adapts to your environment—GUI, webview, or terminal. It's the tool you didn't know you needed until AI-generated Markdown became your daily reality.
The Clever Cloud team built something genuinely useful here. "Vibe coded" might undersell it—this is thoughtful systems programming solving a real developer pain point with elegance.
Stop previewing. Start reading. Install mdr today from github.com/CleverCloud/mdr and feel what Markdown review should have been all along.
# One command to transform your workflow
cargo install --git https://github.com/CleverCloud/mdr
# Or grab a pre-built binary and go
Your future self, reviewing the next AI-generated architecture spec, will thank you.
