Components

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

Callout

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

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

Alerts（GitHub 语法）

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

Columns

Cards

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

• 快速开始

  安装依赖并初始化文档结构。

• 组件库

  内置的 MDX 组件语义。

• 项目结构

  了解内容与导航的组织方式。

• 构建校验

  CI 检查文档质量与链接。

卡片（指令语法）

• 快速开始

  安装依赖并初始化文档结构。

• 组件库

  内置的 MDX 组件语义。

• 项目结构

  了解内容与导航的组织方式。

• 构建校验

  CI 检查文档质量与链接。

Link Buttons

Badges

行内语法：实验中。

Math Equations

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

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

Diff Block

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

Code Block

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

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

Colored Diffs

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

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

Code Tabs

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

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

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

富内容面板

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

[docs]static = true

:::

Steps

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

1. 安装 typematter 依赖。

2. 调整 content/ 目录结构。

3. 构建前先执行 npm run validate:docs。

File Tree

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

Details / Accordion

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

Annotations

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

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

Feature Matrix

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