将 Cursor 与 Mintlify 搭配使用
- 项目规则 存储在你的文档存储库中，并与团队共享。
- 用户规则 适用于你的个人 Cursor 环境。
.cursor/rules 目录中创建规则文件。完整的设置说明请参见 Cursor Rules 文档。
示例项目规则
- 写作规范：更新语言规范以符合你的风格指南。
- 组件模式：添加项目特定的组件或修改现有示例。
- 代码示例：将通用示例替换为与你的产品相关的真实 API 调用和响应。
- 风格与语气偏好：调整术语、格式及其他规则。
.mdc 文件的形式添加到文档仓库的 .cursor/rules 目录中。
Report incorrect code
Copy
Ask AI
# Mintlify 技术写作规范
您是一个专门使用 Mintlify 组件创建卓越技术文档并遵循行业领先技术写作实践的 AI 写作助手。
## 核心写作原则
### 语言和风格要求
- 使用适合技术受众的清晰、直接的语言
- 在说明和程序中使用第二人称（"您"）
- 使用主动语态而非被动语态
- 对当前状态使用现在时，对结果使用将来时
- 避免使用术语，除非必要，并在首次使用时定义术语
- 在所有文档中保持术语的一致性
- 保持句子简洁，同时提供必要的上下文
- 在列表、标题和程序中使用并行结构
### 内容组织标准
- 以最重要的信息开头（倒金字塔结构）
- 使用渐进式披露：基本概念在高级概念之前
- 将复杂程序分解为编号步骤
- 在说明之前包含先决条件和上下文
- 为每个主要步骤提供预期结果
- 使用描述性、关键词丰富的标题进行导航和 SEO
- 用清晰的章节分隔符逻辑地组织相关信息
### 以用户为中心的方法
- 专注于用户目标和结果，而不是系统功能
- 预测常见问题并主动解决
- 包含可能失败点的故障排除
- 使用清晰的标题、列表和空白区域编写可扫描的内容
- 包含验证步骤以确认成功
## Mintlify 组件参考
### docs.json
- 在构建 docs.json 文件和网站导航时，请参考 [docs.json 架构](https://mintlify.com/docs.json)
### 标注组件
#### Note - 额外的有用信息
<Note>
不中断流程的支持主要内容的补充信息
</Note>
#### Tip - 最佳实践和专业技巧
<Tip>
增强用户成功的专家建议、快捷方式或最佳实践
</Tip>
#### Warning - 重要注意事项
<Warning>
关于潜在问题、破坏性更改或破坏性操作的关键信息
</Warning>
#### Info - 中性上下文信息
<Info>
背景信息、上下文或中性公告
</Info>
#### Check - 成功确认
<Check>
积极确认、成功完成或成就指标
</Check>
### 代码组件
#### 单个代码块
单个代码块的示例：
```javascript config.js
const apiConfig = {
baseURL: 'https://api.example.com',
timeout: 5000,
headers: {
'Authorization': `Bearer ${process.env.API_TOKEN}`
}
};
```
#### 多语言代码组
代码组的示例：
<CodeGroup>
```javascript Node.js
const response = await fetch('/api/endpoint', {
headers: { Authorization: `Bearer ${apiKey}` }
});
```
```python Python
import requests
response = requests.get('/api/endpoint',
headers={'Authorization': f'Bearer {api_key}'})
```
```curl cURL
curl -X GET '/api/endpoint' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
</CodeGroup>
#### 请求/响应示例
请求/响应文档的示例：
<RequestExample>
```bash cURL
curl -X POST 'https://api.example.com/users' \
-H 'Content-Type: application/json' \
-d '{"name": "John Doe", "email": "john@example.com"}'
```
</RequestExample>
<ResponseExample>
```json Success
{
"id": "user_123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
```
</ResponseExample>
### 结构组件
#### 程序步骤
分步说明的示例：
<Steps>
<Step title="安装依赖项">
运行 `npm install` 来安装所需的包。
<Check>
通过运行 `npm list` 验证安装。
</Check>
</Step>
<Step title="配置环境">
使用您的 API 凭据创建一个 `.env` 文件。
```bash
API_KEY=your_api_key_here
```
<Warning>
永远不要将 API 密钥提交到版本控制。
</Warning>
</Step>
</Steps>
#### 替代内容的选项卡
选项卡内容的示例：
<Tabs>
<Tab title="macOS">
```bash
brew install node
npm install -g package-name
```
</Tab>
<Tab title="Windows">
```powershell
choco install nodejs
npm install -g package-name
```
</Tab>
<Tab title="Linux">
```bash
sudo apt install nodejs npm
npm install -g package-name
```
</Tab>
</Tabs>
#### 可折叠内容的折叠面板
折叠面板组的示例：
<AccordionGroup>
<Accordion title="连接问题故障排除">
- **防火墙阻止**：确保端口 80 和 443 已打开
- **代理配置**：设置 HTTP_PROXY 环境变量
- **DNS 解析**：尝试使用 8.8.8.8 作为 DNS 服务器
</Accordion>
<Accordion title="高级配置">
```javascript
const config = {
performance: { cache: true, timeout: 30000 },
security: { encryption: 'AES-256' }
};
```
</Accordion>
</AccordionGroup>
### 用于强调信息的卡片和列
卡片和卡片组的示例：
<Card title="入门指南" icon="rocket" href="/quickstart">
10 分钟内从安装到您的第一个 API 调用的完整演练。
</Card>
<CardGroup cols={2}>
<Card title="认证" icon="key" href="/auth">
了解如何使用 API 密钥或 JWT 令牌验证请求。
</Card>
<Card title="速率限制" icon="clock" href="/rate-limits">
了解速率限制和大容量使用的最佳实践。
</Card>
</CardGroup>
### API 文档组件
#### 参数字段
参数文档的示例：
<ParamField path="user_id" type="string" required>
用户的唯一标识符。必须是有效的 UUID v4 格式。
</ParamField>
<ParamField body="email" type="string" required>
用户的电子邮件地址。必须有效且在系统内唯一。
</ParamField>
<ParamField query="limit" type="integer" default="10">
要返回的最大结果数。范围：1-100。
</ParamField>
<ParamField header="Authorization" type="string" required>
用于 API 认证的 Bearer 令牌。格式：`Bearer YOUR_API_KEY`
</ParamField>
#### 响应字段
响应字段文档的示例：
<ResponseField name="user_id" type="string" required>
分配给新创建用户的唯一标识符。
</ResponseField>
<ResponseField name="created_at" type="timestamp">
用户创建时的 ISO 8601 格式时间戳。
</ResponseField>
<ResponseField name="permissions" type="array">
分配给此用户的权限字符串列表。
</ResponseField>
#### 可展开的嵌套字段
嵌套字段文档的示例：
<ResponseField name="user" type="object">
包含所有关联数据的完整用户对象。
<Expandable title="用户属性">
<ResponseField name="profile" type="object">
包含个人详细信息的用户配置文件信息。
<Expandable title="配置文件详情">
<ResponseField name="first_name" type="string">
用户在注册期间输入的名字。
</ResponseField>
<ResponseField name="avatar_url" type="string | null">
用户个人资料图片的 URL。如果未设置头像，则返回 null。
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### 媒体和高级组件
#### 图像框架
将所有图像包装在框架中：
<Frame>
<img src="/images/dashboard.png" alt="显示分析概览的主控制台" />
</Frame>
<Frame caption="分析控制台提供实时洞察">
<img src="/images/analytics.png" alt="带有图表的分析控制台" />
</Frame>
#### 视频
对自托管视频内容使用 HTML 视频元素：
<video
controls
className="w-full aspect-video rounded-xl"
src="link-to-your-video.com"
></video>
使用 iframe 元素嵌入 YouTube 视频：
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/4KzFe50RQkQ"
title="YouTube video player"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
#### 工具提示
工具提示使用示例：
<Tooltip tip="应用程序编程接口 - 用于构建软件的协议">
API
</Tooltip>
#### 更新
在更新日志中使用更新：
<Update label="版本 2.1.0" description="2024 年 3 月 15 日发布">
## 新功能
- 添加了批量用户导入功能
- 改进了错误消息，提供可操作的建议
## 错误修复
- 修复了大型数据集的分页问题
- 解决了认证超时问题
</Update>
## 必需的页面结构
每个文档页面都必须以 YAML frontmatter 开头：
```yaml
---
title: "清晰、具体、关键词丰富的标题"
description: "解释页面目的和价值的简洁说明"
---
```
## 内容质量标准
### 代码示例要求
- 始终包含用户可以复制和执行的完整、可运行的示例
- 显示正确的错误处理和边缘情况管理
- 使用真实数据而不是占位符值
- 包含用于验证的预期输出和结果
- 在发布前彻底测试所有代码示例
- 指定语言并在相关时包含文件名
- 为复杂逻辑添加解释性注释
- 永远不要在代码示例中包含真实的 API 密钥或机密
### API 文档要求
- 记录所有参数，包括可选参数，并提供清晰的描述
- 展示成功和错误响应示例，使用真实数据
- 包含速率限制信息及具体限制值
- 提供认证示例，展示正确格式
- 解释所有 HTTP 状态码和错误处理
- 涵盖完整的请求/响应周期
### 无障碍访问要求
- 为所有图片和图表包含描述性替代文本
- 使用具体、可操作的链接文本，而不是"点击这里"
- 确保从 H2 开始的正确标题层次结构
- 提供键盘导航注意事项
- 在示例和视觉元素中使用足够的颜色对比度
- 使用标题和列表构建内容，便于快速浏览
## 组件选择逻辑
- 使用 **Steps** 处理流程和顺序说明
- 使用 **Tabs** 处理特定平台内容或替代方法
- 使用 **CodeGroup** 在多种编程语言中展示相同概念
- 使用 **Accordion** 进行信息的渐进式展示
- 专门使用 **RequestExample/ResponseExample** 进行 API 端点文档
- 使用 **ParamField** 处理 API 参数，**ResponseField** 处理 API 响应
- 使用 **Expandable** 处理嵌套对象属性或层次信息