Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI & keys

mdpad is a CLI tool; this page is its canonical interface reference: command line, keys, environment variables and exit behavior. New here? Start with Getting started.

Synopsis

mdpad [OPTIONS] [FILE]

FILE is a markdown file, or - to read from stdin. With no argument, mdpad reads stdin when it is piped. When stdout is not a terminal (a pipe or redirect), mdpad prints the rendered document instead of opening the viewer.

Options

FlagEffect
-p, --printrender to stdout instead of opening the viewer
-w, --width <N>render width in columns (default: terminal width; minimum 20)
--color <auto|always|never>color policy; auto strips colors when stdout is piped (default: auto)
--lightlight theme (default: dark)
--asciiASCII-only glyphs, no box drawing or unicode bullets
--urlsalways show link URLs inline after the link text
--prose-width <N>cap prose line length for readability (default 100; 0 = full width)
--no-highlightdisable code syntax highlighting
--no-mousenever capture the mouse (keeps terminal-native selection)
-h, --helpprint help
-V, --versionprint version

Viewer keys

KeyAction
j / k, ↓ / ↑scroll one line (Enter also scrolls down)
Space / b, PgDn / PgUp, fscroll one page
d / uscroll half page
g / G, Home / Endgo to top / bottom
/incremental search; Enter confirms, Esc cancels
n / Nnext / previous search match
ttable of contents (j/k move, Enter jumps, Esc closes)
Lshow/hide link URLs inline
mouse click on a linkfollow it: local files open in the viewer, #anchors jump to their heading, URLs open in the browser/OS handler
Backspacego back to the document you followed a link from
mouse wheelscroll (3 lines per notch)
mouse dragselect text; copied to clipboard on release (details)
Ctrl+Ccopy the current selection again; without a selection, quit
Escclear search and selection / close overlay
mtoggle mouse capture (off = terminal-native selection)
eopen the built-in editor
Eopen $VISUAL/$EDITOR, reload on exit
rreload the file from disk
?help overlay
qquit

Link following needs mouse capture (on by default; m toggles). Relative link targets resolve against the current document’s directory — against the working directory for stdin documents. The back history is kept in memory, so Backspace returns to a piped document too. Destinations with a URI scheme (https:, mailto:, …) are handed to the OS handler.

Mermaid code blocks get a view in browser link on their label line: clicking it opens the diagram rendered in the mermaid.live viewer (the source travels in the URL fragment and is not sent to any server). See the FAQ for why diagrams are not drawn in the terminal.

Editor keys

KeyAction
Ctrl+Ssave (atomic: temp file + rename) and re-render
Escback to viewer (asks to save/discard/cancel if unsaved)
Ctrl+Z / Ctrl+Yundo / redo

Editing is disabled for stdin documents (there is no file to save to). CRLF line endings, missing final newlines and UTF-8 BOMs round-trip byte-identical through an open/save cycle; files with mixed line endings warn that saving unifies them.

Environment variables

VariableEffect
NO_COLORdisables all color output (viewer and print mode)
COLORTERMwhen it advertises truecolor/24bit, syntax highlighting uses RGB; otherwise colors quantize to the 256-color palette
COLUMNSrender width when output is piped and no --width is given
VISUAL, EDITORexternal editor for E (checked in that order; may contain arguments, runs through the shell)

Exit behavior

  • Exit code 0 on success, 1 on errors (unreadable file, no input); errors print to stderr as mdpad: <message>.
  • Broken pipes in print mode (mdpad x.md | head) exit cleanly.
  • The terminal is always restored on exit — including panics and termination signals (SIGTERM/SIGHUP/SIGINT quit like q) — so a crash or a kill never leaves your shell in raw mode.
  • If the terminal itself disappears (emulator crash, orphaned pty), the viewer notices the hangup and exits immediately instead of lingering.

See also