mdcat 3.2.1001

mdcat

A tiny cat for Markdown. Reads a Markdown file (or stdin) and renders it to styled terminal output using Console.Lib's MarkdownRenderer — headings, bold/italic, inline code, lists, blockquotes, fenced code blocks, OSC 8 hyperlinks, and LaTeX math.

Usage

mdcat [options] [file]

Color auto-detection. With no --color, mdcat emits truecolor and, when it detects a 24-bit-capable terminal (COLORTERM=truecolor/24bit, or a known terminal via WT_SESSION / TERM_PROGRAM), switches to a richer GitHub-Dark palette; otherwise it uses the default 16-color-safe palette. An explicit --color overrides detection. NO_COLOR (see no-color.org) disables color unless --color overrides it.

Examples

mdcat README.md                  # render a file
cat README.md | mdcat -          # render from stdin
mdcat --mode unicode notes.md    # force Unicode math (no raster)
mdcat --plain README.md > out.txt # strip styling for plain capture

Exit codes

Math

Display math rasterizes (sixel / sextant / half-block per --mode) only when the delimiters sit on their own lines — i.e. a block:

$$
\int_0^1 x^2\,dx = \frac{1}{3}
$$

Single-line $$...$$ and inline $...$ always render as single-row Unicode, never rastered.

Rastering needs an OpenType math font. mdcat bundles STIX Two Math (Fonts/STIX2Math.otf, SIL OFL — see Fonts/STIX2-OFL.txt) next to the executable, so math renders the same everywhere without relying on system fonts. If that file is ever missing, MarkdownRenderer falls back to an internal system-font search (STIX Two Math, Cambria Math, …) and, failing that, a Unicode-only approximation.

Images

An image that sits alone on its own line (![alt](path)) is rendered as a picture — Sixel on capable terminals, otherwise Unicode block characters (sextant / half-block), scaled to fit the render width. An image inside a line of text, or one that can't be displayed, renders as its alt text instead (the file name when the alt is empty).

![architecture diagram](docs/arch.png)

Supported formats: PNG and baseline JPEG (plus BMP / GIF / TGA), via a pure-managed decoder. Progressive JPEG, SVG and WebP are not supported and fall back to alt text.

No network support. mdcat does not download images. Only local files are read — relative paths resolve against the markdown file's directory (or the current directory when reading from stdin). Remote http(s):// and data: URLs are never fetched and render as their alt text. Add --no-color / --plain (or set NO_COLOR) to force every image to alt text.

Install

As a .NET global tool (needs the .NET 10 runtime)

dotnet tool install --global mdcat

Auto-updatable (dotnet tool update -g mdcat) and discoverable via dotnet tool search mdcat. The bundled math font ships inside the package, so display math works out of the box.

Prebuilt native binary (no runtime required)

Download a self-contained binary from the Releases page. Native AOT builds are published for:

Each archive contains the mdcat executable plus the Fonts/ directory (the bundled math font must sit next to the binary). Extract it and put the folder on your PATH, e.g.:

tar -xzf mdcat-1.0.0-linux-x64.tar.gz
sudo cp -r mdcat-1.0.0-linux-x64/* /usr/local/bin/   # mdcat + Fonts/

Releases are cut by pushing a mdcat-vX.Y.Z tag, which runs .github/workflows/mdcat-release.yml.

Build from source

dotnet build src/MdCat                          # build
dotnet run --project src/MdCat -- README.md     # run in place

# native, self-contained binary for the current platform
dotnet publish src/MdCat -c Release -r <rid> --self-contained -o out
# (rid = linux-x64 | win-x64 | osx-arm64 | …; output in out/, with out/Fonts/)

# or install as a .NET global tool from a local package
dotnet pack src/MdCat -c Release
dotnet tool install --global --add-source src/MdCat/bin/Release mdcat