The high-performance Markdown & Mermaid viewer your terminal deserves.
Render rich GitHub-flavored Markdown and standalone Mermaid diagrams (.mmd, .mermaid) with native inline graphics (Kitty, iTerm2, Sixel), responsive ANSI tables, Chroma syntax highlighting, and clickable OSC 8 links directly in your command line.
Built with an SRE Mindset
Most Markdown renderers break down on complex tables, drop raw escape codes, or crash when piped. mdee is architected from the ground up for stability and terminal aesthetics.
Multi-Protocol Inline Graphics
Renders PNG, JPEG, GIF, WebP, and SVG images directly inside your terminal grid using Kitty (\033_G), iTerm2 (OSC 1337), or DEC Sixel (\033Pq) protocols. Features in-memory PNG transcoding for Kitty, responsive cell sizing, and graceful box art fallback.
$ mdee --image-protocol kitty --image-width 80 architecture.md
Native Mermaid Diagrams & .mmd Files
Open standalone .mmd and .mermaid files directly or render embedded diagram blocks inside Markdown documents. Supports Kitty, iTerm2, and Sixel graphics with Catmull-Rom 2x HiDPI rasterization, auto-contrast cards, and pure-Go Unicode/ASCII fallback via built-in mmaid-go.
$ mdee architecture.mmd # or cat flow.mermaid | mdee -
OSC 8 Clickable Links
Terminal links render as native OSC 8 clickable hyperlinks. Hold Cmd and click any link to open the target URL directly in your browser without cluttering terminal output.
[GitHub](https://github.com/smford/mdee)
Unicode-Aware Responsive Tables
Uses Unicode grapheme cluster segmentation (uniseg) to accurately compute visual column widths for emojis, variation selectors, and East Asian characters. Dynamically allocates column budgets and wraps text at word boundaries without clipping.
$ mdee -w 80 --table-style rounded sla-matrix.md
Chroma Syntax Highlighting
Automatic language detection and TrueColor syntax highlighting across 200+ programming languages. Features rounded framed enclosures, optional line numbers, and built-in themes: Dracula, Monokai, Solarized Dark/Light, and Standard Dark/Light.
$ mdee --theme dracula -n script.py
Broken Pipe Resilience (EPIPE)
Piping into head -n 5 or grep terminates gracefully without Go runtime panics, stack traces, or broken pipe crashes.
Built-In Pager Integration
Seamlessly route long documentation through your favorite terminal pager (less -R -F -X) using --pager.
Scripting Plain Output
Use --plain to strip all ANSI escape sequences, borders, and colors for seamless parsing in automated bash/awk pipelines.
Persistent Config (~/.mdeerc)
Auto-loads ~/.mdeerc in YAML or JSON, point to custom configs with -c, or run mdee init to generate one.
Native Mermaid & .mmd File Display
Open standalone .mmd and .mermaid files directly or pipe them from stdin. Full multi-protocol graphics with zero configuration and zero external dependencies.
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Client Request (.mmd) ├────────►│ mdee Terminal Engine │
└────────────────┬────────────────┘ └────────────────┬────────────────┘
│ │
▼ ▼
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Kitty / iTerm2 / Sixel Image │ │ Pure-Go Unicode Fallback │
│ (2x Retina HiDPI Canvas) │ │ (mmaid-go Engine) │
└─────────────────────────────────┘ └─────────────────────────────────┘
Standalone .mmd & .mermaid Files
Pass any .mmd or .mermaid file path directly as an argument. mdee automatically recognizes the extension, wraps the diagram syntax, and renders it directly in your terminal grid.
$ mdee architecture.mmd
Pipe Streams & Stdin Diagrams
Pipe raw Mermaid diagrams straight from standard input using mdee -. Automatic diagram keyword detection recognizes flowcharts, sequence diagrams, and git graphs without requiring file extensions.
$ cat workflow.mmd | mdee -
Multi-Protocol High-Resolution Graphics
Renders crisp diagram images with 2x HiDPI Catmull-Rom resampling in Kitty (\033_G), Ghostty, WezTerm, iTerm2 (OSC 1337), and Sixel terminals with automatic background contrast cards.
$ mdee -m image --mermaid-scale 2.0 flow.mmd
Zero-Dependency Pure-Go Fallback
No Node.js, npm, or headless browser required! Built-in mmaid-go engine renders high-fidelity Unicode box art and 7-bit ASCII in standard terminals (Apple Terminal, Alacritty, tmux, SSH).
$ mdee -m unicode sequence.mermaid
Terminal Compatibility Matrix
First-class multi-protocol graphics and layout compatibility across macOS, Linux, and Windows terminal emulators.
| Terminal Emulator | Default Protocol | Display Output | Notes |
|---|---|---|---|
| Kitty | kitty | 🖼️ Native Inline Image | High-speed Kitty graphics (\033_G) with chunking |
| Ghostty | kitty | 🖼️ Native Inline Image | Native Kitty protocol preferred; OSC 1337 also supported |
| WezTerm | iterm2 | 🖼️ Native Inline Image | Full OSC 1337 and Kitty protocol support |
| iTerm2 | iterm2 | 🖼️ Native Inline Image | Native OSC 1337 inline image protocol |
| Foot | sixel | 🖼️ Native Inline Image | High-performance DEC Sixel bitmap graphics |
| mlterm | sixel | 🖼️ Native Inline Image | DEC Sixel bitmap protocol |
| mintty | iterm2 | 🖼️ Native Inline Image | Windows terminal with OSC 1337 and Sixel |
| Apple Terminal | none | 🔤 Unicode Box Art | Graceful fallback (no image protocol support) |
| Alacritty | none | 🔤 Unicode Box Art | Graceful fallback (no image protocol support) |
| CI/CD Runners | none | 🔤 Unicode Box Art / ASCII | Automated non-interactive TTY fallback |
| Output piped to file / grep | none | 📄 Clean Text | Safe TTY detection protects output files from binary graphics escape sequences |
See mdee in Action
Real terminal screenshots captured directly in macOS iTerm2.
Full Markdown Demo
Inline graphic badges, styled headings, code cards, and rounded table borders.
Microservice SLA Matrix
Auto-aligned columns, emoji health checks, and responsive word wrapping.
Terminal Diagnostics (mdee doctor)
Instant hardware, graphics protocol, Mermaid text engine, and config validation report with inline verification tests.
Mermaid Telemetry Diagrams
Failover topology diagram rendered with high-contrast light background (--mermaid-bg light).
Verify Your Terminal in Seconds
Run mdee doctor to audit terminal capabilities, truecolor depth, Mermaid engines, and inline graphics protocols.
╭──────────────────────────────────────────────────────────────╮ │ mdee - SRE Terminal Diagnostic & Capabilities │ ╰──────────────────────────────────────────────────────────────╯
╭──────────────────────────┬─────────────────┬─────────────────────────────────╮ │ Diagnostic Check │ Value │ Status │ ├──────────────────────────┼─────────────────┼─────────────────────────────────┤ │ OS / Architecture │ darwin / arm64 │ PASS │ │ Go Runtime Version │ go1.26.0 │ PASS │ │ Standard Output TTY │ true │ ENABLED │ │ Terminal Dimensions │ 120 cols x 35 │ INFO │ │ │ rows │ │ │ TERM_PROGRAM │ iTerm.app │ INFO │ │ TERM │ xterm-256color │ INFO │ │ Terminal Emulator │ iTerm2 │ DETECTED (iterm2 graphics) │ │ Inside tmux Session │ false │ No │ │ Active Graphics Protocol │ iterm2 │ iTerm2 Graphics (OSC 1337) │ │ Kitty Graphics (APC) │ false │ DISABLED │ │ OSC 1337 (iTerm2 │ true │ ENABLED │ │ Graphics) │ │ │ │ DEC Sixel Graphics (DCS) │ false │ DISABLED │ │ OSC 8 (Terminal Links) │ true │ ENABLED │ │ TrueColor (24-bit) │ true │ ENABLED │ │ Mermaid Protocol │ iterm2 │ iTerm2 Graphics (OSC 1337) │ │ Mermaid CLI (mmdc) │ false │ Not Found (Remote / Text │ │ │ │ fallback) │ │ Mermaid Text Engine │ mmaid-go │ READY (Pure-Go) │ │ Config File (~/.mdeerc) │ ~/.mdeerc │ LOADED │ ╰──────────────────────────┴─────────────────┴─────────────────────────────────╯
┌─────────────────────────┐ ┌───────────────────────┐ │ │ │ │ │ Terminal ├───►│ Mermaid │ │ │ │ │ └─────────────────────────┘ └───────────────────────┘
CLI Flags & Configuration
Tailor width constraints, themes, borders, and image behaviors to your workflow.
$ mdee [options] [file.md | file.mmd | file.mermaid | url | -]
| Flag | Shorthand | Default | Description |
|---|---|---|---|
| --config | -c | "" |
Custom config file path (auto-loads ~/.mdeerc if present) |
| --width | -w | 0 (auto-detect) |
Explicit terminal width constraint in columns (e.g. -w 80) |
| --theme | -t | "dark" |
Syntax theme: dark, light, dracula, monokai, solarized-dark, solarized-light, plain |
| --table-style | -s | "rounded" |
Border style: rounded, box, double, ascii, markdown, minimal |
| --images | -i | "auto" |
Inline image rendering: auto (detect protocol), always, never |
| --image-width | — | "auto" |
Image column constraint: auto, 100%, 80, 400px |
| --image-height | — | "auto" |
Image height constraint: auto, 20, 300px |
| --image-protocol | — | "auto" |
Image graphics protocol: auto, kitty, iterm2, sixel, none |
| --mermaid | -m | "auto" |
Mermaid render mode: auto, image, ansi, unicode, ascii, raw (supports .mmd & .mermaid files) |
| --mermaid-theme | — | "" |
Mermaid theme: dark, default, slate, blueprint, neon, neutral, forest |
| --mermaid-width | — | "auto" |
Mermaid display width constraint: auto (responsive cell-fit), 100%, 80, 800px |
| --mermaid-bg | — | "auto" |
Mermaid background canvas: auto, dark, light, transparent, #RRGGBB |
| --mermaid-scale | — | 2.0 |
HiDPI rasterization scale factor (1.0 - 4.0 for Retina sharpness) |
| --line-numbers | -n | false |
Display line numbers in code blocks |
| --hyperlinks | — | true |
Enable OSC 8 clickable terminal hyperlinks |
| --pager | — | false |
Route output through interactive pager ($PAGER or less -R -F -X) |
| --plain | — | false |
Strip all ANSI escapes and borders for clean scripting pipelines |
| --debug | — | false |
Emit SRE diagnostic log traces to stderr |
| --init-config | — | false |
Generate default ~/.mdeerc configuration file and exit |
Installation Options
Choose the package manager or build method that matches your environment.
🍺 Homebrew Tap (Recommended)
Directly install pre-built binaries for macOS (Apple Silicon & Intel) or Linux via custom tap:
brew install smford/tap/mdee
To upgrade later: brew update && brew upgrade mdee
🐹 Go Toolchain
Compile and install the latest tagged binary directly into your $GOPATH/bin:
go install github.com/smford/mdee/cmd/mdee@latest
Requires Go 1.24 or newer.
🛠️ Build From Source
Clone the repository and build using the dynamic Git-aware Makefile:
git clone https://github.com/smford/mdee.git
cd mdee
make build
# Binary at ./bin/mdee
Runs full suite via make test-race.