Terminal Markdown previewer — GUI-like experience.
1<p align="center">
2 <img src="images/logo-wordmark.svg" alt="leaf" width="360" />
3</p>
4
5<p align="center">
6 Terminal Markdown previewer — GUI-like experience.
7</p>
8
9<p align="center">
10 <img src="images/preview.png" alt="leaf" width="710px" /><br>
11 <sub>See more screenshots in the <a href="demo/README.md">features</a> demo</sub>
12</p>
13
14## Install
15
16Install the latest published binary.
17
18macOS / Linux / Android / Termux:
19
20```bash
21curl -fsSL https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.sh | sh
22```
23
24Windows:
25
26```powershell
27irm https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.ps1 | iex
28```
29
30npm:
31
32```bash
33npm install -g @rivolink/leaf
34```
35
36Verify the installation:
37
38```bash
39leaf --version
40```
41
42## Update
43
44Update an existing installation to the latest published release.
45
46Self:
47
48```bash
49leaf --update
50```
51
52`leaf --update` downloads the matching published asset, verifies it against the published `checksums.txt` SHA256, and then installs it.
53
54On Windows, if replacing the running `.exe` is blocked by the OS, rerun the PowerShell installer from the install section.
55
56npm:
57
58```bash
59npm update -g @rivolink/leaf
60```
61
62## Build
63
64Clone the repository:
65
66```bash
67git clone https://github.com/RivoLink/leaf.git
68cd leaf
69```
70
71Build the release binary locally:
72
73```bash
74cargo build --release
75```
76
77Create a local bin directory if needed and symlink `leaf` into it:
78
79```bash
80mkdir -p ~/.local/bin
81ln -sf "$(pwd)/target/release/leaf" ~/.local/bin/leaf
82```
83
84If `~/.local/bin` is not already on your `PATH`, add it to `~/.bashrc` or `~/.zshrc`:
85
86```bash
87export PATH="$HOME/.local/bin:$PATH"
88```
89
90## Usage
91
92```bash
93# Open a Markdown file
94leaf TESTING.md
95
96# Watch mode — reloads automatically on save
97leaf --watch TESTING.md
98leaf -w TESTING.md
99
100# Open the fuzzy Markdown picker
101leaf
102
103# Open the classic directory browser picker
104leaf --picker
105
106# Open the fuzzy Markdown picker, then watch the selected file
107leaf -w
108
109# Open the classic directory browser picker, then watch the selected file
110leaf -w --picker
111
112# Open a dash-prefixed filename
113leaf -- -notes.md
114
115# Stream Markdown from another CLI tool
116claude "explain Rust lifetimes" | leaf
117
118# Preview a local file through stdin
119cat TESTING.md | leaf
120
121```
122
123## Keybindings
124
125| Key | Action |
126|---|---|
127| `j` / `↓` | Scroll down |
128| `k` / `↑` | Scroll up |
129| `d` / PgDn | Page down (20 lines) |
130| `u` / PgUp | Page up (20 lines) |
131| `g` / Home | Top |
132| `G` / End | Bottom |
133| `t` | Toggle TOC sidebar |
134| `Shift+Sel` | Select text |
135| `Shift+T` | Open theme picker |
136| `Shift+E` | Open editor picker |
137| `Shift+P` | Open file browser |
138| `Ctrl+E` | Open in editor |
139| `Ctrl+P` | Open fuzzy picker |
140| `Ctrl+F` / `/` | Find |
141| `n` / `N` | Next / prev match |
142| `?` | Show help popup |
143| `r` | Force reload (watch mode) |
144| `q` | Quit |
145
146## Features
147
148- **Live preview** — Watch mode with automatic reload and visual feedback.
149- **File picker** — Fuzzy Markdown picker, directory browser, and watch after selection.
150- **Editor integration** — Open the current file in your preferred editor.
151- **Rich Markdown rendering** — Tables, lists, blockquotes, rules, bold, italic, and strikethrough.
152- **Syntax highlighting** — Common aliases like `py`, `cpp`, `json`, `toml`, `ps1`, `dockerfile`.
153- **LaTeX support** — Inline, block, and `latex` / `tex` code blocks rendered as formulas.
154- **Navigation** — TOC sidebar, active section tracking, heading jumps, and search.
155- **Terminal UX** — Theme picker, help popup, file path popup, mouse and keyboard support.
156- **CLI friendly** — stdin support and `leaf --update` with SHA256 verification.
157
158## Typical AI Workflow
159
160```bash
161# Terminal 1: generate the file
162aichat "..." > notes.md
163
164# Terminal 2: live watch
165leaf --watch notes.md
166```
167
168## Troubleshooting
169
170### Windows: missing Visual C++ runtime
171
172If `leaf.exe` does not start on Windows and reports a missing MSVC runtime, install the latest supported Microsoft Visual C++ Redistributable from Microsoft Learn:
173
174- https://learn.microsoft.com/fr-fr/cpp/windows/latest-supported-vc-redist?view=msvc-170
175
176Direct download for the latest supported **X64** Microsoft Visual C++ Redistributable:
177
178- https://aka.ms/vc14/vc_redist.x64.exe
179
180For `leaf-windows-x86_64.exe`, the relevant package is the latest supported **X64** Visual C++ v14 Redistributable.
181
182### Windows: update or file replacement error
183
184If `leaf --update` fails on Windows with an error about replacing, renaming, or writing `leaf.exe`, the running executable was likely locked by the OS.
185
186Close any terminal session still running `leaf`, then rerun the PowerShell installer from the install section:
187
188```powershell
189irm https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.ps1 | iex
190```
191
192## Uninstall
193
194macOS / Linux / Android / Termux:
195
196```bash
197rm -f ~/.local/bin/leaf
198```
199
200Windows:
201
202```powershell
203Remove-Item "$env:LOCALAPPDATA\Programs\leaf\leaf.exe" -Force
204```
205
206npm:
207
208```bash
209npm uninstall -g @rivolink/leaf
210```