Windsurf

将 Windsurf 配置为你的写作助手

通过工作区规则和记忆，将 Windsurf 打造成了解你风格指南、组件和项目 context 的文档专家。

​

将 Windsurf 与 Mintlify 配合使用

Windsurf 的 Cascade AI 助手可以配合 Mintlify 组件，按照你的规范撰写文档。Workspace 规则和记忆为你的项目提供持久的 context，确保 Cascade 提供的建议更加一致。

• Workspace 规则 存储在你的文档存储库中，并与团队共享。
• Memories（记忆） 提供会随时间累积的个人 context。

我们建议为共享的文档规范设置 Workspace 规则。你可以在工作中逐步积累记忆，但由于它们不共享，团队成员之间的体验将不一致。

在文档存储库的 .windsurf/rules 目录中创建 Workspace 规则。更多信息请参阅 Windsurf 文档中的 Memories & Rules。

​

示例工作区规则

此规则为 Cascade 提供关于 Mintlify 组件以及通用技术写作最佳实践的 context。

你可以直接使用此示例规则，或根据你的文档需求进行自定义：

• 写作标准：更新语言规范以符合你的风格指南。
• 组件模式：添加与你的项目相关的组件，或修改现有示例。
• 代码示例：将通用示例替换为与你的产品相关的真实 API 调用和响应。
• 风格与语气偏好：调整术语、格式和其他规则。

将你的规则保存为 .md 文件，放在文档仓库的 .windsurf/rules 目录中。

# Mintlify 技术写作规范

## 项目背景

- 这是一个基于 Mintlify 平台的文档项目
- 我们使用带有 YAML frontmatter 的 MDX 文件  
- 导航在 `docs.json` 中配置
- 我们遵循技术写作最佳实践

## 写作标准

- 使用第二人称（"你"）来编写说明
- 使用主动语态和现在时
- 操作步骤开始前先列出前提条件
- 为主要步骤提供预期结果
- 使用描述性、关键词丰富的标题
- 保持句子简洁但信息丰富

## 必需的页面结构

每个页面都必须以 frontmatter 开始：

```yaml
---
title: "清晰、具体的标题"
description: "用于 SEO 和导航的简洁说明"
---
```

## Mintlify 组件

### docs.json

- 在构建 docs.json 文件和网站导航时，请参考 [docs.json 架构](https://mintlify.com/docs.json)

### 标注

- `<Note>` 用于有用的补充信息
- `<Warning>` 用于重要警告和破坏性更改
- `<Tip>` 用于最佳实践和专家建议  
- `<Info>` 用于中性的上下文信息
- `<Check>` 用于成功确认

### 代码示例

- 在适当的时候，包含完整的、可运行的示例
- 使用 `<CodeGroup>` 进行多语言示例
- 在所有代码块上指定语言标签
- 包含真实数据，而不是占位符
- 对于 API 文档使用 `<RequestExample>` 和 `<ResponseExample>`

### 操作步骤

- 使用 `<Steps>` 组件进行顺序说明
- 在相关时包含带有 `<Check>` 组件的验证步骤
- 将复杂操作分解为更小的步骤

### 内容组织

- 使用 `<Tabs>` 进行平台特定内容
- 使用 `<Accordion>` 进行渐进式展示
- 使用 `<Card>` 和 `<CardGroup>` 突出显示内容
- 将图像包装在带有描述性替代文本的 `<Frame>` 组件中

## API 文档要求

- 使用 `<ParamField>` 记录所有参数 
- 使用 `<ResponseField>` 显示响应结构
- 包含成功和错误示例
- 对嵌套对象属性使用 `<Expandable>`
- 始终包含认证示例

## 质量标准

- 在发布前测试所有代码示例
- 对内部链接使用相对路径
- 为所有图像包含替代文本
- 确保正确的标题层次结构（从 h2 开始）
- 检查现有模式的一致性

​

使用 Cascade

设置好规则后，你可以使用 Cascade 来协助处理各类文档任务。更多信息请参阅 Windsurf 文档中的 Cascade。

​

示例提示

撰写新内容：

创建一个新页面，说明如何通过我们的 API 进行身份验证。包含 JavaScript、Python 和 cURL 的代码示例。

改进现有对象:

审查此页面并建议改进清晰度和组件使用方式。重点让步骤更易于理解和执行。

创建代码示例：

生成一个完整的代码示例，展示此 API 端点的错误处理。使用真实数据并包含预期响应。

保持一致：

检查此新页面是否符合我们的文档标准，并提出必要的修改建议。