mdv 4.1.0

Terminal Markdown Viewer
Documentation

[!TIP] Русская версия: README-RU.md

[!NOTE] mdv is a terminal Markdown viewer focused on precise rendering inside ANSI-capable terminals. It offers:

  • Terminal-first rendering - Syntax highlighted output, optional HTML export, and careful handling of inline formatting.
  • Reusable layouts - Control width, wrapping strategy, heading indentation, and table behavior to match your workspace.
  • Link presentation control - Switch between clickable, inline, or tabular links and choose how long URLs are truncated.
  • Rich theming - Built-in color schemes plus on-the-fly overrides for UI and syntax palettes.
  • Live monitoring - Watch files with --monitor to refresh the view whenever the source changes.
  • Script friendly CLI - Read from stdin, jump to sections with --from, and share configuration files across machines.

[!IMPORTANT]

Required dependencies:

  • Rust toolchain
  • Terminal with ANSI color support for the best experience

Installation

Install from crates.io

cargo install mdv

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

Install with Nix (Flake)

nix run github:WhoSowSee/mdv
nix profile install github:WhoSowSee/mdv

The Nix flake builds mdv from flake.nix and installs the mdv binary into the Nix profile. Use nix run to try it without installing, or nix profile install for a persistent install.

Install from source

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).

Run locally without installing

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

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

Usage

mdv [OPTIONS] [FILE]

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

mdv [OPTIONS] -
cat <FILE> | mdv

Output and workflow

  • -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.

Theming

  • -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>[:show-icons;icon-only] — switches between a single gutter and a boxed frame for code blocks. show-icons adds a language icon to the label, and icon-only shows only the icon while hiding the language text (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.
  • -J, --custom-code-block <lang:icon=...,label=...,aliases=...>[;...] — overrides the icon, label, and aliases for specific code block languages. Multiple languages are separated by ;, options within one language by ,, and aliases by | (for example, python:icon=*,label=Python,aliases=py|py3;rust:icon=). Works for any language hint, even if it is not in the built-in icon mapping. Syntax highlighting is applied only when the language is supported by mdv's syntax highlighting logic. Use default:icon=... to set the fallback icon for unknown languages.

Callouts

  • --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.

Checkboxes

  • -P, --pretty-checkbox <square|circle> — renders task-list checkboxes as Nerd Font icons instead of the default [ ] / [x] markers. Requires a Nerd Font in the terminal.
  • -B, --custom-checkbox <char>:<icon>[:<color>];... — overrides the built-in checkbox icons or adds new states (only with --pretty-checkbox). <char> is the checkbox character (, , x, *, ?, !, etc.); <icon> is the new glyph; <color> is optional. Colors accept named, hex, rgb, and ansi(N) values.
    • Override: -B ' :icon' replace the unchecked icon
    • Add: -B '*:icon' add a new [*] checkbox state
    • Color: -B ' :icon:yellow' or #ff0000, 128,1,1, ansi(200)
    • Iconless: -B '?:red' keep the default [?] icon, apply red color

Lists

  • -D, --pretty-list — replaces the default - unordered list markers with Nerd Font icons per nesting level. Requires a Nerd Font to render correctly.
  • -Q, --custom-list <level>:<icon>[:<color>];... — overrides the marker icon and/or color for specific nesting levels (only with --pretty-list). Level is 1-based; icon is the marker glyph. Colors accept named (red), hex (#ff0000), rgb (255,0,0), and ansi(N) values.
    • Icon + color: --custom-list '1:*:yellow' marker * in yellow
    • Icon only: --custom-list '1:>' marker > in theme color
    • Color only: --custom-list '1:red' keep built-in icon, red color

Layout and wrapping

  • -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).
  • -R, --reflow — collapses in-paragraph source newlines (soft breaks) and refills each line to the wrap width, so hard-wrapped source reflows to fit smaller screens. Requires wrapping to be enabled; hard breaks are preserved.
  • -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).

Content visibility

  • -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).

Links

  • -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).

Footnotes

  • --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.

Information

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

Configuration

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"

Environment variables

  • 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.

Themes

Built-in themes include:

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.

User themes

Drop one or more *.yaml/*.yml files into <config_dir>/themes/ to register your own themes. The directory follows the same resolution order as config.yaml (the --config-file flag, $MDV_CONFIG_PATH, then ~/.config/mdv/). Two ready-to-use examples ship with the repository:

# <config_dir>/themes/warm.yaml
name: warm
description: Warm red accent layered on top of monokai.
extends: monokai

h1: "#ff5577"
link: "#66ccff"
background: "#1c1c1c"

syntax:
  keyword: "#ff5577"

Field reference:

  • name (required) — the value accepted by --theme.
  • description (optional) — shown in mdv --theme-info; falls back to the base theme's description.
  • extends (optional) — names a built-in theme or any other theme file loaded earlier in the same directory (alphabetical order). When omitted, missing fields are filled from the default terminal theme.
  • Every color field is optional and inherits from the base theme when omitted. Available UI fields: text, text_light, h1..h6, code, code_block, quote, link, emphasis, strong, strikethrough, highlight_background, background, border, list_marker, table_header, table_border, error, warning.
  • syntax: (optional) — overrides the syntax-highlight palette. Each field is optional and merges against the base: keyword, string, comment, number, operator, function, variable, type_name.
  • Color values follow the same syntax as --custom-theme: named (red, darkgrey, dark_grey), hex (#ff5577), rgb (187,154,247), or 256-color (ansi(42) or 42).

A user theme with the same name as a built-in takes precedence and fully replaces it, which is the supported way to fork a built-in without copying all 33 fields. Broken or unrecognized files are skipped with a warning, so a single bad theme does not break the rest.

Star History