组件体系

Experimentalv0.4.0-rc

版本关联

当前版本v0.4.0-rc更新日志v0.4.0-rc

文档组件用于表达语义，例如提示、对比、结构块与列布局。多数组件既可用 MDX 标签，也支持 Markdown 指令。

如果你主要关心写法速查，而不是视觉效果，直接看指令速查表。

Callout 提示块

Callout 用于提示类信息，建议按语义选择不同级别：

Tip/Note：白色提示块，适合轻量提醒或补充说明。
Info：蓝色提示块，适合稳定信息或一致性说明。
Warning：橙色提示块，适合风险提示或强约束。
Deprecated：红色提示块，适合弃用说明与迁移提醒。

提示

用于补充说明或小技巧提示。

信息

用于稳定的规则或信息提示。

警告

用于风险提示或强约束。

弃用

用于标记弃用功能或迁移提醒。

Alerts（GitHub 语法）

使用 GitHub 风格的提示语法，会自动映射为 Callout。

说明

会渲染成 Note 提示块，便于迁移和协作时统一语法。

警告

用于风险提示或强约束说明。

Columns 分栏

并列信息

适合并排展示概念或步骤。

结构化对比

帮助读者快速理解差异点。

Cards 卡片

卡片用于展示入口或推荐阅读，默认一行最多 4 个，移动端最多 2 个。

卡片（指令语法）

LinkButton 链接按钮

进入快速开始浏览组件查看更新日志

Badge 标签

测试版稳定注意

行内语法：实验中。

数学公式

行内公式用 $...$ ，块级公式用 $$...$$，渲染由 KaTeX 提供。

行内示例： $E = mc^2$ 。

\int_0^1 x^2 \, dx = \frac{1}{3}

DiffBlock 对比块

用于并排对比两个方案/版本，beforeLabel 与 afterLabel 可选，必要时再显示顶部标签。

旧行为新行为

cache: "manual"

需要手动维护缓存策略。

cache: "filesystem"

自动与文件结构同步。

代码块

使用标准 Markdown 代码块语法，渲染时自动应用统一样式与复制按钮。

export const navStrategy = "filesystem";
export const contentPath = "content";

差异高亮

代码块中以 + / - 开头的行会自动渲染为增删差异背景。

diff

- cache: "manual"
+ cache: "filesystem"

CodeGroup / Tabs

用于在同一块内切换多段代码。使用 code-group 指令即可，无需写额外 JSX。

Chat CompletionsResponses

Structured Outputs

javascript

const completion = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Jane, 54 years old" }],
});

Structured Outputs

javascript

const response = await openai.responses.create({
  model: "gpt-5",
  input: "Jane, 54 years old",
});

富内容面板

需要混合文字、图片或其它块时，使用 :::code-group + :::tab 语法。

说明

可用于说明、图示或配置对比。

配置

toml

[docs]
static = true

:::

Steps 步骤

将有序列表渲染为步骤块，适合安装/迁移/排查流程。

安装 typematter 依赖。
调整 content/ 目录结构。
构建前先执行 npm run validate:docs。

FileTree 文件树

将列表渲染为带文件/目录图标的可折叠树形结构。

app
- layout.tsx
- page.tsx
content
- core-concepts
  - components.mdx
package.json项目元信息

Details 折叠块

折叠块用于放置补充说明或可选项，避免打断阅读主线。

为什么重要

保持长说明的可读性，同时不干扰主流程。

Annotation 注释

在正文中插入注释标记，悬停或聚焦后显示解释内容。

这个 API 仍在实验中：注意查看迁移指南以了解限制。。

FeatureMatrix 能力矩阵

用于对比多方案能力矩阵，仍使用 Markdown 表格语义即可。

能力	Chat Completions API	Responses API
文本生成
音频		即将支持
视觉
Structured Outputs
Function calling
Web search
File search
Computer use
Code interpreter
MCP
Image generation
Reasoning summaries

Endpoint / ParamTable / ResponseSchema API 结构

这组组件适合 API 页面，重点是把接口头、参数、返回结构拆成稳定语义块，而不是堆散乱表格。

GET/v1/docs/[slug]

获取文档页面

按路由返回 registry 中的页面元信息。

认证: optional自 0.4.0-rc

路径参数

名称类型必填默认值说明

slug

string[]

是

文档路由片段数组。

lang

"cn" | "en"

否

cn

语言代码。

200 响应

HTTP 200application/json

titlestring必填

页面标题

sectionstring必填

所属分组

tocTocItem[]

标题目录

idstring必填

锚点 id

titlestring必填

标题文本

levelnumber必填

标题层级

指令语法

mdx

:::endpoint{method="GET" path="/v1/docs/[slug]" title="获取文档页面" summary="按路由返回 registry 中的页面元信息。" auth="optional" since="0.4.0-rc"}:::param-table[路径参数]::param-field[slug]{type="string[]" required="true" description="文档路由片段数组。"}::param-field[lang]{type='"cn" | "en"' default="cn" description="语言代码。"}::::::response-schema[200 响应]{code="200" mediaType="application/json"}::schema-field[title]{type="string" required="true" description="页面标题"}::schema-field[section]{type="string" required="true" description="所属分组"}:::schema-field[toc]{type="TocItem[]" description="标题目录"}::schema-field[id]{type="string" required="true" description="锚点 id"}::schema-field[title]{type="string" required="true" description="标题文本"}::schema-field[level]{type="number" required="true" description="标题层级"}:::::::::

DoDont 建议对照

用于最佳实践、迁移规范、代码 review 规则这类非常高频的“该做 / 不该做”表达。

写 API 文档时

推荐做法

避免做法

指令语法

mdx

:::do-dont[写 API 文档时]:::do[保持字段名稳定]对外字段名、枚举值和错误码应该保持长期稳定。::::::dont[不要只给示例不给结构]示例响应不能替代字段级结构定义。::::::

VersionGate 版本策略

用于明确能力从何时可用、何时弃用、何时移除。

Legacy search index

自 0.2.0弃用 0.4.0移除 1.0.0

当一个能力进入迁移期时，不要只写一句“未来会调整”，直接把版本策略贴在能力块附近。

指令语法

mdx

:::version-gate[Legacy search index]{since="0.2.0" deprecated="0.4.0" removedIn="1.0.0" replacement="standard search manifest"}当一个能力进入迁移期时，不要只写一句“未来会调整”，直接把版本策略贴在能力块附近。:::

CommandGroup 命令切换

适合按包管理器、操作系统、运行环境切换命令。

安装 Typematter

pnpmnpmyarnbun

指令语法

mdx

:::command-group[安装 Typematter]:::command[pnpm]{description="推荐"}```bashpnpm installpnpm dev```::::::command[npm]```bashnpm installnpm run dev```::::::

PreviewFrame 预览框

用于嵌入截图、录屏、产品 demo 或同源 iframe 页面。

快速开始页面预览

打开源地址

适合放同源页面预览；如果是截图或录屏，也可以传图片或视频地址。

指令语法

mdx

::preview-frame[快速开始页面预览]{src="/cn/get-started/quickstart/" caption="适合放同源页面预览；如果是截图或录屏，也可以传图片或视频地址。"}

Timeline / ReleaseItem 时间线

适合版本演进、迁移路线、破坏性变更编年说明。

0.1.0初版 shell

2026-01-26

建立静态文档壳、MDX 内容读取和基础导航。

0.2.0搜索与 Ask AI

2026-02-03测试版

引入标准搜索索引与可选的 Ask AI 集成。

0.4.0-rc版本关联与中文搜索

2026-03-20当前

增加版本关联面板、文档类型模板、中文别名召回，以及更稳的 Ask AI 检索体验。

指令语法

mdx

:::timeline:::release-item[初版 shell]{version="0.1.0" date="2026-01-26"}建立静态文档壳、MDX 内容读取和基础导航。::::::release-item[版本关联与中文搜索]{version="0.4.0-rc" date="2026-03-20" status="当前"}增加版本关联面板、文档类型模板、中文别名召回，以及更稳的 Ask AI 检索体验。::::::