https://github.com/aydiler/md-viewer
Fast, lightweight markdown viewer for Linux with tabs, file explorer, and live reload
https://github.com/aydiler/md-viewer
desktop-app egui file-explorer linux markdown markdown-viewer rust syntax-highlighting wayland x11
Last synced: 11 days ago
JSON representation
Fast, lightweight markdown viewer for Linux with tabs, file explorer, and live reload
- Host: GitHub
- URL: https://github.com/aydiler/md-viewer
- Owner: aydiler
- License: mit
- Created: 2026-01-21T01:32:05.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-15T03:45:43.000Z (20 days ago)
- Last Synced: 2026-05-15T04:43:30.277Z (20 days ago)
- Topics: desktop-app, egui, file-explorer, linux, markdown, markdown-viewer, rust, syntax-highlighting, wayland, x11
- Language: Rust
- Size: 4.78 MB
- Stars: 11
- Watchers: 1
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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 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](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
### 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.
```bash
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
```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--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 (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](https://github.com/emilk/egui) - Immediate mode GUI framework
- [egui_commonmark](https://github.com/lampsitter/egui_commonmark) - Markdown rendering (vendored fork with typography improvements)
- [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