[Media] markdown-reader: a terminal markdown browser with inline mermaid, vim-style editing, and project-wide search (Rust/ratatui)

I've been iterating on a terminal markdown reader in Rust over the last few weeks and it's at a point where I'd love some outside eyes. Main goal: browse a folder of markdown notes (research, specs, project docs) without leaving the terminal, and actually see mermaid diagrams and tables inline.

cargo install markdown-tui-explorer → binary is markdown-reader.

What it does

Browses a .gitignore-respecting tree of markdown files, live-reloads on change, restores tabs + scroll per directory
Renders fenced code with proper syntax highlighting (syntect + pure-Rust regex)
Rasterizes mermaid diagrams inline via Kitty graphics / Sixel / iTerm2 protocols (falls back to styled source in tmux or terminals without graphics support)
Full-screen global search: per-file match counts + previews, smartcase matching, results cap with a truncation footer
Vim-style navigation with a visible cursor, plus V/y/yy for line-wise visual selection and clipboard yank via OSC 52
i drops into an in-place vim-style editor (edtui) at the exact source line the cursor was on; :w/:q/:wq/:q!
8 themes (including GitHub Light and Gruvbox Light for the light-theme crowd)

Stack

ratatui + crossterm for the TUI
pulldown-cmark for parsing, syntect (fancy-regex backend) for highlighting
mermaid-rs-renderer + resvg for mermaid → PNG, ratatui-image for inline display
edtui for the embedded editor
tokio for async file I/O and background search

What's rough

State diagrams in mermaid have rendering issues (upstream mermaid-rs-renderer#67); flowcharts and sequence diagrams look great
No horizontal char-level selection — visual mode is line-wise only
Edit mode relies on edtui so some vim-power-user features (registers, macros, regex search) aren't there yet

Meta: how this was built

The project is a small experiment in agent-driven development — the
backlog, architectural decisions, release notes, and feature specs all
live in markdown inside the repo, and that documentation is the source
of truth that both I and a coding agent work from. The agent reads the
docs, implements changes, and the human (me) reviews the diff; the docs
get updated first whenever the direction changes. No issue tracker, no
separate spec tool — just markdown the agent and I both read.

Mildly circular: the tool I built to read project docs in a terminal
is itself most often used to read the project docs that drive its own
development. Which is also why inline mermaid rendering, fast
project-wide search with preview, and a visible cursor that tracks
which source line you're on all existed as scratch-your-own-itch
features before they were framed as a product.

Links

Crate: https://crates.io/crates/markdown-tui-explorer
Source: https://github.com/leboiko/markdown-reader
Changelog: https://github.com/leboiko/markdown-reader/blob/master/CHANGELOG.md

Feedback welcome — especially on the editing experience and anything that feels un-idiomatic on the Rust side.