Write documentation with Windsurf

Transform Windsurf into a documentation expert that understands your style guide, components, and project context through workspace rules and memories.

Use Windsurf with Mintlify

Windsurf’s Cascade AI assistant can be tuned to write documentation according to your standards using Mintlify components. Workspace rules and memories provide persistent context about your project, ensuring more consistent suggestions from Cascade.

Workspace rules are stored in your documentation repository and shared with your team.
Memories provide individual context that builds up over time.

Set up workspace rules for shared documentation standards. You can develop memories as you work, but since they are not shared, they are not consistent across team members. Create workspace rules in the .windsurf/rules directory of your docs repo. See Memories & Rules in the Windsurf documentation for more information.

Example workspace rule

This rule provides Cascade with context about Mintlify components and general technical writing best practices. You can use this example rule as-is or customize it for your documentation:

Writing standards: Update language guidelines to match your style guide.
Component patterns: Add project-specific components or modify existing examples.
Code examples: Replace generic examples with real API calls and responses for your product.
Style and tone preferences: Adjust terminology, formatting, and other rules.

Save your rule as a .md file in the .windsurf/rules directory of your docs repo.

# Mintlify technical writing rule

## Project context

- This is a documentation project on the Mintlify platform
- We use MDX files with YAML frontmatter  
- Navigation is configured in `docs.json`
- We follow technical writing best practices

## Writing standards

- Use second person ("you") for instructions
- Write in active voice and present tense
- Start procedures with prerequisites
- Include expected outcomes for major steps
- Use descriptive, keyword-rich headings
- Keep sentences concise but informative

## Required page structure

Every page must start with frontmatter:

```yaml
---
title: "Clear, specific title"
description: "Concise description for SEO and navigation"
---
```

## Mintlify components

### docs.json

- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation

### Callouts

- `<Note>` for helpful supplementary information
- `<Warning>` for important cautions and breaking changes
- `<Tip>` for best practices and expert advice  
- `<Info>` for neutral contextual information
- `<Check>` for success confirmations

### Code examples

- When appropriate, include complete, runnable examples
- Use `<CodeGroup>` for multiple language examples
- Specify language tags on all code blocks
- Include realistic data, not placeholders
- Use `<RequestExample>` and `<ResponseExample>` for API docs

### Procedures

- Use `<Steps>` component for sequential instructions
- Include verification steps with `<Check>` components when relevant
- Break complex procedures into smaller steps

### Content organization

- Use `<Tabs>` for platform-specific content
- Use `<Accordion>` for progressive disclosure
- Use `<Card>` and `<CardGroup>` for highlighting content
- Wrap images in `<Frame>` components with descriptive alt text

## API documentation requirements

- Document all parameters with `<ParamField>` 
- Show response structure with `<ResponseField>`
- Include both success and error examples
- Use `<Expandable>` for nested object properties
- Always include authentication examples

## Quality standards

- Test all code examples before publishing
- Use relative paths for internal links
- Include alt text for all images
- Ensure proper heading hierarchy (start with h2)
- Check existing patterns for consistency

Working with Cascade

Once your rules are set up, you can use Cascade to assist with various documentation tasks. See Cascade in the Windsurf documentation for more information.

Example prompts

Writing new content:

Create a new page explaining how to authenticate with our API. Include code examples in JavaScript, Python, and cURL.

Improving existing content:

Review this page and suggest improvements for clarity and component usage. Focus on making the steps easier to follow.

Creating code examples:

Generate a complete code example showing error handling for this API endpoint. Use realistic data and include expected responses.

Maintaining consistency:

Check if this new page follows our documentation standards and suggest any needed changes.

Enhance with MCP server

Connect the Mintlify MCP server to Windsurf to give Cascade access to search the Mintlify documentation while helping you write. When you connect the MCP server, Cascade searches the up to date Mintlify documentation for context so you don’t have to leave your IDE to reference documentation. See Model Context Protocol for complete setup instructions.

Overview

AI

API docs

Best practices

Git

Use cases

Write documentation with Windsurf

Use Windsurf with Mintlify

Example workspace rule

Working with Cascade

Example prompts

Enhance with MCP server

​Use Windsurf with Mintlify

​Example workspace rule

​Working with Cascade

​Example prompts

​Enhance with MCP server

Use Windsurf with Mintlify

Example workspace rule

Working with Cascade

Example prompts

Enhance with MCP server