ratatui_markdown/lib.rs
1//! # ratatui-markdown
2//!
3//! A Rust library providing markdown rendering, collapsible JSON/TOML tree views,
4//! and a rich hybrid scroll system — all built on top of [ratatui].
5//!
6//! [ratatui]: https://github.com/ratatui/ratatui
7//!
8//! ## Features
9//!
10//! - **Markdown rendering** — parse and render markdown to styled [`ratatui::text::Line`]s,
11//! with support for headings, lists, code blocks, blockquotes, tables, and inline
12//! formatting (bold, italic, inline code)
13//! - **Collapsible trees** — parse JSON or TOML into interactive collapsible trees with
14//! expand/collapse, styled keys, and keyboard navigation
15//! - **Hybrid scroll system** — dual-mode scrolling: free-scroll for exploring content,
16//! engaged mode for navigating focusable items
17//! - **`MarkdownPreview` widget** — unified widget combining markdown rendering, tree
18//! views, and action items into a single scrollable view
19//! - **`RichTextTheme`** — fully themeable via a trait: 15+ color slots for text,
20//! borders, JSON values, popups, and more
21//! - **CJK-aware text wrapping** — correct width calculation for CJK characters via
22//! `unicode-width`
23//! - **TOML frontmatter support** — optionally strip `+++`-delimited TOML frontmatter
24//!
25//! ## Feature Flags
26//!
27//! All features are enabled by default. Disable default features to enable only what
28//! you need:
29//!
30//! ```toml
31//! [dependencies]
32//! ratatui-markdown = { version = "0.2", default-features = false, features = ["markdown"] }
33//! ```
34//!
35//! | Feature | Requires | Description |
36//! |------------|-----------------------------------------|-------------------------------------------|
37//! | `markdown` | — | Markdown parser and renderer |
38//! | `image` | `image` crate | Image resolution via `ImageResolver` |
39//! | `scroll` | — | HybridScrollView, scrollable lists |
40//! | `tree` | `scroll`, `serde_json`, `toml` | Collapsible JSON/TOML tree |
41//! | `preview` | `markdown`, `scroll`, `tree` | `MarkdownPreview` unified widget |
42//! | `mermaid` | `markdown` | Mermaid diagram rendering |
43//! | `viewer` | `markdown`, `scroll` | `MarkdownViewer` widget |
44//!
45//! ## Quick Start
46//!
47//! ```rust
48//! use ratatui_markdown::preview::MarkdownPreview;
49//!
50//! let mut preview = MarkdownPreview::new();
51//! preview.set_content("# Hello, world!\n\nThis is a paragraph.");
52//! // render and handle input in your ratatui app loop
53//! ```
54//!
55//! ### Markdown Rendering
56//!
57//! ```rust
58//! use ratatui_markdown::markdown::MarkdownRenderer;
59//!
60//! let renderer = MarkdownRenderer::new(80);
61//! let blocks = renderer.parse("# Title\n\nParagraph with **bold** text.");
62//! let lines = renderer.render(&blocks, &my_theme);
63//! ```
64//!
65//! ### Custom Rendering with Hooks
66//!
67//! ```rust
68//! use ratatui_markdown::markdown::{MarkdownRenderer, RenderHooks};
69//! use ratatui::text::Line;
70//!
71//! struct MyHooks;
72//!
73//! impl RenderHooks for MyHooks {
74//! fn heading1(&self, text: &str) -> Option<Line<'static>> {
75//! Some(Line::raw(format!(">>> {}", text)))
76//! }
77//! }
78//!
79//! let renderer = MarkdownRenderer::new(80)
80//! .with_render_hooks(Box::new(MyHooks));
81//! ```
82//!
83//! ### Collapsible Trees
84//!
85//! ```rust
86//! use ratatui_markdown::tree::CollapsibleTree;
87//!
88//! let mut tree = CollapsibleTree::from_json_str(
89//! r#"{"key": "value", "nested": {"a": 1}}"#
90//! ).unwrap();
91//! let lines = tree.render_lines(80, &my_theme);
92//! let items = tree.build_focusable_items();
93//! tree.toggle("nested");
94//! ```
95//!
96//! ### Scroll System
97//!
98//! ```rust
99//! use ratatui_markdown::scroll::HybridScrollView;
100//!
101//! let mut scroll = HybridScrollView::new()
102//! .with_cursor_indicator(true);
103//! // set content, handle input, render
104//! ```
105//!
106//! ### Theming
107//!
108//! ```rust
109//! use ratatui::style::Color;
110//! use ratatui_markdown::theme::{Generation, RichTextTheme};
111//!
112//! struct MyTheme;
113//!
114//! impl RichTextTheme for MyTheme {
115//! fn generation(&self) -> Generation { Generation(1) }
116//! fn get_text_color(&self) -> Color { Color::White }
117//! fn get_muted_text_color(&self) -> Color { Color::Gray }
118//! fn get_primary_color(&self) -> Color { Color::Cyan }
119//! fn get_secondary_color(&self) -> Color { Color::Blue }
120//! fn get_info_color(&self) -> Color { Color::LightBlue }
121//! fn get_background_color(&self) -> Color { Color::Black }
122//! fn get_border_color(&self) -> Color { Color::DarkGray }
123//! fn get_focused_border_color(&self) -> Color { Color::White }
124//! fn get_popup_selected_background(&self) -> Color { Color::DarkGray }
125//! fn get_popup_selected_text_color(&self) -> Color { Color::White }
126//! fn get_json_key_color(&self) -> Color { Color::LightCyan }
127//! fn get_json_string_color(&self) -> Color { Color::Green }
128//! fn get_json_number_color(&self) -> Color { Color::Yellow }
129//! fn get_json_bool_color(&self) -> Color { Color::Magenta }
130//! fn get_json_null_color(&self) -> Color { Color::DarkGray }
131//! fn get_accent_yellow(&self) -> Color { Color::Yellow }
132//! }
133//! ```
134//!
135//! ## Modules
136//!
137//! | Module | Feature | Description |
138//! |--------|---------|-------------|
139//! | [`markdown`] | `markdown` | Parse and render markdown text |
140//! | [`scroll`] | `scroll` | Hybrid scroll system with focusable items |
141//! | [`tree`] | `tree` | Collapsible JSON/TOML tree view |
142//! | [`preview`] | `preview` | Unified `MarkdownPreview` widget |
143//! | [`mermaid`] | `mermaid` | Mermaid diagram rendering |
144//! | [`viewer`] | `viewer` | `MarkdownViewer` widget |
145//! | [`theme`] | always | `RichTextTheme` trait for theming |
146//! | [`constants`] | always | Box-drawing chars, tree connectors, arrows |
147
148pub mod constants;
149#[cfg(feature = "highlight")]
150pub mod highlight;
151#[cfg(feature = "markdown")]
152pub mod markdown;
153#[cfg(feature = "mermaid")]
154pub mod mermaid;
155#[cfg(feature = "preview")]
156pub mod preview;
157#[cfg(feature = "scroll")]
158pub mod scroll;
159pub mod text_input;
160pub mod theme;
161#[cfg(feature = "tree")]
162pub mod tree;
163#[cfg(feature = "viewer")]
164pub mod viewer;
165
166#[allow(deprecated)]
167pub use theme::DefaultTheme;
168pub use theme::{CodeColors, RichTextTheme, ThemeBuilder, ThemeConfig};