V2 componentsUpdated Oct 3, 2026

Markdown

The one markdown surface. Read-only it renders GitHub-flavored markdown; with editable it swaps in a Tiptap editor that looks the same, because one stylesheet draws both. Headings, lists, quotes, code, tables and links take their type, rhythm and tokens from the system.

Import

Source: packages/ui/src/components/markdown

tsx

1import { Markdown, slackFeatures, githubFeatures, inlineOnlyFeatures } from '@highlight/ui'

Playground

Change the props; the preview and the snippet update together.

Standup, Thursday

Highlight heard three commitments and attributed two to you.

Capture
- On device
Port the foundation
Move the chat surfaces over

Nobody agreed to March.

const gap = 16

Props

Size

Ladder

Measure

Line numbers

Editable

tsx

1const source = `## Standup, Thursday2 3- [x] Port the foundation`4 5<Markdown>{source}</Markdown>

Basic

Pass the source as children. The elements style themselves; nothing needs a class.

Standup, Thursday

Highlight heard three commitments and attributed two to you. The other has no owner, so it is still on the list. See the plan or run hl status.

Capture
- On device
Ship the Markdown component

Open the capture
Review the summary

Nobody agreed to March. Two people left believing it was agreed.

Below the rule.

tsx

1import { Markdown } from '@highlight/ui'2 3const SOURCE = `## Standup, Thursday4 5Highlight heard **three commitments** and attributed two to you. The other has no owner, so it is6still on the list. See [the plan](https://example.com/plan) or run \`hl status\`.7 8- Capture9  - On device10- Ship the \`Markdown\` component11 121. Open the capture132. Review the summary14 15> Nobody agreed to March. Two people left believing it was agreed.16 17---18 19Below the rule.`20 21export default function MarkdownBasic() {22  return (23    <div className="w-full max-w-xl">24      <Markdown>{SOURCE}</Markdown>25    </div>26  )27}

Heading ladder

document is for a page: ## is the section heading and everything below steps down from it. compact is for a narrow column such as a side panel or chat reply: # is 22px, ## is 18px. specimen runs the whole scale, # at display size.

ladder="document"

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

ladder="compact"

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

ladder="specimen"

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

tsx

1import { Markdown } from '@highlight/ui'2 3const SOURCE = `# Heading 14## Heading 25### Heading 36#### Heading 47##### Heading 5`8 9export default function MarkdownHeadings() {10  return (11    <div className="grid w-full max-w-5xl gap-8 sm:grid-cols-3">12      {(['document', 'compact', 'specimen'] as const).map((ladder) => (13        <div key={ladder} className="flex min-w-0 flex-col gap-3">14          <span className="text-foreground-secondary text-xs">ladder=&quot;{ladder}&quot;</span>15          <Markdown ladder={ladder}>{SOURCE}</Markdown>16        </div>17      ))}18    </div>19  )20}

Sizes

md is body copy. sm is the dense reading size, with tighter rhythm, for transcripts and side panels. inherit sets no type or colour of its own, so the text takes the font and colour of whatever it sits in, with md rhythm.

size="md"

Standup, Thursday

Highlight heard three commitments and attributed two to you.

Capture
- On device
Port the foundation
Move the chat surfaces over

Nobody agreed to March.

const gap = 16

size="sm"

Standup, Thursday

Highlight heard three commitments and attributed two to you.

Capture
- On device
Port the foundation
Move the chat surfaces over

Nobody agreed to March.

const gap = 16

tsx

1import { Markdown } from '@highlight/ui'2 3const SOURCE = `## Standup, Thursday4 5Highlight heard **three commitments** and attributed two to you.6 7- Capture8  - On device9- [x] Port the foundation10- [ ] Move the chat surfaces over11 12> Nobody agreed to March.13 14\`\`\`ts15const gap = 1616\`\`\``17 18export default function MarkdownSizes() {19  return (20    <div className="grid w-full max-w-3xl gap-8 sm:grid-cols-2">21      {(['md', 'sm'] as const).map((size) => (22        <div key={size} className="flex min-w-0 flex-col gap-3">23          <span className="text-foreground-secondary text-xs">size=&quot;{size}&quot;</span>24          <Markdown size={size}>{SOURCE}</Markdown>25        </div>26      ))}27    </div>28  )29}

Code blocks

A fenced block is a figure: the language and a copy button in its head, then highlighted code. lineNumbers adds a sticky gutter.

// Radius is three eighths of the height, so every size looks equally round.
export function radius(height: number) {
  return (height * 3) / 8
}

css

.hl-btn[data-size="md"] { --hl-btn-h: 28px; }

1// Radius is three eighths of the height, so every size looks equally round.2export function radius(height: number) {3  return (height * 3) / 84}

css

1.hl-btn[data-size="md"] { --hl-btn-h: 28px; }

tsx

1import { Markdown } from '@highlight/ui'2 3const SOURCE = `\`\`\`ts4// Radius is three eighths of the height, so every size looks equally round.5export function radius(height: number) {6  return (height * 3) / 87}8\`\`\`9 10\`\`\`css11.hl-btn[data-size="md"] { --hl-btn-h: 28px; }12\`\`\``13 14export default function MarkdownCodeBlock() {15  return (16    <div className="flex w-full max-w-xl flex-col gap-6">17      <Markdown>{SOURCE}</Markdown>18      <Markdown lineNumbers>{SOURCE}</Markdown>19    </div>20  )21}

Task list

GFM task items share one marker column with bullets and numbers, and a done item dims its own text.

tsx

1import { Markdown } from '@highlight/ui'2 3const SOURCE = `- [x] Typography4- [x] Icons5  - [x] Lucide only6- [ ] Shadow7- [ ] Buttons`8 9export default function MarkdownTaskList() {10  return (11    <div className="w-full max-w-xl">12      <Markdown>{SOURCE}</Markdown>13    </div>14  )15}

Table

A table scrolls sideways inside its own box, so a wide one never widens the page.

Token	System	Notes
background	gray-1	The page
border	gray-a-6	The default hairline
link	blue-11	Underlined, and firmer on hover

tsx

1import { Markdown } from '@highlight/ui'2 3const SOURCE = `| Token | System | Notes |4|---|---|---|5| background | gray-1 | The page |6| border | gray-a-6 | The default hairline |7| link | blue-11 | Underlined, and firmer on hover |`8 9export default function MarkdownTable() {10  return (11    <div className="w-full max-w-xl">12      <Markdown>{SOURCE}</Markdown>13    </div>14  )15}

Plugins and components

Syntax GFM does not have is opt-in: ==mark== and [[kbd]]. components replaces any element; keep the map outside the component so it stays stable.

The part that matters is nobody agreed to March. Press Cmd Shift 4 to capture.

See the plan and the notes.

tsx

1import { Markdown, type MarkdownProps } from '@highlight/ui'2 3const SOURCE = `The part that matters is ==nobody agreed to March==. Press [[Cmd]] [[Shift]] [[4]] to capture.4 5See [the plan](https://example.com/plan) and [the notes](https://example.com/notes).`6 7// Declared outside the component: a new map each render rebuilds the whole tree.8const COMPONENTS: MarkdownProps['components'] = {9  a: ({ node: _node, ...props }) => <a target="_blank" rel="noreferrer" {...props} />,10}11 12const PLUGINS = [Markdown.remarkMark, Markdown.remarkKbd]13 14export default function MarkdownPlugins() {15  return (16    <div className="w-full max-w-xl">17      <Markdown remarkPlugins={PLUGINS} components={COMPONENTS}>18        {SOURCE}19      </Markdown>20    </div>21  )22}

Editable

editable swaps in Tiptap, loaded on demand, so a read-only Markdown never ships it. defaultValue seeds it once; onChange gets the markdown and the editor. Select text for the floating toolbar.

tsx

1import { useState } from 'react'2import { Markdown } from '@highlight/ui'3 4const INITIAL = `## Launch retro5 6- [x] Move the release date7- [ ] Split the migration into two steps8 9Owner: **Lin**. Select text for the toolbar.`10 11export default function MarkdownEditable() {12  const [markdown, setMarkdown] = useState(INITIAL)13 14  return (15    <div className="grid w-full max-w-3xl gap-8 sm:grid-cols-2">16      <div className="flex min-w-0 flex-col gap-3">17        <span className="text-foreground-secondary text-xs">editable</span>18        <Markdown editable defaultValue={INITIAL} onChange={setMarkdown} placeholder="Start writing…" />19      </div>20      <div className="flex min-w-0 flex-col gap-3">21        <span className="text-foreground-secondary text-xs">read-only, the same source</span>22        <Markdown>{markdown}</Markdown>23      </div>24    </div>25  )26}

Parts

The root, then any compound sub-components. Every part accepts className and forwards the rest of its props to the element or Base UI part beneath it.

Markdown: The editor, read-only unless editable. value or children set the content; features pick the syntax it accepts.
Markdown.Prose: A container with the markdown styles and nothing else, for HTML or React children you already have. Takes size, ladder and measure; nothing is parsed.
Markdown.CodeBlock: The default for a fenced block: a figure with the language and a copy button in its head, then lowlight-highlighted code. Takes lineNumbers.
Markdown.Table: The default for a table: scrolls sideways inside its own box.
Markdown.Paragraph: The default for a paragraph: one that is only an image becomes a figure, with the title as its caption.
Markdown.remarkMark: Remark plugin: ==text== becomes <mark>. Pass it in remarkPlugins.
Markdown.remarkKbd: Remark plugin: [[Cmd]] becomes <kbd>. Pass it in remarkPlugins.

Props

Props added on top of the underlying element or Base UI part.

Prop	Type	Default	Description
`children`	string	—	The markdown source.
`size`	'md' \| 'sm' \| 'inherit'	'md'	md is body copy. sm is the dense size: prose-sm, tighter rhythm, headings no larger than md. inherit sets no type or colour of its own: the text takes the font and colour of its container, with md rhythm.
`ladder`	'document' \| 'compact' \| 'specimen'	'document'	The heading scale. document starts at ##; compact tops out at 22px for narrow columns; specimen runs h1 to h4 as display to h3. Ignored at sm.
`measure`	boolean	false	Caps paragraphs at 72ch. Off, because most surfaces already set a width.
`lineNumbers`	boolean	false	A sticky line-number gutter on code blocks.
`components`	Components	—	react-markdown component overrides, merged over the defaults. Memoise the map.
`remarkPlugins`	PluggableList	—	Appended after remark-gfm.
`rehypePlugins`	PluggableList	—	Appended after the built-in table and task-list transforms.
`urlTransform`	UrlTransform	—	Replaces react-markdown's URL sanitizer, which blanks unknown protocols.
`renderImage`	MarkdownImageRenderer	—	Renders image nodes, for src values that are app pseudo-URLs. Read-only and editable.
`ref`	Ref<HTMLDivElement>	—	The root element.
`className`	string	—	Goes on the .markdown element.
`editable`	boolean	false	Renders a Tiptap editor styled as the read-only output. Loaded on demand, in the browser.
`value`	string	—	The source for an editable Markdown, kept in sync except while the editor has focus. children is used if this is omitted.
`defaultValue`	string	—	Seeds an editable Markdown once, on mount; later changes are ignored.
`onChange`	(markdown: string, editor: Editor) => void	—	Called with the source and the Tiptap editor as the document changes. Editable only.
`placeholder`	string	—	Shown while an editable document is empty.
`readOnly`	boolean	false	Locks an editable Markdown without unmounting the editor, so its content and history survive.
`autoFocus`	boolean \| 'start' \| 'end' \| 'all' \| number	—	Focuses an editable Markdown on mount.
`features`	MarkdownFeatures	—	Which formatting an editable Markdown allows. Omit for everything, or pass a preset (slackFeatures, githubFeatures, ...) and override fields.
`mentionables`	MentionablesHandler	—	Platform-aware @ and # mentions, e.g. createSlackMentionables.
`maxLength`	number	—	Hard cap on an editable document, in plain-text characters.
`extensions`	Array<AnyExtension>	—	Extra Tiptap extensions, appended after the built-in set. Read once, on mount.
`toolbar`	'bubble' \| 'docked' \| false	'bubble'	The formatting bar: floating over a selection, docked above the text, or none.
`editorRef`	Ref<Editor>	—	Receives the Tiptap editor once it has loaded, and null when it unmounts. Pass a state setter or a ref object.

Notes

The stylesheet is markdown-content.css. It styles bare elements under .markdown at zero specificity, so it reaches react-markdown and Tiptap output alike and any utility class still wins.
Every gap is a margin on the block below it, so adjoining margins never stack. The gap above a heading states its rank; the gap below binds it to its content.
Tiptap is a separate chunk, loaded when the first editable Markdown renders. A read-only Markdown never imports it.
remark-math and rehype-katex are not built in; pass them in remarkPlugins and rehypePlugins where the source is math.