= mdcat(1)
Sebastian Wiesner <sebastian@swsnr.de>
:doctype: manpage
:revnumber: 2.9.0
:revdate: 2026-06-20
:mansource: mdcat {revnumber}
:manmanual: mdcat
== Name
mdcat - render CommonMark Markdown to text terminals
== Synopsis
*mdcat* [_OPTIONS_] [FILE]...
*mdless* [_OPTIONS_] [FILE]...
== Description
mdcat renders Markdown ``FILE``s 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.
=== 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:
1. `$TERM`
2. `$TERM_PROGRAM`
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.
=== 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.
=== SVG support
In iTerm2, kitty, WezTerm, and Ghostty mdcat renders SVG images into pixel graphics using the https://github.com/RazrFalcon/resvg[resvg] library.
Currently this library only supports SVG 1, and only the static subset thereof; see https://github.com/RazrFalcon/resvg#svg-support[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.
== Options
-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.
Math rendering uses the Unicode fallback when paginating.
+
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=_COLUMNS_::
Maximum number of columns to use for text output.
Defaults to the size of the underlying terminal if omitted.
-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.
--completions=_SHELL_::
Generate completions for _SHELL_ to standard output and exit.
_SHELL_ can be one of `bash`, `zsh`, `fish`, `powershell`, or `elvish`.
-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.
== Exit status
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.
== Environment
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
* `xterm-ghostty`: Ghostty
+
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.
* `ghostty`: Ghostty
+
For all other values `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::
no_proxy::
NO_PROXY::
Proxies settings for HTTP requests made by mdcat to retrieve remote resources.
+
mdcat uses curl for its network transfers, hence see `curl(1)` for these variables.
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=pulldown_cmark_mdcat::render=trace` to trace rendering only.
== Conforming to
=== CommonMark support, extensions, and limitations
mdcat supports version 0.30 of the https://spec.commonmark.org/[CommonMark Spec], plus footnotes, https://github.github.com/gfm/#task-list-items-extension-[Task lists], https://github.github.com/gfm/#strikethrough-extension-[strikethrough], and math, through https://github.com/raphlinus/pulldown-cmark[pulldown-cmark].
Support for https://github.github.com/gfm/#tables-extension-[tables] 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 https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda[OSC 8] 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):
* https://iterm2.com/[iTerm2]: Inline images (https://iterm2.com/documentation-images.html[iTerm2 protocol]) and
https://iterm2.com/documentation-escape-codes.html[Marks].
* https://github.com/kovidgoyal/kitty[kitty]: Inline images (https://sw.kovidgoyal.net/kitty/graphics-protocol.html[kitty Graphics protocol]).
* https://wezfurlong.org/wezterm/[WezTerm]: Inline images (kitty graphics protocol, see above).
* https://mitchellh.com/ghostty[Ghostty]: Inline images (kitty graphics protocol, see above).
== Bugs
Please report bugs to https://github.com/swsnr/mdcat/issues.
Currently does not provide means to customize styles and colours.
== Examples
mdcat hello - world::
Render markdown in `hello`, then from standard input, then from `world`.
mdless hello:: Render markdown from `mdless` through a pager.
== See also
*cat(1)*, *bat(1)*
== Copyright
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.