# md-viewer
[](https://crates.io/crates/md-viewer)
[](https://aur.archlinux.org/packages/md-viewer-git)
[](https://snapcraft.io/md-viewer)
[](https://opensource.org/licenses/MIT)
[](https://github.com/aydiler/md-viewer/stargazers)
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, and footnotes
- **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](https://github.com/Latias94/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
### 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
| 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
| 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
| 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
| 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 |
| Shift+Scroll over a wide table | Scroll the table horizontally |
### File Operations
| 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.
```bash
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
```bash
sudo snap install md-viewer
```
Auto-updates via snapd.
### Arch Linux (AUR)
```bash
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:
```bash
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](https://github.com/aydiler/md-viewer/releases/latest), extract `md-viewer.exe`, and run it. Verify the included `.sha256` if you'd like.
### Cargo (crates.io) — slower, builds from source
```bash
cargo install md-viewer
```
Compiles locally (~2–3 minutes). Update with `cargo install --force md-viewer`. Requires the system dependencies listed below.
### From Source
```bash
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:
```bash
sudo pacman -S --needed \
base-devel clang pkg-config \
libxcb libxkbcommon openssl \
gtk3 fontconfig dbus zenity \
xdg-desktop-portal xdg-desktop-portal-gtk
```
## Usage
```bash
# Open a file and return the terminal prompt (live reload is enabled by default)
md-viewer README.md
# Keep the viewer attached to the terminal for debugging/logs
md-viewer --foreground README.md
# Disable live reload
md-viewer README.md --no-watch
```
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](https://github.com/emilk/egui) - Immediate mode GUI framework
- [egui_commonmark](https://github.com/lampsitter/egui_commonmark) - Markdown rendering (vendored fork with typography, math, and alignment improvements)
- [typst](https://github.com/typst/typst) + [mitex](https://github.com/mitex-rs/mitex) - LaTeX math rendering (LaTeX → typst → rasterized inline)
- [merman](https://github.com/Latias94/merman) - Mermaid diagram rendering
- [syntect](https://github.com/trishume/syntect) - Syntax highlighting
- [notify](https://github.com/notify-rs/notify) - File watching
- [rfd](https://github.com/PolyMeilex/rfd) - Native file dialogs
## License
MIT