The rs-rich guide¶

rs-rich brings Python's rich to Rust: styled text, tables, trees, progress bars, syntax highlighting, Markdown and more in the terminal, plus exports to HTML and SVG. On top of that faithful core it adds Rust-first extensions (diagnostics, structured data, CLI authoring, diffs, test tooling, capability detection, accessibility, tracing spans, workflow renderables and charts), graph diagrams, interactive components, micro assets, image and GIF art, and the rich command-line tool.

This guide walks through all of it. Every code sample on these pages is taken from an example program that CI compiles, and every screenshot is that program's real output, exported to SVG by the library itself.

Section	Crate	What it covers
Core	rs-rich	The faithful port of rich: console, markup, tables, layout, progress, Markdown, export
Extensions	rs-rich-ext	Everything added on top: diagnostics, structured data, charts, workflows, QA tooling
Art	rs-rich-art	Banners, images, GIFs and image diffs
Interactive	rs-rich-interact	Pickers, inputs, forms, pagers and explorers
Using rich with ratatui	rs-rich-ratatui	Rich renderables as ratatui widgets, and back
Diagrams	rs-rich-diagram	Graphs, Mermaid flowcharts and DOT sources
Data and schemas	rs-rich-data	CSV, JSON Lines and Arrow sources, profiles and schemas
Micro assets	rs-rich-micro	Emoji-sized inline images
The rich CLI	rs-rich-cli	The rich command
Write a plugin	rs-rich-plugin-api	A sandboxed WASM plugin, from the template to the marketplace

A Markdown document from the core, a dashboard of rs-rich-ext charts in a core Layout, and an rs-rich-interact explorer searching a YAML file:

fn markdown(console: &Console) {
    let source = r#"# Release notes

Markdown renders **bold**, *italic*, `code` and [links](https://docs.rs/rs-rich).

- bullet lists
  - nested
1. and numbered ones

> Block quotes, too.

| Crate | Lib name |
|-------|---------:|
| rs-rich | `rich` |
| rs-rich-ext | `rich_ext` |

```rust
fn main() { println!("fenced code is highlighted"); }

fn dashboard() -> Layout {
    let card = |c: KpiCard| Layout::with_renderable(Box::new(c.expand(true)));
    let mut cards = Layout::new().size(6);
    cards.split_row(vec![
        card(
            KpiCard::new("Requests", 1240.0)
                .unit("/s")
                .previous(1180.0)
                .trend(trend(0.0)),
        ),
        card(
            KpiCard::new("Errors", 7.0)
                .delta(2.0)
                .higher_is_better(false)
                .trend(trend(5.0))
                .status(Status::Warning),
        ),
    ]);
    let checks = StatusMatrix::new()
        .columns(["eu", "us", "ap"])
        .row("api", ["pass", "pass", "flaky"])
        .row("worker", ["pass", "fail", "pass"]);
    let deploy = Timeline::new()
        .span("build", 0.0, 18.0)
        .span("test", 12.0, 34.0)
        .span("rollout", 36.0, 52.0)
        .milestone("live", 60.0)
        .unit("s");
    let mut root = Layout::new();
    root.split_column(vec![
        cards,
        Layout::with_renderable(Box::new(Panel::new(Box::new(checks)).title("checks"))).size(6),
        Layout::with_renderable(Box::new(Panel::new(Box::new(deploy)).title("deploy"))),
    ]);
    root
}

fn explorer() -> DataExplorer {
    let document = parse(Format::Yaml, CONFIG).expect("valid YAML");
    DataExplorer::new("config.yaml", document)
}

The pieces¶

Each crate versions independently; see the home page for the current numbers.

How it fits together¶

                        your program                         the `rich` binary
                            │                                      │
            ┌───────────────┼───────────────┐                      │ composes the
            ▼               ▼               ▼                      │ libraries below
       rich_ext  ───────▶  rich  ◀─────── rich_art                  │
   (extensions,        (faithful       (banners, images,     ◀─────┘
    features)           core)           GIFs, image diff)
       │  ▲
       │  └── rich_macros (proc-macros behind ext's `macros` feature)
       ▼
   the extension registry, extended theme and capability data are
   installed onto a core Console; core never depends on ext

The dependency graph only points inwards: rich knows nothing about the other crates. That is what keeps the core a faithful mirror of upstream rich while everything new lives in rich-ext (see AGENTS.md).

One render, step by step¶

Everything you print goes through the same pipeline:

1. A renderable. Anything implementing rich::Renderable: Text, a Table, a Panel, your own type, or a rich-ext view such as a diagnostic.
2. Measure. The console asks the renderable for its minimum and maximum width (Measurement), so containers can lay children out.
3. Render to segments. Given ConsoleOptions (width, height, colour system, capabilities), the renderable returns Segments: runs of text, each with a Style, plus control codes.
4. Write or export. The Console turns segments into ANSI for a terminal, or records them for HTML, SVG or plain-text export.

Because steps 2 and 3 only depend on the options you pass in, rendering is deterministic: the same renderable at the same width and capabilities gives the same bytes. The screenshot tests, the golden parity tests and this guide's images all rely on that.

Features at a glance¶

Where to start¶

• Printing nicer output from a Rust program: read Console and printing, then Text, markup and style and Tables. The shorter tutorial covers the same ground in six steps.
• Reporting errors well: Diagnostics and Logging.
• Showing config files or API responses: Structured data.
• Drawing data or structure: Charts, Diagrams and Dependency graphs and JSON Schemas.
• Tables from data files, profiles and schemas: Tabular data, Schemas and Developer views.
• Writing a CLI: CLI authoring for help, errors, completions and man pages, with or without clap.
• Testing terminal output: Diffs and test reports and QA tooling.
• Adapting to whatever terminal you are on: Capabilities and fidelity and Accessibility.
• Using the rich command: the CLI guide, then the walkthrough. The smoke test runs every command end to end.

Running the examples yourself¶

Every example named on these pages lives in a crate's examples/ folder and starts with the command that runs it, for instance:

cargo run -p rs-rich --example guide_tables
cargo run -p rs-rich-ext --example guide_data --features data,yaml,toml,xml,jsonpath

Add -- --svg DIR to write the example's screenshots into DIR instead of printing them. python3 scripts/capture_guide.py regenerates every guide screenshot this way, and python3 scripts/smoke_cli.py --screenshots docs/media/guide regenerates the CLI ones.