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

Every save creates a timestamped snapshot in a .mdlive/ directory next to your files. Open the revisions panel (h or r shortcut, or the Revisions button) to browse previous versions and restore any of them. You'll probably want to add .mdlive to your .gitignore unless you want revision history in your repo -- which can actually be handy for shared design docs or architecture decisions.

Directory mode

Pass a directory and mdlive recursively finds all .md, .markdown, .txt, and .json files, builds a collapsible tree sidebar with document tabs for quick switching between open files. Right-click folders to create files in specific subdirectories. The sidebar is resizable (drag the edge) and collapsible (k shortcut or the toggle button). Search the tree by pressing s.

Daemon mode

Run mdlive with no arguments and it starts in daemon mode -- a single long-running process you keep around. Instead of spawning a new process per directory, you switch between projects from the UI.

On first launch you get a workspace picker: type a path (directories and individual files both work, ~ expansion included), use the Browse button to navigate your filesystem, or click a recent entry. Once a workspace is loaded, everything works the same as direct mode -- sidebar, tabs, editing, revisions. Hit o or click the folder icon in the bottom-right to switch to a different workspace without restarting.

The recent workspaces list (up to 15 entries, FIFO) is stored at ~/.config/mdlive/config.toml. This is the only file mdlive writes outside of the directories you open.

Auto-start on login (macOS)

mdlive can install itself as a LaunchAgent so it starts automatically when you log in and stays running in the background.

mdlive service install              # install and start (port 3000)
mdlive service install -p 3030      # use a specific port
mdlive service start                # start the daemon
mdlive service stop                 # stop the daemon
mdlive service status               # check if it's running
mdlive service uninstall            # stop and remove

The plist lives at ~/Library/LaunchAgents/com.beardedgiant.mdlive.plist. Uninstalling removes it cleanly -- no system-level changes, nothing left behind.

Desktop app

The macOS desktop app wraps the same server in a native window via Tauri. No browser required. It launches in daemon mode with the workspace picker, and the bundled CLI means mdlive works from your terminal too.

The app automatically finds a free port (starting at 3000) and opens a WebKit webview. File watching, WebSocket reload, and everything else works identically to the browser experience.

Keyboard shortcuts

Press / to see all available shortcuts. Shortcuts are suppressed when typing in inputs, when modifier keys are held, and when dialogs are open.

Usage

mdlive                        # daemon mode with workspace picker
mdlive file.md                # serve a single file (port 3000)
mdlive docs/                  # directory mode with sidebar
mdlive docs/ -p 8080          # custom port
mdlive file.md --no-open      # don't auto-open the browser
mdlive file.md -H 0.0.0.0    # bind to all interfaces
mdlive service install        # auto-start on login (macOS)
mdlive service start          # start the daemon
mdlive service stop           # stop the daemon
mdlive service uninstall      # remove auto-start
mdlive service status         # check daemon status

Development

Rust 1.82+, 2021 edition. The project is a Cargo workspace with two crates: mdlive (library + CLI) and mdlive-app (Tauri desktop app). Templates and static assets are embedded at compile time (minijinja-embed, include_str!, include_bytes!), so changes to templates/ or static/ need a rebuild.

cargo build --release             # CLI binary
cargo test                        # all tests (99 unit + integration)
cargo test --test pages_test      # specific test file
cargo test test_server_starts     # by name
cargo tauri dev                   # run desktop app in dev mode
cargo tauri build                 # produce .dmg and .app bundle

See docs/architecture.md for internals.

License

MIT. See LICENSE.

Attribution

Based on mdserve by Jose Fernandez, MIT licensed. Original contributors are in the git history. Desktop app built with Tauri.