A quick-look Markdown viewer for the Wayland desktop.
Open a README without breaking flow. Launches fast, doesn't pin your terminal, gets out of your way.
Hosted on both github.com/beleon/mdview and codefloe.com/beleon/mdview
- Near-instant startup for quick looks at
.mdfiles - Native Wayland window that gets out of your way
- Detaches from the shell by default, so your terminal stays free
- Real Markdown rendering: headings, tables, links, images, anchors, and highlighted code blocks
- Follow local
.mdlinks and[[wiki]]links in place, with back/forward history - Find, live reload, dark mode, zoom, text selection, and outline sidebar
- Keyboard, mouse, and touchpad-friendly navigation
- No GTK, Qt, Electron, Tauri, browser engine, or XWayland fallback
Developers swim in .md files: READMEs, design notes, runbooks, the
random NOTES.md in every project. You're in the terminal. You want to
actually read one. The options aren't great:
less/vim— fine for skimming, but it's raw text. No heading hierarchy, no tables, no anchors, no code-block highlighting.pandoc/asciidoctor→ browser — too many steps for a glance. By the time you've set it up the moment's gone.- Electron viewers — slow to launch, heavy on memory, often tie up the terminal you ran them from.
mdview is the missing middle. It opens in milliseconds, detaches from
the launching shell so your terminal is free, and gives you a real
renderer with syntax-highlighted code, an outline sidebar, live reload,
dark mode, and a proper find bar. Run it side-by-side with your terminal;
treat it like less for .md files.
The cost is low enough that you'll actually use it.
- Native Wayland. First-class
xdg-shell,wp_cursor_shape_v1,xdg-toplevel-icon-v1,pointer-gestures-unstable-v1,xdg-decoration-unstable-v1. No XWayland fallback. - Frameworkless. No GTK, Qt, Electron, Tauri, or browser engine.
The whole UI is direct Cairo draw calls onto a
wl_shmbuffer. - Drops into any modern Wayland desktop. GNOME, KDE Plasma, Sway, Hyprland. Only links against libraries already loaded in every Wayland session.
.md file ──▶ md4c (Markdown→HTML) ──▶ litehtml (HTML/CSS→layout) ──▶ Cairo+Pango (render)
│
┌──────┘
▼
libwayland-client + xdg-shell
(window, input, shared memory)
 Find bar (light mode). Case / whole-word / regex, full text-cursor editing. |
 Outline sidebar (dark mode). Ctrl+T. h1–h3, click to jump.
|
./build.shProduces dist/mdview. The binary is self-contained: icons baked in, no runtime data files.
sudo apt install libwayland-dev libwayland-cursor0 wayland-protocols libxkbcommon-dev \
libcairo2-dev libpango1.0-dev libgdk-pixbuf-2.0-dev
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build buildRequires CMake ≥ 3.16 and a C++17 compiler.
./mdview --install # writes binary, icons, .desktop entry under ~/.local/
./mdview --uninstall # undoes the above--install is XDG-compliant: binary lands in ~/.local/bin, icons go under ~/.local/share/icons/hicolor/<size>/apps/, the .desktop file under ~/.local/share/applications/.
mdview path/to/document.md| Flag | Action |
|---|---|
--no-highlight |
Disable syntax highlighting of code blocks |
--no-reload |
Disable live-reload on file change |
-f / --foreground |
Stay attached to the launching terminal |
--install |
Install binary + icons + .desktop under ~/.local/ |
--uninstall |
Undo --install |
-h / --help |
Show usage |
Env vars:
MDVIEW_NO_HIGHLIGHT=1suppresses syntax highlighting globally.MDVIEW_DEBUG=1prints a startup perf report (phase timings, RSS, doc stats) to stderr at first paint. Combine with-fso stderr stays attached to your terminal:MDVIEW_DEBUG=1 mdview -f doc.md.
| Key | Action |
|---|---|
j / ↓ |
Scroll down |
k / ↑ |
Scroll up |
Space / PageDown |
Page down |
Shift+Space / PageUp |
Page up |
g / Home |
Top of document |
G / End |
Bottom of document |
Ctrl+C |
Copy selection to clipboard |
Ctrl+A |
Select all text |
Ctrl+F |
Open find bar |
Enter / F3 |
Next match (while find bar is open) |
Shift+Enter / Shift+F3 |
Previous match |
Alt+C / Alt+W / Alt+R |
Toggle case-sensitive / whole-word / regex (in find bar) |
Ctrl+Backspace / Ctrl+W |
Delete word (in find bar) |
Ctrl++ / Ctrl+= |
Increase text size (reflows) |
Ctrl+- |
Decrease text size |
Ctrl+0 |
Reset text size + zoom |
Ctrl+T |
Toggle outline (TOC) sidebar |
Ctrl+D |
Toggle dark mode |
Alt+← / Backspace |
Back through followed links |
Alt+→ / Shift+Backspace |
Forward |
F1 / ? |
Toggle help overlay |
q |
Quit |
Escape |
Close find / help / context menu (doesn't quit) |
- Wheel — scroll
- Shift+wheel — horizontal scroll
- Ctrl+wheel — zoom
- Pinch (touchpad) — zoom
- Click + drag — select text · double-click word · triple-click line
- Click on link — open in browser, scroll to
#anchor, or follow a local.md/wiki link in place (back/forward viaAlt+←/Alt+→) - Right-click — context menu (Open Link / Copy / Select All / Find / Reload / Toggle Dark)
- Title bar drag — move window (CSD mode) · double-click to toggle maximize
mdview keeps two files under ~/.config/mdview/:
state— machine-managed. Per-file scroll / zoom / text-size LRU (hashed paths, last 20 files), last window size, dark mode, search flags. Rewritten on every close; don't edit by hand.config— user-editable. Defaults for newly-opened files only; the LRU always wins for files you've already adjusted. Optional: if missing, built-in defaults apply.
# ~/.config/mdview/config
font_size = 16 # body font-size in px (8..48)
zoom = 1.0 # pinch-zoom level, 1.0 = 100% (1.0..5.0)# comments and whitespace around = are tolerated.
mdview negotiates server-side decorations via xdg-decoration-unstable-v1. Compositors that support it (KDE Plasma, Sway, Hyprland, …) draw their own title bar. If the compositor doesn't support the protocol or requests client-side decorations (e.g. GNOME/Mutter), mdview draws a minimal dark title bar with a close button.
Only libraries already loaded in any Wayland session:
| Library | Why |
|---|---|
libwayland-client.so |
Wayland protocol |
libwayland-cursor.so |
Cursor theme; only loaded on compositors without wp_cursor_shape_v1 |
libxkbcommon.so |
Keyboard layout & keysyms |
libcairo.so |
2D rendering |
libpangocairo-1.0.so / libpango-1.0.so |
Text shaping & layout |
libgdk_pixbuf-2.0.so |
Raster image loading (PNG/JPG/GIF) |
SVG support is provided by lunasvg
- plutovg, vendored under
thirdparty/lunasvg/and statically linked. No runtime dependency on librsvg / glib-gobject / libxml2 / ICU.
Designed by Leon Becker; implementation largely by Claude Code. The project's structure, scope, and design decisions are mine; most of the code itself was produced by Claude under my direction.
Markdown viewing has a small but varied ecosystem. A few neighbours and how they differ:
- glow — terminal TUI viewer. Excellent if you want to stay inside the terminal entirely and skip rendering altogether.
- mdcat — terminal "cat for markdown" with syntax highlighting. Stream-style, no scrolling UI.
- litemdview — GUI viewer in the same spirit (also embeds litehtml), built on GTKmm 3.
mdview occupies the Wayland-native, frameworkless-GUI niche.
mdview is MIT-licensed. See LICENSE.
Bundled / linked dependencies:
| Component | License |
|---|---|
| litehtml | BSD-3-Clause |
| md4c | MIT |
| lunasvg, plutovg | MIT |
| Cairo, Pango, Wayland | LGPL |