markdown

assistant-ui Markdown

请始终查阅 assistant-ui.com/llms.txt，以获取最新 API。

Assistant-ui 为助手文本部分提供两种渲染器。MarkdownTextPrimitive 是轻量级的 react-markdown 路径，已安装的 MarkdownText 元素则是它的样式化实现。当块级感知流式处理以及可选的 Shiki、KaTeX、Mermaid 或 CJK 支持值得采用更大的渲染器时，可以选择另一种方案 StreamdownTextPrimitive。

参考资料

• ./references/markdown-text.md —— 安装并组合 MarkdownText、自定义 MarkdownTextPrimitive，以及区分行内代码与围栏代码
• ./references/syntax-highlighting.md —— 安装 Shiki 或 Prism 渲染器，并为每种围栏语言选择渲染器
• ./references/latex-mermaid.md —— 配置 KaTeX、规范化模型数学公式、保留代码片段，并在流完成后启用 Mermaid
• ./references/streamdown.md —— 使用 Streamdown 替代方案、插件、Tailwind 源以及延迟解析

选择渲染器

当应用需要小型渲染器、自定义 react-markdown 组件映射，或按语言覆盖 SyntaxHighlighter 和 CodeHeader 时，请使用 markdown-text。仅在消息格式需要时才添加代码高亮、数学公式和 Mermaid 支持。

当文本部分需要基于块的流式处理、不完整 Markdown 修复，或可选的代码、数学公式、Mermaid 和 CJK 插件时，请使用 StreamdownTextPrimitive。它会替换该文本部分的 Markdown 渲染器。不要为同一部分同时挂载两个渲染器。

安装并接入 MarkdownText

安装渲染器，文件将位于 components/assistant-ui/elements/markdown-text.tsx。

npx assistant-ui@latest add markdown-text

MarkdownText 会自行读取当前消息部分。仅在 text 分支中渲染它，其他部分类型继续使用各自的渲染器。

"use client";

import { MessagePrimitive } from "@assistant-ui/react";
import { MarkdownText } from "@/components/assistant-ui/elements/markdown-text";

export function AssistantMessageText() {
  return (
    <MessagePrimitive.Parts>
      {({ part }) => (part.type === "text" ? <MarkdownText /> : null)}
    </MessagePrimitive.Parts>
  );
}

thread 元素已包含此渲染器。仅当替换 thread 的消息布局时，才直接组合使用它。

自定义原语

MarkdownTextPrimitive 通过上下文读取周围的文本部分，因此无需传入文本子项或 value 属性。它的 components 映射控制常规 Markdown 标签以及 SyntaxHighlighter 和 CodeHeader；componentsByLanguage 可为某种围栏语言替换其中任一项。有关直接实现原语，请参阅 markdown-text.md。

preprocess 会在平滑处理和解析之前作用于完整的累积文本，是修复特定模型分隔符的切入点。smooth 默认为 true；defer 默认为 false。对于快速增长的大型消息，可设置 defer，让 React 优先处理输入和滚动，而不是中间解析。渲染器挂载期间请保持其值不变，因为切换该值会重新挂载已解析的树。

高亮围栏代码

在注册 SyntaxHighlighter 之前，MarkdownText 会将围栏代码显示为纯文本。建议使用感知运行时的 Shiki 元素，它会等待当前部分稳定后再进行分词。

npx assistant-ui@latest add shiki-highlighter

import { SyntaxHighlighter } from "@/components/assistant-ui/elements/shiki-highlighter.aui";

const defaultComponents = memoizeMarkdownComponents({
  SyntaxHighlighter,
});

对于已依赖 react-syntax-highlighter 的应用，基于 Prism 的 syntax-highlighter 元素仍然很有用。

npx assistant-ui@latest add syntax-highlighter

import { SyntaxHighlighter } from "@/components/assistant-ui/elements/syntax-highlighter";

编辑已安装的 markdown-text 组件的默认映射，或在渲染该元素的位置传入 components 覆盖项。有关渲染器的确切约定，请参阅 syntax-highlighting.md。

渲染数学公式和图表

KaTeX 需要 remark-math、rehype-katex 和 KaTeX 样式表。markdown 包导出 normalizeMathDelimiters、rewriteCustomMathTags、rewriteLatexBracketDelimiters 和 escapeCurrencyDollars，用于预处理模型输出。这些辅助函数会改写行内代码和围栏代码之外的内容，因此代码中的示例会保持原样。

安装 mermaid-diagram，并将其 .aui 渲染器注册为 mermaid 语言覆盖项。它会读取消息部分的状态，并在流式传输期间显示骨架屏，而不是解析不完整的 Mermaid 源码。请参阅 latex-mermaid.md。

改用 Streamdown

StreamdownTextPrimitive 会读取相同的文本部分上下文，并可接入同一个 MessagePrimitive.Parts 分支。它默认使用 mode="streaming"，在最后一个区块持续增长时保持已完成区块的稳定。请显式提供可选插件，并为 Streamdown 及每个已安装的插件添加 Tailwind @source 条目，以便其控件和光标应用样式。

这里既可以使用 defer，也可以使用 smooth。defer 默认为 false，负载较高时可能跳过中间状态，但仍会渲染最终文本。smooth 也默认为 false；除非确实需要打字机式显示，否则请使用 Streamdown 原生的 animated 属性实现进入动画。完整设置方法和迁移要点见 streamdown.md。

常见问题

Markdown 被渲染为纯文本

• 在 text 分支中渲染 MarkdownText 或 StreamdownTextPrimitive。直接渲染 part.text 会绕过 Markdown 解析。

围栏代码没有语法颜色

• markdown-text 包含标签和复制控件，但不包含语法高亮器。请安装并注册 shiki-highlighter 或 syntax-highlighter。

数学公式没有样式，或价格被解析成数学公式

• 为 KaTeX 导入一次 katex/dist/katex.min.css。当消息同时包含单美元符号数学公式和货币金额时，请组合使用 escapeCurrencyDollars(normalizeMathDelimiters(text))。

响应流式传输时 Mermaid 不断重绘

• 在 componentsByLanguage 中使用 @/components/assistant-ui/elements/mermaid-diagram.aui。其运行时封装会等到消息部分完成后再进行解析。

延迟解析导致视觉重置

• 挂载后不要切换 defer。当该属性变化时，两个原语都会选择不同的延迟渲染器路径。

Streamdown 控件或光标样式异常

• 为 streamdown 和每个已安装的 @streamdown/* 插件添加所需的 Tailwind @source 指令。

相关技能

• primitives -- 组合 MessagePrimitive.Parts 和周围的消息 UI
• elements -- 安装并自定义复制的 markdown-text、语法高亮器和 Mermaid 元素源码