mdee

Terminal Markdown reader and editor: rendered preview with Tree-sitter highlighting, optional plain-text edit mode, and save to disk. Built with Bun and OpenTUI.

Requirements

• Bun (the CLI is a Bun script)

Install from this repo

bun install
bun link          # optional: adds `mdee` to your PATH

Usage

mdee path/to/file.md
# or, without linking:
bun src/index.ts path/to/file.md

Standalone binary

bun run compile              # writes dist/mdee (runs optional @opentui/core cross-platform install first)
bun run compile -- --skip-install   # after a normal bun install (e.g. in CI)
./dist/mdee path/to/file.md

Release tarballs (mdee-{mac|linux}-{arch}.tar.gz) contain the mdee binary from dist/; the GitHub Actions release workflow uses bun run compile.

If the file does not exist, mdee starts with an empty document; saving creates it. The window title is set to the file’s basename.

Keys

Key	Action
i	Enter edit mode (plain text; preview is hidden)
Esc	Leave edit mode (buffer is applied to the preview)
Ctrl+S / Cmd+S	Save to the file on disk
q	Quit (prompts if there are unsaved changes)
Ctrl+C	Same quit flow as q

When the quit prompt is open: Y save and exit, N discard and exit, Esc cancel.

Mouse scrolling is enabled in view mode where the terminal supports it.

Theme

By default, mdee uses system theme: transparent backgrounds and colors derived from your terminal palette. Works best with terminal transparency enabled (Ghostty, iTerm, Kitty, etc.).

mdee --theme system path/to/file.md   # default
mdee --theme dark path/to/file.md     # fixed dark palette
mdee --theme light path/to/file.md    # fixed light palette
MDEE_THEME=dark mdee path/to/file.md  # env default

If palette detection is unavailable (SSH, older terminals), mdee falls back to the static dark or light palette.

Remote install (optional)

The project site is mdee.bkh.dev. The repo root install script downloads the full installer from https://mdee.bkh.dev/install and runs it. Set MDEE_INSTALL_URL to another URL (for example a raw.githubusercontent.com link to your fork) if you do not use that host.

Develop

bun install
bun src/index.ts sample.md

Static landing page and installer sources live under web/.

TODO

• Fix cursor position display
• Fix cursor moving content
• Fix tree sitter wasm worker bun
• Add usage instructions
• Make lil announcement media content
• Add --version
• Fix download progress animation for linux
• mermaid support?