内置公开组件

Clarify 在 MDX 中默认注册了一组公开组件。你无需手动 import，可直接在 .mdx 文件里使用它们来组织首页入口、提示信息、操作按钮和代码示例。

自动可用的 MDX 组件

以下组件可直接在 MDX 页面中使用：

内容提示：Callout、Note
入口与动作：CardGroup / Card、Button
代码与折叠：CodeGroup、Collapse
布局与属性说明：Row / Col、Properties / Property
Markdown 渲染：Markdown
OpenAPI：OpenApiOperation、OpenApiDocument

组件一览

Callout / Note

用于展示提示、警告、成功状态和补充说明。

CardGroup / Card

用于制作入口卡片、功能矩阵和文档索引。

Button

用于提供明确的行动入口或外部跳转。

CodeGroup

用于展示多语言、多包管理器或多环境代码示例。

Collapse

用于收起可选细节、长列表和进阶说明。

OpenAPI

用于展示完整 API Reference 或单个接口。

Callout

Callout 适合放置与正文强相关的说明、注意事项或风险提示。

基础用法

<Callout type="info">
  模型列表会持续更新，生产接入前应以控制台或模型广场中当前可用模型为准。
</Callout>

类型

type 支持 info、note、tip、warning、danger、success。

Note

适合补充说明上下文，避免正文被细节打断。

Tip

适合展示推荐实践、效率技巧或更优路径。

Warning

适合展示可能导致构建失败、权限不足或行为变化的注意事项。

Danger

适合展示高风险操作，例如删除数据、重置环境或暴露密钥。

Success

适合展示操作完成、配置生效或验证通过。

属性

属性	类型	默认值	说明
`type`	`'info' \| 'note' \| 'tip' \| 'warning' \| 'danger' \| 'success'`	`'info'`	控制颜色和图标
`title`	`ReactNode`	根据 `type` 自动生成	标题，传空值可隐藏
`icon`	`boolean`	`true`	是否显示图标
`className`	`string`	-	追加样式类名

Note

Note 是更轻量的内联提示组件，适合放置不会改变任务流程的补充说明。和 Callout 相比，它不需要选择类型，也没有标题栏。

<Note>
  标题、H2/H3 和导航命名会影响站内搜索结果，建议使用用户能理解的词。
</Note>

标题、H2/H3 和导航命名会影响站内搜索结果，建议使用用户能理解的词。

属性

属性	类型	默认值	说明
`children`	`ReactNode`	必填	提示内容

CardGroup / Card

CardGroup 和 Card 适合做文档入口、功能清单、方案矩阵或章节导航。

基础用法

<CardGroup cols={2}>
  <Card title="关于 Clarify" icon="badge-info" href="/getting-started">
    了解 Clarify 的产品定位、核心价值和推荐使用路径。
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    准备环境、安装 CLI 并创建第一个文档站点。
  </Card>
</CardGroup>

渲染效果：

关于 Clarify

了解 Clarify 的产品定位、核心价值和推荐使用路径。

快速开始

准备环境、安装 CLI 并创建第一个文档站点。

写作文档

使用 Markdown、JSX 和内置组件编写更丰富的内容。

API 文档

从 OpenAPI 描述文件生成接口文档和单接口展示。

图标命名

Card 的 icon 使用 lucide-react 图标名，支持 kebab-case 自动转换。例如：

写法	对应图标
`badge-info`	`BadgeInfo`
`rocket`	`Rocket`
`file-code-2`	`FileCode2`
`shield-check`	`ShieldCheck`

属性

CardGroup

属性	类型	默认值	说明
`cols`	`1 \| 2 \| 3 \| 4`	`2`	桌面端列数
`className`	`string`	-	追加样式类名

Card

属性	类型	默认值	说明
`title`	`string`	必填	卡片标题
`icon`	`string`	-	lucide 图标名，支持 kebab-case
`href`	`string`	-	卡片跳转链接，站内路径会使用客户端路由
`className`	`string`	-	追加样式类名

Collapse

Collapse 适合把可选补充说明、实现细节或长列表内容收起，保持文档主流程简洁。

<Collapse title="查看详细说明">
  这是默认折叠的内容，只有在用户点击标题后才会显示。
</Collapse>

<Collapse summary="默认展开" defaultOpen>
  这段内容初始可见，用户仍然可以手动收起。
</Collapse>

这是默认折叠的内容，只有在用户点击标题后才会显示。

属性

属性	类型	默认值	说明
`title`	`ReactNode`	-	折叠面板标题，优先级高于 `summary`
`summary`	`ReactNode`	`'Details'`	备用标题
`defaultOpen`	`boolean`	`false`	是否默认展开
`className`	`string`	-	追加样式类名

Button

Button 适合在文档中提供明确的下一步动作。

<Button href="/getting-started" arrow="right">
  开始安装
</Button>

<Button href="https://github.com/taicode-labs/clarify" variant="outline">
  查看 GitHub
</Button>

渲染效果：

开始安装

查看 GitHub

属性

属性	类型	默认值	说明
`variant`	`'primary' \| 'secondary' \| 'filled' \| 'outline' \| 'text'`	`'primary'`	按钮样式
`arrow`	`'left' \| 'right'`	-	是否显示方向箭头
`href`	`string`	-	存在时渲染为链接，否则渲染为按钮

CodeGroup

CodeGroup 用于组织并列代码示例，例如不同包管理器或不同语言的写法。

<CodeGroup>

```bash
pnpm add @clarify-labs/cli
```

```bash
npm install @clarify-labs/cli
```

</CodeGroup>

渲染效果：

pnpm add @clarify-labs/cli

Row / Col

Row 和 Col 用于在大屏上创建左右两栏布局，常见于“左侧解释、右侧示例”或“左侧步骤、右侧接口”的文档结构。

<Row>
  <Col>
    ## 写作建议

    先解释用户为什么要执行这个步骤。
  </Col>
  <Col sticky>
    ```bash
    pnpm exec clarify dev
    ```
  </Col>
</Row>

属性

Row

属性	类型	默认值	说明
`children`	`ReactNode`	必填	两栏内容

Col

属性	类型	默认值	说明
`children`	`ReactNode`	必填	当前列内容
`sticky`	`boolean`	`false`	大屏下是否吸顶

Properties / Property

Properties 和 Property 适合描述配置项、组件 props 或 API 字段，比普通表格更适合承载多行说明。

<Properties>
  <Property name="routePrefix" type="string">
    部署子路径，例如 `/docs/`。
  </Property>
  <Property name="tabs" type="ClarifyTabsConfig">
    配置顶部业务分类和侧边栏结构。
  </Property>
</Properties>

属性

Properties

属性	类型	默认值	说明
`children`	`ReactNode`	必填	一个或多个 `Property`

Property

属性	类型	默认值	说明
`name`	`string`	必填	属性名
`type`	`string`	-	类型说明
`children`	`ReactNode`	必填	属性描述

Markdown

Markdown 用于渲染字符串形式的 Markdown 内容，主要适合自定义 MDX 组件或数据驱动内容中复用 Clarify 的 Markdown 渲染能力。

<Markdown>{"**重要：** 发布前请运行构建检查。"}</Markdown>

属性

属性	类型	默认值	说明
`children`	`string`	-	要渲染的 Markdown 字符串
`className`	`string`	-	外层容器样式类名

OpenAPI 组件

OpenApiOperation 用于在指南中嵌入单个接口，OpenApiDocument 用于嵌入完整 API Reference。

<OpenApiOperation specPath="/api" path="/sessions" method="post" />

<OpenApiDocument specPath="/api" />

组件	关键属性	说明
`OpenApiOperation`	`specPath`、`path`、`method`	展示单个接口，适合任务型指南
`OpenApiDocument`	`specPath`	展示完整 OpenAPI Reference

OpenAPI 面板会根据规范展示服务器、认证、参数、请求体、响应示例，并生成多语言请求代码。更多说明见 API 文档。

使用建议

首页、章节索引和功能矩阵优先使用 CardGroup / Card。
与正文强相关的限制、风险和补充说明使用 Callout，轻量补充说明使用 Note。
引导用户继续阅读或执行操作时使用 Button。
多语言、多环境、多包管理器示例使用 CodeGroup。
可选细节、长列表和进阶内容使用 Collapse。
配置项、组件属性和字段说明优先使用 Properties / Property。
指南中解释流程，接口事实交给 OpenApiOperation 或 OpenApiDocument。

自定义 MDX 组件

如果你需要项目专属组件，可以在 MDX 文件顶部显式导入：

import { Alert } from '../components/Alert'

<Alert type="warning">
  这是一个自定义 React 组件示例。
</Alert>

Clarify 的内置组件会自动在 MDX 中注册；自定义组件需要手动导入。