mdmdview
A fast, standalone markdown viewer built with Rust and egui
π Overview
mdmdview is a professional markdown viewer designed for speed, simplicity, and reliability. Built entirely in Rust with the egui framework, it delivers a native, responsive experience with zero external dependencies. Perfect for viewing documentation, notes, technical specs, or any markdown content with beautiful formatting and syntax-highlighted code blocks.
Why mdmdview?
- π Blazing Fast - Instant startup and rendering with efficient Rust implementation
- π¦ Single Binary - No installation, no dependencies, just run the executable
- π¨ Beautiful Rendering - Professional formatting with syntax highlighting for 100+ languages
- β¨οΈ Keyboard-First - Comprehensive shortcuts for power users
- π Smart Search - Unicode-aware search with accent normalization
- π· Live Images - Automatic refresh when linked images change
- π Drag & Drop - Drop files or folders to open instantly
- π Cross-Platform - Works on Windows, Linux, and macOS
β¨ Features
Core Functionality
- Pure Rust Implementation - Single executable (~4.8MB) with all assets embedded
- Fast Markdown Rendering - CommonMark compliant parsing with pulldown-cmark
- Syntax Highlighting - 100+ languages supported via syntect
- Native File Dialogs - Seamless OS integration with rfd
- Embedded Examples - Built-in sample files demonstrating all features
- Command Line Support - Open files directly:
mdmdview document.md
- Custom Application Icon - Distinctive markdown document icon with full Windows metadata
Advanced Features
- π Navigation History - Browser-like back/forward through files and samples (
Alt+β/Alt+β)
- π Accent-Aware Search - Finds matches across case and diacritics (e.g., "istanbul" matches "Δ°stanbul")
- π· Live Image Refresh - Automatically reloads textures when linked images change on disk
- π Raw Mode with Edit - View and edit source markdown (
Ctrl+R to toggle, Ctrl+E to edit)
- π Internal Anchors - In-document navigation via
[link](#anchor) syntax
- π Table Support - Professional grid layout with headers and striped rows
- π¨ Mermaid Diagrams - Render flowcharts, sequence diagrams, and more
- π Emoji Support - Embedded Twemoji assets with shortcode expansion (
:rocket: β π)
- π Encoding Fallback - Opens non-UTF-8 legacy files via lossy decoding
- πΎ Window State Persistence - Remembers position, size, and zoom level across sessions
- π Zoom Support - Adjustable font sizes (
Ctrl++/Ctrl+-/Ctrl+0)
- π Multi-File Queue - Drag multiple files to queue them for sequential viewing
Drag and Drop Support
Drop files and folders directly from your file explorer:
- Single File - Drop a
.md file to open it immediately
- Multiple Files - Drop multiple files to open the first and queue the rest
- Navigate through queue with
Alt+β / Alt+β
- Status bar shows: "π N files in queue"
- Folders - Drop a folder to open all markdown files within (non-recursive, top-level only)
- Visual Feedback - Blue overlay appears during drag operations
- Supported Extensions -
.md, .markdown, .mdown, .mkd, .txt
- Protection - 50 file maximum per drop (prevents accidental large drops)
π Getting Started
Prerequisites
- Rust 1.70+ - Install from rustup.rs
- Operating System - Windows 10/11, Linux (Ubuntu 20.04+, Fedora 35+), or macOS 10.15+
Installation
Option 1: Windows MSI Installer (Recommended for Windows)
- Go to Releases
- Download
mdmdview-vX.Y.Z-windows-x86_64.msi
- Run the installer β it will:
- Install to
C:\Program Files\mdmdview\
- Create a Start Menu shortcut
- Register
.md and .markdown file associations
- Add an entry in Add/Remove Programs
- Upgrading: run a newer MSI and the old version is removed automatically
Option 2: Download Portable Binary
- Go to Releases
- Download the ZIP for your platform:
mdmdview-vX.Y.Z-windows-x86_64.zip (Windows)
- Extract and run the executable β no installation required
Option 3: Build from Source
# Clone the repository
git clone https://github.com/0x4D44/mdmdview.git
cd mdmdview
# Build in release mode (optimized, ~4.8MB binary)
cargo build --release
# Run the application
./target/release/mdmdview
Mermaid Rendering (Default)
Embedded Mermaid rendering (QuickJS, offline) is enabled by default.
On Windows, QuickJS builds require a patch tool in PATH (e.g., Git for Windows or MSYS2).
# Build without embedded Mermaid rendering
cargo build --release --no-default-features
π Usage
Opening Files
Interactive:
- Use
File > Open or press Ctrl+O
- Drag and drop
.md files into the window
- Explore
File > Samples for built-in examples
Command Line:
# Open with welcome screen
mdmdview
# Open a specific file
mdmdview document.md
mdmdview "C:\path\to\my document.md"
# Works with relative paths
mdmdview ../README.md
Screenshot Mode (PNG)
Render a markdown file directly to an image:
mdmdview --screenshot document.md --output out.png
Optional flags:
--width / --height : viewport size (default 1280x720 in screenshot mode)--theme light|dark: override theme for render--zoom : scale factor (e.g., 1.25)--content-only: hide window chrome in the capture--scroll : scroll ratio from 0.0 (top) to 1.0 (bottom)--wait-ms : delay before capture to allow assets to load--settle-frames : extra frames to wait for layout stability--test-fonts : load fonts from a directory (QA/automation use)
Windows Shell Integration
Associate mdmdview with .md files for double-click opening:
- Right-click any
.md file in Windows Explorer
- Select "Open with > Choose another app"
- Click "More apps" β "Look for another app on this PC"
- Browse to
mdmdview.exe and select it
- Check "Always use this app to open .md files"
- Click OK
Now all .md files will open in mdmdview by double-clicking!
View Modes
- Rendered Mode (default) - Formatted markdown with styling and images
- Raw Mode (
Ctrl+R) - Source text in monospace editor
- Write Mode (
Ctrl+E in Raw mode) - Edit and auto-save changes
Search Functionality
Press Ctrl+F to open the search panel:
- Unicode-aware matching - Finds "resume" and "rΓ©sumΓ©" from single query
- Case-insensitive - "istanbul" matches "Istanbul" and "Δ°stanbul"
- Grapheme-aware highlighting - Preserves emoji and accent marks
- Navigation - Use
Enter/Shift+Enter or F3/Shift+F3 to cycle results
- Real-time highlighting - Matches highlighted as you type
β¨οΈ Keyboard Shortcuts
File Operations
| Shortcut | Action |
|---|
Ctrl+O | Open file dialog |
Ctrl+W | Close current file |
F5 | Reload current file from disk |
Ctrl+Q | Quit application |
Navigation
| Shortcut | Action |
|---|
Alt+β | Navigate back in history |
Alt+β | Navigate forward in history |
Home | Jump to top of document |
End | Jump to bottom of document |
Page Up | Scroll up one page (~80% viewport) |
Page Down | Scroll down one page (~80% viewport) |
β / β | Scroll up/down (small increment) |
View Controls
| Shortcut | Action |
|---|
Ctrl+F | Toggle search panel |
Ctrl+R | Toggle Rendered/Raw view |
Ctrl+E | Toggle edit mode (in Raw view) |
F11 | Toggle fullscreen |
Ctrl++ | Zoom in (increase font size) |
Ctrl+- | Zoom out (decrease font size) |
Ctrl+0 | Reset zoom to default |
Search Navigation
| Shortcut | Action |
|---|
Enter | Next search result |
Shift+Enter | Previous search result |
F3 | Next search result |
Shift+F3 | Previous search result |
Esc | Close search panel |
π¨ Markdown Support
mdmdview supports all CommonMark elements with professional formatting:
Text Formatting
- Bold (
**text** or __text__)
- Italic (
*text* or _text_)
Strikethrough (~~text~~)Inline code with proper inline rendering- Links that open in browser
- Internal anchors:
[Section](#section) for in-document navigation
Structure
- Headers (H1-H6) with proper hierarchy and sizing
- Lists - Bulleted and numbered with nesting support
- Tables - Professional grid with headers and striped rows
- Blockquotes - Styled with orange accent bar
- Horizontal rules (
---) for section separation
Code Blocks
- Syntax highlighting for 100+ languages
- Rust, Python, JavaScript, C++, Go, TypeScript, SQL, and more
- Proper indentation and color schemes
- Line-based rendering for readability
Rich Content
- Images - PNG, JPEG, GIF, BMP, ICO, WebP, SVG
- Relative paths resolved from markdown file location
- Live refresh when source files change
- Graceful fallback for missing images
- Emoji - Color Twemoji assets embedded
- Shortcode expansion:
:rocket:, :tada:, :heart:
- Native Unicode emoji rendering
- Mermaid Diagrams - Flowcharts, sequence diagrams, gantt charts, etc.
- Embedded renderer is built by default (disable with
--no-default-features)
- Theme selection via View menu: Auto, Dark, Default, Forest, Neutral
Special Features
- Line break preservation - Single newlines respected (perfect for poetry/lyrics)
- Header IDs - Auto-generated for anchor navigation
- Nested structures - Lists within blockquotes, tables with formatting, etc.
π§ Configuration
Mermaid Theme
Select the Mermaid diagram theme via View > Mermaid Theme:
- Auto (default) - resolves to Dark or Default based on the app's dark/light mode
- Dark - Mermaid's dark theme
- Default - Mermaid's light theme
- Forest - Mermaid's green/forest theme
- Neutral - Mermaid's neutral/grayscale theme
The theme setting persists across sessions.
Environment Variables
| Variable | Purpose | Default |
|---|
RUST_LOG | Logging level (error, warn, info, debug, trace) | warn |
Example:
# Enable debug logging
RUST_LOG=debug mdmdview document.md
Window State Persistence
Window position, size, and maximized state are automatically saved:
- Windows:
%APPDATA%\MarkdownView\window_state.txt + Registry backup
- Linux:
~/.config/mdmdview/window_state.txt (respects XDG_CONFIG_HOME)
- macOS:
~/Library/Application Support/MarkdownView/window_state.txt
State is saved every second (throttled) and on exit.
ποΈ Architecture
Project Structure
mdmdview/
βββ src/
β βββ main.rs # Entry point, eframe setup, CLI args
β βββ app.rs # Main app state, UI logic, shortcuts
β βββ markdown_renderer.rs # Parsing, rendering, syntax highlighting
β βββ sample_files.rs # Embedded markdown examples
β βββ window_state.rs # Cross-platform state persistence
β βββ emoji_catalog.rs # Emoji shortcode mappings
β βββ emoji_assets.rs # Embedded Twemoji PNGs
β βββ lib.rs # Library interface for testing
βββ build.rs # Windows resources, version metadata
βββ assets/
β βββ icon.ico # Application icon
β βββ vendor/
β βββ mermaid.min.js # For embedded Mermaid renderer
βββ wix/
β βββ main.wxs # WiX installer source (stable GUIDs)
β βββ License.rtf # License shown during install
βββ Cargo.toml # Dependencies and build config
βββ README.md # This file
βββ tests.md # Comprehensive testing guide
Core Components
-
Main Entry Point (src/main.rs)
- eframe/egui application setup
- Command-line argument parsing
- Window configuration with icon
- Cross-platform initialization
-
Application Logic (src/app.rs)
MarkdownViewerApp struct manages all state- UI rendering (menu bar, status bar, content area)
- Keyboard shortcut handling
- Navigation history (back/forward stack)
- View mode switching (Rendered/Raw/Write)
- Search state and result navigation
- File operations and error handling
-
Markdown Renderer (src/markdown_renderer.rs)
- Parsing with pulldown-cmark into
MarkdownElement enum
- Conversion to egui widgets
- Syntax highlighting with syntect
- Image loading and texture caching
- Mermaid diagram rendering (embedded QuickJS)
- Table layout with proper sizing
- Search result highlighting
- Emoji rendering with Twemoji assets
-
Window State (src/window_state.rs)
- Platform-specific persistence
- Geometry validation and sanitization
- Registry storage on Windows
- Config file storage on Linux/macOS
-
Build Script (build.rs)
- Windows resource file generation
- Version info from Cargo.toml
- Icon embedding
- Mermaid.js embedding for embedded renderer
Key Design Decisions
- Single Binary - All dependencies embedded for zero-config distribution
- Immediate Mode GUI - egui provides responsive, native-feeling interface
- CommonMark Compliance - pulldown-cmark ensures standard compatibility
- Efficient Rendering - Texture caching, incremental updates, scroll optimization
- Cross-Platform - Platform-specific code isolated, core logic portable
- Zero Warnings - Strict compilation standards for code quality
π οΈ Development
Building
# Development build (faster compilation, larger binary)
cargo build
# Release build (optimized, ~4.8MB)
cargo build --release
# Without embedded Mermaid renderer
cargo build --release --no-default-features
# Run in development mode
cargo run
# Run with specific file
cargo run -- document.md
# Build MSI installer (requires WiX Toolset v3 + cargo-wix)
cargo wix # full: build release + create MSI
cargo wix --no-build # MSI only (if release binary already built)
MSI Installer Prerequisites
Building the MSI installer requires:
- WiX Toolset v3.14.1 β install and ensure
candle.exe/light.exe are in PATH
cargo-wix β install with cargo install cargo-wix
The WiX source file (wix/main.wxs) is checked into the repository. Do not regenerate it β it contains a stable UpgradeCode GUID required for upgrade detection across versions.
Testing
The project has 1,100+ tests across four categories: unit tests, D2 conformance tests, visual regression tests, and Mermaid visual tests. See tests.md for the full testing guide.
# Run all unit tests (~8 minutes)
nice -n 10 mdtimeout 600 cargo test
# Run a specific module (seconds)
cargo test markdown_renderer
cargo test app
cargo test window_state
# Run with output
cargo test -- --nocapture
# Pre-release validation
.\scripts\prerelease.ps1
Visual Regression (Optional)
python -m pip install -r tools/regression/requirements.txt
python -m playwright install chromium
cargo build --release
python tools/regression/runner.py update-reference
python tools/regression/runner.py update-baseline
python tools/regression/runner.py run
Code Quality
# Format code (required before commits)
cargo fmt --all
# Lint with Clippy (zero warnings policy)
cargo clippy --all-targets -- -D warnings
# Check compilation without building
cargo check
# Run all quality checks
cargo fmt --all && cargo clippy --all-targets -- -D warnings && cargo test
Release Process
Tagged Releases:
# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0
This triggers the Release workflow which:
- Builds release binary and MSI installer on Windows
- Creates release artifacts:
mdmdview-vX.Y.Z-windows-x86_64.msi (installer)mdmdview-vX.Y.Z-windows-x86_64.zip (portable)
- Attaches artifacts to GitHub release
Manual Release:
- Go to Actions β Release β Run workflow
- Choose toolchain (
stable, beta, or nightly)
File Metadata (Windows)
Version information is auto-generated from Cargo.toml:
- ProductName/InternalName:
package.name
- FileDescription:
package.description
- FileVersion:
package.version (e.g., 0.3.3.0)
- CompanyName: First entry in
package.authors
- BuildDateTime: ISO-8601 timestamp at build time
Update Cargo.toml before release, then rebuild to refresh metadata.
π€ Contributing
Contributions are welcome! Please follow these guidelines:
Code Standards
- Zero Warnings Policy - Code must compile cleanly with no warnings
- Documentation - Each
.rs file needs a descriptive block comment explaining:
- File's purpose and functionality
- Key components/structures defined
- How it fits in the overall architecture
- Comments - Public functions and complex logic must be well-commented
- Test Coverage - New features should include unit tests
- Formatting - Run
cargo fmt before committing
- Linting - Run
cargo clippy and address all warnings
Contribution Workflow
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature
- Make your changes following code standards
- Run quality checks:
cargo fmt && cargo clippy && cargo test
- Test both debug and release builds
- Commit with clear, descriptive messages
- Push to your fork and submit a pull request
Testing Checklist
π Supported File Types
mdmdview recognizes these file extensions:
.md - Standard markdown.markdown - Alternative markdown extension.mdown - Common variation.mkd - Short markdown extension.txt - Plain text files
All files are processed as UTF-8 with lossy fallback for legacy encodings.
π Troubleshooting
Images Not Displaying
- Check file path - Relative paths resolved from markdown file location
- Verify format - Supported: PNG, JPEG, GIF, BMP, ICO, WebP, SVG
- Press F5 - Manually reload if live refresh doesn't trigger
- Check console - Error messages printed to stderr
Non-UTF-8 Files Show Strange Characters
mdmdview uses String::from_utf8_lossy for legacy encodings:
- Replacement characters (
U+FFFD) mark invalid bytes
- Save file as UTF-8 in text editor to fix permanently
- Warning emitted once to console/stderr
Mermaid Diagrams Not Rendering
Embedded mode:
- Ensure you did not build with
--no-default-features
- Ensure
assets/vendor/mermaid.min.js exists before building
- Check that diagram syntax is valid
Window Position Lost
State file may be corrupted:
- Windows: Delete
%APPDATA%\MarkdownView\window_state.txt
- Linux: Delete
~/.config/mdmdview/window_state.txt
- macOS: Delete
~/Library/Application Support/MarkdownView/window_state.txt
App will recreate with default centered window.
Performance Issues
- Large files - Files with 1000+ elements may render slowly
- Many images - Texture memory usage grows with image count
- Syntax highlighting - Code blocks in very large files may lag
Try breaking large documents into smaller files.
π Security Considerations
Safe Markdown Rendering
- No script execution - JavaScript in markdown is not executed
- Safe link handling - External links open in browser, not in-app
- Image loading - Only from local filesystem or explicit URLs
- No remote code - All rendering done locally
Mermaid Rendering
QuickJS mode (offline):
- JavaScript sandboxed in QuickJS runtime
- No network access during rendering
- Security level is hardcoded to strict
- Strict mode still allows inline Mermaid label tags:
<i>, <b>, <em>, <strong>, ``
- Recommended for sensitive/confidential content
π License
This project is licensed under the MIT License.
Third-Party Assets
Emoji Graphics:
Β© 2020 Twitter, Inc and other contributors
Licensed under CC-BY 4.0 (Twemoji)
See https://github.com/twitter/twemoji for details
Images embedded in executable for offline use
Mermaid:
Copyright (c) 2014-2024 Mermaid Team
Licensed under MIT
See https://github.com/mermaid-js/mermaid for details
JavaScript bundled in assets/vendor/mermaid.min.js
Dependencies
All Rust crates used are listed in Cargo.toml with their respective licenses (mostly MIT/Apache-2.0).
π Acknowledgments
- egui - Excellent immediate-mode GUI framework
- pulldown-cmark - Fast, CommonMark-compliant parser
- syntect - Comprehensive syntax highlighting
- Twemoji - Beautiful open-source emoji set
- Rust Community - Amazing ecosystem and tooling
π¬ Contact & Support