MDCAT(1) mdcat MDCAT(1)

mdcat - render CommonMark Markdown to text terminals

mdcat [OPTIONS] [FILE]...

mdless [OPTIONS] [FILE]...

mdcat renders Markdown FILEs in CommonMark dialect to text terminals with sophisticated formatting. If no FILE is given, or if FILE is '-', it reads from standard input.

If invoked as mdless automatically use a pager to display the output, see below.

mdcat supports all basic CommonMark syntax plus a few extensions, 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.

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:

1.$TERM
2.$TERM_PROGRAM
3.$TERMINOLOGY

For some terminals mdcat also checks $TERM_PROGRAM_VERSION to determine whether the terminal supports the expected feature set.

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

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.

In iTerm2, kitty, Terminology, WezTerm, and VSCode (1.80 or newer) 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.

In Terminology mdcat also renders SVG images, using the built-in support of Terminology.

In iTerm2, kitty, VSCode, and WezTerm 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.

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.

Note that some terminals (e.g. Terminology) directly render images from URLs and do not require that mdcat fetches the image data first. In this case --local has no effect: mdcat always passes the URL to the terminal, and leaves it up to the terminal to fetch it.

-p, --paginate

Paginate the output of mdcat with a pager like less.

Note: When paginating mdcat only uses standard ANSI formatting and hyperlinks, but no images or other proprietary format codes, because pager programs normally do not support any of these.

This is the default when run as mdless.

-P, --no-pager

Do not paginate output.

This is the default when run as mdcat.

-c, --no-colour

Disable all colours and other styles.

--ansi

Skip terminal detection and only use ANSI formatting.

--columns

Maximum number of columns to use for text output. Defaults to the size of the underlying terminal.

-l, --local

Do not access remote resources.

--fail

Fail immediately at the first FILE which fails to read. By default, mdcat continues with the next file.

--detect-terminal

Detect the terminal program, print its name, and exit.

-h, --help

Show a help message to the user and exit.

-V, --version

Show the version of mdcat and exit. The long flag also includes information about the builtin features.

mdcat exits with 0 if no error occurred, or 1 otherwise.

If run as mdless or if --paginate is given and the pager fails to start mdcat exists with 128.

TERM


mdcat first checks this variable to identify the terminal program (see section Terminal detection). It understands the following values.
•wezterm: WezTerm. Note that WezTerm sets $TERM to xterm-256color by default, and only uses wezterm for $TERM if explicitly configured to do so.
•xterm-kitty: kitty

For all other values mdcat proceeds to check $TERM_PROGRAM.

TERM_PROGRAM

If $TERM does not conclusively identify the terminal program mdcat checks this variable next. It understands the following values:
•iTerm.app: iTerm2
•WezTerm: WezTerm
•vscode: VSCode integrated terminal, but only if $TERM_PROGRAM_VERSION indicates a sufficient version to support all required features..

For all other values mdcat proceeds to check $TERMINOLOGY.

TERM_PROGRAM_VERSION

If $TERM_PROGRAM is vscode, mdcat checks this variable to determine whether VSCode has a sufficient version to support all required features.

TERMINOLOGY

If this variable is 1, mdcat assumes that the terminal is Terminology.

Otherwise mdcat ends terminal detection and assumes that the terminal is only capable of standard ANSI formatting.

COLUMNS

The number of character columns on screen.

mdcat only uses this variable if it fails to query the size from the underlying terminal.

ROWS

The number of character rows on screen.

mdcat only uses this variable if it fails to query the size from the underlying terminal.

MDCAT_PAGER

The pager program to use for mdless or if --paginate is given.

The pager program must support basic ANSI formatting sequences, like e.g. less -r.

The value of this variable is subject to shell-like word-splitting. It is not subject to any kind of expansion or substitution (e.g. parameter expansion, process substitution, etc.).

If set to an empty value, mdcat completely disables pagination.

PAGER

The pager program to use if $MDCAT_PAGER is unset.

Subject to the same rules as $MDCAT_PAGER.

If both $PAGER and $MDCAT_PAGER are unset use less -r as pager.

http_proxy, https_proxy, HTTPS_PROXY, all_proxy, ALL_PROXY

Proxies for HTTP, HTTPS, or both protocols, to use when fetching images.

Each variable provides the proxy for the corresponding protocol as URL, e.g. http://proxy.example.com:3128.

The lowercase name takes precedence; note that $http_proxy deliberately has no uppercase variant.

no_proxy, NO_PROXY

A comma-separated list of host/domain names or IP address not to use a proxy for.

Matches partial hostnames (e.g. example.org also disables proxy for www.example.org), but always at name boundaries.

MDCAT_LOG

Directives to configure output of tracing information.

See https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html#directives for syntax details; use MDCAT_LOG=trace for complete debugging information, and MDCAT_LOG=mdcat::render=trace to trace rendering only.

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

mdcat does not yet support footnotes and tables <https://github.github.com/gfm/#tables-extension->. mdcat parses HTML blocks and inline tags but does not apply special rendering; it prints HTML as is.

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):

•iTerm2 https://iterm2.com/: Inline images ( iTerm2 protocol https://iterm2.com/documentation-images.html) and Marks https://iterm2.com/documentation-escape-codes.html.
•kitty https://github.com/kovidgoyal/kitty: Inline images ( kitty Graphics protocol https://sw.kovidgoyal.net/kitty/graphics-protocol.html).
•Terminology http://terminolo.gy: Inline images (terminology protocol).
•WezTerm https://wezfurlong.org/wezterm/: Inline images (kitty graphics protocol, see above).
•VSCode https://code.visualstudio.com/ 1.80 or newer, integrated terminal: Inline images (iTerm2 protocol, see above)

Please report bugs to https://github.com/swsnr/mdcat/issues.

Currently does not provide means to customize styles and colours.

mdcat hello - world

Render markdown in hello, then from standard input, then from world.

mdless hello

Render markdown from mdless through a pager.

cat(1), bat(1)

Copyright Sebastian Wiesner <sebastian@swsnr.de> and contributors

Binaries are subject to the terms of the Mozilla Public License, v. 2.0. See https://github.com/swsnr/mdcat/blob/main/LICENSE.

Most of the source is subject to the terms of the Mozilla Public License, v. 2.0, 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.

Sebastian Wiesner

mdcat 2.1.2