CommonMark and terminal support

mdcat supports all basic CommonMark syntax plus a few extensions, renders footnotes and math expressions, highlights syntax in code blocks, and shows inline links and even inline images in some terminal programs. In iTerm2 it also adds jump marks for section headings.

See section Terminal support below for a list of supported terminal programs and their features.

Terminal detection

To enable formatting extensions such as inline images, mdcat needs to detect the terminal program, by checking the following environment variables in the given order:

See section ENVIRONMENT below for a detailed description of each environment variable.

Pagination

mdcat can render output in a pager; this is the default when run as mdless. The environment variables $MDCAT_PAGER and $PAGER control the pager used.

Note that common pagers do not support proprietary terminal codes for e.g. image support, so mdcat falls back to pure ANSI formatting when pagination is enabled. In particular this disables all image support which relies on proprietary escape codes. Math rendering remains enabled, but uses Unicode substitutions instead of PNG images.

Interactive picking

mdpick requires fzf <https://github.com/junegunn/fzf> to be installed and on $PATH; it exits with an error if fzf cannot be found.

It recursively collects .md files below DIRECTORY, honouring .gitignore and other ignore files the same way fzf and rg do, then hands that list to fzf for fuzzy selection. If the picker is cancelled, e.g. with kbd:[Esc] or kbd:[Ctrl+C], mdpick exits with status 0 without rendering anything. Once a file is selected, mdpick renders it exactly as mdless would, paginating by default.

Image support

In iTerm2, kitty, WezTerm, and Ghostty mdcat prints inline images. mdcat supports most standard pixel formats by default.

mdcat silently ignores images larger than 100 MiB, under the assumption that images of that size cannot reasonably be rendered in a terminal.

Math support

mdcat renders inline math delimited by $...$ and display math delimited by .... On terminals with the iTerm2 or kitty image protocol it renders math as PNG images. Otherwise it uses Unicode substitutions.

For PNG output mdcat uses RaTeX. If an expression cannot be rendered as an image, mdcat uses the Unicode fallback for that expression.

Mermaid support

mdcat renders Mermaid <https://mermaid.js.org> diagrams in fenced ` ```mermaid ` code blocks. On terminals with an image protocol it renders diagrams as PNG images; otherwise it uses a Unicode diagram rendering. If a diagram can be rendered as neither, mdcat falls back to printing its source as a literal code block.

Diagram arrows, borders, and text use the theme’s mermaid style, so diagrams match the active theme instead of Mermaid’s own default colours.

For diagram rendering mdcat uses merman <https://github.com/Latias94/merman>, a headless Rust implementation of Mermaid.

SVG support

In iTerm2, kitty, WezTerm, and Ghostty mdcat renders SVG images into pixel graphics using the resvg <https://github.com/RazrFalcon/resvg> library. Currently this library only supports SVG 1, and only the static subset thereof; see SVG support <https://github.com/RazrFalcon/resvg#svg-support> for details. While this is sufficient for most simple SVG images, complex SVG images may fail to render or render incompletely.

For local SVG files mdcat relies on the file extension to identify SVG images. For remote images from HTTP(S) URLs mdcat inspects the Content-Type header to identify SVG images.

HTTP/HTTPS support

mdcat fetches images from HTTP(S) URLs for rendering if the underlying terminal supports image rendering; pass --local to disable this and force mdcat to only use images from the local filesystem. In this case remote images render as hyperlinks.

[defaults]

Each key sets the default value for a CLI flag, used only when that flag isn’t passed explicitly (and, for columns, when $COLUMNS/terminal size detection doesn’t otherwise apply).

margin

smart_punctuation

columns

local_only

fail_fast

image_protocol

tabs

[theme]

The file picks a built-in theme as a starting point (base), and overrides individual styles on top of it.

base

rule

[theme.palette]

[theme.styles]

CommonMark support, extensions, and limitations

mdcat supports version 0.30 of the CommonMark Spec <https://spec.commonmark.org/>, plus footnotes, Task lists <https://github.github.com/gfm/#task-list-items-extension->, strikethrough <https://github.github.com/gfm/#strikethrough-extension->, and math, through pulldown-cmark <https://github.com/raphlinus/pulldown-cmark>.

Support for tables <https://github.github.com/gfm/#tables-extension-> is limited; text wrapping and inline markup in table cells are not yet supported. mdcat parses HTML blocks and inline tags but does not apply special rendering; it prints HTML as is.

Terminal support

Unless --no-colour is given, mdcat translates CommonMark text into ANSI formatted text, with standard SGR formatting codes and hyperlinks. It uses bold (SGR 1), italic (SGR 3) and strikethrough (SGR 9) formatting, and the standard 4-bit color sequences, as well as OSC 8 <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda> for hyperlinks. It does not use 8-bit or 24-bit color sequences, though this may change in future releases.

Additionally, it uses proprietary escape codes if it detects one of the following terminal emulators (see sections Terminal detection and ENVIRONMENT for details):