\n\n## Install\n\nInstall the latest published binary.\n\n**macOS / Linux / Android / Termux**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.sh | sh\n```\n\n**Windows**\n\n```powershell\nirm https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.ps1 | iex\n```\n\n**npm**\n\nInstall the package from [npmjs.com](https://www.npmjs.com/package/@rivolink/leaf):\n\n```bash\nnpm install -g @rivolink/leaf\n```\n\n**Homebrew**\n\nInstall the formula from [brew.sh](https://formulae.brew.sh/formula/leaf-markdown-viewer):\n\n```bash\nbrew install leaf-markdown-viewer\n```\n\n**Cargo**\n\nInstall the crate from [crates.io](https://crates.io/crates/leaf-markdown-viewer):\n\n```bash\ncargo install leaf-markdown-viewer\n```\n\n**Scoop (Windows)**\n\nInstall the app from [scoop.sh](https://scoop.sh/#/apps?q=leaf-markdown-viewer):\n\n```bash\nscoop install leaf-markdown-viewer\n```\n\n**ArchLinux (AUR)**\n\nInstall the package from [archlinux.org](https://aur.archlinux.org/packages/leaf-markdown-viewer-bin), use an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers) such as `yay`:\n\n```bash\nyay -S leaf-markdown-viewer\n```\n\n**Verify the installation**\n\n```bash\nleaf --version\n```\n\n## Update\n\nUpdate an existing installation to the latest published release.\n\n**Self**\n\n```bash\nleaf --update\n```\n\n`leaf --update` downloads the matching published asset, verifies it against the published `checksums.txt` SHA256, and then installs it.\n\nOn Windows, if replacing the running `.exe` is blocked by the OS, rerun the PowerShell installer from the install section.\n\n**npm**\n\n```bash\nnpm update -g @rivolink/leaf\n```\n\n**Homebrew**\n\n```bash\nbrew upgrade leaf-markdown-viewer\n```\n\n**Cargo**\n\n```bash\ncargo install leaf-markdown-viewer --force\n```\n\n**Scoop (Windows)**\n\n```bash\nscoop update leaf-markdown-viewer\n```\n\n## Usage\n\n```bash\n# Open a Markdown file\nleaf TESTING.md\n\n# Watch mode: reloads automatically on save\nleaf --watch TESTING.md\nleaf -w TESTING.md\n\n# Open the fuzzy Markdown picker\nleaf\n\n# Open the fuzzy Markdown picker with a pre-filled filter\n# keyword: alphanumeric, max 15 chars\nleaf --fuzzy keyword\nleaf keyword\n\n# Open the classic directory browser picker\nleaf --picker\n\n# Open the fuzzy Markdown picker, then watch the selected file\nleaf -w\n\n# Open the classic directory browser picker, then watch the selected file\nleaf -w --picker\n\n# Open a dash-prefixed filename\nleaf -- -notes.md\n\n# Open the file history picker\nleaf --history\nleaf -H\n\n# Open the most recent from file history\nleaf --last\nleaf -l\n\n# Combine with watch mode\nleaf --last --watch\n\n# Pick a color theme\nleaf --theme forest TESTING.md\n\n# Set the external editor\nleaf --editor nvim TESTING.md\nleaf -e code TESTING.md\n\n# Cap the content width (min: 20)\nleaf --width 100 TESTING.md\n\n# Stream Markdown from another CLI tool\nclaude \"explain Rust lifetimes\" | leaf\n\n# Preview a local file through stdin\ncat TESTING.md | leaf\n```\n\n## Inline Mode\n\nRender Markdown directly to **stdout** without the interactive TUI:\n\n```bash\n# Render to terminal with colors\nleaf --inline README.md\n\n# Force plain text, no ANSI codes (no colors)\nleaf --inline plain README.md\n\n# Force ANSI colors even when piping\nleaf --inline ansi README.md\n\n# Set a specific width\nleaf --inline 60 README.md\nleaf --inline ansi:60 README.md\n\n# Pipe from stdin\ncat README.md | leaf --inline\n\n# Use as a fzf preview\nfzf --preview 'leaf --inline ansi {}'\nfzf --preview 'leaf --inline ansi:$FZF_PREVIEW_COLUMNS {}'\n```\n\n## Shell Completions\n\nEnable Tab completion for all arguments:\n\n```bash\nleaf --auto-complete\n```\n\nSupports **bash**, **zsh**, **fish**, **Nushell**, and **PowerShell**. Restart your shell to activate.\n\n## Vim Integration\nAdd the following to your `~/.vimrc` to preview the current Markdown file in a vertical split:\n\n```vim\n\" Preview the current Markdown file in a vertical split using leaf\nnnoremap md :vertical botright terminal leaf -w %\n```\n\nOnce added, use `\\md` to open a live preview. To switch focus back to the Markdown buffer, press `Ctrl+w,h`.\n\n## Configuration\n\nSet default values for **theme**, **editor**, **watch** mode, **extra** file types, and more via `config.toml`:\n\n```bash\nleaf --config\n```\n\nThis opens the configuration file in your editor. If the file does not exist yet, **leaf** creates it with documented defaults.\n\n```toml\ntheme = \"ocean\" # arctic, forest, ocean, solarized-dark, or a custom theme file\neditor = \"nano\" # any editor in PATH\nwatch = false # auto-reload when opening a file\nwidth = 80 # maximum content width (min: 20, default: terminal width)\nextras = [\"txt\", \"rs\"] # extra file types shown in the picker\nfile-picker-width = \"75%\" # width of the file picker (fuzzy + file browser)\nmain-line-numbers = false # show line numbers in the main document by default\ncode-line-numbers = true # show line numbers inside fenced code blocks\ntab-title-length = -1 # terminal tab title truncation (min: 20, -1: no truncation)\nfile-history-length = 0 # recent file history length (0 disables, max: 50)\nhyper-link-prefix = \"#\" # single character before link text (\"\" for none)\n```\n\nTo reset the configuration to defaults:\n\n```bash\nleaf --config reset\n```\n\nTo remove the configuration directory and all its contents:\n\n```bash\nleaf --config remove\n```\n\nAll settings are optional. CLI arguments always take priority. See [`config.toml`](config.toml) for details.\n\n## Open in Editor\n\nPress `Ctrl+E` to open the current file in the configured editor.\n\nUse `{$line}` in `editor` to open at the line currently visible in **leaf**:\n\n```toml\neditor = 'nano +{$line}'\neditor = 'nvim +{$line} +\"normal! zz\"'\n```\n\nFor further customization, `{$path}` is also available for the file path:\n\n```toml\neditor = 'code -g {$path}:{$line}'\n```\n\nWithout `{$line}`, the editor opens at the top of the file.\n\n## Extra Files\n\nNon-Markdown files can be listed in the file picker by adding their extensions to `config.toml`:\n\n```toml\nextras = [\"txt\", \"csv\", \"rs\", \"java\", \"json\", \"yaml\"]\n```\n\nCode files get syntax highlighting; text files are rendered as plain Markdown.\n\nAny file can also be opened directly from the command line, regardless of the `extras` setting:\n\n```bash\nleaf main.rs\n```\n\nBrowse and preview code files with fzf:\n\n```bash\nfind . -name '*.rs' | fzf --preview 'leaf --inline ansi {}'\n```\n\n## Custom Themes\n\nCreate a `.toml` file that inherits from a built-in theme and overrides specific colors:\n\n```toml\ntheme = \"/path/to/custom-theme.toml\"\n```\n\nRelative paths are resolved from the config file directory.\n\n```toml\n# custom-theme.toml\nbase = \"ocean\"\nsyntax = \"base16-ocean.dark\"\n\n[ui]\ncontent_bg = \"#282828\"\ntoc_accent = \"#fe8019\"\n\n[markdown]\ntext = \"#ebdbb2\"\nheading_1 = \"#fabd2f\"\n```\n\nSee [`gruvbox.toml`](gruvbox.toml) for a complete example with all available color keys.\n\n## Keybindings\n\n| Key | Action | Key | Action |\n|---|---|---|---|\n| `j` / `↓` | Scroll down | `?` | Show help popup |\n| `k` / `↑` | Scroll up | `p` | Show file path |\n| `d` / PgDn | Page down (20 lines) | `Shift+L` | Toggle line numbers |\n| `u` / PgUp | Page up (20 lines) | `Shift+T` | Open theme picker |\n| `g` / Home | Top | `Shift+E` | Open editor picker |\n| `G` / End | Bottom | `Shift+P` | Open file browser |\n| `1-9` / `0+1-9` | Jump / reverse jump (TOC) | `Shift+M` | Toggle mouse capture |\n| `J/K` / `U/D` | Navigate TOC | `Ctrl+P` | Open fuzzy picker |\n| `y/Y` / `c/C` | Focus code block | `Ctrl+H` | Open file history picker |\n| `Ctrl+L` / `:` | Go to line | `Ctrl+E` | Open in editor |\n| `Ctrl+F` / `/` | Find | `Ctrl+Click` | Open link |\n| `n` / `N` | Next / prev match | `Double-Click` (link) | Copy link |\n| `w` | Toggle watch mode | `Double-Click` (code) | Copy code block |\n| `r` | Force reload (watch mode) | `Shift+Drag` | Select text |\n| `t` | Toggle TOC sidebar | `Option+Drag` | Select text (iTerm2) |\n| `q` | Quit | | |\n\n## Features\n\n- **Live preview** : *Watch mode with automatic reload and visual feedback*.\n- **File picker** : *Fuzzy Markdown picker, directory browser, and watch after selection*.\n- **File history** : *Recently opened files stored in `history.toml`, picker via `Ctrl+H` or `leaf --history`*.\n- **Editor integration** : *Open the current file in your preferred editor*.\n- **Frontmatter support** : *YAML frontmatter rendered as a table (horizontal or vertical based on key count)*.\n- **Rich Markdown rendering** : *Tables, lists, blockquotes, rules, bold, italic, and strikethrough*.\n- **GitHub extras** : *Alert callouts, task list checkboxes, and `==mark==` text highlighting*.\n- **Inline HTML tags** : *Common inline formatting tags (``, ``, ``, ...) rendered with proper styling*.\n- **Extra file types** : *Open any file; code files get syntax highlighting, text files render as Markdown*.\n- **Syntax highlighting** : *Common aliases like `py`, `cpp`, `json`, `toml`, `ps1`, `dockerfile`*.\n- **Line numbers** : *Toggle display with `Shift+L`, jump to a line with `Ctrl+L` or `:`*.\n- **LaTeX support** : *Inline, block, and `latex` / `tex` code blocks rendered as formulas*.\n- **Mermaid diagrams** : *`mermaid` code blocks rendered as ASCII diagrams*.\n- **Clickable links** : *`Ctrl+Click` to open, double-click to copy, hover feedback*.\n- **Code block interactions** : *Focus and copy with `y/Y` / `c/C`, or double-click on a block*.\n- **Mouse capture** : *`Shift+M` to toggle mouse capture and let the terminal handle selection*.\n- **Navigation** : *TOC sidebar, active section tracking, heading jumps, and search*.\n- **Terminal UX** : *Theme picker, help popup, file path popup, mouse and keyboard support*.\n- **Custom themes** : *TOML theme files inheriting from built-in presets with color overrides*.\n- **Inline mode** : *Render to stdout with `--inline` for pipes and fzf previews*.\n- **Shell completions** : *Tab completion for bash, zsh, fish, Nushell, and PowerShell via `leaf --auto-complete`*.\n- **CLI friendly** : *stdin support and `leaf --update` with SHA256 verification*.\n\n## Typical AI Workflow\n\n```bash\n# Terminal 1: generate the file\naichat \"...\" > notes.md\n\n# Terminal 2: live watch\nleaf --watch notes.md\n```\n\n## Troubleshooting\n\n### Windows: missing Visual C++ runtime\n\nIf `leaf.exe` does not start on Windows or reports a missing MSVC runtime, install the latest supported Microsoft Visual C++ Redistributable from Microsoft Learn:\n\n- https://learn.microsoft.com/fr-fr/cpp/windows/latest-supported-vc-redist?view=msvc-170\n\nDirect download for the latest supported **X64** Microsoft Visual C++ Redistributable:\n\n- https://aka.ms/vc14/vc_redist.x64.exe\n\nFor `leaf-windows-x86_64.exe`, the relevant package is the latest supported **X64** Visual C++ v14 Redistributable.\n\n### Windows: update or file replacement error\n\nIf `leaf --update` fails on Windows with an error about replacing, renaming, or writing `leaf.exe`, the running executable was likely locked by the OS.\n\nClose any terminal session still running `leaf`, then rerun the PowerShell installer from the install section:\n\n```powershell\nirm https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.ps1 | iex\n```\n\n### Windows: auto-complete execution policy error\n\nIf PowerShell reports that running scripts is disabled on this system after `leaf --auto-complete`, allow local scripts and restart PowerShell:\n\n```powershell\nSet-ExecutionPolicy RemoteSigned -Scope CurrentUser\n```\n\n## Uninstall\n\nThe uninstall script removes the **leaf** configuration, shell auto-completion, and binary. It is interactive, so download first and run locally.\n\n**macOS / Linux / Android / Termux**\n\n```bash\n# Download\ncurl -fsSL https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/uninstall.sh -o uninstall.sh\n\n# Run\nsh uninstall.sh\n```\n\n**Windows**\n\n```powershell\n# Download\nirm https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/uninstall.ps1 -OutFile uninstall.ps1\n\n# Run\npowershell -ExecutionPolicy Bypass -File .\\uninstall.ps1\n```\n\n**npm**\n\n```bash\nleaf --config remove\nleaf --auto-complete remove\n\nnpm uninstall -g @rivolink/leaf\n```\n\n**Homebrew**\n\n```bash\nleaf --config remove\nleaf --auto-complete remove\n\nbrew uninstall leaf-markdown-viewer\n```\n\n**Cargo**\n\n```bash\nleaf --config remove\nleaf --auto-complete remove\n\ncargo uninstall leaf-markdown-viewer\n```\n\n**Scoop (Windows)**\n\n```bash\nleaf --config remove\nleaf --auto-complete remove\n\nscoop uninstall leaf-markdown-viewer\n```\n\n## Contributors\n\nThanks to all contributors.\n\n\n\n## Support\n\nContributions are welcome. Feel free to open an issue or submit a pull request.\n\nSee the [CONTRIBUTING.md](CONTRIBUTING.md) file for details.\n\nIf you like **leaf**, consider giving the project a star ⭐\n\n## License\n\nThis project is licensed under the MIT License.\n\nSee the [LICENSE](LICENSE) file for details.\n","readmeFilename":"README.md"}
![\"leaf\"](\"images/logo-wordmark.svg\"){kind=logo}
\n![\"leaf\"](\"images/preview.png\")