> ## Documentation Index
> Fetch the complete documentation index at: https://mint-tsdocs.saulo.engineer/llms.txt
> Use this file to discover all available pages before exploring further.

# Windsurf setup

> Configure Windsurf for your documentation workflow

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

<Note>
  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.
</Note>

## Workspace rules

Create workspace rules that provide Windsurf with context about your documentation project and standards.

Create `.windsurf/rules.md` in your project root:

````markdown theme={null}
# 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:

1. Open Windsurf settings
2. Verify that your docs folder is not excluded from indexing
3. 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:

```markdown theme={null}
See the [MarkdownDocumenter](/reference/...
```

Then ask Cascade:

```
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]
```

<Tip>
  Point Cascade to your `docs/reference/` folder explicitly in queries for faster results: "Check the reference folder for..."
</Tip>

## 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]
```