跳转到主要内容
通过工作区规则和记忆，将 Windsurf 打造成一名深谙你的风格指南、组件和项目上下文的文档专家。

​
将 Windsurf 与 Mintlify 搭配使用

Windsurf 的 Cascade AI 助手可以结合 Mintlify 组件进行调优，使其按照你的规范撰写文档。工作区规则与记忆为你的项目提供持久化上下文，帮助 Cascade 输出更一致的建议。
  • 工作区规则 存放在你的文档代码库中，并与团队共享。
  • 记忆 提供随时间累积的个人上下文。
我们建议为共享的文档规范配置工作区规则。你可以在实际使用中逐步积累记忆，但由于记忆不共享，团队成员之间的一致性无法保证。 在你的文档代码库的 .windsurf/rules 目录中创建工作区规则。更多信息请参见 Windsurf 文档中的 Memories & Rules。

​
示例工作区规则

此规则为 Cascade 提供关于 Mintlify 组件及通用技术写作最佳实践的上下文。 你可以直接使用此示例规则，或根据你的文档进行定制：
  • 写作规范：更新语言指南，使其与您的风格指南一致。
  • 组件模式：添加项目特有的组件或修改现有示例。
  • 代码示例：用与您的产品相关的真实 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 端点的错误处理。使用贴近实际的数据，并包含预期的响应结果。
保持一致性：
换行
检查此新页面是否符合我们的文档标准，并提出必要的修改建议。