# markdown-reader
A terminal-based markdown file browser and viewer built with Rust and [ratatui](https://github.com/ratatui/ratatui).
## Layout
```
+-------------------+----------------------------------------------+
| | |
| ▼ docs/ | # Document Title |
| README.md | |
| guide.md | Some rendered **markdown** content with |
| ▶ src/ | syntax highlighting, lists, tables, and |
| CHANGELOG.md | code blocks displayed inline. |
| | |
| 30% | 70% |
+-------------------+----------------------------------------------+
| Search [Files] (Tab to toggle) / query█ |
+-------------------+----------------------------------------------+
| TREE | readme.md (42%) Tab:panel /:search q:quit |
+-----------------------------------------------------------------+
```
The interface is split into three sections: a file tree on the left (30% width),
a markdown viewer on the right (70% width), and a status bar at the bottom. A
search bar appears between the main area and the status bar when activated.
## Features
- **File tree browser** -- navigate directories with collapsible folder nodes
- **Rendered markdown preview** -- headings, lists, code blocks, tables, links,
blockquotes, task lists, and more, all rendered with color and style
- **Vim-style keybindings** -- `j`/`k` navigation, `g`/`G` jump to start/end,
`d`/`u` for half-page scrolling
- **Fuzzy search** -- search by file name or file content, with result cycling
- **Live file watching** -- the tree and open file automatically reload when
files change on disk
- **Respects .gitignore** -- uses the `ignore` crate to skip ignored files
- **Async runtime** -- built on Tokio for non-blocking I/O and file watching
## Installation
### Prerequisites
- [Rust toolchain](https://rustup.rs/) (1.85+ recommended, edition 2024)
### From crates.io
```sh
cargo install markdown-tui-explorer
```
### From GitHub
```sh
cargo install --git https://github.com/leboiko/markdown-reader
```
### Building from source
```sh
git clone https://github.com/leboiko/markdown-reader.git
cd markdown-reader
cargo build --release
```
The binary will be at `target/release/markdown-reader`.
## Usage
```sh
# Browse the current directory
markdown-reader
# Browse a specific directory
markdown-reader ~/projects/my-docs
# Show help
markdown-reader --help
```
Once inside the TUI, use `Tab` to switch between the file tree and the viewer,
`/` to open the search bar, and `q` to quit.
## Keyboard Shortcuts
### Tree Panel
| `j` / Down | Move cursor down |
| `k` / Up | Move cursor up |
| `l` / Right / Enter | Open file or expand directory |
| `h` / Left | Collapse directory |
| `g` | Jump to first item |
| `G` | Jump to last item |
| `Tab` | Switch focus to viewer |
| `/` | Open search |
| `q` | Quit |
### Viewer Panel
| `j` / Down | Scroll down one line |
| `k` / Up | Scroll up one line |
| `d` / PageDown | Scroll down half page |
| `u` / PageUp | Scroll up half page |
| `g` | Scroll to top |
| `G` | Scroll to bottom |
| `Tab` | Switch focus to tree |
| `/` | Open search |
| `q` | Quit |
### Search Mode
| Any character | Append to search query |
| `Backspace` | Delete last character |
| `Tab` | Toggle between file name / content search |
| `Down` / `Ctrl-n`| Next result |
| `Up` / `Ctrl-p` | Previous result |
| `Enter` | Open selected result |
| `Esc` | Close search |
## Markdown Rendering
| H1 | Cyan, bold, underlined, with `█` prefix |
| H2 | Blue, bold, with `▌` prefix |
| H3 | Magenta, bold, with `▎` prefix |
| H4-H6 | White, bold |
| Bold | Terminal bold |
| Italic | Terminal italic |
| Strikethrough | Terminal strikethrough |
| Inline code | Green, bold, wrapped in backticks |
| Code block | Box-drawn border, tinted background |
| Blockquote | Gray text with `│` left border |
| Unordered list | Colored bullets: `•`, `◦`, `▪` by depth |
| Ordered list | Numbered with yellow markers |
| Task list | Checkbox markers (checked/unchecked) |
| Table | Box-drawn grid with bold cyan header |
| Link | Blue, underlined |
| Horizontal rule | Full-width `─` line |
## Dependencies
| ratatui | Terminal UI framework |
| crossterm | Terminal backend / input events |
| pulldown-cmark | Markdown parsing |
| ignore | .gitignore-aware file discovery |
| tokio | Async runtime |
| notify-debouncer-mini | Filesystem change watching |
| clap | CLI argument parsing |
| anyhow | Error handling |
## License
MIT