Configure Windsurf’s Cascade AI assistant to help you write and maintain documentation with mint-tsdocs. This guide shows how to set up Windsurf to leverage your generated API reference and maintain documentation consistency.
Prerequisites
- Windsurf editor installed
- Access to your documentation repository
Why use Windsurf with mint-tsdocs?
Windsurf’s Cascade AI can help you:
- Navigate your API: Search through hundreds of generated API reference pages
- Write consistently: Match the style and structure of your existing documentation
- Link accurately: Get help finding correct paths to API reference pages
- Customize templates: Get context-aware assistance when modifying Liquid templates
Windsurf doesn’t currently support MCP integration like Claude Code and Cursor, but it can still access your documentation through its codebase indexing feature and by reading your local MDX files.
Workspace rules
Create workspace rules that provide Windsurf with context about your documentation project and standards.
Create .windsurf/rules.md in your project root:
# 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
### 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
Using your generated API reference
Once you’ve generated your API documentation with mint-tsdocs generate, Windsurf’s Cascade can help you navigate and use your reference pages through its codebase indexing:
Enable codebase indexing
Windsurf automatically indexes your documentation files. Ensure your docs/reference/ folder is included:
- Open Windsurf settings
- Verify that your docs folder is not excluded from indexing
- Let Windsurf complete the initial index
Quick lookups while editing
Ask Cascade about your API while writing documentation:
Cmd+L: Open Cascade
You: "What properties does ITemplateData have? Check the reference folder"
Cascade: [Reads from docs/reference/ and explains]
You: "Find the MarkdownDocumenter class reference and show me its constructor"
Cascade: [Opens the relevant MDX file]
Link completion
When writing MDX files, Cascade can help complete links:
See the [MarkdownDocumenter](/reference/...
You: "Complete this link to the MarkdownDocumenter reference page"
Cascade: /reference/mint-tsdocs.markdowndocumenter
Verify API references
Select text → Cmd+L
You: "Are all the API references in this paragraph correct? Check the reference folder"
Cascade: [Validates links against your generated reference pages]
Template development
When customizing Liquid templates:
You: "I'm editing class.liquid. What template variables are available? Search ITemplateData in the reference"
Cascade: [Finds the interface definition in your API reference]
Point Cascade to your docs/reference/ folder explicitly in queries for faster results: “Check the reference folder for…”
Common workflows
Learning mint-tsdocs
When getting started:
Cmd+L: Open Cascade
You: "Explain the ITemplateData interface from the reference folder"
You: "What's the difference between LiquidTemplateEngine and LiquidTemplateManager? Check the reference"
Writing documentation
When creating guides:
You: "I'm writing about template customization. What classes from the API should I link to?"
Cascade: [Suggests relevant classes from your reference folder]
You: "Add proper links to these API terms in my draft"
Cascade: [Inserts links to /reference/ pages]
Maintaining consistency
You: "Does this page follow the same frontmatter structure as my other guides?"
Cascade: [Checks your existing docs]
You: "Compare my quickstart to the installation guide. Are they consistent?"
Cascade: [Analyzes both files]
Troubleshooting
You: "Find all occurrences of 'TemplateManager' in my docs folder"
Cascade: [Searches across all MDX files]
You: "Check if there are any broken links to the reference folder"
Cascade: [Scans for invalid paths]
