Themes

Select a theme

Built-in themes: terminal, solarized-dark, nord, tokyonight, kanagawa, gruvbox, monokai, material-ocean, catppuccin.

The default is terminal. Code follows the document palette unless --code-theme selects another palette. --theme-info shows the active colors; with a filename, it also renders that document.

mdv --no-config --theme terminal --cols 64 example.md

Example
 
 Read Markdown with `mdv`.
 
 ╭─ Note ─────────────────────╮
 │ Terminal document preview. │
 ╰────────────────────────────╯
 
   fn main() {
       println!("hello, mdv");
   }
 
 Open the guide.

# Example

Read **Markdown** with `mdv`.

> [!NOTE]
> Terminal document preview.

```rust
fn main() {
    println!("hello, mdv");
}
```

Open the [guide](https://example.org/guide).

mdv --no-config --theme catppuccin --cols 64 --code-theme terminal example.md

  fn main() {
      println!("hello, mdv");
  }

```rust
fn main() {
    println!("hello, mdv");
}
```

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 the platform user configuration directory). Two ready-to-use examples ship with the repository:

• docs/examples/themes/theme-warm.yaml - uses extends: monokai to override just a handful of fields.
• docs/examples/themes/theme-custom.yaml - example of a standalone palette.

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

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

inline_style:
  code:
    backticks: false
    underline: true

syntax:
  keyword: "#ff5577"

Theme file basics:

• name (required) - the value accepted by --theme.
• description (optional) - shown in mdv --theme-info; inherits from the base theme.
• extends (optional) - a built-in theme or a user theme loaded earlier in alphabetical order. Without it, missing fields inherit from terminal.
• pager - footer colors, transparency, selection, and search highlighting in the built-in pager.
• inline_style - inline Markdown decorations; colors belong to the corresponding color sections.

Colors inherit per field.

• Explicit null clears an inherited optional border or background color override; reset uses the terminal’s default color.
• See the field reference and inheritance rules for the full schema and special cases.
• The bundled theme files show all fields; terminal.yaml defines the default palette.

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 every field. Broken or unrecognized files are skipped with a warning, so a single bad theme does not break the rest.