mdterm

A terminal-based Markdown viewer written in Rust. Renders Markdown files with syntax highlighting, styled formatting, and interactive navigation.

Screenshots

Features

• Interactive TUI — Scroll, navigate with keyboard and mouse
• Syntax highlighting — Code blocks highlighted via syntect (base16-ocean.dark / InspiredGitHub themes)
• Rich formatting — Headings, bold, italic, strikethrough, lists, blockquotes, tables, task lists
• Inline images — Renders images in the terminal via Kitty, iTerm2, or Unicode half-block fallback
• Clickable links — OSC 8 hyperlinks in supporting terminals
• In-document search — / to search with regex support, n/N to jump between matches
• Table of contents — Press o to browse and jump to any heading
• Fuzzy heading search — Press : to filter headings by name
• Heading jumps — [ / ] to jump between sections
• Local file links — Click or select relative markdown links to navigate between files, with Backspace to go back
• Link picker — Press f to list all links, type a number to open in browser
• Click-to-copy — Click any heading section, list, or code block to copy it; Y copies full document, c copies nearest code block
• Mermaid diagrams — Visual rendering of flowcharts/graphs in the terminal with box-drawing characters
• Math rendering — LaTeX to Unicode: $\alpha + \beta$ renders as α + β
• Slide mode — --slides treats --- as slide separators for terminal presentations
• Auto-reload — Automatically detects file changes and reloads (via inotify/FSEvents/kqueue)
• Stdin support — Pipe markdown from any command: curl ... | mdterm
• Multiple files — mdterm a.md b.md, switch with Tab / Shift+Tab
• HTML export — --export html outputs themed, self-contained HTML
• Dark/light themes — Toggle with t, or set via --theme / config file
• Line numbers — Toggle with l for code blocks
• Config file — ~/.config/mdterm/config.toml for persistent preferences
• Word wrapping — Responsive re-wrapping on terminal resize
• Pipe-friendly — Outputs plain styled text when stdout is piped

Installation

Requires Rust 1.85+ (edition 2024).

cargo install --path .

Usage

mdterm README.md                    # view a file
mdterm a.md b.md                    # multiple files (Tab to switch)
cat README.md | mdterm              # read from stdin
mdterm --slides deck.md             # slide mode
mdterm --export html doc.md > out.html  # export to HTML
mdterm --theme light README.md      # light theme
mdterm -l README.md                 # line numbers in code blocks

When piped, mdterm outputs styled text without the interactive viewer:

mdterm README.md | less -R

Controls

Navigation

Key	Action
j / Down	Scroll down one line
k / Up	Scroll up one line
Space / Page Down	Page down
b / Page Up	Page up
d / u (or Ctrl+d / Ctrl+u)	Half-page down / up
g / Home	Jump to top
G / End	Jump to bottom
[ / ]	Previous / next heading
Backspace	Go back (after following a local file link)
Mouse scroll	Scroll up/down

Search

Key	Action
/	Open search (supports regex)
Enter	Execute search
n / N	Next / previous match
Esc	Clear search

Features

Key	Action
o	Table of contents overlay
:	Fuzzy heading search
f	Link picker (open URLs / follow local links)
t	Toggle dark/light theme
l	Toggle line numbers in code blocks
Click heading	Copy heading section to clipboard
Click list	Copy entire list to clipboard
Click code block	Copy code block to clipboard
Y	Copy entire document to clipboard
c	Copy nearest code block to clipboard
Tab / Shift+Tab	Switch between files
F1	Help screen
q / Ctrl+C	Quit

Slide Mode (--slides)

Key	Action
Right / Space / l / j / Down / Page Down	Next slide
Left / b / h / k / Up / Page Up	Previous slide
g / Home	First slide
G / End	Last slide

Configuration

Create ~/.config/mdterm/config.toml:

theme = "dark"          # "dark" or "light"
line_numbers = false     # show line numbers in code blocks
width = 0               # display width (0 = auto)

CLI flags override config file settings.

CLI Reference

mdterm [OPTIONS] [FILES]...

Arguments:
  [FILES]...               Markdown file(s) to view

Options:
  -T, --theme <THEME>      Theme: dark or light
  -w, --width <WIDTH>      Display width override (0 = auto)
  -s, --slides             Slide mode (--- as slide separators)
  -l, --line-numbers       Show line numbers in code blocks
      --export <FORMAT>    Export format (html)
      --no-color           Disable colors
  -h, --help               Print help
  -V, --version            Print version

Building

cargo build --release

Demo

License

MIT