🌈 bleamd

A powerful standalone Markdown renderer for the terminal with advanced search, hyperlink support, and extensive customization options.

🚀 Features

• 📖 Beautiful Markdown rendering in your terminal
• 🔍 Advanced Search - Full-text search with smart highlighting and match navigation
  • Current match highlighted in bright orange
  • All matches highlighted in yellow
  • Match counter in status bar
  • Navigate with n/N (next/previous)
• 🔗 Clickable hyperlinks - Links are underlined and clickable in supported terminals
• ⌨️ Fully customizable keybindings - Vim-like defaults with custom keyboard layout support
• ❓ Interactive Help - Press ? for instant keybinding reference popup
• 🎨 Advanced theming system
  • 4 built-in themes (One Dark, Dracula, Solarized Dark, Catppuccin Latte)
  • Full color customization for all elements
  • ANSI 256 color support
• 🖱️ Mouse support - Click and scroll support in compatible terminals
• 📊 Rich table rendering with proper borders and alignment
• 💻 Syntax highlighting for code blocks
• ⚡ Vim Bindings - Native support for Vim bindings using Qwerty and Colemak-DH layouts
• ❄️ Native NixOS support with flakes and development shell

💿 Installation

📦 Binary Release

Download a pre-compiled binary for your platform.

❄️ NixOS / Nix

# Run directly
nix run github:guttermonk/bleamd -- README.md

# Install to profile
nix profile install github:guttermonk/bleamd

# Build locally
git clone https://github.com/guttermonk/bleamd
cd bleamd
nix build
./result/bin/bleamd README.md

🔨 From Source

git clone https://github.com/guttermonk/bleamd
cd bleamd
go build
./bleamd README.md

📔 Usage

bleamd README.md                  # Render a markdown file
bleamd < file.md                  # Read from stdin
curl example.com/file.md | bleamd # Pipe from network
bleamd --init-config              # Create default config file
bleamd --config-path              # Show config file location

⌨️ Keybindings

Press ? at any time to display an interactive help popup with all available keybindings. All keybindings are fully configurable via the config file.

🧭 Default Navigation Keys

Key	Action
↑ k i	Scroll up
↓ j e	Scroll down
← h	Scroll left
→ l o	Scroll right
PgUp	Page up
PgDn Space	Page down
g	Go to top
G	Go to bottom
?	Show interactive help
q Ctrl+C	Quit

🔍 Search Features

Key	Action
Ctrl+F /	Start search
Enter	Execute search
n	Next match
N	Previous match
ESC	Clear search/Cancel

Search highlights:

• 🟠 Current match: Bright orange background
• 🟡 Other matches: Yellow text
• 📊 Status bar: Shows "Match X of Y" with search term

🔗 Hyperlinks

Links in your markdown are automatically converted to clickable hyperlinks in compatible terminals:

• Underlined and styled according to your theme
• Click to open in your default browser
• Works with http/https URLs and mailto links

🎛️ Configuration & Theming

Create and customize your configuration:

bleamd --init-config      # Create default config with One Dark theme
bleamd --config-path      # Show config file location

🥸 Pre-built Themes

Choose from professionally designed themes:

# One Dark (default)
cp themes/one-dark.json ~/.config/bleamd/config.json

# Dracula
cp themes/dracula.json ~/.config/bleamd/config.json

# Solarized Dark  
cp themes/solarized-dark.json ~/.config/bleamd/config.json

# Catppuccin Latte (light theme)
cp themes/catppuccin-latte.json ~/.config/bleamd/config.json

🪄 Custom Keybindings

Configure your preferred keybindings in ~/.config/bleamd/config.json. Each action supports multiple key combinations:

{
  "keybindings": {
    "scroll_up": ["k", "i", "Up", "C-p"],
    "scroll_down": ["j", "e", "Down", "C-n"],
    "scroll_left": ["h", "Left"],
    "scroll_right": ["l", "o", "Right"],
    "page_up": ["PageUp"],
    "page_down": ["PageDown", "Space"],
    "go_to_top": ["g"],
    "go_to_bottom": ["G"],
    "start_search": ["/", "C-f"],
    "next_match": ["n"],
    "prev_match": ["N"],
    "clear_search": ["Escape"],
    "quit": ["q", "C-c"],
    "show_help": ["?"]
  }
}

Supported key formats:

• Single characters: "k", "j", "h", "l"
• Arrow keys: "Up", "Down", "Left", "Right"
• Special keys: "PageUp", "PageDown", "Space", "Enter", "Escape"
• Control combinations: "C-f", "C-c", "C-n", "C-p"

🦄 Advanced Color Customization

Customize every visual element in your config file:

{
  "colors": {
    "heading1": "#61afef",
    "heading2": "#c678dd", 
    "bold": "#abb2bf",
    "italic": "#98c379",
    "code": "#e5c07b",
    "link": "#56b6c2",
    "search_current": "#d19a66",
    "search_match": "#e5c07b",
    "search_box_border": "#ff5fff",
    "help_box_border": "#5f87d7",
    "hovered_link_url": "#00ffff",
    "hyperlink_underline": "#56b6c2",
    "hyperlink_hovered_underline": "#e5c07b"
  }
}

Customizable elements:

• Headings: heading1 through heading6
• Text: bold, italic, strikethrough
• Code: code, code_block, code_block_bg
• Links: link, link_url
• Lists: list_marker, task_checked, task_unchecked
• Layout: blockquote, table_header, table_row, table_border
• Search: search_current, search_match
• UI: status_bar_text, status_bar_bg, search_box_border, help_box_border, hovered_link

All colors use hex format (e.g., #ff0000) and are automatically converted to the nearest ANSI 256 color for terminal display.

🔧 Development

Nix Development Shell

nix develop  # Or use direnv with the included .envrc
go build
go test ./...

Traditional Development

go mod download
make build

The development environment includes Go, gopls, golangci-lint, and other useful tools.

⏳ Contributing

PRs welcome! When contributing:

1. Use the Nix development shell for consistent tooling
2. Run tests with go test ./...
3. Update vendor hash in flake.nix if dependencies change
4. Test with different themes and keybinding configurations

⚖️ License

MIT

❓ FAQ

How does bleamd compare to other markdown viewers?

Feature	bleamd	Glow	mdr	md-tui	mdv	Grip	Pandoc
Interactive TUI	✅	✅	✅	✅	❌	❌	❌
Full-text search	✅	✅	❌	❌	❌	❌	❌
Clickable hyperlinks	✅	❌	❌	❌	❌	✅	❌
Custom keybindings	✅	❌	❌	❌	❌	❌	❌
Multiple themes	✅	✅	❌	✅	✅	✅	❌
Mouse support	✅	✅	❌	✅	❌	✅	❌
File management	❌	✅	❌	❌	❌	❌	❌
Cloud sync	❌	✅	❌	❌	❌	❌	❌
Live reload	❌	❌	❌	❌	❌	✅	❌
Format conversion	❌	❌	❌	❌	❌	❌	✅
Terminal-native	✅	✅	✅	✅	✅	❌	✅
Offline support	✅	✅	✅	✅	✅	❌	✅
Language	Go	Go	Go	Rust	Python	Python	Haskell

bleamd's niche: Fast, interactive terminal viewer with powerful search, full customization, and clickable links for terminal-centric workflows.

📓 Origin

This tool is a fork of mdr with extensive enhancements including:

• Advanced search functionality with highlighting
• Hyperlink support (OSC 8)
• Interactive help system
• Configurable keybindings
• Rich theming system
• Mouse support
• Custom keyboard layout support

Perfect for developers, writers, and anyone who works with Markdown files in the terminal.