https://github.com/zemse/md-tui
Terminal markdown reader with mouse support, clickable links and task lists, fuzzy search, and a directory browser.
https://github.com/zemse/md-tui
Last synced: about 1 month ago
JSON representation
Terminal markdown reader with mouse support, clickable links and task lists, fuzzy search, and a directory browser.
- Host: GitHub
- URL: https://github.com/zemse/md-tui
- Owner: zemse
- License: mit
- Created: 2026-05-05T15:09:06.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-05T17:04:41.000Z (about 2 months ago)
- Last Synced: 2026-05-05T17:20:50.339Z (about 2 months ago)
- Language: Rust
- Size: 64.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# md
A terminal markdown reader. Built with Rust + [ratatui](https://ratatui.rs).
## Install
```sh
cargo install md-tui-rs
```
Or from a local checkout:
```sh
cargo install --path .
```
The binary is named `md`.
## Use
```sh
md # browse the current directory
md README.md # open a file
md docs/ # browse a directory
cat NOTES.md | md # read from stdin
```
## Features
- **Mouse-aware** — wheel to scroll, click links to follow, hover for highlight, click `‹ Back` in the header.
- **Clickable task lists** — click `- [ ]` / `- [x]` to toggle; the file is rewritten in place.
- **Native text selection** — press `m` to drop mouse capture and drag-select with the terminal.
- **In-document search** — `/` in Reader, then `n`/`N` to step matches; `T` for fuzzy file search.
- **Directory browser** — full-screen one-level listing; `Enter`/`→` opens or descends, `Esc`/`←` walks back; gitignore-aware.
- **Wiki links** — `[[Page]]` / `[[Page|Display]]` resolve relative to the current file or anywhere under the launch root.
- **Image rendering** — kitty / iTerm2 / sixel / unicode halfblocks via `ratatui-image` when supported.
- **`$EDITOR` integration** — press `e` to edit the current file; the TUI restores after the editor exits.
- **Header bar** — current path with a clickable back button.
- **Proportional scrollbar** — thumb size reflects how much of the document is visible.
- **History** — `h`/`l` (or `b`/`f`) walk back and forward; cursor and scroll position are remembered.
- **Themes** — Catppuccin Mocha / Latte; auto-selects from `COLORFGBG`, override with `-s dark|light`.
- **GitHub-flavored** — tables, strikethrough, footnotes, task lists, code-block syntax highlighting (syntect), heading anchors.
## Keys
| Key | Action |
| -------------- | ------------------------------------------------------ |
| `j` / `k` | Scroll down / up |
| `d` / `u` | Half page down / up |
| `g` / `G` | Top / bottom |
| `Tab` / `S-Tab`| Next / previous link |
| `Enter` / `→` | Open file / enter directory / follow link |
| `Esc` / `←` | Back (parent directory or previous view) |
| `/` | In-doc search (Reader) / fuzzy file search (Browser) |
| `n` / `N` | Next / previous in-doc match |
| `T` | Fuzzy file search (anywhere) |
| `o` | Open focused link in system browser |
| `e` | Edit current file in `$EDITOR` |
| `h` / `l` | Back / forward in history |
| `m` | Toggle mouse capture (drag-to-select) |
| `?` | Help |
| `q` / `Ctrl-C` | Quit |
## Config
Optional `md/config.toml` under your platform config dir
(`~/.config/md/config.toml` on Linux, `~/Library/Application Support/md/config.toml`
on macOS):
```toml
theme = "dark" # "dark" | "light" | "auto"
width = 0 # word-wrap width; 0 = terminal width
line_numbers = false
```
CLI flags override the config: `-s dark|light|auto`, `-w 100`, `-l`.
## License
[MIT](LICENSE)