From cf483ac4e72c2426729de46eaf49ecb42092ff93 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 9 Jul 2025 16:35:31 -0700 Subject: [PATCH 1/4] add windsurf guide to nav --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 9f5bd19f2..051633aec 100644 --- a/docs.json +++ b/docs.json @@ -112,6 +112,7 @@ "mcp", "guides/claude-code", "guides/cursor", + "guides/windsurf", "translations", "react-components", "settings/custom-scripts", From 19021b584e41a7c28e7ad069960632e81fa36702 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 10 Jul 2025 10:21:25 -0700 Subject: [PATCH 2/4] add windsurf guide --- guides/windsurf.mdx | 142 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 guides/windsurf.mdx diff --git a/guides/windsurf.mdx b/guides/windsurf.mdx new file mode 100644 index 000000000..a17610474 --- /dev/null +++ b/guides/windsurf.mdx @@ -0,0 +1,142 @@ +--- +title: "Windsurf" +description: "Configure Windsurf to be your writing assistant" +icon: "waves" +--- + +Transform Windsurf into a documentation expert that understands your style guide, components, and project context through workspace rules and memories. + +## Using 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. + +We recommend setting up workspace rules for shared documentation standards. You can develop memories as you work, but since they are not shared, they will not be consistent across team members. + +Create workspace rules in the `.windsurf/rules` directory of your docs repo. See [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) 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. + +````mdx +# 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 + +- `` for helpful supplementary information +- `` for important cautions and breaking changes +- `` for best practices and expert advice +- `` for neutral contextual information +- `` for success confirmations + +### Code examples + +- When appropriate, include complete, runnable examples +- Use `` for multiple language examples +- Specify language tags on all code blocks +- Include realistic data, not placeholders +- Use `` and `` for API docs + +### Procedures + +- Use `` component for sequential instructions +- Include verification steps with `` components when relevant +- Break complex procedures into smaller steps + +### Content organization + +- Use `` for platform-specific content +- Use `` for progressive disclosure +- Use `` and `` for highlighting content +- Wrap images in `` components with descriptive alt text + +## API documentation requirements + +- Document all parameters with `` +- Show response structure with `` +- Include both success and error examples +- Use `` 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](https://docs.windsurf.com/windsurf/cascade) in the Windsurf documentation for more information. + +### Example prompts + + + + +```text wrap +Create a new page explaining how to authenticate with our API. Include code examples in JavaScript, Python, and cURL. +``` + + + +```text wrap +Review this page and suggest improvements for clarity and component usage. Focus on making the steps easier to follow. +``` + + + +```text wrap +Generate a complete code example showing error handling for this API endpoint. Use realistic data and include expected responses. +``` + + + +```text wrap +Check if this new page follows our documentation standards and suggest any needed changes. +``` + + \ No newline at end of file From 1962c7ea53c4e4478a9047b35694370f88e5a9e4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 10 Jul 2025 11:01:56 -0700 Subject: [PATCH 3/4] remove cards --- guides/windsurf.mdx | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/guides/windsurf.mdx b/guides/windsurf.mdx index a17610474..c773842da 100644 --- a/guides/windsurf.mdx +++ b/guides/windsurf.mdx @@ -114,29 +114,22 @@ Once your rules are set up, you can use Cascade to assist with various documenta ### Example prompts - - - +**Writing new content**: ```text wrap Create a new page explaining how to authenticate with our API. Include code examples in JavaScript, Python, and cURL. ``` - - +**Improving existing content**: ```text wrap Review this page and suggest improvements for clarity and component usage. Focus on making the steps easier to follow. ``` - - +**Creating code examples**: ```text wrap Generate a complete code example showing error handling for this API endpoint. Use realistic data and include expected responses. ``` - - +**Maintaining consistency** ```text wrap Check if this new page follows our documentation standards and suggest any needed changes. -``` - - \ No newline at end of file +``` \ No newline at end of file From ca62497eb7fb0f0d10f8a990937ae27f8fbd521b Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 10 Jul 2025 11:03:32 -0700 Subject: [PATCH 4/4] add `:` --- guides/windsurf.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/windsurf.mdx b/guides/windsurf.mdx index c773842da..3bdbb65e7 100644 --- a/guides/windsurf.mdx +++ b/guides/windsurf.mdx @@ -129,7 +129,7 @@ Review this page and suggest improvements for clarity and component usage. Focus Generate a complete code example showing error handling for this API endpoint. Use realistic data and include expected responses. ``` -**Maintaining consistency** +**Maintaining consistency**: ```text wrap Check if this new page follows our documentation standards and suggest any needed changes. ``` \ No newline at end of file