How to Install and Use mdcat in Linux to Render Markdown with Syntax Highlighting and Images in the Terminal

Reading software documentation, project README files, technical changelogs, and release notes directly inside the Linux terminal is a standard part of any developer’s daily workflow. While piping markdown files into basic terminal utilities like cat or less outputs raw, unrendered text cluttered with raw syntax tags (such as backticks, hashes, and bracketed links), full terminal text editors can feel overly heavy for quick inspection. mdcat is a dedicated CommonMark CLI tool written in Rust that formats markdown documents into beautiful, colorized terminal presentations complete with syntax-highlighted code blocks, clickable hyperlinks, and inline image rendering.

Key Features of mdcat

Unlike simple pager wrappers, mdcat is purpose-built to respect modern terminal capabilities:

• Full CommonMark Conformance: Accurately parses standard CommonMark formatting, including tables, blockquotes, ordered lists, and strikethrough text.
• Syntax-Highlighted Code Blocks: Automatically detects programming languages from markdown code fences and highlights code using the syntect library and Sublime Text theme palettes.
• Inline Terminal Image Rendering: Renders inline diagrams and images natively across compatible terminal emulators (supporting iTerm2, Kitty, and Sixel graphics protocols) or falls back to text descriptions on standard terminals.
• Clickable Hyperlinks: Formats web links using ANSI escape sequences (OSC 8), enabling direct mouse-clicking in supported terminals without printing ugly raw URL paths across the screen.
• Integrated Paging: Automatically invokes system pagers (like less) when output exceeds the visible terminal window height.

Prerequisites and System Compatibility

Ensure your Linux environment meets these baseline requirements:

• Operating System: Any modern Linux distribution (Ubuntu, Debian, Fedora, Arch Linux, Alpine).
• Terminal Emulator: A modern terminal emulator with true-colour (24-bit) support (e.g., Kitty, Alacritty, WezTerm, GNOME Terminal, or Windows Terminal over WSL).
• Rust/Cargo (Optional): Required only if installing via Cargo rather than pre-compiled binaries.

Step-by-Step: Installing mdcat on Linux

You can install mdcat through native package managers, pre-compiled binaries, or Cargo.

Method 1: Installing via Native Package Repositories

On distributions where mdcat is packaged officially:

• Arch Linux:

  sudo pacman -S mdcat

• Alpine Linux:

  sudo apk add mdcat

• Void Linux:

  sudo xbps-install -S mdcat

Method 2: Installing Pre-Compiled Release Binaries (Ubuntu / Debian / Fedora)

For Debian-based and Red Hat systems, fetch the official static musl binary from GitHub releases:

1. Navigate to your temporary directory:

   cd /tmp

2. Download the latest release tarball for Linux x86_64:

   curl -LO https://github.com/swsnr/mdcat/releases/latest/download/mdcat-x86_64-unknown-linux-musl.tar.gz

3. Extract the archive:

   tar -xzvf mdcat-x86_64-unknown-linux-musl.tar.gz

4. Move the executable into your system path:

   sudo mv mdcat-*/mdcat /usr/local/bin/

5. Verify successful installation:

   mdcat --version

Method 3: Installing via Cargo

If you have Rust configured, compile directly from source:

cargo install mdcat

Step-by-Step: Rendering Markdown Documents

Using mdcat is as straightforward as using traditional cat:

1. Rendering Local Files

To render a documentation file with full syntax highlighting:

mdcat README.md

If the document is longer than your terminal screen, mdcat automatically pipes the output into less -R so you can scroll smoothly using your arrow keys or Space.

2. Piping from Standard Input

You can pipe raw markdown text directly into mdcat from curl commands or shell pipelines:

curl -s https://raw.githubusercontent.com/rust-lang/rust/master/README.md | mdcat -

3. Disabling Pagination for Script Pipelines

If you want mdcat to print markdown continuously without pausing inside a pager (for example, in CI/CD log outputs):

mdcat --no-pager README.md

Configuring Column Width and Image Protocols

Fine-tune rendering behaviour by passing operational flags or defining shell environment variables:

• Custom Column Wrapping: By default, mdcat wraps text to your current terminal width. To enforce a specific column width (e.g., 80 characters for narrow reading):

  mdcat --columns 80 README.md

• Forcing Terminal Pager: Specify your preferred pager using standard environment variables:

  export PAGER="less -FIRX"

• Image Rendering Modes: By default, mdcat auto-detects whether your terminal supports Kitty or iTerm2 image rendering. If images fail to display, you can explicitly force or disable inline graphics:

  mdcat --ansi-images=sixel README.md
  mdcat --ansi-images=none README.md

Setting Up a Convenient Shell Alias

To make mdcat your default documentation viewer, add this handy alias to your ~/.bashrc or ~/.zshrc:

alias mless='mdcat'

Reload your shell configuration with source ~/.bashrc to start inspecting markdown documentation with instant readability.