https://github.com/birsax2/mdcat
cat for markdown
https://github.com/birsax2/mdcat
cat iterm2 kitty markdown terminal
Last synced: 16 days ago
JSON representation
cat for markdown
- Host: GitHub
- URL: https://github.com/birsax2/mdcat
- Owner: BIRSAx2
- License: mpl-2.0
- Created: 2026-06-18T12:43:59.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-30T06:33:28.000Z (25 days ago)
- Last Synced: 2026-06-30T08:12:17.274Z (25 days ago)
- Topics: cat, iterm2, kitty, markdown, terminal
- Language: Rust
- Homepage: https://crates.io/crates/mdcat
- Size: 3.61 MB
- Stars: 10
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# mdcat
Fancy `cat` for Markdown (that is, [CommonMark][]):
```
$ mdcat sample.md
```
![mdcat showcase with different colour themes][sxs]
mdcat in [Ghostty], with `--theme catppuccin-mocha`, `--theme dracula`,
and `--theme nord` (left to right), using [JetBrains Mono].
[CommonMark]: http://commonmark.org
[JetBrains Mono]: https://www.jetbrains.com/lp/mono/
[sxs]: ./screenshots/side-by-side.png
## Features
`mdcat` works best with [iTerm2], [WezTerm], [kitty], and [Ghostty], and a good terminal font with italic characters.
Then it
- nicely renders all basic CommonMark syntax,
- renders footnotes and inline markup in table cells,
- highlights code blocks with syntax definitions from [bat] (TOML, TypeScript, Dockerfile, Zig, Nix, and more),
using the colour theme of your choice — including any theme [bat] supports via `$BAT_THEME`,
- renders inline and display math, as PNGs through the iTerm2 or kitty image protocol, and as Unicode substitutions otherwise,
- renders [GFM alerts][gfm-alerts] (`[!NOTE]`, `[!TIP]`, `[!WARNING]`, etc.) with coloured borders and icons,
- shows [links][osc8], and also images inline in supported terminals (see above, where "Rust" is a clickable link!),
- adds jump marks for headings in [iTerm2] (jump forwards and backwards with ⇧⌘↓ and ⇧⌘↑),
- ships eight built-in colour themes (`catppuccin-mocha`, `catppuccin-latte`, `gruvbox-dark`, `gruvbox-light`,
`dracula`, `nord`, `solarized-dark`, `solarized-light`) plus auto dark/light detection.
| Terminal | Basic syntax | Syntax highlighting | Images | Math | Jump marks |
| :----------------- | :----------: | :-----------------: | :----: | :---: | :--------: |
| Basic ANSI¹ | ✓ | ✓ | | ✓³ | |
| Windows 10 console | ✓ | ✓ | | ✓³ | |
| [iTerm2] | ✓ | ✓ | ✓² | ✓³ | ✓ |
| [kitty] | ✓ | ✓ | ✓² | ✓³ | |
| [WezTerm] | ✓ | ✓ | ✓² | ✓³ | |
| [VSCode] | ✓ | ✓ | | ✓³ | |
| [Ghostty] | ✓ | ✓ | ✓² | ✓³ | |
| [foot]⁴ | ✓ | ✓ | ✓² | ✓³‧⁵ | |
| [xterm]⁴ | ✓ | ✓ | ✓² | ✓³‧⁵ | |
1. mdcat requires that the terminal supports strikethrough formatting and [inline links][osc8].
This includes most modern terminal emulators, such as Windows Terminal, KDE Konsole, or anything based on VTE, GNOME's terminal emulation library.
But mdcat likely won't work well on old terminals that lack these features (e.g. the Linux text console).
2. SVG images are rendered with [resvg], see [SVG support].
3. On terminals with the iTerm2, kitty, or Sixel image protocol, math is rendered as PNG images.
Otherwise mdcat uses Unicode substitutions.
4. Uses Sixel for images, which is also supported by many other terminals.
The capability detection logic would need to be extended to also provide the feature on other terminals, though.
5. Inline math with Sixel breaks the layout, as it causes vertical scrolling that is not taking into account.
Not supported:
- Text wrapping inside table cells.
[bat]: https://github.com/sharkdp/bat
[gfm-alerts]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
[osc8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
[iterm2]: https://www.iterm2.com
[WezTerm]: https://wezfurlong.org/wezterm/
[kitty]: https://sw.kovidgoyal.net/kitty/
[resvg]: https://github.com/RazrFalcon/resvg
[SVG support]: https://github.com/RazrFalcon/resvg#svg-support
[VSCode]: https://code.visualstudio.com/
[Ghostty]: https://mitchellh.com/ghostty
[foot]: https://codeberg.org/dnkl/foot
[xterm]: https://invisible-island.net/xterm/xterm.html
## Usage
Try `mdcat --help` or read the [mdcat(1)](./mdcat.1.adoc) manpage.
To pick a colour theme:
```console
$ mdcat --theme catppuccin-mocha sample.md
$ MDCAT_THEME=dracula mdcat sample.md
```
To use a [bat] syntax-highlighting theme for code blocks:
```console
$ BAT_THEME="Catppuccin Mocha" mdcat sample.md
```
See [sample/math.md](./sample/math.md) for math examples, [sample/alerts.md](./sample/alerts.md) for GFM alerts, and [sample/tables.md](./sample/tables.md) for table rendering.
## Installation
- [Release binaries](https://github.com/BIRSAx2/mdcat/releases/) built on Github Actions.
- These binaries are built from Git source on Github Actions; you find provenance attestations at .
- 3rd party packages at [Repology](https://repology.org/project/mdcat/versions)
- You can also build `mdcat` manually with `cargo install mdcat` (see below for details).
`mdcat` can be linked or copied to `mdless`; if invoked as `mdless` it automatically uses pagination.
## Building
Run `cargo build --release`.
Building requires `libcurl`.
## Packaging
When packaging `mdcat` you may wish to include the following additional artifacts:
- A symlink or hardlink from `mdless` to `mdcat` (see above).
- Shell completions for relevant shells, by invoking `mdcat --completions` after building, e.g.
```console
$ mdcat --completions fish > /usr/share/fish/vendor_completions.d/mdcat.fish
$ mdcat --completions bash > /usr/share/bash-completion/completions/mdcat
$ mdcat --completions zsh > /usr/share/zsh/site-functions/_mdcat
# Same for mdless if you include it
$ mdless --completions fish > /usr/share/fish/vendor_completions.d/mdless.fish
$ mdless --completions bash > /usr/share/bash-completion/completions/mdless
$ mdless --completions zsh > /usr/share/zsh/site-functions/_mdless
```
- A build of the man page `mdcat.1.adoc`, using [AsciiDoctor]:
```console
$ asciidoctor -b manpage -a reproducible -o /usr/share/man/man1/mdcat.1 mdcat.1.adoc
$ gzip /usr/share/man/man1/mdcat.1
# If you include a mdless as above, you may also want to support man mdless
$ ln -s mdcat.1.gz /usr/share/man/man1/mdless.1.gz
```
[AsciiDoctor]: https://asciidoctor.org/
## Troubleshooting
`mdcat` can output extensive tracing information when asked to.
Run `mdcat` with `$MDCAT_LOG=trace` for complete tracing information, or with `$MDCAT_LOG=mdcat::render=trace` to trace only rendering.
## License
Copyright Sebastian Wiesner and Mouhieddine Sabir
Currently maintained by [BIRSAx2](https://github.com/BIRSAx2).
Binaries are subject to the terms of the Mozilla Public
License, v. 2.0, see [LICENSE](LICENSE).
Most of the source is subject to the terms of the Mozilla Public
License, v. 2.0, see [LICENSE](LICENSE), unless otherwise noted;
some files are subject to the terms of the Apache 2.0 license,
see