Windsurf setup

Configure Windsurf for your documentation workflow

Set up Windsurf’s Cascade AI assistant to help you write and maintain your Mintlify documentation.

Prerequisites

• Windsurf editor installed

Setup

1. Open your docs directory in Windsurf

   Open the root of your documentation repository where docs.json is located.

2. Install the Mintlify skill

   In the integrated terminal, run:

   npx skills add https://mintlify.com/docs
   

   This gives Windsurf Mintlify’s component reference, writing standards, and workflow guidance.

3. Customize project instructions

   Edit AGENTS.md in your project root to add project-specific terminology, style preferences, and content boundaries.

4. Start writing with Cascade

   Open a file and use Cascade to draft and edit documentation.

Using Cascade with Mintlify

Cascade can understand your documentation structure and suggest consistent patterns across all your pages.

Cascade modes

Windsurf’s Cascade offers different modes for documentation work:

• Chat mode - Ask questions and get guidance
• Edit mode - Make direct changes to files
• Flow mode - Multi-step documentation tasks

Flow mode is particularly useful for creating multiple related pages or updating navigation structures.

Example workflows

Create a new section

"Create a new API reference section with pages for all REST endpoints"

Best practices

Project context

Make sure your AGENTS.md file includes:

• Product-specific terminology
• Preferred component usage patterns
• Content boundaries and what to avoid documenting

Cascade reads AGENTS.md automatically, so keeping it updated ensures consistent documentation quality.

Iterative refinement

Use Cascade iteratively:

1. Draft content with Cascade
2. Preview with mint dev
3. Refine based on preview
4. Ask Cascade to adjust specific sections

You can reference specific components or sections by highlighting them before invoking Cascade.