ratatui-markdown 0.2.0

A Rust library providing markdown rendering, collapsible JSON/TOML tree views, and a rich hybrid scroll system — all built on top of ratatui.

Features

• Markdown rendering — parse and render markdown to styled ratatui::text::Lines, with support for headings, lists, code blocks, blockquotes, tables, images, and inline formatting (bold, italic, inline code)
• Image support — resolve ![alt](path) images via the ImageResolver trait (feature-gated: image)
• Custom rendering hooks — override rendering of any block type (headings, code blocks, lists, tables, etc.) via the RenderHooks trait
• Collapsible trees — parse JSON or TOML into interactive collapsible trees with expand/collapse, styled keys, and keyboard navigation
• Hybrid scroll system — dual-mode scrolling: free-scroll for exploring content, engaged mode for navigating focusable items
• MarkdownPreview widget — unified widget that combines markdown rendering, tree views, and action items into a single scrollable view
• RichTheme — fully themeable via the RichTextTheme trait: 15+ color slots for text, borders, JSON values, popups, and more
• CJK-aware text wrapping — correct width calculation for CJK characters via unicode-width
• TOML frontmatter support — optionally strip +++-delimited TOML frontmatter from rendered content

Quick Start

Prerequisites

• Rust 1.74+
• ratatui 0.29

Installation

[dependencies]
ratatui-markdown = "0.2"

For the full feature set (enabled by default):

[dependencies]
ratatui-markdown = { version = "0.2", features = ["preview"] }

Individual features can be enabled selectively:

Example

use ratatui_markdown::{
    markdown::MarkdownRenderer,
    preview::MarkdownPreview,
    theme::RichTextTheme,
};

struct App {
    preview: MarkdownPreview,
}

impl App {
    fn render(&mut self, f: &mut ratatui::Frame, theme: &impl RichTextTheme) {
        self.preview.set_content("# Hello\n\nThis is **markdown**!");
        self.preview.render(f, f.area(), f.area(), theme);
    }

    fn handle_input(&mut self, key: ratatui::crossterm::event::KeyCode) {
        match key {
            KeyCode::Up | KeyCode::Char('k') => self.preview.scroll_up(),
            KeyCode::Down | KeyCode::Char('j') => self.preview.scroll_down(),
            KeyCode::Enter => { self.preview.toggle_tree_node(); }
            _ => {}
        }
    }
}

// Parse and render markdown to ratatui Lines
use ratatui_markdown::markdown::MarkdownRenderer;

let md = MarkdownRenderer::new(80);
let blocks = md.parse("# Title\n\nParagraph text\n\n```rust\nlet x = 1;\n```");
let lines = md.render(&blocks, &my_theme);

// Render a collapsible JSON tree
use ratatui_markdown::tree::CollapsibleTree;

let mut tree = CollapsibleTree::from_json_str(r#"{"key": "value", "nested": {"a": 1}}"#).unwrap();
let lines = tree.render_lines(80, &my_theme);
let focusable = tree.build_focusable_items();
tree.toggle("nested"); // collapse/expand

Documentation

• Getting Started
• Markdown Module
• Scroll System
• Tree View
• Preview Widget
• Theme Customization
• Contributing
• API Reference

Languages

License

Dual-licensed under MIT OR Apache-2.0.