Crate zorite_markdown

Expand description

Zorite’s reader view: a small read-only markdown renderer for GPUI. (Editing — WYSIWYG and raw — is the separate zorite-editor crate; the two engines share nothing, so any markdown behavior added here must be checked there and vice versa. See AGENTS.md “The three views”.)

It parses markdown to an AST (via the markdown crate) and renders it with gpui’s own StyledText / InteractiveText, so paragraphs wrap properly and links are clickable through a real callback — not cx.open_url, which only opens externally.

It is deliberately host-agnostic: styling comes in via MarkdownStyle, and clicking a [[wiki-link]] invokes a caller-supplied closure (on_wiki_link) rather than knowing anything about the host app. Standard [text](url) links open externally via cx.open_url.

Covers CommonMark + GFM: headings, paragraphs, bold/italic/strikethrough/ inline-code, fenced code blocks, ordered/unordered/nested and task lists, blockquotes, thematic breaks, hard breaks, tables, links (inline and reference-style), images (rendered by the host via on_image), footnotes, and raw HTML (shown literally, never executed — except <mark>, which renders as highlighted text). [[wiki-links]] and #tags become clickable via caller callbacks.

Modules§

syntax: Shared markdown-construct recognition — the definitions both of Zorite’s engines consume so they can never drift apart (links navigated in the reader for months while WYSIWYG ignored clicks; alerts were once recognized in three separate places). The reader (this crate’s view), the WYSIWYG editor (zorite-editor), and any other consumer (PDF export) share what counts as a construct and what’s its payload; each keeps its own rendering. Everything here is engine-neutral and gpui-free.

Structs§

AlertColors: Border + title colors for the five GitHub-style alerts (> [!NOTE] …). Defaults are GitHub’s dark palette; the host overlays its theme.
AlertIcons: Per-kind SVG asset paths for the alert title icons.
ImageInfo: A standalone image (a paragraph that is just ![alt](src), optionally followed by a {width=N} attribute). Handed to the host’s ImageRenderer so it can render a real, possibly interactive, image element.
Labels: A rendered markdown document element — the reader view of a note.
MarkdownStyle: Visual configuration for the renderer. The host fills this from its own theme; defaults are a neutral dark palette.
MarkdownView: A rendered markdown document element — the reader view of a note.
Snippet: An authoring snippet for a markdown construct: a label, the text to insert, and the caret offset (bytes) within that text. Exposed so a host’s command palette can offer markdown commands without re-deriving the syntax. Pure data — no rendering involved.

Enums§

ListEdit: What pressing Enter should do on a markdown list / blockquote line.

Constants§

INDENT: The default indent level (two spaces) for Tab / Shift+Tab on list items. The host passes its configured indent to indent_list_line / outdent_line; this is just the fallback / a convenience for callers without a setting.
SNIPPETS: Built-in markdown authoring snippets (for a / command palette).

Functions§

alert_children: If blockquote b is a GitHub alert, return its kind and a copy of its children with the marker stripped (the first text’s source offset advances by the stripped length, so the rendered→source click map stays aligned). Public so other renderers of the same construct (e.g. a PDF exporter) share the exact recognition.
alert_parts: alert_children plus the callout’s fold state (Some(true) = folded) and the marker’s source byte offset — what a foldable callout’s chevron click reports so the host can flip the -/+ in the source.
all_image_srcs: Every image src in source — block (leading) AND inline — so the host can pre-decode them all (inline images render as rasters too, not just leading ones). Pure: parses the markdown, no I/O.
find_matches: The block index (top-level column-child index, as rendered) of each match of query in source, in document order. Pair with MarkdownView::track_blocks: the host reads bounds_for_item(find_matches(..)[current]) to scroll the active match’s block into view. No I/O; shares the render path’s memoized parse, so calling it per keystroke costs one parse, not one per character.
images: Every standalone image in source (a paragraph or list item that begins with ![alt](src)), in document order — each with its parsed {width=N} (if any) and the attr_target byte range to overwrite to set or replace that width. Mirrors how the renderer detects block images, so the offsets line up with what’s on screen. Pure: parses the markdown, no I/O or storage.
indent_list_line: If the caret’s line is a list/quote item, indent it one level (insert indent at the line start), returning the new text and shifted caret. None when the line isn’t a list item, so the caller can insert a literal tab instead.
list_continuation: Decide how Enter continues a markdown list/quote at cursor in value. Recognizes -/*/+ bullets, N./N) ordered items, - [ ] task items, and > blockquotes (leading indent preserved). A non-empty item continues with the next marker; an empty item exits the list. None when the current line isn’t a list/quote item.
match_count: Count case-insensitive matches of query in the rendered (visible) text of source — the same matches MarkdownView::search highlights, in the same order. Pure: parses the markdown, no I/O or storage. Empty query → 0. Use it to size a host find bar’s “n of m” and to bound the active-match index.
needs_warm: Would rendering source block on a parse — i.e. is it expensive-shaped AND not cached yet? Hosts check this before spawning a warm task, so ordinary notes (which parse inline in microseconds) spawn nothing at all.
outdent_line: Outdent the caret’s line one level: remove up to indent’s width of leading spaces (or one leading tab). Returns the new text and caret, or None if the line has no leading indent to remove.
reindent: Re-indent every space-indented list / quote item in content from old-space nesting units to new-space units (e.g. when the list-indent setting changes), so existing nesting matches the new width. Each item’s level is its leading spaces ÷ old. Non-list lines, top-level items, and tab-indented lines are left untouched. None when nothing changes.
toggle_task_at: Toggle the GFM task checkbox on the source line containing byte offset (a task item’s offset, as reported by MarkdownView::on_task_toggle). Returns the full content with that one checkbox flipped ([ ]↔[x]), or None if there’s no task checkbox on that line. Length is unchanged (one ASCII byte swapped).
warm_parse: Parse source into the shared cache unless it’s already there. Pure and gpui-free by design — call it from a background thread (the host uses cx.background_executor()), because that is the only place a superlinear parse can run without wedging the UI.

Type Aliases§

BlockRefCountFn: Maps a block id to how many pages reference it (0 = no badge).
ClickSourceHandler: Called when the rendered text is clicked (outside a link), with the source byte offset nearest the click and the click’s window y — so the host can place its editor caret there and keep it under the cursor when switching into edit mode. Set via MarkdownView::on_click_source.
CodeHighlighter: Colors a fenced code block’s tokens: (language tag, code) → sorted, non-overlapping styled ranges (byte offsets into the code). Supplied by the host (e.g. a tree-sitter highlighter) so the crate stays engine-free; absent it, code renders in the single code_color.
EmbedProvider: Resolves a standalone ![[target]] embed to (source label, content) — the host pre-resolves targets from its database (a page, a #^id block, or a #Heading section) since render-time providers can’t query. None (or a missing target) falls back to rendering the line as text.
HeadingToggleHandler: Called when a heading’s fold chevron is clicked, with the heading’s fold key — its trimmed source line (## Goals). The host owns the fold set (this view is rebuilt every frame) and passes it back via MarkdownView::folded_headings.
ImagePreviewHandler: A click on an inline image reports its src so the host can open a full-size preview. Set via MarkdownView::on_image_preview.
ImageRenderer: Renders a standalone image. The element’s event handlers run later (with their own context), so building it needs no window/app — letting the host supply a stateful, draggable image while this crate stays host-agnostic.
InlineImageRenderer: A renderer for an INLINE image (![](src) amid text): its src → the raster plus logical (w, h) sized to flow at the text’s line height. Like inline math, the caller reserves a spacer in the line and paints the image over it; None (still decoding / no renderer) falls back to a clickable label.
InlineMathRenderer: Resolves an inline $…$ formula’s LaTeX to its typeset raster + logical (display) px size at text size, so the renderer can reserve a gap in the line and paint the image over it. The host owns the (cached, off-thread) render; None while it’s still rasterizing (the raw $…$ shows until then). Set via MarkdownView::on_inline_math.
MathRenderer: Renders a $$…$$ math block as a typeset image, given the block’s LaTeX. Like MermaidRenderer, the host owns the (cached, off-thread) render — this crate just detects the block and hands over the source. Set via MarkdownView::on_math.
MermaidRenderer: Renders a ```mermaid code block as a diagram, given the block’s source. The host owns the (expensive, async) render — this crate just detects the fence and hands the source over, staying renderer-agnostic. Set via MarkdownView::on_mermaid.
PropertyIconFn: Maps a property key to an icon asset path the host serves, or None for no icon. Host-provided so the crate makes no assumption about which assets exist.
TaskToggleHandler: Toggle the task checkbox of a clicked list item — the argument is the source byte offset of that task item (feed it to toggle_task_at). Set via MarkdownView::on_task_toggle.
WikiLinkHandler: Called when a [[wiki-link]] is clicked, with the trimmed title.