md-viewer

A fast, lightweight markdown viewer for Linux built with Rust and egui. Designed for distraction-free reading with excellent typography and syntax highlighting.

Features

Rendering

• GitHub Flavored Markdown - Full GFM support including tables, task lists, and footnotes
• Syntax Highlighting - 200+ languages via syntect with beautiful color schemes
• Mermaid Diagrams - Flowcharts, sequence diagrams, and more rendered natively via merman (click to enlarge)
• Resizable Table Columns - Drag column dividers to fit content (new in v0.1.5)
• HTML Tables - Rendered as formatted grids with proper cell padding
• Images & SVG - Embedded and remote image support (PNG, JPEG, GIF, SVG, HTTP URLs)
• Unicode Support - System font fallbacks (Noto, DejaVu) for emojis, CJK, and non-Latin scripts
• 60 FPS Rendering - Viewport virtualization keeps scroll smooth on 100k+ line docs
• Typography - 1.5x line height for optimal readability (WCAG 2.1 compliant)

Navigation

• Tab System - Open multiple documents with tab bar (Ctrl+Click links to open in new tab)
• In-Document Search (Ctrl+F) - Find bar with inline highlights, Enter/Shift+Enter to cycle matches
• File Explorer - Hierarchical sidebar with lazy-loading directories and sorting options
• Outline Sidebar - Click-to-navigate table of contents from document headers
• Navigation Buttons - Back/forward buttons in title bar for quick history navigation
• Per-Tab History - Independent back/forward navigation within each tab (Alt+Left/Right)
• Internal Links - Navigate between markdown files with relative links

View

• Dark & Light Themes - Toggle with Ctrl+D
• Zoom - 50% to 300% zoom (Ctrl++/-/0 or Ctrl+Scroll)
• Live Reload - Auto-refresh on file changes (enabled by default)

Usability

• Drag and Drop - Drop markdown files onto the window to open
• Native Dialogs - System file picker integration
• Session Persistence - Remembers open tabs, theme, zoom, and sidebar state
• Cross-Platform - Works on X11 and Wayland

Screenshots

Dark Mode

Mermaid flowchart, tech stack table, file explorer, and outline sidebar

Dark Mode -- Syntax Highlighting

Rust and YAML code blocks with semantic coloring, mermaid sequence diagram

Light Mode

Documentation with bullet lists, blockquotes, inline code, and bash code blocks

Light Mode -- API Docs

JSON syntax highlighting, inline code rendering, and outline navigation

Light Mode -- Tables & Lists

Troubleshooting table with inline code in cells, ordered list, and resizable columns (drag dividers)

Search (Ctrl+F)

Find bar with inline highlights and match counter; Enter / Shift+Enter to cycle

Resizable Table Columns

Drag column dividers to fit wide content (new in v0.1.5)

Keyboard Shortcuts

Tab Management

Shortcut	Action
Ctrl+T	New tab (open file dialog)
Ctrl+W	Close current tab
Ctrl+Tab	Next tab
Ctrl+Shift+Tab	Previous tab
Ctrl+1-9	Switch to tab 1-9

Navigation

Shortcut	Action
Ctrl+O	Open file dialog
Alt+Left	Navigate back in history
Alt+Right	Navigate forward in history
Click link	Navigate in current tab
Ctrl+Click link	Open link in new tab

Search

Shortcut	Action
Ctrl+F	Open find bar (or refocus if already open)
Enter / ↓	Jump to next match
Shift+Enter / ↑	Jump to previous match
Esc	Close find bar and clear highlights

View

Shortcut	Action
Ctrl+D	Toggle dark/light mode
Ctrl+Shift+E	Toggle file explorer
Ctrl+Shift+O	Toggle outline sidebar
Ctrl++ / Ctrl+=	Zoom in
Ctrl+-	Zoom out
Ctrl+0	Reset zoom to 100%
Ctrl+Scroll	Zoom with mouse wheel

File Operations

Shortcut	Action
F5	Toggle file watching
Ctrl+Q	Quit application

Installation

Quick Install (Linux / macOS) — recommended

Downloads the prebuilt binary for your platform, verifies its SHA256, and installs to ~/.local/bin. No compilation, takes seconds.

curl -fsSL https://raw.githubusercontent.com/aydiler/md-viewer/main/scripts/install.sh | sh

Supports Linux x86_64 and macOS arm64 (Apple Silicon). Set INSTALL_DIR=/usr/local/bin to install elsewhere. Intel Macs need to build from source via cargo install md-viewer.

macOS Gatekeeper note: binaries are not yet signed/notarized. If macOS refuses to run the app, run: xattr -d com.apple.quarantine ~/.local/bin/md-viewer

Snap Store

sudo snap install md-viewer

Auto-updates via snapd.

Arch Linux (AUR)

yay -S md-viewer-git    # or: paru -S md-viewer-git

Builds from the latest main commit (rolling) — your system update grabs new versions automatically.

Flatpak / Flathub

Once published to Flathub:

flatpak install flathub io.github.aydiler.md-viewer

(Flathub submission in progress — see flatpak/ and PUBLISHING.md.)

Windows

Download md-viewer-<version>-windows-x86_64.zip from the latest release, extract md-viewer.exe, and run it. Verify the included .sha256 if you'd like.

Cargo (crates.io) — slower, builds from source

cargo install md-viewer

Compiles locally (~2–3 minutes). Update with cargo install --force md-viewer. Requires the system dependencies listed below.

From Source

git clone https://github.com/aydiler/md-viewer
cd md-viewer
cargo build --release
make install   # installs to ~/.local/bin (optional)

System Dependencies (Arch Linux)

Only needed for cargo install / building from source:

sudo pacman -S --needed \
    base-devel clang pkg-config \
    libxcb libxkbcommon openssl \
    gtk3 fontconfig dbus zenity \
    xdg-desktop-portal xdg-desktop-portal-gtk

Usage

# Open a file (live reload is enabled by default)
md-viewer README.md

# Disable live reload
md-viewer README.md --no-watch

Technical Details

• Binary size: ~35 MB (includes syntax highlighting, mermaid renderer, math rendering, image support, X11+Wayland). ~7 MB as snap.
• Startup time: < 200ms
• Rendering: 60 FPS with viewport-based clipping
• Memory: Uses mimalloc for improved allocation performance
• Platform: Linux (X11 and Wayland via glow backend)

Built With

• eframe/egui - Immediate mode GUI framework
• egui_commonmark - Markdown rendering (vendored fork with typography improvements)
• merman - Mermaid diagram rendering
• syntect - Syntax highlighting
• notify - File watching
• rfd - Native file dialogs

License

MIT