Terminal Markdown previewer — GUI-like experience.
Merge pull request #16 from RivoLink/docs/contributing-security-guides
docs: contributing and security guides
+188
-23
+104
CONTRIBUTING.md
+104
CONTRIBUTING.md
···
1
+
# Contributing
2
+
3
+
Thank you for your interest in contributing to `leaf`.
4
+
5
+
## Getting Started
6
+
7
+
1. Fork the repository.
8
+
2. Clone your fork:
9
+
10
+
```bash
11
+
git clone https://github.com/<your-username>/leaf.git
12
+
cd leaf
13
+
```
14
+
15
+
3. Install Rust if needed:
16
+
17
+
```bash
18
+
rustup show
19
+
```
20
+
21
+
4. Build the project:
22
+
23
+
```bash
24
+
cargo build
25
+
```
26
+
27
+
5. Run the application:
28
+
29
+
```bash
30
+
cargo run -- README.md
31
+
```
32
+
33
+
## Development Workflow
34
+
35
+
Before submitting a PR, run the full validation sequence:
36
+
37
+
```bash
38
+
cargo test
39
+
cargo clippy --all-targets --all-features -- -D warnings
40
+
cargo build --release
41
+
```
42
+
43
+
## Pull Requests
44
+
45
+
1. Create a feature branch from `main`.
46
+
2. Make focused changes.
47
+
3. Keep documentation in sync when behavior changes.
48
+
4. Ensure all checks pass.
49
+
5. Open a PR with a clear description of:
50
+
- what changed;
51
+
- why it changed;
52
+
- how it was tested.
53
+
54
+
## Commit Messages
55
+
56
+
- Use clear, direct messages.
57
+
- Keep the first line short.
58
+
- Prefer the existing prefixes used in the repository when they fit.
59
+
60
+
Examples:
61
+
62
+
- `feat: custom themes`
63
+
- `chore: refactor main.rs`
64
+
- `fix: file picker alignment`
65
+
- `docs: update README.md`
66
+
67
+
## Code Style
68
+
69
+
- Follow the existing Rust style in the repository.
70
+
- Prefer small, targeted refactors over broad rewrites.
71
+
- Preserve the current terminal UX unless the change explicitly improves it.
72
+
- Keep ASCII by default unless the file already uses Unicode intentionally.
73
+
74
+
## Testing Notes
75
+
76
+
- Add regression tests when fixing rendering or parsing bugs.
77
+
- Prefer narrow, behavior-focused tests over snapshot-heavy tests.
78
+
- If a change affects terminal layout, verify both tests and manual rendering.
79
+
80
+
## Architecture
81
+
82
+
See:
83
+
84
+
- [ARCHITECTURE.md](./ARCHITECTURE.md)
85
+
86
+
## Releases
87
+
88
+
Release automation lives in:
89
+
90
+
- [.github/workflows/release-cut.yml](./.github/workflows/release-cut.yml)
91
+
- [.github/workflows/release-build.yml](./.github/workflows/release-build.yml)
92
+
- [scripts/release-cut.sh](./scripts/release-cut.sh)
93
+
94
+
Installers live in:
95
+
96
+
- [scripts/install.sh](./scripts/install.sh)
97
+
- [scripts/install.ps1](./scripts/install.ps1)
98
+
99
+
## Questions
100
+
101
+
Open an issue or discussion in the repository:
102
+
103
+
- https://github.com/RivoLink/leaf/issues
104
+
- https://github.com/RivoLink/leaf/discussions
+38
-23
README.md
+38
-23
README.md
···
6
6
Terminal Markdown previewer — GUI-like experience.
7
7
</p>
8
8
9
-
## Install
10
-
11
-
Install the latest published binary:
9
+
## Install or update
12
10
13
-
```bash
14
-
curl -fsSL https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.sh | sh
15
-
```
11
+
Install or update to the latest published binary.
16
12
17
-
Or download then run:
13
+
macOS / Linux / Android / Termux:
18
14
19
15
```bash
20
-
curl -fsSL -o install.sh https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.sh
21
-
sh install.sh ~/.local/bin
16
+
curl -fsSL https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.sh | sh
22
17
```
23
18
24
-
On Windows:
19
+
Windows:
25
20
26
21
```powershell
27
22
irm https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.ps1 | iex
28
23
```
29
24
30
-
Or download then run:
25
+
Verify the installation:
31
26
32
-
```powershell
33
-
Invoke-WebRequest https://raw.githubusercontent.com/RivoLink/leaf/main/scripts/install.ps1 -OutFile install.ps1
34
-
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Destination $env:LOCALAPPDATA\Programs\leaf
27
+
```bash
28
+
leaf --version
35
29
```
36
30
37
31
## Build
32
+
33
+
Clone the repository:
34
+
35
+
```bash
36
+
git clone https://github.com/RivoLink/leaf.git
37
+
cd leaf
38
+
```
38
39
39
40
Build the release binary locally:
40
41
···
55
56
export PATH="$HOME/.local/bin:$PATH"
56
57
```
57
58
58
-
Check the installed version:
59
-
60
-
```bash
61
-
leaf --version
62
-
```
63
-
64
59
## Usage
65
60
66
61
```bash
···
77
72
# Pipe from stdin
78
73
claude "explain Rust lifetimes" | leaf
79
74
cat TESTING.md | leaf
75
+
76
+
# Open the file picker in the current directory
77
+
leaf
80
78
```
81
79
82
80
## Keybindings
···
101
99
## Features
102
100
103
101
- ✅ **Watch mode** `--watch` / `-w` — reloads every 250ms, with `⟳ reloaded` flash feedback
104
-
- ✅ Syntax highlighting (200+ languages, syntect)
102
+
- ✅ Syntax highlighting with common language aliases like `py`, `cpp`, `json`, `toml`, `ps1`, and `dockerfile`
105
103
- ✅ Unicode box-drawing tables with left / center / right alignment
106
104
- ✅ TOC sidebar with active section tracking and two-level navigation
107
-
- ✅ Search with match highlighting and `n` / `N`
105
+
- ✅ Search with match highlighting, `/`, `Ctrl+F`, and `n` / `N`
108
106
- ✅ Code blocks `┌─ lang ───┐`
109
107
- ✅ Bold, italic, strikethrough, blockquotes, lists, and horizontal rules
110
108
- ✅ YAML frontmatter is ignored in both preview and TOC
111
-
- ✅ Native stdin input
109
+
- ✅ Native stdin input with bounded size
110
+
- ✅ File picker when launched without a file
111
+
- ✅ Theme picker with runtime preview
112
+
- ✅ Help modal with in-app shortcuts
112
113
113
114
## Typical AI Workflow
114
115
···
126
127
- [ ] Copy code block `y`
127
128
- [ ] Code block horizontal scroll
128
129
- [ ] Improve search performance on large files
130
+
131
+
## Troubleshooting
132
+
133
+
### Windows: missing Visual C++ runtime
134
+
135
+
If `leaf.exe` does not start on Windows and reports a missing MSVC runtime, install the latest supported Microsoft Visual C++ Redistributable from Microsoft Learn:
136
+
137
+
- https://learn.microsoft.com/fr-fr/cpp/windows/latest-supported-vc-redist?view=msvc-170
138
+
139
+
Direct download for the latest supported **X64** Microsoft Visual C++ Redistributable:
140
+
141
+
- https://aka.ms/vc14/vc_redist.x64.exe
142
+
143
+
For `leaf-windows-x86_64.exe`, the relevant package is the latest supported **X64** Visual C++ v14 Redistributable.
+46
SECURITY.md
+46
SECURITY.md
···
1
+
# Security Policy
2
+
3
+
## Reporting a Vulnerability
4
+
5
+
If you discover a security vulnerability in `leaf`, please report it responsibly.
6
+
7
+
**Do not open a public issue for security vulnerabilities.**
8
+
9
+
Instead, use one of these channels:
10
+
11
+
- [GitHub private vulnerability reporting](https://github.com/RivoLink/leaf/security/advisories/new)
12
+
- Email the maintainer directly at [rivo.link@gmail.com](mailto:rivo.link@gmail.com)
13
+
14
+
Please include:
15
+
16
+
- a clear description of the issue;
17
+
- steps to reproduce;
18
+
- potential impact;
19
+
- affected versions or release assets;
20
+
- a suggested fix, if you have one.
21
+
22
+
We will review the report and respond as quickly as possible.
23
+
24
+
## Scope
25
+
26
+
This policy covers the `leaf` repository, including:
27
+
28
+
- the `leaf` CLI/TUI application;
29
+
- Markdown parsing and rendering logic;
30
+
- release workflows and published binaries;
31
+
- install scripts for Unix-like systems and Windows;
32
+
- repository documentation when it affects security-sensitive behavior.
33
+
34
+
## Best Practices for Users
35
+
36
+
- Install `leaf` from official releases or the documented install scripts.
37
+
- Keep `leaf` updated to the latest release.
38
+
- Review scripts before piping them into a shell if your environment requires stricter controls.
39
+
- On Windows, install the latest supported Microsoft Visual C++ Redistributable from Microsoft if required by the published binary.
40
+
- Avoid running untrusted Markdown content with unrealistic expectations of isolation; `leaf` is a local preview tool, not a sandbox.
41
+
42
+
## Supported Versions
43
+
44
+
Security fixes are generally applied to the latest released version.
45
+
46
+
If a vulnerability affects older releases, fixes may be backported at maintainer discretion.