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.

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 Mermaid diagrams (flowcharts, sequence diagrams, and more) in fenced ```mermaid code blocks, as PNGs through an image protocol, and as Unicode diagrams 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,
• can fuzzy-find a Markdown file to render, via mdpick (see below), if you have fzf installed.

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.

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/mermaid.md for Mermaid diagrams, sample/alerts.md for GFM alerts, and sample/tables.md for table rendering.

To fuzzy-find and open a Markdown file below the current directory (requires fzf):

$ mdpick
$ mdpick docs  # search below docs instead

mdcat looks at the name it was invoked as (argv[0]) to decide how to behave:

• Invoked as mdless, it automatically paginates output, as if --paginate were given.
• Invoked as mdpick, it skips straight to the interactive picker described above, instead of expecting a file argument.

Both are the same binary as mdcat, just under a different name, so you get them for free by linking or copying the binary:

$ ln -s "$(command -v mdcat)" ~/.local/bin/mdless
$ ln -s "$(command -v mdcat)" ~/.local/bin/mdpick

(make sure ~/.local/bin, or wherever you put the links, is on $PATH). A hardlink or plain copy works just as well as a symlink.

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

• Package managers — mdcat is available from several package managers:

  Package manager	Command
  Homebrew (macOS/Linux)	brew install mdcat
  AUR (Arch Linux)	paru -S mdcat-bin
  Nixpkgs	nix-env -iA nixpkgs.mdcat
  MacPorts	sudo port install mdcat
  FreeBSD Ports	pkg install mdcat
  Void Linux	sudo xbps-install mdcat
  MSYS2 (Windows)	pacman -S mingw-w64-x86_64-mdcat

  See Repology for the full list of packages and their versions.

• You can also build mdcat manually with cargo install mdcat (see below for details).

mdcat can be linked or copied to mdless or mdpick (see mdless and mdpick above).

Run cargo build --release.

Building requires libcurl.

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

• A symlink or hardlink from mdless to mdcat (see above), and, if you want to ship the picker, likewise from mdpick to mdcat. mdpick additionally needs fzf installed to work; consider depending on it in your package.

• 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 and mdpick if you include them
  $ 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
  $ mdpick --completions fish > /usr/share/fish/vendor_completions.d/mdpick.fish
  $ mdpick --completions bash > /usr/share/bash-completion/completions/mdpick
  $ mdpick --completions zsh > /usr/share/zsh/site-functions/_mdpick

• 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 mdless and/or mdpick as above, you may also want to support their man pages
  $ ln -s mdcat.1.gz /usr/share/man/man1/mdless.1.gz
  $ ln -s mdcat.1.gz /usr/share/man/man1/mdpick.1.gz

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.

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