tui_markdown/lib.rs
1//! Convert Markdown into Ratatui [`Text`](ratatui_core::text::Text).
2//!
3//! [`from_str`] renders with the default styles and options. [`from_str_with_options`] accepts an
4//! [`Options`] value for custom [`StyleSheet`] styles and symbols, image fallback mode, and, when
5//! the `highlight-code` feature is enabled, syntax-highlighting theme.
6//!
7//! The returned text may borrow from the Markdown input. It contains terminal text and styles only;
8//! image syntax produces a configurable text fallback and does not read or render image resources.
9//!
10//! # Markdown output
11//!
12//! Tables use Unicode box-drawing borders, terminal display widths, and the alignment declared by
13//! the Markdown delimiter row. Raw HTML stays visible as literal text. Math retains its delimiters,
14//! and images render as `[img]` followed by their description or destination.
15//!
16//! # Syntax highlighting
17//!
18//! The default `highlight-code` feature highlights fenced code blocks whose language is recognized.
19//! It uses `Base16OceanDark` unless [`Options`] selects another [`CodeTheme`]. Themes can come from
20//! the built-in set, TextMate source bundled with the application, or a TextMate file read before
21//! rendering. Unrecognized code fences use [`StyleSheet::code`] instead.
22#![cfg_attr(feature = "document-features", doc = "\n# Features")]
23#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
24//!
25//! # Example
26//!
27//! ~~~
28//! use ratatui::text::Text;
29//! use tui_markdown::from_str;
30//!
31//! # fn draw(frame: &mut ratatui::Frame) {
32//! let markdown = r#"
33//! This is a simple markdown renderer for Ratatui.
34//!
35//! - List item 1
36//! - List item 2
37//!
38//! ```rust
39//! fn main() {
40//! println!("Hello, world!");
41//! }
42//! ```
43//! "#;
44//!
45//! let text = from_str(markdown);
46//! frame.render_widget(text, frame.area());
47//! # }
48//! ~~~
49
50#[cfg(feature = "highlight-code")]
51mod code_theme;
52mod options;
53mod renderer;
54mod style_sheet;
55
56#[doc(inline)]
57#[cfg(feature = "highlight-code")]
58pub use crate::code_theme::{BuiltinCodeTheme, CodeTheme, CodeThemeLoadError};
59pub use crate::options::{ImageFallback, Options};
60pub use crate::renderer::{from_str, from_str_with_options};
61pub use crate::style_sheet::{AlertKind, DefaultStyleSheet, StyleSheet};