Markdown Peek

Markdown Peek (mdpeek) is a lightweight, repository-aware CLI tool that watches your markdown and renders it live — either in your browser or in an interactive terminal viewer.

• Features
• Quick Start
• Installation
• Configuration
• Status
• License

Features

Available now

• ⚡ Fast — a single binary with all assets embedded
• 🔄 Live, in-place updates — only the blocks you changed re-render (no full reload), your scroll position is kept, and changed blocks are briefly highlighted
• 🌐 Browser preview with a repository/worktree file explorer, outline + fuzzy heading search, a front matter panel, and light/dark themes
• 🔍 Two-file diff — source or rendered, unified or side-by-side, including the same file across worktrees/branches
• 🖥️ Interactive terminal viewer (TUI) — scrolling, wrapping, vim-style search, and live updates without flicker
• 📝 GitHub Flavored Markdown (GFM); GitLab Flavored Markdown (GLFM) planned
• ⚙️ Easy to configure via TOML (XDG)

Planned (roadmap)

mdpeek is growing from a strong markdown viewer into a tool that understands your documents and renders a UI tailored to each. Upcoming layers:

• 🧠 Semantic view — a document model with document-type detection and a side panel of outline / TODOs / risks / open questions.
• 🎛️ Generated UI — a UI generated per document type (design doc, README, ADR, meeting notes, runbook, changelog, …), first by rules and then by Claude (LLM).
• 📚 Non-developer document types — domain widgets for novels, contracts, and manufacturing/procedure docs (character roster, tolerance meter, step navigator, obligation matrix, glossary), with spoiler control.
• 🔗 Repository-aware checks — README ↔ code links, docs/code consistency, ADR ↔ git history, and TODO ↔ issue cross-references.
• 🧩 Editor & tooling integration — an IR-aware TUI renderer, a Neovim plugin, and GitHub preview integration.

Quick start

Preview in your browser

Run mdpeek with no arguments. It discovers the markdown in your current git repository (and any linked worktrees) and opens a browser preview with a file-explorer sidebar:

mdpeek
 INFO mdpeek::server: Listening on http://127.0.0.1:3030

Or point it at a single file: mdpeek serve path/to/file.md.

The preview updates in place as you edit — only the blocks that changed re-render (your scroll position is kept) and they are briefly highlighted. From the sidebar you can:

• switch between files across worktrees/branches (toggle grouping by worktree or branch),
• open a two-file diff with the ⇄ compare buttons — source or rendered, unified or side-by-side,
• toggle the outline (with fuzzy heading search), the color theme, and auto-scroll-to-change.

A breadcrumb shows which worktree/branch the open file belongs to.

Preview in your terminal

Use the term subcommand. On a TTY it opens an interactive full-screen viewer that live-updates as the file changes:

mdpeek term             # interactive viewer (watches by default on a TTY)
mdpeek term --no-watch  # render once and exit (also the default when piped)

Terminal viewer keybindings

Key	Action
q / Ctrl-c	quit
j / k, ↓ / ↑	scroll one line
Ctrl-d / Ctrl-u	half page down / up
PgDn / PgUp	page down / up
g / G	jump to top / bottom
/	search
n / N	next / previous match
Esc	clear search
?	toggle the keybindings help

Installation

cargo

cargo install markdown-peek

nix(Planed)

nix-shell -p markdown-peek --command mdpeek

npm(Planed)

npm install -g markdown-peek

download prebuild-binary

curl -SL https://github.com/takeshid/markdown-peek

Configuration

mdpeek reads an optional configuration file following the XDG Base Directory specification:

$XDG_CONFIG_HOME/mdpeek/config.toml

When XDG_CONFIG_HOME is unset, it falls back to ~/.config/mdpeek/config.toml. The file is optional; any missing key uses its built-in default. Settings are resolved with the following precedence:

CLI arguments  >  config file  >  built-in defaults

A different config file can be loaded with -c/--config, which overrides the default XDG location:

mdpeek --config ./my-config.toml
mdpeek -c ./my-config.toml term README.md

Options

Key	Values	Default	Description
default_mode	serve | term	auto (serve on a TTY, otherwise term)	Mode used when mdpeek is run without a subcommand
server.host	IP string	127.0.0.1	Address the browser preview binds to
server.port	port string	3030	Port the browser preview listens on
server.theme	light | dark	light	Default browser preview theme
term.theme	glow | mono | catputtin | dracura | solarized | nord | ayu	glow	Default terminal color theme
term.pager	command string	$PAGER, else less -R	Pager for long terminal output; set to "" to disable paging

Example

See config.example.toml for a complete, commented example. To get started:

mkdir -p ~/.config/mdpeek
cp config.example.toml ~/.config/mdpeek/config.toml

default_mode = "serve"

[server]
host = "127.0.0.1"
port = "3030"
theme = "light"

[term]
theme = "glow"
pager = "less -R"

Status

Viewer

• Live in-place updates with changed-block highlighting
• Repository + worktree file explorer sidebar (group by worktree / branch)
• Breadcrumb showing the active file's worktree/branch
• Outline panel with fuzzy heading search
• Front matter panel
• Two-file diff (source / rendered, unified / split; across worktrees)
• Interactive terminal viewer (scroll, wrap, vim-style search, live update)

GFM

• Table
• TaskList
• Strike throough
• Fenced Code
• Syntax Hightlight
• Emoji
• Alert
• MathJax
• Color Model
• Auto Link
• InPage Link
• Footnote
• Table of Contents
• Theme Switch(Light/Dark)

GLFM(Planed)

• Table
• Strike throough
• TaskList
• Fence Code
• Syntax Hightlight
• Auto Link
• Emoji
• Alert
• Math equation

Terminal

• Table
• TaskList
• Strike throough
• Fenced Code
• Syntax Hightlight
• Emoji
• Alert
• Math Equation
• Color Model
• Footnote

License

MIT License. LICENSE.