mdview

A feature-rich terminal markdown viewer built with Textual. Renders markdown beautifully in the terminal with syntax-highlighted code blocks, LaTeX math equations, table of contents navigation, full-text search, and theme switching.

Features

Markdown Rendering

Full GitHub-Flavored Markdown support including headings, paragraphs, lists, blockquotes, horizontal rules, tables, inline formatting (bold, italic, strikethrough), and syntax-highlighted code blocks.

Code Syntax Highlighting

Theme-aware fenced code blocks with Monokai highlighting in dark mode and GitHub-style highlighting in light mode. Supports 100+ languages via Pygments.

LaTeX / Math Equations

Supports both inline ($...$) and block ($$...$$) math with a smart rendering cascade:

• Image mode — high-quality PNG rendering via matplotlib (requires a terminal with graphics support)
• Unicode mode — converts LaTeX to Unicode approximations via flatlatex
• Source mode — displays raw LaTeX with syntax highlighting

Cycle through render modes with the l key.

Themes

Two built-in themes toggled with t:

• Dark (Monokai) — cyan, green, pink accents on a dark background
• Light (GitHub) — blue, green, red accents on a white background

Theme switching preserves scroll position and search state.

Table of Contents

Press Tab to open a sidebar with clickable headings. The active heading is highlighted as you scroll through the document.

Search

Press f to open the search bar:

• Live search as you type
• Smart case — lowercase query is case-insensitive, any uppercase makes it case-sensitive
• Match counter showing "X of Y"
• Enter to jump to the next match, Delete for the previous match
• Escape to close and clear highlights

Link Handling

• Anchor links (#section) scroll to the heading
• External links open in your default browser
• A URL preview bar appears briefly when hovering over links

Image Support (coming soon)

• Inline image rendering in the terminal is not yet supported
• Currently, images display as clickable (alt text) labels that open in your browser

Mermaid Diagrams (coming soon)

• Rendering of Mermaid diagram blocks is planned for a future release

Keybindings

Key	Action
j / Down	Scroll down
k / Up	Scroll up
Tab	Toggle table of contents
t	Toggle theme (dark/light)
l	Cycle LaTeX render mode
f	Toggle search bar
Enter	Next search match
Delete	Previous search match
Escape	Close search bar
Ctrl+Q	Quit

CLI Usage

mdview <file.md>                    # View a markdown file
mdview <file.md> --graphics kitty   # Force Kitty graphics protocol
mdview <file.md> --graphics sixel   # Force Sixel graphics protocol
mdview <file.md> --graphics none    # Disable graphics (text-only)

Graphics protocol is auto-detected if --graphics is not specified.

Installation

Quick Install (recommended)

git clone https://github.com/YOUR_USER/cli-markdown.git
cd cli-markdown
chmod +x install.sh
./install.sh

The install script creates a virtual environment, installs dependencies, and sets up a shell alias so you can run mdview from anywhere.

Manual Install

1. Clone and set up a virtual environment:

git clone https://github.com/YOUR_USER/cli-markdown.git
cd cli-markdown
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Add a shell alias so mdview works outside the venv. Add this line to your shell config (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, etc.):

For bash / zsh:

alias mdview='/path/to/cli-markdown/.venv/bin/python -m mdview'

For fish:

alias mdview '/path/to/cli-markdown/.venv/bin/python -m mdview'

Replace /path/to/cli-markdown with the actual path where you cloned the repo.

Then reload your shell:

source ~/.bashrc   # or ~/.zshrc

3. Verify:

mdview README.md

Requirements

• Python >= 3.9
• A terminal emulator (Kitty, WezTerm, iTerm2, etc. recommended for image rendering)

Dependencies

• textual — TUI framework
• flatlatex — LaTeX to Unicode conversion
• mdit-py-plugins — markdown-it plugins (dollarmath)
• matplotlib — LaTeX image rendering
• textual-image — terminal graphics protocol support

License

MIT