Skip to content
Browse documentation
whisk/ui

Markdown

Render read-only Markdown with Whisk/UI presentation rules.

Overview

Markdown renders read-only Markdown from a source of at most 64,000 UTF-16 code units with Whisk/UI components. It omits raw HTML and remote images; navigation, syntax highlighting, and math rendering follow explicit host policies.

Use when

The application needs to display read-only Markdown from an application-owned or validated source of at most 64,000 UTF-16 code units.

Use instead

Use native Whisk/UI components when the page structure or interactions are known in advance. Use a rich-text editor when people need to author and edit content.

Usage

Release notes

  • Fixed the upload flow.
import { Markdown } from "@smoothie-framework/whisk-react/markdown";

<Markdown
  source={"## Release notes\n\n- Fixed the upload flow."}
/>

Examples

Document

Markdown accepts at most 64,000 UTF-16 code units. It supports headings, emphasis, lists, quotes, tables, inline code, and fenced code; keep application controls outside the source.

Deployment checklist

  1. Run bun run typecheck
  2. Review the release notes

Publish only after the checks pass.

import { Markdown } from "@smoothie-framework/whisk-react/markdown";

<Markdown
  source={"## Deployment checklist\n\n1. Run `bun run typecheck`\n2. Review the release notes\n\n> Publish only after the checks pass."}
/>

Links

Safe is the default and permits relative, http, https, and mailto destinations. Use text when the source is display-only; the label remains, but no link is created.

Read the deployment guide.

import { Markdown } from "@smoothie-framework/whisk-react/markdown";

<Markdown
  links="text"
  source={"Read the [deployment guide](/guides/deployments)."}
/>

Streaming

Append received chunks while more source can arrive, then switch to complete when the final chunk arrives. Use incomplete only when delivery has ended with an unfinished response; both states repair unfinished inline Markdown for display.

The release is being

import { useEffect, useState } from "react";
import { Button, Stack } from "@smoothie-framework/whisk-react";
import { Markdown } from "@smoothie-framework/whisk-react/markdown";

export function ReleasePreview() {
  const chunks = ["The release is ", "**being", " prepared", " for", " deployment**."];
  const [count, setCount] = useState(2);
  const isStreaming = count < chunks.length;

  useEffect(() => {
    if (!isStreaming) return;
    const timer = setTimeout(() => setCount((value) => value + 1), 800);
    return () => clearTimeout(timer);
  }, [count, isStreaming]);

  return (
    <Stack gap={3}>
      <Markdown
        status={isStreaming ? "streaming" : "complete"}
        source={chunks.slice(0, count).join("")}
      />
      <Button variant="secondary" onClick={() => setCount(2)}>Replay</Button>
    </Stack>
  );
}

Syntax

Ordinary Markdown deliberately keeps fenced code plain. Import the optional highlighter only when syntax highlighting is useful for this surface.

ts
const ready = true;
import { Markdown } from "@smoothie-framework/whisk-react/markdown";
import { MarkdownHighlightedCodeBlock } from "@smoothie-framework/whisk-react/markdown/highlight";

<Markdown
  codeBlock={MarkdownHighlightedCodeBlock}
  source={"\`\`\`ts\nconst ready = true;\n\`\`\`"}
/>

HTML and images

Raw HTML is omitted. Image syntax becomes safe link text instead of fetching or rendering remote media, so supply media through application components.

Architecture diagram

import { Markdown } from "@smoothie-framework/whisk-react/markdown";

<Markdown
  links="text"
  source={"<aside>Ignored HTML</aside>\n\n![Architecture diagram](https://example.com/diagram.png)"}
/>

Props

Component props

PropTypeDefaultDescription
sourcestringnoneRequired source, up to 64,000 UTF-16 code units. At a known parser-complexity limit, the complete source is shown as plain text rather than truncated.
statusstreaming | complete | incompletecompletestreaming means more source is expected; incomplete means delivery has stopped with unfinished source. Both repair unfinished inline Markdown for display; complete does not.
linkssafe | textsafeSafe renders relative, http, https, and mailto destinations as native anchors. In a single-page app, relative links use normal browser navigation; Markdown has no router-link override. Use text to preserve labels without navigation, then render application-owned routed links outside Markdown.
sizeTextSizesmSet the paragraph text size.
codeBlock | mathComponentType<MarkdownCodeProps> | ComponentType<MarkdownMathProps>MarkdownCodeBlock | noneThese are the trusted extension points for fenced code and math. The default code block wraps long lines and includes a copy action. Markdown has no react-markdown components prop.

Shared props

PropSupportedNotes
as / asChildNoMarkdown owns its document wrapper.
Style propsNoMarkdown exposes its documented rendering props instead. See Style props.
className / styleYesApplied to the document wrapper.
refYesForwards to the document wrapper.
Native HTML attributesYesNative div attributes are forwarded.

Accessibility

Markdown produces semantic headings, lists, quotes, and tables, but it does not turn task items into controls. Keep the source heading hierarchy consistent with the surrounding page; heading levels cannot be shifted. Write descriptive link text, and keep forms, consent, and other interactive controls outside the source. Use links="text" when displayed content must not navigate.