mdcat 2.18.871

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]

NO_COLOR (see no-color.org) is honored: any non-empty value disables color unless an explicit --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.

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