https://github.com/rrbe/termdown
Render Markdown in terminal with large-font headings.
https://github.com/rrbe/termdown
Last synced: 3 months ago
JSON representation
Render Markdown in terminal with large-font headings.
- Host: GitHub
- URL: https://github.com/rrbe/termdown
- Owner: rrbe
- License: apache-2.0
- Created: 2026-04-14T16:10:59.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-04-14T16:21:20.000Z (3 months ago)
- Last Synced: 2026-04-14T18:12:49.049Z (3 months ago)
- Language: Rust
- Size: 152 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Termdown
[中文文档](README_CN.md)
Render Markdown with large-font headings in the terminal using the Kitty graphics protocol.
## Motivation
Inspired by [glow](https://github.com/charmbracelet/glow) and [mdfried](https://github.com/benjajaja/mdfried).
glow is a great terminal Markdown renderer, but headings are only distinguished by ANSI bold/color -- they can't actually be displayed at a larger size. mdfried supports image-rendered headings, but requires entering a TUI.
termdown aims to be **a lightweight `cat`-like tool where headings are truly rendered large**. It rasterizes H1-H3 text as PNG images and displays them via the Kitty graphics protocol -- no TUI, pipe-friendly, just direct output.
## Terminal Support
Requires a terminal with **Kitty graphics protocol** support:
- [Ghostty](https://ghostty.org)
- [Kitty](https://sw.kovidgoyal.net/kitty/)
- [WezTerm](https://wezfurlong.org/wezterm/)
- [iTerm2](https://iterm2.com)
On unsupported terminals, termdown will print a warning and heading images may not display correctly. H4-H6 headings always render as plain ANSI bold text.
## Installation
### From source
```sh
cargo install --path .
```
### Build manually
```sh
cargo build --release
cp target/release/termdown /usr/local/bin/
```
## Usage
```sh
# Render a file
termdown README.md
# Pipe from stdin
cat notes.md | termdown
# Use a specific theme instead of auto-detect
termdown --theme light README.md
# Flags
termdown --help
termdown --version
```
## Configuration
termdown reads configuration from `~/.termdown/config.toml`.
```toml
# Theme: "auto" (default), "dark", or "light"
# Auto-detection queries the terminal background color via OSC 11.
theme = "auto"
[font.heading]
# Font for Latin/English text in H1-H3 headings (sans-serif recommended)
latin = "Inter"
# Font for CJK text in H1-H3 headings
cjk = "LXGW WenKai"
# Optional emoji / symbol fallback font for image-rendered headings
emoji = "Apple Color Emoji"
```
Headings with mixed scripts (e.g. "Hello 世界") will render each character with the appropriate font automatically.
Standalone emoji in H1-H3 headings are also supported through font fallback when the selected emoji font exposes outline or raster glyphs.
> **Note:** Body text is rendered as plain ANSI text -- its font is determined by your terminal emulator settings, not by termdown. To change the body font, configure your terminal directly.
If no config file exists, termdown uses platform-specific defaults and falls back to an embedded SourceSerif4 font.
### Platform default heading fonts
**Latin** (sans-serif):
| macOS | Linux | Windows |
|-------|-------|---------|
| Avenir | Inter | Segoe UI |
| Avenir Next | Noto Sans | Arial |
| Futura | DejaVu Sans | Verdana |
| Helvetica Neue | Liberation Sans | |
**CJK**:
| macOS | Linux | Windows |
|-------|-------|---------|
| Noto Serif CJK SC | Noto Serif CJK SC | SimSun |
| Source Han Serif SC | Source Han Serif SC | KaiTi |
| Songti SC | Noto Serif | Microsoft YaHei |
| STSong | DejaVu Serif | |
## Uninstall
Remove the binary and delete the configuration directory:
```sh
rm $(which termdown)
rm -rf ~/.termdown
```
## Known Issues
- **Line wrapping** -- long lines may not wrap correctly when mixed with ANSI escape sequences
- **Terminal compatibility** -- only tested on Ghostty and iTerm2; other Kitty-protocol terminals may behave differently
- **Font selection & fallback** -- weight matching relies on platform font APIs (Core Text / fontconfig) which may not always resolve to the expected variant
- **Theme detection** -- auto-detection relies on OSC 11 terminal responses; if your terminal does not support this, use `--theme` or the config file to set the theme manually
- **Complex emoji sequences** -- ZWJ-heavy emoji sequences (family/grouping variants, some skin-tone combinations) may still render as separate glyphs because heading layout does not perform full text shaping
## License
[Apache-2.0](LICENSE)