# Markdown

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/markdown
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=620-31413

```tsx
import { Markdown } from '@commenda/pathfinder/markdown';

<Markdown content={messageText} referenceConfig={referenceConfig} />;
```


## Usage [#usage]

```tsx
import { Markdown } from '@commenda/pathfinder/markdown';

<Markdown content={messagePart.text} isStreaming={status === 'streaming'} />;
```

Pass each text part without flattening tool calls, attachments, or other message parts into Markdown. The renderer needs no chat provider or AI SDK runtime.

## Streaming [#streaming]

Incomplete fences and formatting remain readable while content arrives. Finished blocks use the same components and styles as static content.


```tsx
<Markdown content={streamedText} isStreaming={status === 'streaming'} />;
```


## References [#references]

Resolve known record URLs using application data. Pathfinder renders the reference and preview; the application supplies routing and data access.

```tsx
<Markdown
  content={messagePart.text}
  referenceConfig={{
    resolve: (href, label) =>
      href === '/entities/acme'
        ? {
            label,
            href,
            previewConfig: {
              title: 'Acme Pte Ltd',
              content: <EntitySummary entity={entity} />,
            },
          }
        : undefined,
  }}
/>
```

Use an icon in the resolved reference to add the correct Pathfinder flag to an entity in a table. The renderer does not infer countries from names.

## Tables [#tables]

Tables use compact Pathfinder cell styles, a pinned first column, horizontal scrolling, copy as TSV, CSV/Markdown downloads, and an expanded dialog. Use Markdown alignment markers (`---:`) for numeric columns. Rich cell overrides can use existing Pathfinder cells; sorting, editing, and pagination belong in the standalone Table component.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `content` | `string` | conditional | Required; choose one. `children` preserves the existing MessageResponse calling pattern |
| `children` | `string` | conditional | Required; choose one. `children` preserves the existing MessageResponse calling pattern |
| `isStreaming` | `boolean` | optional | Enables incomplete Markdown handling; defaults to false |
| `isAnimating` | `boolean` | optional | Compatibility alias; explicit `isStreaming` wins. Does not add word animation |
| `components` | `MarkdownComponents` | optional | Typed overrides for prose, headings, links, lists, tables/cells, and images |
| `referenceConfig` | `{ resolve: (href: string, label: string) => InlineReferenceProps \| undefined; }` | optional |  |
| `codeConfig` | `{ showLineNumbers?: boolean; }` | optional |  |

### referenceConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resolve` | `(href: string, label: string) => InlineReferenceProps` | Yes |  |

### codeConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `showLineNumbers` | `boolean` | No |  |

Custom renderers are trusted application code and own their accessibility and URL handling. Raw HTML is not a supported extension mechanism. Math, diagrams, custom tool cards, and executable previews are outside Phase 1; their fences render as code.

## Design and accessibility rules [#design-and-accessibility-rules]

- **MARKDOWN-01:** Body 13/20; h1/h2 use Heading/15, h3–h6 use Copy/13 Strong. Paragraph gaps 12px; lists 4px between items. No library-default typography.
- **MARKDOWN-02:** Use this renderer for chat, briefing, and human threads. Keep the application's original message text.
- **MARKDOWN-03:** Code is inert. Unsafe navigation schemes and executable HTML are not rendered. External links use native browser navigation; app-specific confirmation is an explicit link override.
- **MARKDOWN-REF-01:** Record references have strong body text and a neutral underline. Preview data belongs to the application.
- **MARKDOWN-TABLE-01:** Subtle tray, compact semantic table, pinned first column, copy/export/expand controls.
- Streaming marks the content busy but does not announce every token. The conversation layer owns meaningful reply announcements.

## Migration notes [#migration-notes]

```tsx
// Existing text and stream state can be reused without converting messages.
<Markdown isAnimating={isLiveAssistant && isLastSegment}>
  {segment.part.text}
</Markdown>
```

`components` remains available. Product-specific question fences, math/Mermaid plugins, link-confirmation providers, and word animations are not silently copied; document those separately before migrating a consumer. See the [AI content integration guide](/docs/guides/ai-content).