cargo install mdv

This installs the latest published release from crates.io into your Cargo bin directory.

git clone https://github.com/WhoSowSee/mdv.git
cd mdv
cargo install --path .

The command above builds mdv and places the binary into the Cargo bin directory (usually ~/.cargo/bin).

cargo build --release
./target/release/mdv README.md

Use the mdv binary from target/release directly or add it to your PATH.

mdv [OPTIONS] [FILE]

Also, mdv supports reading from standard input (stdin) and working in pipelines

mdv [OPTIONS] -
cat <FILE> | mdv

• -H, --html — prints HTML instead of terminal formatting.
• -A, --no-colors — strips ANSI styling regardless of the selected theme.
• -C, --hide-comments — removes Markdown comments from the rendered output.
• -i, --theme-info [FILE] — shows the active palette; when FILE is provided it renders the file along with palette information.
• -f, --from <TEXT> — starts rendering from the first match of <TEXT>. Adding :<lines> limits the number of lines (for example --from "Install:20").
• -r, --reverse — renders the document starting from the end while keeping block formatting intact.
• -p, --pager — opens the rendered output in the built-in minus pager. Press E|e or У|у to open the current file in the configured editor; saved changes are rendered automatically.
• -m, --monitor — watches the source file and re-renders when it changes.
• -F, --config-file <CONFIG_DIR> — reads configuration from the provided directory.
• -n, --no-config — skips loading configuration files (uses CLI options and defaults only).
• -G, --init-config [CONFIG_DIR] — creates the default config file. Uses the provided directory, --config-file, MDV_CONFIG_PATH, or the default config directory.

• -t, --theme <NAME> — chooses a built-in theme (default terminal).
• -T, --code-theme <NAME> — sets the syntax highlight palette (default terminal).
• -s, --code-block-style <simple|pretty> — switches between a single gutter and a boxed frame for code blocks (default pretty).
• -y, --custom-theme <key=value;...> — overrides UI colors on top of the selected theme.
• -Y, --custom-code-theme <key=value;...> — overrides syntax colors using the same format as --custom-theme.

• --callout-style <pretty|simple>[:show-icons;fold-icons;label-inside;uppercase] — sets the callout layout and label behavior. label-inside is only supported with pretty, fold-icons requires show-icons.
• --custom-callout <name:icon=...,color=...;...> — overrides or adds callout labels. icon and color are optional; color formats match --custom-theme.
• Icons require Nerd Fonts in the terminal to render correctly.

• -c, --cols <N> — enforces the output width. When omitted mdv uses the detected terminal width or a fallback of 80 columns.
• -b, --tab-length <N> — replaces tab characters with N spaces (default 4).
• -W, --wrap <char|word|none> — selects the text wrapping mode (default char).
• -w, --table-wrap <fit|wrap|none> — chooses how wide tables are handled (default fit).
• -S, --table-smart-indent — automatic table indent adjustment based on available width.
• -d, --heading-layout <level|center|flat|none> — controls heading indentation (default level).
• -I, --smart-indent — smooths indentation jumps between heading levels in level mode.
• -K, --code-wrap-indent <none|base|double> — sets the hanging indent applied to wrapped code block lines (default double).

• -L, --no-code-language — hides the language label above code blocks when metadata is available.
• -e, --show-empty-elements — keeps normally hidden empty lists, block quotes, and code blocks in the output.
• -g, --no-code-guessing — disables heuristic detection of code block languages (unknown blocks remain plain text).

• -u, --link-style <clickable|fclickable|inline|inlinetable|endtable|hide> — changes how links are displayed (default clickable).
• -l, --link-truncation <wrap|cut|tablecut|none> — determines how long links are shortened (default wrap).

• --footnote-style <endnotes|attached> — places footnotes at the end of the document or after each paragraph.
• --missing-footnote-style <show|hide> — controls placeholder entries for missing, invalid, or empty footnote definitions. show renders a placeholder message in the footnote block hide omits those entries entirely.

• -h, --help — shows the help text.
• -V, --version — prints the current version.

mdv merges settings from several sources in the following order of precedence:

1. CLI options (highest priority).
2. Environment variable MDV_CONFIG_PATH or the --config-file flag.
3. User-level configuration under ~/.config/mdv/ (~\.config\mdv\ on Windows).

Create the default user config with mdv --init-config or mdv -G. Add a directory path (mdv -G custom/dir), use --config-file <CONFIG_DIR>, or set MDV_CONFIG_PATH to write it somewhere else.

Configuration files must be written in YAML (.yaml or .yml). See docs/examples/config.yaml for a complete template including inline documentation:

# docs/examples/config.yaml
theme: "terminal"
code_theme: null
wrap: "char"
table_wrap: "fit"
heading_layout: "level"
smart_indent: false
code_wrap_indent: "double"
link_style: "clickable"
link_truncation: "wrap"

• MDV_CONFIG_PATH — custom path to a configuration directory; also used by mdv --init-config when no directory is provided.
• MDV_EDITOR — editor opened from pager mode; takes priority over EDITOR. Known GUI editors launch asynchronously while terminal editors block until exit; Emacs and Vim modes are selected from their CLI arguments. Unknown commands are treated as terminal editors.
• MDV_EDITOR_MODE — optional editor launch mode: tui waits for the editor to exit, while gui launches it asynchronously. When unset, the mode is detected automatically. Explicit tui may be used with GUI launchers to pause the pager; explicit gui overrides unknown commands but is rejected for known terminal editors to prevent both processes from controlling the same terminal. Invalid values and conflicts are reported in the pager without launching the editor.
• MDV_NO_COLOR — accepts True or False and enforces color usage regardless of CLI arguments or theme settings.

Built-in themes include:

terminal

monokai

solarized-dark

nord

tokyonight

kanagawa

gruvbox

material-ocean

catppuccin

Switch between them with --theme or set a default in your configuration file.

Use --custom-theme to override UI colors and --custom-code-theme to fine-tune syntax highlighting. Overrides accept key=value pairs separated by semicolons, where keys match palette fields (for example text, h1, border, keyword, function). Color values can be hex codes (#rrggbb), comma-separated RGB (187,154,247), named ANSI colors (red, darkgrey), or 256-color indexes (ansi(42)).

Run mdv --theme-info to preview the active palette. Add a path (mdv --theme-info README.md) to inspect how colors apply to a document. Starting from examples/config.yaml you can build your own theme variants and keep them in version control.

© 2026-present WhoSowSee