x-markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🎯 技能定位

🎯 Skill Positioning

本技能专注解决一个问题：如何用

@ant-design/x-markdown

正确、稳定地渲染 Markdown 内容。

覆盖范围包括：

基础渲染与包职责边界
LLM 流式输出与不完整语法处理
自定义组件映射与聊天富内容渲染
插件、主题与安全默认配置

This skill focuses on solving one problem: How to correctly and stably render Markdown content using

@ant-design/x-markdown

Coverage includes:

Basic rendering and package responsibility boundaries
LLM streaming output and incomplete syntax handling
Custom component mapping and rich chat content rendering
Plugins, themes, and secure default configurations

📦 Package Responsibility Boundaries
🚀 Quick Decision Guide
🛠 Recommended Workflow
🚨 Development Rules
🤝 Skill Collaboration
🔗 Reference Resources

📦 包职责边界

📦 Package Responsibility Boundaries

层级	包名	职责
UI层	`@ant-design/x`	聊天 UI、Bubble、Sender、交互组件
数据层	`@ant-design/x-sdk`	Provider、请求、流式数据流、状态管理
渲染层	`@ant-design/x-markdown`	Markdown 解析、流式渲染、插件、主题、自定义渲染

⚠️
x-markdown
不是聊天状态管理工具。它负责把已有消息内容渲染出来，不负责请求和消息流本身。

Layer	Package Name	Responsibility
UI Layer	`@ant-design/x`	Chat UI, Bubble, Sender, interactive components
Data Layer	`@ant-design/x-sdk`	Provider, requests, streaming data flow, state management
Rendering Layer	`@ant-design/x-markdown`	Markdown parsing, streaming rendering, plugins, themes, custom rendering

⚠️
x-markdown
is not a chat state management tool. It is responsible for rendering existing message content, not for requests or the message flow itself.

🚀 快速决策指南

🚀 Quick Decision Guide

当你需要...	优先阅读	典型结果
用最小配置渲染 Markdown	CORE.md	用 `XMarkdown` 渲染基础内容
渲染 LLM 流式输出	STREAMING.md	正确处理 `hasNextChunk` 、占位符、尾部指示器
把标签映射到业务组件	EXTENSIONS.md	为自定义标签、代码块、富内容组件建立稳定映射
增加插件或主题定制	EXTENSIONS.md	完成插件导入、主题类名接入、最小 CSS 覆盖
查看属性细节和默认值	API.md	获取 `XMarkdown` 与 streaming 的完整属性表

When you need to...	Priority Reading	Typical Outcome
Render Markdown with minimal configuration	CORE.md	Render basic content with `XMarkdown`
Render LLM streaming output	STREAMING.md	Correctly handle `hasNextChunk` , placeholders, and tail indicators
Map tags to business components	EXTENSIONS.md	Establish stable mappings for custom tags, code blocks, and rich content components
Add plugins or customize themes	EXTENSIONS.md	Complete plugin import, theme class name integration, and minimal CSS overrides
View property details and default values	API.md	Get the complete property table for `XMarkdown` and streaming

🛠 推荐工作流

🛠 Recommended Workflow

先看 CORE.md，先让基础渲染跑通。
只有在内容是分块到达时，才继续看 STREAMING.md。
只有在需要自定义标签、插件、主题时，才继续看 EXTENSIONS.md。
属性名与默认值以 API.md 为准，不要凭记忆猜。

First read CORE.md to get basic rendering working.
Only proceed to STREAMING.md if content arrives in chunks.
Only proceed to EXTENSIONS.md if you need custom tags, plugins, or themes.
Rely on API.md for property names and default values; don't guess from memory.

最小使用示例

Minimal Usage Example

tsx

import { XMarkdown } from '@ant-design/x-markdown';

export default () => <XMarkdown content="# Hello" />;

tsx

import { XMarkdown } from '@ant-design/x-markdown';

export default () => <XMarkdown content="# Hello" />;

🚨 开发规则

🚨 Development Rules

```
components
```
映射尽量保持稳定，不要在每次渲染时创建新的内联组件对象。
最后一块内容必须设置
```
streaming.hasNextChunk = false
```
，否则不完整占位内容不会被刷新成最终结果。
谨慎处理原始 HTML。如果只想保留文本展示，优先使用
```
escapeRawHtml
```
。
如果必须渲染 HTML，请显式审查
```
dompurifyConfig
```
，不要依赖模糊默认行为。
主题覆盖尽量最小化。先继承
```
x-markdown-light
```
或
```
x-markdown-dark
```
，只改必要变量。
如果自定义组件依赖完整语法，再在
```
streamStatus === 'done'
```
时执行昂贵逻辑。

Keep
```
components
```
mappings as stable as possible; do not create new inline component objects on each render.
The last chunk must set
```
streaming.hasNextChunk = false
```
, otherwise incomplete placeholder content will not be refreshed to the final result.
Handle raw HTML carefully. If you only want to retain text display, prioritize using
```
escapeRawHtml
```
.
If you must render HTML, explicitly review
```
dompurifyConfig
```
; do not rely on vague default behavior.
Minimize theme overrides. Inherit
```
x-markdown-light
```
or
```
x-markdown-dark
```
first, and only modify necessary variables.
If custom components depend on complete syntax, execute expensive logic only when
```
streamStatus === 'done'
```
.

🤝 技能协作

🤝 Skill Collaboration

场景	推荐技能组合	原因
聊天中的富文本回答	`x-chat-provider` → `x-request` → `use-x-chat` → `x-markdown`	前三者负责数据流， `x-markdown` 负责最终内容渲染
内置 Provider + Markdown 回复	`x-request` → `use-x-chat` → `x-markdown`	请求配置与渲染职责分离
独立的 Markdown 页面或文档视图	`x-markdown`	不需要聊天状态管理

Scenario	Recommended Skill Combination	Reason
Rich text responses in chat	`x-chat-provider` → `x-request` → `use-x-chat` → `x-markdown`	The first three are responsible for data flow, `x-markdown` is responsible for final content rendering
Built-in Provider + Markdown responses	`x-request` → `use-x-chat` → `x-markdown`	Separation of request configuration and rendering responsibilities
Independent Markdown pages or document views	`x-markdown`	No chat state management required

边界规则

Boundary Rules

适配接口格式，用 x-chat-provider
配置传输、认证、重试、流分隔，用 x-request
管理 React 聊天状态，用 use-x-chat
处理 Markdown 解析、流式恢复和富组件渲染，用 x-markdown

To adapt interface formats, use x-chat-provider
To configure transmission, authentication, retries, and stream separation, use x-request
To manage React chat state, use use-x-chat
To handle Markdown parsing, streaming recovery, and rich component rendering, use x-markdown

🔗 参考资源

🔗 Reference Resources

CORE.md - 包职责、安装与起步、安全默认值、常见渲染模式
STREAMING.md - 分块渲染、不完整语法恢复、loading/done 行为
EXTENSIONS.md - 组件映射、插件、主题、自定义标签建议
API.md - 从官方
```
x-markdown
```
文档生成的 API 参考

CORE.md - Package responsibilities, installation and getting started, secure defaults, common rendering modes
STREAMING.md - Chunked rendering, incomplete syntax recovery, loading/done behavior
EXTENSIONS.md - Component mapping, plugins, themes, custom tag recommendations
API.md - API reference generated from official
```
x-markdown
```
documentation