mdlive

mdlive

A lightweight markdown editor and live preview server. Point it at a file or directory, get instant rendered output with live reload. Edit, create, rename, delete -- all from the UI. Run it as a persistent daemon and switch between projects without spawning new processes.

Available as a native macOS app (DMG), a CLI tool, or both.

I built this to sit next to AI coding agents. When an agent writes markdown -- plans, architecture docs, research -- I'd rather read it rendered than squint at raw text in a terminal. But it works just as well as a standalone markdown workspace.

This started as a fork of Jose Fernandez's mdserve. The original idea and initial core implementation are his. I've since taken it in a different direction: in-browser editing, file CRUD, version history, workspace switching, keyboard shortcuts, theming, native desktop app. Different enough to warrant its own repo.

https://github.com/bearded-giant/mdlive/raw/main/docs/images/mdlive.mp4

Install

macOS app (recommended)

Download the DMG from the releases page or install via Homebrew:

brew install --cask bearded-giant/tap/mdlive-app

The app bundle includes both the native desktop app and the mdlive CLI. On first launch, the app will prompt for your password to symlink the CLI to /usr/local/bin/mdlive (or /opt/homebrew/bin/mdlive). This is a one-time setup so the mdlive command is available from your shell.

CLI only

brew install bearded-giant/tap/mdlive          # homebrew (macOS / Linux)
cargo install mdlive                           # from crates.io

Or grab a prebuilt binary from the releases page -- single binary, no runtime dependencies. Everything (templates, JS libraries, images) is embedded at compile time.

Claude Code plugin

mdlive is available as a Claude Code plugin. Once installed, Claude will automatically use mdlive to preview markdown when it makes sense -- plans, architecture docs, tables, diagrams, and anything that reads better rendered than raw.

/plugin install mdlive@bearded-giant/mdlive

Quick start

mdlive README.md         # single file, opens browser
mdlive docs/             # directory mode with sidebar
mdlive                   # daemon mode -- workspace picker

Single file view

Directory view

It watches for changes and reloads instantly via WebSocket. New files in directory mode get picked up automatically. The browser opens on launch by default (pass --no-open to suppress).

Running alongside an AI agent

Point mdlive at whatever directory the agent writes to. As the agent creates or updates markdown files, the browser reflects changes in real time.

mdlive scratch/ &        # background it, work alongside your agent

This is particularly useful for reviewing agent-generated plans, design docs, and research as they're being written.

Features

Viewing

GFM rendering with tables, task lists, strikethrough, and fenced code blocks. Syntax highlighting via highlight.js. Mermaid diagram rendering. YAML and TOML frontmatter is stripped before rendering. Images referenced in markdown are served inline (png, jpg, gif, svg, webp). Plain text and JSON files are also viewable and editable with syntax highlighting.

Themes

Five built-in themes: Catppuccin Mocha (default), Catppuccin Macchiato, Catppuccin Latte, Light, and Dark. Switch via the palette icon in the bottom-right corner. Selection is persisted to localStorage.

Editing

Every markdown file has a built-in editor accessible via the edit icon or the e shortcut. The editor is a split-pane view: raw markdown on the left, live preview on the right. The divider is draggable (persisted to localStorage). Scroll position syncs between panes. Ctrl+S saves, Esc closes. An unsaved-changes dot and beforeunload guard prevent accidental data loss.

File operations

Full CRUD from the browser. Create new files, rename/move existing ones, delete with confirmation. All operations available from both the right-click context menu (on sidebar items) and from buttons in the editor header. In single-file mode, right-click the content area for the context menu.

Revisions