ratatui-markdown

Markdown rendering, Mermaid diagrams, syntax highlighting, collapsible trees, and rich scroll widgets for ratatui

Quick Start | Documentation | API Reference

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Français | Español | Русский | العربية

A Rust library providing markdown rendering, Mermaid diagrams, syntax highlighting, 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)
• Mermaid diagrams — render sequence, pie, gantt, and state diagrams from ```mermaid code blocks (feature-gated: mermaid)
• Syntax highlighting — tree-sitter based code block highlighting with per-language feature flags (feature-gated: highlight-lang-*)
• 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 / MarkdownViewer — unified widgets combining markdown, tree views, and scroll into a single 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.3"

For the full feature set (enabled by default):

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

Individual features can be enabled selectively:

Feature	Description	Default
markdown	Markdown parsing and rendering	✓
image	Image resolution via ImageResolver trait	✓
scroll	Hybrid scroll and scrollable widgets	✓
tree	JSON/TOML collapsible tree (requires scroll)	✓
preview	MarkdownPreview unified widget (requires markdown, scroll, tree)	✓
mermaid	Mermaid diagram rendering (requires markdown)	✓
viewer	MarkdownViewer widget (requires markdown, scroll)	✓
highlight	Syntax highlighting via tree-sitter
highlight-lang-*	Individual language grammars (requires highlight)
highlight-lang-all	All bundled language grammars

Examples

Example	Description	Features required
basic	Minimal markdown rendering	—
code	Syntax-highlighted code blocks	highlight-lang-all
custom_code_block	Custom code block rendering hooks	—
image	Image embedding and zoom	image
mermaid	Mermaid diagram rendering	mermaid
tree_list	Collapsible JSON/TOML tree view	—

cargo run --example basic
cargo run --example code --features highlight-lang-all
cargo run --example image
cargo run --example mermaid
cargo run --example tree_list

Documentation

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

License

Licensed under the Synthetic Source License (SySL), Version 1.0.