<p align="center">
<img src="docs/images/icon.svg" height="128" alt="mdv icon" />
</p>
<p align="center">
<a href="https://github.com/WhoSowSee/mdv/graphs/contributors"><img src="https://img.shields.io/github/contributors/WhoSowSee/mdv?style=for-the-badge&color=CBA6F7&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTkgMTFhNCA0IDAgMSAwIDAtOCA0IDQgMCAwIDAgMCA4Wm0wIDJjLTMuOSAwLTcgMi03IDQuNVYyMGgxNHYtMi41QzE2IDE1IDEyLjkgMTMgOSAxM1ptOC41LTEuNWEzLjI1IDMuMjUgMCAxIDAgMC02LjUgMy4yNSAzLjI1IDAgMCAwIDAgNi41Wm0wIDEuOGMtLjkgMC0xLjc1LjE1LTIuNS40MiAxLjcgMS4wNSAyLjcgMi40NSAyLjcgMy45OFYyMEgyMnYtMi4zYzAtMi40LTItNC40LTQuNS00LjRaIi8+PC9zdmc+" alt="CONTRIBUTORS"></a>
<a href="https://github.com/WhoSowSee/mdv/forks"><img src="https://img.shields.io/github/forks/WhoSowSee/mdv?style=for-the-badge&color=89B4FA&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTIgMTIpIHNjYWxlKDEuMDgpIHRyYW5zbGF0ZSgtMTIgLTEyKSI%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTYgM2EzIDMgMCAxIDAgMCA2IDMgMyAwIDAgMCAwLTZabTEyIDBhMyAzIDAgMSAwIDAgNiAzIDMgMCAwIDAgMC02Wk0xMiAxNWEzIDMgMCAxIDAgMCA2IDMgMyAwIDAgMCAwLTZaIi8%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTUgOGgydjIuNGMwIC4zMy4yNy42LjYuNmg4LjhjLjMzIDAgLjYtLjI3LjYtLjZWOGgydjIuNGEyLjYgMi42IDAgMCAxLTIuNiAyLjZIMTN2MmgtMnYtMkg3LjZBMi42IDIuNiAwIDAgMSA1IDEwLjRWOFoiLz48L2c%2BPC9zdmc%2B" alt="FORKS"></a>
<a href="https://github.com/WhoSowSee/mdv/stargazers"><img src="https://img.shields.io/github/stars/WhoSowSee/mdv?style=for-the-badge&color=F9E2AF&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMCAtMS42KSI%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTEyIDIuNSAxNC45IDguNGw2LjUgMWEuOC44IDAgMCAxIC40NSAxLjM2bC00LjcgNC41OCAxLjEgNi40NWEuOC44IDAgMCAxLTEuMTYuODRMMTIgMTkuOTUgNi4yIDIyLjYzYS44LjggMCAwIDEtMS4xNi0uODRsMS4xLTYuNDUtNC43LTQuNThBLjguOCAwIDAgMSAxLjkgOS40bDYuNS0xTDEyIDIuNVoiLz48L2c%2BPC9zdmc%2B" alt="STARS"></a>
</p>
<p align="center">
<a href="https://crates.io/crates/mdv"><img src="https://img.shields.io/crates/v/mdv?style=for-the-badge&color=FAB387&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI%2BCjxwYXRoIGZpbGw9IiNjZGQ2ZjQiIGQ9Ik0xLjUgNi45ODRWMTFsNi41MDMgMy41TDE0LjUgMTFWM0wxMSAxLjVsLTYuNSAzdjF6Ii8%2BCjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzMwMkQ0MSIgc3Ryb2tlLXdpZHRoPSIuOSIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIj4KPHBhdGggZD0iTTEuNSA3TDggMTAuNUwxNC41IDdtLTEwLTIuNWwzLjUwMyAyTDE0LjQ5OCAzTTQuNSA1LjV2N20zLjUtNlYxNCIvPgo8cGF0aCBkPSJNOC4wMDMgM0wxMS41IDQuNXY4Ii8%2BCjwvZz4KPC9zdmc%2B&labelColor=302D41" alt="CRATES.IO"></a>
<a href="https://crates.io/crates/mdv"><img src="https://img.shields.io/crates/d/mdv?style=for-the-badge&color=A6E3A1&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI%2BCjxwYXRoIGZpbGw9IiNjZGQ2ZjQiIGQ9Ik0xLjUgNi45ODRWMTFsNi41MDMgMy41TDE0LjUgMTFWM0wxMSAxLjVsLTYuNSAzdjF6Ii8%2BCjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzMwMkQ0MSIgc3Ryb2tlLXdpZHRoPSIuOSIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIj4KPHBhdGggZD0iTTEuNSA3TDggMTAuNUwxNC41IDdtLTEwLTIuNWwzLjUwMyAyTDE0LjQ5OCAzTTQuNSA1LjV2N20zLjUtNlYxNCIvPgo8cGF0aCBkPSJNOC4wMDMgM0wxMS41IDQuNXY4Ii8%2BCjwvZz4KPC9zdmc%2B&labelColor=302D41" alt="DOWNLOADS"></a>
</p>
<h2 align="center">Fast, themeable Markdown viewer for the terminal</h2>
<p align="center">
<img src="docs/images/overview.webp" width="750" alt="Overview" />
</p>
> [!TIP]
> **Russian version:** [README-RU.md](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
```bash
cargo install mdv
```
This installs the latest published release from crates.io into your Cargo bin directory.
### Install from source
```bash
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
```bash
cargo build --release
./target/release/mdv README.md
```
Use the `mdv` binary from `target/release` directly or add it to your PATH.
## Usage
```text
mdv [OPTIONS] [FILE]
```
Also, mdv supports reading from standard input (stdin) and working in pipelines
```text
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.
### 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:
```yaml
# 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:
<details>
<summary><code>terminal</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_terminal_1.webp" alt="Theme Terminal preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_terminal_2.webp" alt="Theme Terminal preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_terminal_3.webp" alt="Theme Terminal preview" width="900px">
</div>
</details>
<details>
<summary><code>monokai</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_monokai_1.webp" alt="Theme Monokai preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_monokai_2.webp" alt="Theme Monokai preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_monokai_3.webp" alt="Theme Monokai preview" width="900px">
</div>
</details>
<details>
<summary><code>solarized-dark</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_solarized-dark_1.webp" alt="Theme Solarized Dark preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_solarized-dark_2.webp" alt="Theme Solarized Dark preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_solarized-dark_3.webp" alt="Theme Solarized Dark preview" width="900px">
</div>
</details>
<details>
<summary><code>nord</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_nord_1.webp" alt="Theme Nord preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_nord_2.webp" alt="Theme Nord preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_nord_3.webp" alt="Theme Nord preview" width="900px">
</div>
</details>
<details>
<summary><code>tokyonight</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_tokyonight_1.webp" alt="Theme Tokyonight preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_tokyonight_2.webp" alt="Theme Tokyonight preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_tokyonight_3.webp" alt="Theme Tokyonight preview" width="900px">
</div>
</details>
<details>
<summary><code>kanagawa</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_kanagawa_1.webp" alt="Theme Kanagawa preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_kanagawa_2.webp" alt="Theme Kanagawa preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_kanagawa_3.webp" alt="Theme Kanagawa preview" width="900px">
</div>
</details>
<details>
<summary><code>gruvbox</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_gruvbox_1.webp" alt="Theme Gruvbox preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_gruvbox_2.webp" alt="Theme Gruvbox preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_gruvbox_3.webp" alt="Theme Gruvbox preview" width="900px">
</div>
</details>
<details>
<summary><code>material-ocean</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_material-ocean_1.webp" alt="Theme Material Ocean preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_material-ocean_2.webp" alt="Theme Material Ocean preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_material-ocean_3.webp" alt="Theme Material Ocean preview" width="900px">
</div>
</details>
<details>
<summary><code>catppuccin</code></summary>
<div style="text-align: center;">
<img src="docs/images/theme_catppuccin_1.webp" alt="Theme Catppuccin preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_catppuccin_2.webp" alt="Theme Catppuccin preview" width="900px">
</div>
<div style="text-align: center;">
<img src="docs/images/theme_catppuccin_3.webp" alt="Theme Catppuccin preview" width="900px">
</div>
</details>
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.
## Star History
<p align="center">
<a href="https://starchart.cc/WhoSowSee/mdv">
<picture>
<source
media="(prefers-color-scheme: dark)"
srcset="https://starchart.cc/WhoSowSee/mdv.svg?variant=custom&background=%230d1117&axis=%238b949e&line=%232f81f7"
/>
<source
media="(prefers-color-scheme: light)"
srcset="https://starchart.cc/WhoSowSee/mdv.svg?variant=custom&background=%23ffffff&axis=%2357606a&line=%230969da"
/>
<img
alt="Stargazers over time"
src="https://starchart.cc/WhoSowSee/mdv.svg?variant=custom&background=%23ffffff&axis=%2357606a&line=%230969da"
/>
</picture>
</a>
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/footers/gray0_ctp_on_line.svg?sanitize=true" alt="catppuccin" />
</p>
<p align="center">
<i><code>© 2026-present <a href="https://github.com/WhoSowSee">WhoSowSee</a></code></i>
</p>
<p align="center">
<a href="https://github.com/WhoSowSee/mdv/blob/main/LICENSE"><img src="https://img.shields.io/github/license/WhoSowSee/mdv?style=for-the-badge&color=CBA6F7&logoColor=cdd6f4&labelColor=302D41" alt="LICENSE"></a>
</p>