mdcat

Fancy cat for Markdown (that is, CommonMark):

$ mdcat sample.md

mdcat in Ghostty, with --theme catppuccin-mocha, --theme dracula, and --theme nord (left to right), using JetBrains Mono.

Features

mdcat works best with iTerm2, WezTerm, kitty, and Ghostty, and a good terminal font with italic characters. Then it

• nicely renders all basic CommonMark syntax, plus definition lists,
• renders footnotes and inline markup in table cells,
• highlights code blocks with syntax definitions from bat (TOML, TypeScript, Dockerfile, Zig, Nix, and more), using the colour theme of your choice — including any theme bat supports via $BAT_THEME,
• renders inline and display math, as PNGs through the iTerm2 or kitty image protocol, and as Unicode substitutions otherwise,
• renders GFM alerts ([!NOTE], [!TIP], [!WARNING], etc.) with coloured borders and icons,
• shows links, and also images inline in supported terminals (see above, where "Rust" is a clickable link!),
• adds jump marks for headings in iTerm2 (jump forwards and backwards with ⇧⌘↓ and ⇧⌘↑),
• ships eight built-in colour themes (catppuccin-mocha, catppuccin-latte, gruvbox-dark, gruvbox-light, dracula, nord, solarized-dark, solarized-light) plus auto dark/light detection, and lets you fully customise colours, heading markers, and GFM alert icons/labels via ~/.config/mdcat/config.toml (see config.toml.example),
• can render typographic punctuation (curly quotes, en/em dashes, an ellipsis) with --smart-punctuation,
• can watch a file and re-render it on every save with --watch, for a live preview while editing.

Terminal	Basic syntax	Syntax highlighting	Images	Math	Jump marks
Basic ANSI¹	✓	✓		✓³
Windows 10 console	✓	✓		✓³
iTerm2	✓	✓	✓²	✓³	✓
kitty	✓	✓	✓²	✓³
WezTerm	✓	✓	✓²	✓³
VSCode	✓	✓		✓³
Ghostty	✓	✓	✓²	✓³
foot⁴	✓	✓	✓²	✓³‧⁵
xterm⁴	✓	✓	✓²	✓³‧⁵

1. mdcat requires that the terminal supports strikethrough formatting and inline links. This includes most modern terminal emulators, such as Windows Terminal, KDE Konsole, or anything based on VTE, GNOME's terminal emulation library. But mdcat likely won't work well on old terminals that lack these features (e.g. the Linux text console).
2. SVG images are rendered with resvg, see SVG support.
3. On terminals with the iTerm2, kitty, or Sixel image protocol, math is rendered as PNG images. Otherwise mdcat uses Unicode substitutions.
4. Uses Sixel for images, which is also supported by many other terminals. The capability detection logic would need to be extended to also provide the feature on other terminals, though.
5. Inline math with Sixel breaks the layout, as it causes vertical scrolling that is not taking into account.

Not supported:

• Text wrapping inside table cells.

Usage

Try mdcat --help or read the mdcat(1) manpage.

To pick a colour theme:

$ mdcat --theme catppuccin-mocha sample.md
$ MDCAT_THEME=dracula mdcat sample.md
$ mdcat --list-themes  # preview every built-in theme

To customise colours, heading markers, and GFM alert icons/labels, or set defaults for flags like --margin, --smart-punctuation, or --columns, create ~/.config/mdcat/config.toml. See config.toml.example for a fully annotated example, or the mdcat(1) manpage's "Configuration file" section for the reference.

To use a bat syntax-highlighting theme for code blocks:

$ BAT_THEME="Catppuccin Mocha" mdcat sample.md

To get a live preview while editing:

$ mdcat --watch sample.md

See sample/math.md for math examples, sample/alerts.md for GFM alerts, and sample/tables.md for table rendering.

Installation

• Release binaries built on Github Actions.
  • These binaries are built from Git source on Github Actions; you find provenance attestations at https://github.com/BIRSAx2/mdcat/attestations.
• 3rd party packages at Repology
• You can also build mdcat manually with cargo install mdcat (see below for details).

mdcat can be linked or copied to mdless; if invoked as mdless it automatically uses pagination.

Building

Run cargo build --release.

Building requires libcurl.

Packaging

When packaging mdcat you may wish to include the following additional artifacts:

• A symlink or hardlink from mdless to mdcat (see above).

• Shell completions for relevant shells, by invoking mdcat --completions after building, e.g.

  $ mdcat --completions fish > /usr/share/fish/vendor_completions.d/mdcat.fish
  $ mdcat --completions bash > /usr/share/bash-completion/completions/mdcat
  $ mdcat --completions zsh > /usr/share/zsh/site-functions/_mdcat
  # Same for mdless if you include it
  $ mdless --completions fish > /usr/share/fish/vendor_completions.d/mdless.fish
  $ mdless --completions bash > /usr/share/bash-completion/completions/mdless
  $ mdless --completions zsh > /usr/share/zsh/site-functions/_mdless

• A build of the man page mdcat.1.adoc, using AsciiDoctor:

  $ asciidoctor -b manpage -a reproducible -o /usr/share/man/man1/mdcat.1 mdcat.1.adoc
  $ gzip /usr/share/man/man1/mdcat.1
  # If you include a mdless as above, you may also want to support man mdless
  $ ln -s mdcat.1.gz /usr/share/man/man1/mdless.1.gz

Troubleshooting

mdcat can output extensive tracing information when asked to. Run mdcat with $MDCAT_LOG=trace for complete tracing information, or with $MDCAT_LOG=mdcat::render=trace to trace only rendering.

License

Copyright Sebastian Wiesner sebastian@swsnr.de and Mouhieddine Sabir me@mouhieddine.dev

Currently maintained by BIRSAx2.

Binaries are subject to the terms of the Mozilla Public License, v. 2.0, see LICENSE.

Most of the source is subject to the terms of the Mozilla Public License, v. 2.0, see LICENSE, unless otherwise noted; some files are subject to the terms of the Apache 2.0 license, see http://www.apache.org/licenses/LICENSE-2.0