mdmdview

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.

• 🚀 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

• 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

• 🔄 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

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)

• Rust 1.70+ - Install from rustup.rs
• Operating System - Windows 10/11, Linux (Ubuntu 20.04+, Fedora 35+), or macOS 10.15+

1. Go to Releases
2. Download mdmdview-vX.Y.Z-windows-x86_64.msi
3. 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
4. Upgrading: run a newer MSI and the old version is removed automatically

1. Go to Releases
2. Download the ZIP for your platform:
   • mdmdview-vX.Y.Z-windows-x86_64.zip (Windows)
3. Extract and run the executable — no installation required

# 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

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

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

Render a markdown file directly to an image:

mdmdview --screenshot document.md --output out.png

Optional flags:

• --width <px> / --height <px>: viewport size (default 1280x720 in screenshot mode)
• --theme light|dark: override theme for render
• --zoom <scale>: scale factor (e.g., 1.25)
• --content-only: hide window chrome in the capture
• --scroll <ratio>: scroll ratio from 0.0 (top) to 1.0 (bottom)
• --wait-ms <ms>: delay before capture to allow assets to load
• --settle-frames <n>: extra frames to wait for layout stability
• --test-fonts <dir>: load fonts from a directory (QA/automation use)

Associate mdmdview with .md files for double-click opening:

1. Right-click any .md file in Windows Explorer
2. Select "Open with > Choose another app"
3. Click "More apps" → "Look for another app on this PC"
4. Browse to mdmdview.exe and select it
5. Check "Always use this app to open .md files"
6. Click OK

Now all .md files will open in mdmdview by double-clicking!

• 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

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

mdmdview supports all CommonMark elements with professional 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

• 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

• Syntax highlighting for 100+ languages
• Rust, Python, JavaScript, C++, Go, TypeScript, SQL, and more
• Proper indentation and color schemes
• Line-based rendering for readability

• 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

• 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.

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.

Example:

# Enable debug logging
RUST_LOG=debug mdmdview document.md

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.

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

1. Main Entry Point (src/main.rs)

   • eframe/egui application setup
   • Command-line argument parsing
   • Window configuration with icon
   • Cross-platform initialization

2. 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

3. 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

4. Window State (src/window_state.rs)

   • Platform-specific persistence
   • Geometry validation and sanitization
   • Registry storage on Windows
   • Config file storage on Linux/macOS

5. Build Script (build.rs)

   • Windows resource file generation
   • Version info from Cargo.toml
   • Icon embedding
   • Mermaid.js embedding for embedded renderer

• 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 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)

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.

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

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

# 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

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:

1. Builds release binary and MSI installer on Windows
2. Creates release artifacts:
   • mdmdview-vX.Y.Z-windows-x86_64.msi (installer)
   • mdmdview-vX.Y.Z-windows-x86_64.zip (portable)
3. Attaches artifacts to GitHub release

Manual Release:

• Go to Actions → Release → Run workflow
• Choose toolchain (stable, beta, or nightly)

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.

Contributions are welcome! Please follow these guidelines:

1. Zero Warnings Policy - Code must compile cleanly with no warnings
2. 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
3. Comments - Public functions and complex logic must be well-commented
4. Test Coverage - New features should include unit tests
5. Formatting - Run cargo fmt before committing
6. Linting - Run cargo clippy and address all warnings

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes following code standards
4. Run quality checks: cargo fmt && cargo clippy && cargo test
5. Test both debug and release builds
6. Commit with clear, descriptive messages
7. Push to your fork and submit a pull request

• All existing tests pass
• New tests added for new features
• Tested with large markdown files (1000+ elements)
• Tested with images and embedded content
• Verified keyboard shortcuts work correctly
• Checked memory usage with many images
• Tested on target platforms (Windows/Linux/macOS)

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.

• 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

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

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

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.

• 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.

• 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

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>, <br>
• Recommended for sensitive/confidential content

This project is licensed under the MIT License.

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

All Rust crates used are listed in Cargo.toml with their respective licenses (mostly MIT/Apache-2.0).

• 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

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Pull Requests: Contributions welcome!