MarkdownView
Shared Markdown rendering, reading typography, themes, and document layouts
MarkdownView is the read-only Markdown component in @downcity/ui. It manages prose, code, tables, images, math, Mermaid, and SVG with consistent typography. It has no Desktop dependency and can be used in React host applications.
Integration
Load the UI SDK base styles as described in Installation, then import the Markdown stylesheet:
import { MarkdownView } from '@downcity/ui';
import '@downcity/ui/markdown.css';
<MarkdownView text="# Reading a document\n\nBody content goes here." />Use the embedded layout for chats, tool details, or cards, and streaming mode for content that is still being generated:
<MarkdownView text={message_text} mode="streaming" layout="embedded" />Props
| Prop | Type | Default and purpose |
|---|---|---|
text | string | Required; complete or updating Markdown source. Empty strings produce no placeholder |
mode | "static" | "streaming" | static; streaming progressively displays incomplete syntax |
layout | "document" | "embedded" | document; controls reading width and outer padding |
document_url | string | Optional source document URL for relative image resolution and host link navigation |
class_name | string | Optional outer positioning and layout class |
Shared Typography
Body text defaults to medium (0.875rem), weight 400, and a 1.65 line height, following the overall interface scale. Embedded content and its static exports read the Provider's controlled size preset; document layout always uses medium. Headings share the system font used by the body; headings and strong text use weight 500. The h1–h6 sizes use fixed em ratios that scale with the body. An initial h1 acts as the document title, with a 1.5rem gap before the following content. Adjacent paragraphs have a 0.9em gap, while lists, quotes, and code follow shared content spacing rules. Desktop uses the same spacing ratio between agent message parts, calculated from the selected chat text size, so paragraph and part gaps scale together.
Colors follow the current host's semantic theme tokens and update automatically with light and dark themes. The component owns fonts, font sizes, line heights, weights, and content spacing. MarkdownView exposes no typography, size, style, or separate theme prop; size selection uses only the Provider's four text_size presets. class_name applies only to outer layout; hosts must not override internal typography through ancestor styles, descendant selectors, or typography variables.
Local Backgrounds
A host container can set these CSS variables for the Markdown readers inside it:
| Variable | Purpose and default |
|---|---|
--markdown-inline-code-background | Inline code; mixes 5% foreground with 95% theme background |
--markdown-table-header-background | Table header cells; uses --surface-subtle, falling back to a 3% foreground / 97% background mix |
--markdown-code-background | Code block outer background; uses the same default as table headers |
Values can be solid colors, theme variables, or color-mix() results. Transparent values composite over the actual container background. Set overrides in the container's own stylesheet so all nested readers share them:
/* A host-owned panel supplies its background and the inline code fill. */
.reader-panel {
background: var(--muted);
--markdown-inline-code-background: color-mix(in srgb, var(--foreground) 5%, var(--muted) 95%);
}A bg-muted class sets the container's background only; it does not calculate Markdown variables. Desktop supplies the inline code fill centrally for MainView, BayBar, settings groups, and popup roots. Its table headers and code blocks retain the theme's transparent --surface-subtle fill. Text colors, borders, typography, and syntax highlighting remain owned by the component and theme.
If a host maps a local variable to a Tailwind utility, use @theme inline so the generated declaration reads that variable on the consuming element.
Document And Embedded Layouts
| Layout | Width and padding | Typical uses |
|---|---|---|
document | Centered body up to 45rem wide; 2rem vertical and 1.25rem horizontal padding | Standalone documents, file and attachment previews |
embedded | Fills the available host width with no extra outer padding | Chats, tool details, tasks, README cards, and exports |
Table text uses 0.9286em relative to the body and scales with its size preset. Table headers use weight 500.
Both layouts share heading, code, and table styling rules. Document layout uses the default text size; embedded layout inherits the Provider's size preset. Body content shrinks with narrow panels; long code, wide tables, and math scroll horizontally within their own regions. The page owns vertical scrolling; the component creates no separate vertical scroll area. Images stay within the body width, and long links can wrap.
Currency And Math
Dollar amounts can appear directly in prose or bold text, such as **$0.34/hour**, **$2–4**, and **$50 trial credit**. Multiple amounts in one paragraph retain their own formatting.
Inline math supports $x + y$ and \(x + y\). Display math supports $$ delimiters on separate lines or \[...\]. Single-dollar delimiters must not have whitespace immediately inside them, and the closing $ must not be followed immediately by a digit. Numeric-leading candidates cannot cross Markdown bold or code markers. Use explicit \(...\) delimiters when a formula must touch a following digit or contain those markers.
Currency and math can still share ambiguous text forms. Write \$ when a dollar sign must always be literal. Dollar signs in code retain their source text. Static and streaming content use the same parsing rules.
SVG And Mermaid
Invalid or incomplete SVG displays as monospaced source with padding. The source area can receive keyboard focus and scroll independently, preserving the full content without clipping.
Mermaid reads the body's actual font size and recalculates its layout when the four text size presets or overall interface scale change. Wide diagrams retain their natural layout dimensions and scroll horizontally within the diagram area. Small diagrams are centered, and fullscreen viewing remains available. A rendering failure shows the error and retry action and stops the loading spinner.
Host Integration
An application-level MarkdownViewProvider connects resource resolution and translation to the host. Desktop uses the Provider to resolve local image addresses and supply translations. The public component receives these capabilities from the host and never accesses Desktop bridge APIs. document_url supplies source context; the host converts local resources into permitted loadable addresses.
The Provider exposes the following props. Text size, resolution, and translation are optional. In nested Providers, each omitted value inherits from the parent; the outermost Provider uses built-in defaults:
| Prop | Type | Purpose |
|---|---|---|
children | ReactNode | Required; application content sharing the host capabilities |
text_size | MarkdownViewTextSize | Optional controlled size preset for embedded content; defaults to medium, applies to static exports, and does not affect document layout |
resolve_image_src | (src: string, document_url?: string) => string | undefined | Optional; resolves a validated image path to a loadable address. Returning undefined prevents loading |
translate | (key: string) => string | Optional; translates auxiliary labels such as diagram actions. Built-in English labels are the default |
This minimal example resolves HTTPS images against the document URL. Connect local protocols through the host's own controlled resource resolver:
import { MarkdownView, MarkdownViewProvider } from '@downcity/ui';
import '@downcity/ui/markdown.css';
/** Resolve document-relative images to HTTPS addresses; skip invalid addresses. */
function resolve_image_src(src: string, document_url?: string): string | undefined {
try {
const image_url = document_url ? new URL(src, document_url) : new URL(src);
return image_url.protocol === 'https:' ? image_url.href : undefined;
} catch {
return undefined;
}
}
<MarkdownViewProvider resolve_image_src={resolve_image_src}>
<MarkdownView text="" document_url="https://example.com/docs/guide.md" />
</MarkdownViewProvider>The Provider supplies platform capabilities and four controlled size presets, with no arbitrary font, line-height, typography, or plugin configuration. Code blocks retain syntax highlighting, copying, and code actions. Mermaid follows the theme and supports fullscreen viewing and export. Rendering and sanitization stay inside the component.
Links And In-page Navigation
Links such as #installation scroll within the current MarkdownView without opening a window. Heading anchors use lowercase text, remove punctuation, and replace spaces with -. Repeated headings receive -1, -2, and later suffixes. Chinese headings can use their text directly as anchors.
File and web links retain their original href for the host to navigate. When document_url is provided, the outer reader exposes it through data-markdown-document-url. Hosts can read this attribute from the clicked link's nearest reader and resolve relative paths from that document's directory. Desktop uses this context to open or activate the matching BayBar file tab; HTTP(S) addresses open in the default browser.
Controlled Text Size And Composer
MarkdownViewTextSize, get_markdown_text_size, and use_markdown_text_size are exported from @downcity/ui. use_markdown_text_size() returns the current Provider's preset so hosts can pass it into an independent export tree. The UI package owns the preset values; hosts select a preset by name. Use compact for reasoning and activity details:
| Preset | Label | Font size |
|---|---|---|
compact | Compact details | 0.6875rem (11px at a 16px root size) |
small | Small | 0.8125rem |
medium | Standard (default) | 0.875rem |
large | Large | 0.9375rem |
extra_large | Extra large | 1rem |
@downcity/ui/markdown.css also provides .downcity-writing-text for host input text. It shares the Markdown body's system font stack, weight 400, 1.65 line height, natural letter spacing, font-optical-sizing: auto, and antialiasing rules. Text color mixes 90% theme foreground with 10% background and follows theme changes.
This class sets no font size, document width, or paragraph spacing and provides no typography override interface. get_markdown_text_size(text_size) returns the corresponding rem string; combine it with the class so a host composer matches message text:
import { MarkdownView, MarkdownViewProvider, get_markdown_text_size } from '@downcity/ui';
import type { MarkdownViewTextSize } from '@downcity/ui';
const text_size: MarkdownViewTextSize = 'large';
<MarkdownViewProvider text_size={text_size}>
<MarkdownView text={message_text} layout="embedded" />
<textarea className="downcity-writing-text" style={{ fontSize: get_markdown_text_size(text_size) }} />
</MarkdownViewProvider>Desktop's ChatInput, message rewrite editors, pending queue, and plain-text previews reuse this text class. ChatInput sets a 0.9em gap between adjacent paragraphs in the editor, matching message text. A plain textarea handles its own line breaks; the shared class creates no paragraph structure.
Headings and code scale with the body using em ratios; the body line height stays 1.65. The host persists the user's choice and scopes the Provider to the chat areas that need it. Static message exports follow the selected preset. Buttons, navigation, file previews, and task documents retain their sizes. A nested Provider that supplies only resources or translation continues to inherit the outer text size.
Independent Exports
MarkdownExportContext is publicly exported from @downcity/ui. Set it to true only in the independent React tree used to generate a static archive. It preserves the reading styles of text, code, tables, and diagrams while hiding toolbars. Offscreen Mermaid diagrams also enter rendering without waiting to reach the scrolling viewport:
import { MarkdownExportContext, MarkdownView } from '@downcity/ui';
<MarkdownExportContext.Provider value={true}>
<MarkdownView text={export_text} layout="embedded" />
</MarkdownExportContext.Provider>Embedded static exports inherit the Provider's text_size, defaulting to medium. Code, tables, and diagrams retain their normal reading layout. The Context defaults to false and does not save files or generate PDFs or images. The host waits for content and resources to be ready, then performs the export. An independent React root cannot inherit the original tree's context automatically: explicitly pass the current preset to its MarkdownViewProvider, along with any required resource resolution and translations.