function deploy(target: string) {
  return `Deploying to ${target}…`;
}

Install

pnpm exec vegastack-design verify markdown-view

pnpm dlx shadcn@4.21.0 add @vegastack/markdown-view

Usage

Image URLs are normalized against a fixed origin before policy checks; relative images remain local and remote images require an allowed HTTP(S) origin.

import { MarkdownView } from "@/components/ui/markdown-view";

<MarkdownView>{`# Hello\n\nThis is **markdown**.`}</MarkdownView>;

Pass the markdown as children (a string) or via the content prop when the source comes from a data field:

<MarkdownView content={task.description} />

MarkdownView tokenizes with marked's lexer (CommonMark + GitHub-flavored markdown: tables, strikethrough, task lists, autolinks — the same parser TextEdit's Markdown format uses) and rebuilds the tokens as React elements — never dangerouslySetInnerHTML — so any raw HTML in the source renders as inert text. It is server-safe (no 'use client'), light enough for a page's first bundle (one ~13 KB parser), and renders nothing for empty/whitespace input.

Relative image paths render normally. Absolute and protocol-relative remote images are blocked by default so untrusted Markdown cannot create tracking requests. When a trusted media host is required, allow its exact origin; allowed remote images send no referrer:

["*"] allows every HTTP(S) origin, for content whose author is trusted to embed images — TextEdit's read view passes it, matching the editor, which shows any image.

<MarkdownView allowedImageOrigins={["https://media.example.com"]}>
  {"![Product preview](https://media.example.com/preview.png)"}
</MarkdownView>

An image's width set by resizing it in TextEdit travels in its alt text — ![Diagram|320](src) renders 320px wide (never wider than the text column) with the alt "Diagram"; ![Diagram|320x180](src) also gives its height, so its box is reserved before it loads (TextEdit stores the size of every image it inserts). parseImageAlt and imageMarkdown (from @/lib/text-edit-grammar) read and write that form. An image on a line of its own is a block — a figure, its title the caption — laid out as TextEdit lays it out, so the read view and the editor match. To open images in the FileViewer on a click, wrap the view in TextEdit's ImageViewerScope.

Anatomy

Examples

Default

Headings, paragraphs, inline code, links, lists, and blockquotes — styled by the shared prose recipe from @vegastack/design, worn as one class on the root (no @tailwindcss/typography dependency). TextEdit wears the same string, so rendered markdown and edited rich text are the same typography rather than two that agree by review.

function deploy(target: string) {
  return `Deploying to ${target}…`;
}

GitHub-flavored markdown

GitHub-flavored markdown adds tables, ~~strikethrough~~, and - [ ] task lists. Task-list checkboxes are rendered read-only (display only). A table is Notion's simple table — a rounded outer border, a rule between every cell and a header row on a muted ground at medium weight — the exact styles TextEdit edits it in, scrolling in its own box when wider than the page.

Code blocks

Inline code renders as a muted font-mono chip; fenced code blocks delegate to CodeBlock — a <figure> with a language caption and a copy action — rather than a bare <pre>. The language comes from the fence's language-* class and the copy source from the code text, so a transcript, a docs page and a hand-composed example all share one code surface.

function greet(name: string) {
  return `Hello, ${name}`;
}

Links

External links (those starting with http(s)://) open in a new tab with target="_blank" and rel="noreferrer noopener"; relative/internal links stay in the same tab. The link color (text-info-text) and underline are identical in both cases.

Full element set

A consolidated sample exercising every styled element — all six heading levels, ordered, unordered and nested task lists, a quote, fenced code with a language, a GFM table, a horizontal rule, an image, inline emphasis and a long URL — so the complete prose surface renders in one view. It is everything TextEdit writes, in the same body typography and at the same positions. Nothing widens the page: long words and URLs wrap, and code blocks and tables scroll inside their own box.

PreviewCode

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

A paragraph with bold, italic, strikethrough, and inline code.

1. First ordered step
2. Second ordered step
3. Third ordered step

• Unordered item

• Another item

  • Nested item

• Done task

• Open task

  • Nested task

A blockquote settles at the muted foreground.

print("fenced code keeps its language")

Owner	Task
Ada	Release notes
Grace	Pricing page

A long URL wraps inside the line: https://example.com/a/very/long/path/that/would/otherwise/widen/the/page/and/scroll/it/sideways (opens in new tab)

---

Markdown usually starts its outline at #. When it renders under the page's own headings — a card titled with an h2 — pass headingOffset to move every heading down that many levels, capped at h6: headingOffset of 2 renders # as an h3, so the outline never skips back up. Each heading takes the prose style of the level it lands on.

<MarkdownView headingOffset={2}>{notes}</MarkdownView>

HTML source

format="html" renders HTML instead of markdown — TextEdit's format="html" output, which is how TextEdit shows a saved document before it is first edited. The HTML is rebuilt through a tag and attribute allowlist (the elements rich text uses: headings, paragraphs, marks, lists and task lists, quotes, code, tables, links, images), never injected: scripts, styles, event handlers and unsafe URLs are dropped, and the same link, image, code-block and task-list rules apply.

PreviewCode

Release checklist

Ship the lazy editor and tell the team (opens in new tab).

• Read view renders on the server

• Editor loads on intent

const editor = await import("./text-edit-editor");

<MarkdownView format="html" content={note.html} />

Mentions, files, callouts and toggles

The constructs TextEdit's Markdown carries beyond GFM render here too, still server-safe:

• Mentions — [@Asha Rao](mention://user/u1) renders as an InlineChip: a person on blue with their avatar, any other kind on the neutral chip with its kind's icon, then the name; mentionImage(id) gives a person chip their photo. mentionHref(kind, id) makes a chip a link (return null for none); a person is never a link, and an id starting with restricted: renders a muted chip that never links (the target is one the reader may not open). mentionStatus(kind, id) returning { struck: true, status: "Canceled" } strikes a closed target's label and tags its status, as in TextEdit. Any kind matching [a-z][a-z0-9_]{1,31} is a mention: a kind the app names in the InlineChipProvider's kinds ([@Glazing kit](mention://product/v1)) shows its icon, any other a link glyph.
• File chips — a link whose href starts with fileLinkPrefix (default /api/files/) renders as a chip with an icon for the file's type; "" turns file chips off.
• Callouts — GitHub's alert syntax, > [!NOTE], > [!TIP] and > [!WARNING], renders as a role="note" box in the tone's ink.
• Toggles — <details><summary>Title</summary>, a blank line, the body, a blank line and </details> render as a native disclosure, collapsed. <br> is a line break (in a table cell, a heading or a sentence); any other raw HTML still renders as text.
• Heading ids — headingIds gives every heading the id TextEdit's onOutlineChange reports (its words, hyphenated; -1, -2… for a repeat), so an outline links into either. headingIds(texts) (from @/lib/text-edit-grammar) builds the same ids on a server.

<MarkdownView
  headingIds
  mentionHref={(kind, id) => (kind === "page" ? `/library/${id}` : null)}
>
  {page.body}
</MarkdownView>

parseMentionLink(source) reads a mention at the start of a string and mentionMarkdown(kind, id, label) writes one exactly as TextEdit does (the label escapes \, [ and ]). Both come from @/lib/text-edit-grammar, which MarkdownView installs with it.

Embeds

A YouTube or Loom link alone on its line (a bare URL, <url> or [url](url), in the document, a quote, a callout or a toggle) renders, with embeds={EMBED_PROVIDERS} (opt-in; without it such a line is a plain link), as TextEdit's embed facade, MarkdownEmbed: a 16:9 card with the provider's glyph, "YouTube video" or "Loom video", and Play. The markup is server-rendered and nothing loads from the provider until Play, which swaps in a lazy, sandboxed player frame whose src is rebuilt from the video id — never the URL as written. Printed, it is the URL. A link in a sentence, in a list item, or to any other host stays a link. TextEdit's HTML for an embed (div[data-type="embed"] around its link) renders the same way. The allowlist and the frame-src origins come from @/lib/embed-providers, which MarkdownView installs with it: matchEmbed(url) returns { provider, id, start?, src } or null, and EMBED_FRAME_ORIGINS is the Content-Security-Policy frame-src list.

Bookmarks and task lines

A link titled bookmark alone on its line — [https://example.com](https://example.com "bookmark"), what TextEdit's Bookmark writes — renders as a card (MarkdownBookmark): the page's title, its blurb and its icon with the site's address, from the InlineChipProvider's linkPreview (or a fetchPreview / preview given to MarkdownBookmark itself). It loads nothing from the site and opens the page in a new tab. Any other reader shows the link.

onTaskOpen draws a linked checklist line (- [ ] [@Order glass](mention://task/t1)) as a TaskInline: one round box, the title that calls onTaskOpen(taskId) on a click, the assignee's avatar and the due date from mentionStatus (assignee, due, overdue) or the provider's state, and ↗ to its page on hover.

Live task lists

A live task list is a container directive: :::tasks{…} at the start of a line, its rows, and ::: alone on a line.

:::tasks{id="lb_9f2c" v="1" space="page" assignee="me" status="open" sort="due" limit="25" as-of="2026-10-14T09:00:00Z"}
- [ ] [@Order glass for block B](mention://task/0192…) — To do
- [x] [@Fix scaffolding](mention://task/0193…) — Done
:::

The attributes are key="value" pairs separated by spaces. Keys are [a-z][a-z0-9-]*, values are double-quoted, and \" and \\ are the escapes. id is the block's id. The rest are the list's filter, and unknown keys are kept as written. Each row is a task item whose first inline is a task mention, then an em dash between spaces and the status label. MarkdownView renders the rows as a quiet, read-only card (MarkdownLiveBlock): the muted heading "Task list", then each row's done box, task chip and status label. A list with no rows shows "No matching tasks". The card is the snapshot stored with the page, so a public view never gets live data.

Lines that do not make a whole block read as Markdown always did. That includes a missing closing line, a row that is not a list item line, or attributes that do not parse. A renderer without directive support shows the same lines as text and a list. TextEdit's HTML for a list (div[data-type="task-query"]) renders the same card.

renderTaskQuery({ blockId, query, snapshot, editable }) lets a host draw the live list in its place, with editable: false here. TextEdit passes it on to the read view it shows first.

The directive's name is open: liveBlockKinds lists the kinds the view reads, each a LiveBlockKind — { name, rowKind, label, empty? }: the name after ::: ([a-z][a-z0-9_]*), the mention kind of its rows, the snapshot card's heading and its line with no rows. The default is the live task list alone (DEFAULT_LIVE_BLOCK_KINDS), and a block of any other name stays text. A kind's rows may drop the box: - [@Row](mention://row/<id>) is a row too, drawn as its chip alone. renderLiveBlock(kind, props) draws every kind, tasks included; without it renderTaskQuery draws tasks alone, and any block it does not draw shows its stored snapshot under its kind's heading. The grammar comes from @/lib/text-edit-grammar: readLiveBlock(source, { names }) (liveBlockNames(kinds)), liveBlockMarkdown and parseLiveBlockRows(snapshot, rowKind).

Document type scale

typeScale="document" is a page read as a document (TYP-20): 14/24 text — 16/26 on a coarse pointer or a narrow window, where editing is 16px too — 12px between paragraphs, # 24 · ## 20 · ### 16 with more room above a heading than below, inline code in the body's ink, and print rules: code wraps, tables print in full, highlights and controls drop out, external links print their address. TextEdit takes the same typeScale, so a page reads and edits at identical metrics. Place it in a DocumentLayout for the page's fluid text column. A table that is wider than the text scrolls in its own box, fading at the edge with more beyond it; while it scrolls the box is a named, focusable region.

Read mode

A reader needs no editor. annotations draw comment highlights over the words each one quotes — resolved from the quote and its context, the way TextEdit re-anchors, and never drawn when the words are gone or appear twice with nothing to tell them apart — with activeAnnotationId, onAnnotationClick, count pills (annotationCounts) and onAnnotationsLayout (each highlight's top, for a comment margin). onOutlineChange reports the headings for a contents list. headingAnchors gives headings their server slug and block id (data-anchor-id), and headingLinkHref adds a # copy-link button in the gutter before each heading's text (after it on a coarse pointer), shown while the heading is hovered, focused or tapped — a press copies the absolute link and says so in a toast, and the text never moves. sectionMarks draws the same section markers and bars as TextEdit beside the text (a dot on the heading, a bar along its section; inside a phone's 16px gutter), and onSectionMark hears a marker's click. toggleState keeps each reader's own open toggles. findQuery highlights every match with the CSS Custom Highlight API — the DOM is never changed — opens any toggle around the current one, and shows a match bar with previous, next and onFindClose.

<MarkdownView
  typeScale="document"
  annotations={threads.map((t) => ({
    id: t.id,
    anchor: t.anchor,
    count: t.count,
  }))}
  activeAnnotationId={openThread}
  onAnnotationClick={openThreadById}
  onOutlineChange={setOutline}
  headingAnchors={page.anchors}
  headingLinkHref={(a) => `#${a.slug}~${a.id}`}
  sectionMarks={[
    { key: staleBlockId, tone: "warning", label: "May be out of date" },
  ]}
  onSectionMark={openReview}
  toggleState={toggles}
  findQuery={query}
  onFindClose={() => setQuery("")}
>
  {page.markdown}
</MarkdownView>

Comment on a selection

onCreateAnnotation lets a reader comment without an editor: select words in the view and a small Comment button floats over them — the same button TextEdit's read-only selection bubble shows (commentLabel renames it). Pressing it calls onCreateAnnotation(anchor) with { quote, prefix, suffix, start, end }, computed over the same text annotations resolve against, so handing the anchor straight back as an annotation highlights exactly the selected words. A mention or an image counts whole; a selection of only whitespace, mentions, images or code shows nothing, and so does one that leaves the view. The button sits in a <body> portal above the selection — below it on a coarse pointer, where the platform's own callout sits above — flips and slides to stay in view, and hides while the selection is scrolled out. floatingSafeArea keeps it clear of a sticky app header or a bottom bar ({ top: 56 }); a selection under one counts as scrolled out. Tab moves to it from a selection made with the keyboard and

Esc closes it until the selection changes. The view itself stays server-safe: the button is part of its client effects.

<MarkdownView
  typeScale="document"
  annotations={threads}
  onCreateAnnotation={(anchor) => startThread(anchor)}
  floatingSafeArea={{ top: 56 }}
>
  {page.markdown}
</MarkdownView>

Citations

A summary cites its sources with [[n]] markers (n = 1–999). With citation, each marker whose n the function answers for renders as a small superscript n: a button named by label that opens content (a quote, who said it, when) on hover, keyboard focus or a long press, and calls onSelect on a click or tap — play the recording from there. Without onSelect, a tap opens content. A marker the function returns null for, and every marker without the prop, stays literal text, and so does one inside a code span, fenced code or link text. The marker is a client component, so pass citation from one.

<MarkdownView
  citation={(n) =>
    sources[n] && {
      label: `Source ${n}`,
      content: sources[n].quote,
      onSelect: () => player.seek(sources[n].start),
    }
  }
>
  {summary}
</MarkdownView>

Block views

blockViews maps a fence's language to a renderer: with blockViews={{ mermaid: mermaidBlockView }} (from Mermaid Block), a ```mermaid fence is a Diagram block — a header with the view's label, Preview / Code (buttons with aria-pressed; ⌘/Ctrl+Enter toggles and Escape goes back to the preview from the block's controls), Expand (a full-screen dialog with pan and pinch) and a ⋯ menu with Copy source and the view's own actions (Copy SVG, Download SVG). Other fences stay code blocks. The preview is client-only: on the server, and before hydration, the fence shows its source in the same frame with the preview's height reserved, so nothing jumps when it draws. The mode is the reader's own and never saved. The entries hold functions, so pass blockViews from a client component, or an entry a client module exports (mermaidBlockView is one). TextEdit takes the same prop for its read view and its editor.

flowchart LR
  accTitle: Publishing a page
  accDescr: A draft goes to review, then is published or sent back for changes.
  draft[Draft] --> review{Review}
  review -->|Approved| published([Published])
  review -->|Changes| draft
  class draft step
  class review decision
  class published outcome

import { MarkdownView } from "@/components/ui/markdown-view";
import { mermaidBlockView } from "@/components/ui/mermaid-block";

<MarkdownView blockViews={{ mermaid: mermaidBlockView }}>
  {page.body}
</MarkdownView>;

A view of your own is { label, render(source, { mode, theme }) }, plus defaultView, split, starter, hint and actions where it needs them.

API Reference

MarkdownLiveBlock takes a div's props plus:

renderTaskQuery is called with:

Accessibility

• Markdown maps to semantic HTML — # → <h1>, - → <ul><li>, > → <blockquote>, ``` → <pre><code> — so the document structure is exposed to assistive technology and heading navigation works.
• XSS-safe by construction: every element is rebuilt as a React element — never dangerouslySetInnerHTML — and raw HTML in markdown renders as text, so <script>, <img onerror>, and inline event handlers in untrusted input render as plain text rather than executing. format="html" keeps only allowlisted tags and attributes.
• A callout is a role="note" named by its tone ("Note", "Tip", "Warning"); its icon is decorative. A toggle is a native <details>/<summary>: Enter or Space on the summary opens and closes it.
• A mention chip that links is an ordinary link; one that does not (a person, a restricted target) is plain text with an icon.
• Links open in a new tab with rel="noreferrer noopener" (no reverse tabnabbing); unsafe URL protocols (e.g. javascript:) are dropped.
• Remote images are blocked unless their exact HTTP(S) origin appears in allowedImageOrigins; allowed remote images use referrerPolicy="no-referrer".
• Body text inherits the page text color (text-foreground); links use text-info-text with an underline, keeping a visible, color-independent affordance.

A citation marker is a button named by its label ("Source 3"); keyboard focus opens its source without moving focus, and Enter selects it.

With onAnnotationClick, a comment highlight is one tab stop — a button named for its whole quote and count ("3 comments on “annual price”") — that opens on Enter or Space; the rest of a highlight split by formatting is hidden from assistive technology, which heard it in that name. A count pill's number is aria-hidden; its name is the sentence ("3 comments"). The find bar is a search landmark ("Find in page") docked at the window's bottom end: its Previous and Next buttons step through the matches, Esc closes it, and "2 of 12" is announced politely. Overlapping highlights never nest: each thread has exactly one tab stop (where another thread covers exactly its words, its count pill is that stop). A heading's copy-link button is named "Copy link to “Pricing”". A table that scrolls is a focusable region named "Table, scrolls sideways", so the arrow keys scroll it.

With onCreateAnnotation, the selection's Comment button is a toolbar named "Selection actions" holding one button named by commentLabel. Tab from a selection inside the view (focus on the page or in the view) moves focus to it, Shift+Tab goes back,

Enter comments and Esc closes it. A press on it keeps the selection.

Do / Don't