md-viewer
A fast, lightweight markdown viewer for Linux built with Rust and egui. Designed for distraction-free reading with excellent typography, syntax highlighting, and LaTeX math — from quick notes to scientific papers.
Features
Rendering
- GitHub Flavored Markdown - Full GFM support including tables, task lists, footnotes, and recognized emoji shortcodes such as
:pushpin: - LaTeX Math - Inline
$…$and display$$…$$equations rendered via typst + mitex — fractions, sub/superscripts,\boxed, accents, matrices, and more — sized and baseline-aligned to the surrounding text - 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
- Open Folder - Use File → Open Folder… to choose and persist the file explorer root
- 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)
- Keyboard Scrolling - Scroll documents with ↑/↓ by line or Page Up/Page Down by page when the find bar is closed
- 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 and folder picker integration
- Welcome Page & Recent Files - Open files or folders from the idle screen and reopen recent documents
- Session Persistence - Remembers open tabs, theme, zoom, and sidebar state
- Cross-Platform - Works on X11 and Wayland
Screenshots
Scientific paper — math, tables, figures, and navigation
A DESI dark-energy paper: display & inline LaTeX equations, a data table with math headers, an embedded figure, the file explorer, and the click-to-navigate outline — all at once
Same document, light mode
The χ² comparison table, inline math, and the BAO-fit figure rendered on the light theme
Figures, equations, and lists together
Embedded plots with math captions, a checklist with inline equations and emoji, and both sidebars
Dark Mode — Diagrams & Tables
Mermaid flowchart, tech-stack table, file explorer, and outline sidebar
Syntax Highlighting
Rust and YAML code blocks with semantic coloring and a mermaid sequence diagram
Light Mode — Prose & Code
Documentation with bullet lists, blockquotes, inline code, and bash code blocks
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
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% |
| ↑ / ↓ (when find bar is closed) | Scroll document up/down by line |
| Page Up / Page Down | Scroll document up/down by page |
| Ctrl+Scroll | Zoom with mouse wheel |
| Shift+Scroll over a wide table | Scroll the table horizontally |
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 the binary to ~/.local/bin plus bundled third-party notices under ~/.local/share/licenses/md-viewer. No compilation, takes seconds.
|
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
Auto-updates via snapd.
Arch Linux (AUR)
Builds from the latest main commit (rolling) — your system update grabs new versions automatically.
Flatpak / Flathub
Once published to Flathub:
(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
Compiles locally (~2–3 minutes). Update with cargo install --force md-viewer. Requires the system dependencies listed below.
From Source
System Dependencies (Arch Linux)
Only needed for cargo install / building from source:
Usage
# Open a file and return the terminal prompt (live reload is enabled by default)
# Keep the viewer attached to the terminal for debugging/logs
# Disable live reload
Run md-viewer with no file to start on the welcome page, then choose Open File, Open Folder, or a recent document. In the app, use File → Open File… or Ctrl+O to open a document, and File → Open Folder… to choose the file explorer root.
When launched from a terminal, md-viewer detaches by default so the shell prompt is available while the window stays open. Use --foreground when you want terminal logs or blocking process behavior.
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, math, and alignment improvements)
- emojis - GitHub/gemoji shortcode lookup data (
(MIT OR Apache-2.0) AND Unicode-3.0; seeTHIRD_PARTY_NOTICES) - typst + mitex - LaTeX math rendering (LaTeX → typst → rasterized inline)
- merman - Mermaid diagram rendering
- syntect - Syntax highlighting
- notify - File watching
- rfd - Native file dialogs
License
MIT