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.2 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.2"
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.
Mermaid fences
The private mermaid module converts fenced mermaid blocks during layout,
so diagrams share the normal width cache, quote/list indentation, and row
budget. It supports flowcharts (graph / flowchart), sequence diagrams, and
flat state diagrams. Flowcharts and states render one ASCII connection strip
per edge, using repeated node IDs to retain branches and cycles. Node shapes
normalize to boxes. Sequence diagrams use participant lifelines or message
strips when narrow; notes and activation changes remain ordered annotations.
alt / multiple else / end, opt, and loop blocks retain their conditions,
order, and nesting in ASCII frames. Nested frames reserve fixed gutters so
participant lifelines stay aligned across branches.
Labels wrap by grapheme display width; Mermaid colors are ignored.
Theme::diagram
styles diagram labels and lines independently of Theme::code. Its default
is magenta; ordinary code remains yellow. Changing the diagram style invalidates
the cached layout like any other theme change. When upgrading from 0.1 to 0.2,
callers constructing every Theme field explicitly must include diagram,
or use ..Theme::default().
Other diagram types and unsupported syntax (such as subgraphs, nested states,
or other sequence control blocks) retain their source with an explanation, as
do malformed diagrams and areas with fewer than eight cells after indentation
and frame gutters. Missing or unmatched end and else outside alt reject
the entire diagram. Conversion accepts at most 64 KiB of source, 128 nodes,
512 connections, 16 nested sequence blocks, and 256 KiB of expanded labels
before falling back to source. The normal LineLimit still applies to both
diagrams and fallback text. No extra crate, terminal backend, JavaScript
runtime, or I/O is required.
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.