Terminal Markdown previewer — GUI-like experience.

Fork of RivoLink/leaf with a Grok-based Unicode Mermaid renderer.

_{See more screenshots in the features demo}

Upstream leaf renders Mermaid via the mmdflux crate. This fork replaces that dependency with the self-contained Unicode Mermaid engine from xAI Grok Build (xai-grok-markdown mermaid module), vendored as src/markdown/mermaid_engine.rs under Apache-2.0 (see NOTICE).

Simple sequence charts and small flowcharts usually look good. Dense multi-hop flowchart LR graphs with many back-edges may be clearer as source fallback than as full-width art — that is a limit of the Unicode layout engine, not of leaf’s framing.

Homebrew core already has unrelated formulae named leaf (Go reloader) and leaf-md (upstream Markdown viewer). Install this fork with a fully qualified name:

brew tap Shi1xin/leaf https://github.com/Shi1xin/leaf
brew install shi1xin/leaf/leaf

If brew reports a conflict, remove the other package first:

brew uninstall leaf      # Go reloader, if present
brew uninstall leaf-md   # upstream markdown leaf, if present
brew install shi1xin/leaf/leaf

Upgrade later:

brew update
brew upgrade shi1xin/leaf/leaf

macOS / Linux / Android / Termux:

curl -fsSL https://raw.githubusercontent.com/Shi1xin/leaf/main/scripts/install.sh | sh

Windows:

irm https://raw.githubusercontent.com/Shi1xin/leaf/main/scripts/install.ps1 | iex

Default install location: ~/.local/bin/leaf (Unix) or %LOCALAPPDATA%\Programs\leaf (Windows). Ensure that directory is on your PATH.

leaf --version

Self-update (downloads the latest Shi1xin/leaf GitHub Release):

leaf --update

Requirements: Rust (stable), a C linker (Xcode CLT on macOS, build-essential on Debian/Ubuntu, etc.).

git clone https://github.com/Shi1xin/leaf.git
cd leaf
cargo build --release
cp -f target/release/leaf ~/.local/bin/leaf

Keep stock leaf under another name for comparison:

# after installing official leaf somewhere:
mv ~/.local/bin/leaf ~/.local/bin/leaf-official   # or use upstream’s installer into a temp dir
# then install this fork as `leaf` via brew or install.sh
leaf --version            # fork (Grok Mermaid)
leaf-official --version   # upstream (mmdflux)

For stock leaf (mmdflux Mermaid, npm, AUR), see RivoLink/leaf.

# Homebrew
brew upgrade leaf

# install.sh binary
leaf --update

# source checkout
cd /path/to/leaf && git pull && cargo build --release
cp -f target/release/leaf ~/.local/bin/leaf

# Open a Markdown file
leaf TESTING.md

# Watch mode — reloads automatically on save
leaf --watch TESTING.md
leaf -w TESTING.md

# Open the fuzzy Markdown picker
leaf

# Open the classic directory browser picker
leaf --picker

# Open the fuzzy Markdown picker, then watch the selected file
leaf -w

# Open the classic directory browser picker, then watch the selected file
leaf -w --picker

# Open a dash-prefixed filename
leaf -- -notes.md

# Pick a color theme
leaf --theme forest TESTING.md

# Set the external editor
leaf --editor nvim TESTING.md
leaf -e code TESTING.md

# Cap the content width (min: 20)
leaf --width 100 TESTING.md

# Stream Markdown from another CLI tool
claude "explain Rust lifetimes" | leaf

# Preview a local file through stdin
cat TESTING.md | leaf

Render Markdown directly to stdout without the interactive TUI:

# Render to terminal with colors
leaf --inline README.md

# Force plain text, no ANSI codes (no colors)
leaf --inline plain README.md

# Force ANSI colors even when piping
leaf --inline ansi README.md

# Set a specific width
leaf --inline 60 README.md
leaf --inline ansi:60 README.md

# Pipe from stdin
cat README.md | leaf --inline

# Use as a fzf preview
fzf --preview 'leaf --inline ansi {}'
fzf --preview 'leaf --inline ansi:$FZF_PREVIEW_COLUMNS {}'

Enable Tab completion for all arguments:

leaf --auto-complete

Supports bash, zsh, fish, and PowerShell. Restart your shell to activate.

Add the following to your ~/.vimrc to preview the current Markdown file in a vertical split:

" Preview the current Markdown file in a vertical split using leaf
nnoremap <Leader>md :vertical botright terminal leaf -w %<CR>

Once added, use \md to open a live preview. To switch focus back to the Markdown buffer, press Ctrl+w,h.

Set default values for theme, editor, watch mode and extra file types via config.toml:

leaf --config

This opens the configuration file in your editor. If the file does not exist yet, leaf creates it with documented defaults.

theme = "ocean"           # arctic, forest, ocean, solarized-dark, or a custom theme file
editor = "nano"           # any editor in PATH
watch = false             # auto-reload when opening a file
width = 80                # maximum content width (min: 20, default: terminal width)
extras = ["txt", "rs"]    # extra file types shown in the picker
code-line-numbers = true  # show line numbers inside fenced code blocks
tab-title-length = -1     # terminal tab title truncation (min: 20, -1: no truncation)

To reset the configuration to defaults:

leaf --config reset

All settings are optional. CLI arguments always take priority. See config.toml for details.

Press Ctrl+E to open the current file in the configured editor.

Use {$line} in editor to open at the line currently visible in leaf:

editor = 'nano +{$line}'
editor = 'nvim +{$line} +"normal! zz"'

For further customization, {$path} is also available for the file path:

editor = 'code -g {$path}:{$line}'

Without {$line}, the editor opens at the top of the file.

Non-Markdown files can be listed in the file picker by adding their extensions to config.toml:

extras = ["txt", "csv", "rs", "java", "json", "yaml"]

Code files get syntax highlighting; text files are rendered as plain Markdown.

Any file can also be opened directly from the command line, regardless of the extras setting:

leaf main.rs

Browse and preview code files with fzf:

find . -name '*.rs' | fzf --preview 'leaf --inline ansi {}'

Create a .toml file that inherits from a built-in theme and overrides specific colors:

theme = "/path/to/custom-theme.toml"

Relative paths are resolved from the config file directory.

# custom-theme.toml
base = "ocean"
syntax = "base16-ocean.dark"

[ui]
content_bg = "#282828"
toc_accent = "#fe8019"

[markdown]
text = "#ebdbb2"
heading_1 = "#fabd2f"

See gruvbox.toml for a complete example with all available color keys.

• Live preview : Watch mode with automatic reload and visual feedback.
• File picker : Fuzzy Markdown picker, directory browser, and watch after selection.
• Editor integration : Open the current file in your preferred editor.
• Frontmatter support : YAML frontmatter rendered as a table (horizontal or vertical based on key count).
• Rich Markdown rendering : Tables, lists, blockquotes, rules, bold, italic, and strikethrough.
• GitHub extras : Alert callouts, task list checkboxes, and ==mark== text highlighting.
• Extra file types : Open any file; code files get syntax highlighting, text files render as Markdown.
• Syntax highlighting : Common aliases like py, cpp, json, toml, ps1, dockerfile.
• Line numbers : Toggle display with Shift+L, jump to a line with Ctrl+L.
• LaTeX support : Inline, block, and latex / tex code blocks rendered as formulas.
• Mermaid diagrams : mermaid code blocks rendered as Unicode box-drawing art via the Grok terminal engine (this fork); unsupported or oversize diagrams fall back to colored source.
• Clickable links : Ctrl+Click to open, double-click to copy, hover feedback.
• Code block interactions : Focus and copy with y/Y / c/C, or double-click on a block.
• Mouse capture : Shift+M to toggle mouse capture and let the terminal handle selection.
• Navigation : TOC sidebar, active section tracking, heading jumps, and search.
• Terminal UX : Theme picker, help popup, file path popup, mouse and keyboard support.
• Custom themes : TOML theme files inheriting from built-in presets with color overrides.
• Inline mode : Render to stdout with --inline for pipes and fzf previews.
• Shell completions : Tab completion for bash, zsh, fish, and PowerShell via leaf --auto-complete.
• CLI friendly : stdin support and leaf --update with SHA256 verification.

# Terminal 1: generate the file
aichat "..." > notes.md

# Terminal 2: live watch
leaf --watch notes.md

If leaf.exe does not start on Windows or reports a missing MSVC runtime, install the latest supported Microsoft Visual C++ Redistributable from Microsoft Learn:

• https://learn.microsoft.com/fr-fr/cpp/windows/latest-supported-vc-redist?view=msvc-170

Direct download for the latest supported X64 Microsoft Visual C++ Redistributable:

• https://aka.ms/vc14/vc_redist.x64.exe

For leaf-windows-x86_64.exe, the relevant package is the latest supported X64 Visual C++ v14 Redistributable.

If leaf --update fails on Windows with an error about replacing, renaming, or writing leaf.exe, the running executable was likely locked by the OS.

Close any terminal session still running leaf, then rerun the PowerShell installer from the install section:

irm https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.ps1 | iex

If PowerShell reports that running scripts is disabled on this system after leaf --auto-complete, allow local scripts and restart PowerShell:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS / Linux / Android / Termux:

rm -f ~/.local/bin/leaf

Windows:

Remove-Item "$env:LOCALAPPDATA\Programs\leaf\leaf.exe" -Force

npm:

npm uninstall -g @rivolink/leaf

Thanks to all contributors.

Contributions are welcome. Feel free to open an issue or submit a pull request.

See the CONTRIBUTING.md file for details.

If you like leaf, consider giving the project a star ⭐

This project is licensed under the MIT License.

See the LICENSE file for details.