mkdr

TUI markdown renderer with paging, search, theming, and multi-file support.

cargo run -- README.md

Features

• Markdown rendering with full theme support (bold, italic, links, tables, code, headings)
• Interactive links — Enter on a wiki link navigates to the file; Enter on a web link opens the browser; Enter on an image opens the default image viewer
• Vim-style navigation (j/k, b/f, g/G, ←/→)
• Incremental search (/ forward, ? backward, n/N next/prev)
• Go to line (: + number + Enter)
• Word wrap configurable: none, word, char
• Line numbers toggle (-n)
• Multiple files — pass several files, navigate with [ / ]
• Watch mode (-f) — auto-reloads on file change
• Stdin pipe — cat file.md | mkdr
• 10 built-in themes + user themes in ~/.config/mkdr/themes/
• Config file at ~/.config/mkdr/config.toml

Usage

mkdr [OPTIONS] [FILES]...

mkdr doc.md
mkdr -n -t nord doc.md
cat README.md | mkdr
mkdr -f -t catppuccin_mocha doc.md
mkdr -w none chapter1.md chapter2.md chapter3.md

Keybindings

In search and go-to-line modes: Enter to confirm, Esc to cancel, Backspace to delete.

Themes

10 built-in themes:

ayu_dark · ayu_light · ayu_mirage · catppuccin_mocha · dracula · gruvbox_dark · nord · onedark · solarized_light · tokyonight

mkdr -t nord doc.md
mkdr -t ayu_mirage doc.md

User themes

Place .toml files in ~/.config/mkdr/themes/:

# ~/.config/mkdr/themes/my_theme.toml
[colors]
text = "#abb2bf"
bg = "#282c34"
blue = "#61afef"

[styles]
paragraph = { fg = "text" }
heading1 = { fg = "blue", bold = true }
inline_code = { fg = "#ce9178", bg = "#2d2d2d" }

Style keys: paragraph, bold, italic, strikeout, inline_code, code_block, link, heading1–heading6, table, ellipsis, bullet, quote_mark, horizontal_rule.

Style fields: fg (hex or color reference), bg, bold, italic, underline, strikethrough.

Configuration

~/.config/mkdr/config.toml:

wrap = "word"
line_numbers = true
theme = "nord"
show_status = true

CLI flags override config values. All fields optional.

Download

Pre-built binaries for each release:

Trigger a release by pushing a tag:

git tag v0.1.0
git push origin v0.1.0

The release workflow builds all targets, packages them, and creates a GitHub release.

Build

cargo build
cargo run -- README.md

No rust-toolchain.toml — uses whatever rustup default provides. Edition 2024.

Git Flow & releases

See GIT_FLOW.md for the complete workflow.
Releases are automatic: merging to main triggers CI to bump the version, tag, and publish a GitHub release.

License

MIT — see LICENSE.

Dependencies

clap · crossterm · dirs · open · pulldown-cmark · ratatui · serde · toml · unicode-width

Roadmap

• clap_complete as optional dependency — only used for --completions; gate behind a Cargo feature flag
• Integration tests for navigation — add tests for keyboard/mode logic (requires mock terminal or extracted state machine)
• Configurable horizontal rule width — use terminal width instead of fixed 80 columns
• Blockquote colour theming — expose quote-depth colours in the theme file instead of hardcoded palette