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, interactive checkboxes
• 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
• JSON viewer — Render JSON files with syntax-colored keys, values, and structure
• 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)
mdterm data.json                    # view a JSON file
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

Search

Features

Slide Mode (--slides)

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