markdown-ratatui
markdown-ratatui renders Markdown inside any caller-owned ratatui area. It
accepts source text or a shared parsed markdown-model document, performs
Unicode display-width-aware layout, exposes typed heading and link positions,
and provides a StatefulWidget with caller-owned scroll and selection state.
The crate is a widget library, not a terminal application. It does not enable raw mode, enter an alternate screen, read input, choose keys, open links, access files or networks, start an async runtime, or terminate a process.
Status and installation
The API is version 0.1 and follows Cargo SemVer conventions. Types re-exported
from markdown-model and types from ratatui-core are intentional parts of
the public contract.
Within this repository:
[]
= { = "crates/markdown-ratatui" }
After a crates.io release:
[]
= "0.1"
No crates.io release is implied by this documentation; release preparation
must verify registry availability and ownership. The minimum supported Rust
version is 1.88. The crate has no Cargo features. Its normal dependency graph
uses ratatui-core, not a terminal backend or the complete ratatui
application crate.
Render Markdown from memory
MarkdownView combines one shared document with one bounded layout cache.
MarkdownView::new parses source text once; MarkdownView::prepare lays
it out for a terminal width and reuses the result until the document, width, or
options change.
use ;
use ;
let mut markdown = new?;
let area = new;
let mut buffer = empty;
let mut state = default;
let layout = markdown.prepare?;
layout.widget.render;
assert_eq!;
assert_eq!;
# Ok::
Parsing and preparation are separate error boundaries:
MarkdownView::new returns ParseError, while preparation returns
LayoutError. Both operations are synchronous and perform no I/O.
Render an LSP hover or tooltip
Short-lived Markdown supplied by a language server needs no repository or Mira application state. A host such as ChronoGit can retain one view and one state inside its hover overlay:
use ;
use ;
let hover_markdown = "`Action` runs the selected **operation**.";
let mut hover = new?;
let mut hover_state = default;
let popup = new;
let mut buffer = empty;
hover
.prepare?
.widget
.render;
hover_state.scroll_forward; // The host owns the key binding.
# Ok::
Replacing hover content with MarkdownView::set_document invalidates only
the cached layout. Resetting or retaining ViewState is an application
decision.
Reuse a parsed document
markdown-ratatui re-exports Document and the navigation identity types,
so a consumer needs only one direct dependency for ordinary embedding:
use Arc;
use ;
let document = new;
let mut first = from_document;
let mut second = from_document;
assert_eq!;
assert_eq!;
# Ok::
MarkdownView::document borrows the document. Use
MarkdownView::shared_document only when the caller needs the exact Arc.
Supplying an already parsed document never reparses it.
Caller-owned navigation state
ViewState keeps its fields private and exposes intention-revealing methods.
The host decides which keys scroll, select links, and activate destinations:
use ;
let mut markdown = new?;
let mut state = default;
let first_link = markdown.document.links.id;
state.scroll_forward;
state.select_link;
let layout = markdown.prepare?;
if let Some = layout
.links
.iter
.find
state.clamp;
assert_eq!;
# Ok::
Selection changes style only. The widget never emits OSC 8 links or opens a browser. Destination classification, filesystem containment, and explicit user intent belong to the host application.
Width, positions, and policy
Call MarkdownView::prepare with the width of the exact area passed to the
widget. The widget clips if rendered into a narrower area; it does not rewrap.
Width zero produces an empty layout. A grapheme that cannot fit is replaced by
� rather than split across terminal cells.
Layout::links uses LinkPosition values containing a typed LinkId,
DocumentRow, and CellRange. Wrapping or an inline style boundary can
produce several positions for one link. Layout::headings uses the same
HeadingId generated by markdown-model, allowing HTML and terminal views
to share anchor identities.
LayoutOptions contains a Theme, CodePolicy, TablePolicy, and a
validated LineLimit. LineLimit::new(0) intentionally rejects non-empty
layouts; values above LineLimit::MAX are rejected during construction.
use ;
use ;
let mut markdown = new?;
markdown.set_options;
assert_eq!;
# Ok::
sanitize_terminal_text removes control characters, preserves line feeds,
and expands tabs. Layout applies it automatically to model text; hosts can use
it for untrusted titles and status strings rendered outside the widget.
Complete example
The repository includes a complete host that owns its terminal, panels, event loop, keys, layout, and state:
cargo run -p markdown-ratatui --example embedded -- --buffer
The interactive form is cargo run -p markdown-ratatui --example embedded.
License
Licensed under either the Apache License, Version 2.0 or the MIT license at your option.