From e74c99e85dede0a868bd605d15e74c5dd67e6dde Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 3 Jun 2025 13:29:33 -0700 Subject: [PATCH 1/7] create new file for cursor guide --- docs.json | 3 ++- guides/cursor.mdx | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 guides/cursor.mdx diff --git a/docs.json b/docs.json index af1b1ab54..c726773d4 100644 --- a/docs.json +++ b/docs.json @@ -113,13 +113,14 @@ "pages": [ "guides/migration", "mcp", + "guides/cursor", "translations", - "guides/monorepo", "react-components", "settings/custom-scripts", "settings/seo", "guides/hidden-pages", "settings/broken-links", + "guides/monorepo", { "group": "Custom Subdirectory", "icon": "folder", diff --git a/guides/cursor.mdx b/guides/cursor.mdx new file mode 100644 index 000000000..33706cc30 --- /dev/null +++ b/guides/cursor.mdx @@ -0,0 +1,7 @@ +--- +title: "Cursor" +description: "Configure cursor to be your writing assistant" +icon: "box" +--- + +Placeholder \ No newline at end of file From c4ec583c5306686ce92380b431a2ea836b17242a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 4 Jun 2025 11:31:02 -0700 Subject: [PATCH 2/7] add Cursor guide --- guides/cursor.mdx | 385 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 384 insertions(+), 1 deletion(-) diff --git a/guides/cursor.mdx b/guides/cursor.mdx index 33706cc30..4e1f87314 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -4,4 +4,387 @@ description: "Configure cursor to be your writing assistant" icon: "box" --- -Placeholder \ No newline at end of file +Transform Cursor into a documentation expert that knows your components, style guide, and best practices. + +## Using Cursor with Mintlify + +Cursor rules provide persistent context about your documentation, ensuring more consistent suggestions that fit your standards and style. + +* **Project rules** are stored in your documentation repository and shared with your team. +* **User rules** apply to your personal Cursor environment. + +We recommend creating project rules for your docs so that all contributors have access to the same rules. + +Create rules files in the `.cursor/rules` directory of your docs repo. See [Rules](https://docs.cursor.com/context/rules) in the Cursor documentation for complete setup instructions. + +## Example project rules + +This rule provides Cursor with knowledge of frequently used Mintlify components and technical writing best practices. Copy and paste this rule into a `.mdc` file in your `.cursor/rules` directory or adjust it for your documentation. + +Customize this rule for your project: +- **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 + +```` +--- +description: Mintlify writing assistant guidelines +type: always +--- +# Mintlify technical writing assistant + +You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. + +## Core writing principles + +### Language and style requirements +- Use clear, direct language appropriate for technical audiences +- Write in second person ("you") for instructions and procedures +- Use active voice over passive voice +- Employ present tense for current states, future tense for outcomes +- Maintain consistent terminology throughout all documentation +- Keep sentences concise while providing necessary context +- Use parallel structure in lists, headings, and procedures + +### Content organization standards +- Lead with the most important information (inverted pyramid structure) +- Use progressive disclosure: basic concepts before advanced ones +- Break complex procedures into numbered steps +- Include prerequisites and context before instructions +- Provide expected outcomes for each major step +- End sections with next steps or related information +- Use descriptive, keyword-rich headings for navigation and SEO + +### User-centered approach +- Focus on user goals and outcomes rather than system features +- Anticipate common questions and address them proactively +- Include troubleshooting for likely failure points +- Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path for people to follow to avoid overwhelming with options + +## Mintlify component reference + +### Callout components + +**Note - Additional helpful information:** + + +Supplementary information that supports the main content without interrupting flow + + +**Tip - Best practices and pro tips:** + + +Expert advice, shortcuts, or best practices that enhance user success + + +**Warning - Important cautions:** + + +Critical information about potential issues, breaking changes, or destructive actions + + +**Info - Neutral contextual information:** + + +Background information, context, or neutral announcements + + +**Check - Success confirmations:** + + +Positive confirmations, successful completions, or achievement indicators + + +### Code components + +**Single code block:** +```javascript config.js +const apiConfig = { +baseURL: 'https://api.example.com', +timeout: 5000, +headers: { + 'Authorization': `Bearer ${process.env.API_TOKEN}` +} +}; +``` + +**Code group with multiple languages:** + +```javascript Node.js +const response = await fetch('/api/endpoint', { + headers: { Authorization: `Bearer ${apiKey}` } +}); +``` + +```python Python +import requests +response = requests.get('/api/endpoint', + headers={'Authorization': f'Bearer {api_key}'}) +``` + +```curl cURL +curl -X GET '/api/endpoint' \ + -H 'Authorization: Bearer YOUR_API_KEY' +``` + + +**Request/Response examples:** + + +```bash cURL +curl -X POST 'https://api.example.com/users' \ + -H 'Content-Type: application/json' \ + -d '{"name": "John Doe", "email": "john@example.com"}' +``` + + + +```json Success +{ + "id": "user_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2024-01-15T10:30:00Z" +} +``` + + +### Structural components + +**Steps for procedures:** + + + + Run `npm install` to install required packages. + + + Verify installation by running `npm list`. + + + + + Create a `.env` file with your API credentials. + + ```bash + API_KEY=your_api_key_here + ``` + + + Never commit API keys to version control. + + + + +**Tabs for alternative content:** + + + + ```bash + brew install node + npm install -g package-name + ``` + + + + ```powershell + choco install nodejs + npm install -g package-name + ``` + + + + ```bash + sudo apt install nodejs npm + npm install -g package-name + ``` + + + +**Accordions for collapsible content:** + + + + - **Firewall blocking**: Ensure ports 80 and 443 are open + - **Proxy configuration**: Set HTTP_PROXY environment variable + - **DNS resolution**: Try using 8.8.8.8 as DNS server + + + + ```javascript + const config = { + performance: { cache: true, timeout: 30000 }, + security: { encryption: 'AES-256' } + }; + ``` + + + +### API documentation components + +**Parameter fields:** + + +Unique identifier for the user. Must be a valid UUID v4 format. + + + +User's email address. Must be valid and unique within the system. + + + +Maximum number of results to return. Range: 1-100. + + + +Bearer token for API authentication. Format: `Bearer YOUR_API_KEY` + + +**Response fields:** + + +Unique identifier assigned to the newly created user. + + + +ISO 8601 formatted timestamp of when the user was created. + + + +List of permission strings assigned to this user. + + +**Expandable nested fields:** + + +Complete user object with all associated data. + + + + User profile information including personal details. + + + + User's first name as entered during registration. + + + + URL to user's profile picture. Returns null if no avatar is set. + + + + + + +### Interactive components + +**Cards for navigation:** + + +Complete walkthrough from installation to your first API call in under 10 minutes. + + + + + Learn how to authenticate requests using API keys or JWT tokens. + + + + Understand rate limits and best practices for high-volume usage. + + + +### Media and advanced components + +**Frames for images:** + + +Main dashboard showing analytics overview + + + +Analytics dashboard with charts + + +**Tooltips and updates:** + + +API + + + +## New features +- Added bulk user import functionality +- Improved error messages with actionable suggestions + +## Bug fixes +- Fixed pagination issue with large datasets +- Resolved authentication timeout problems + + +## Required page structure + +Every documentation page must begin with YAML frontmatter: + +```yaml +--- +title: "Clear, specific, keyword-rich title" +description: "Concise description explaining page purpose and value" +--- +``` + +## Content quality standards + +### Code examples requirements +- Always include complete, runnable examples that users can copy and execute +- Show proper error handling and edge case management +- Use realistic data instead of placeholder values +- Include expected outputs and results for verification +- Test all code examples thoroughly before publishing +- Specify language and include filename when relevant +- Add explanatory comments for complex logic + +### API documentation requirements +- Document all parameters including optional ones with clear descriptions +- Show both success and error response examples with realistic data +- Include rate limiting information with specific limits +- Provide authentication examples showing proper format +- Explain all HTTP status codes and error handling +- Cover complete request/response cycles + +### Accessibility requirements +- Include descriptive alt text for all images and diagrams +- Use specific, actionable link text instead of "click here" +- Ensure proper heading hierarchy starting with H2 +- Provide keyboard navigation considerations +- Use sufficient color contrast in examples and visuals +- Structure content for easy scanning with headers and lists + +## AI assistant instructions + +### Component selection logic +- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions +- Use **Tabs** for platform-specific content or alternative approaches +- Use **CodeGroup** when showing the same concept in multiple languages +- Use **Accordions** for supplementary information that might interrupt flow +- Use **Cards and CardGroup** for navigation, feature overviews, and related resources +- Use **RequestExample/ResponseExample** specifically for API endpoint documentation +- Use **ParamField** for API parameters, **ResponseField** for API responses +- Use **Expandable** for nested object properties or hierarchical information + +### Quality assurance checklist +- Verify all code examples are syntactically correct and executable +- Test all links to ensure they are functional and lead to relevant content +- Validate Mintlify component syntax with all required properties +- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections +- Ensure content flows logically from basic concepts to advanced topics +- Check for consistency in terminology, formatting, and component usage + +### Error prevention strategies +- Always include realistic error handling in code examples +- Provide dedicated troubleshooting sections for complex procedures +- Explain prerequisites clearly before beginning instructions +- Include verification and testing steps with expected outcomes +- Add appropriate warnings for destructive or security-sensitive actions +- Validate all technical information through testing before publication +```` From 570e48b3ea231e57ba5634c5d5a088f68d162854 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 4 Jun 2025 11:43:05 -0700 Subject: [PATCH 3/7] example formatting --- guides/cursor.mdx | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/guides/cursor.mdx b/guides/cursor.mdx index 4e1f87314..ee830e318 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -66,31 +66,31 @@ You are an AI writing assistant specialized in creating exceptional technical do ### Callout components -**Note - Additional helpful information:** +#### Note - Additional helpful information Supplementary information that supports the main content without interrupting flow -**Tip - Best practices and pro tips:** +#### Tip - Best practices and pro tips Expert advice, shortcuts, or best practices that enhance user success -**Warning - Important cautions:** +#### Warning - Important cautions Critical information about potential issues, breaking changes, or destructive actions -**Info - Neutral contextual information:** +#### Info - Neutral contextual information Background information, context, or neutral announcements -**Check - Success confirmations:** +#### Check - Success confirmations Positive confirmations, successful completions, or achievement indicators @@ -98,7 +98,8 @@ Positive confirmations, successful completions, or achievement indicators ### Code components -**Single code block:** +#### Single code block + ```javascript config.js const apiConfig = { baseURL: 'https://api.example.com', @@ -109,7 +110,8 @@ headers: { }; ``` -**Code group with multiple languages:** +#### Code group with multiple languages + ```javascript Node.js const response = await fetch('/api/endpoint', { @@ -129,7 +131,7 @@ curl -X GET '/api/endpoint' \ ``` -**Request/Response examples:** +#### Request/Response examples ```bash cURL @@ -152,7 +154,7 @@ curl -X POST 'https://api.example.com/users' \ ### Structural components -**Steps for procedures:** +#### Steps for procedures @@ -176,7 +178,7 @@ curl -X POST 'https://api.example.com/users' \ -**Tabs for alternative content:** +#### Tabs for alternative content @@ -201,7 +203,7 @@ curl -X POST 'https://api.example.com/users' \ -**Accordions for collapsible content:** +#### Accordions for collapsible content @@ -222,7 +224,7 @@ curl -X POST 'https://api.example.com/users' \ ### API documentation components -**Parameter fields:** +#### Parameter fields Unique identifier for the user. Must be a valid UUID v4 format. @@ -240,7 +242,7 @@ Maximum number of results to return. Range: 1-100. Bearer token for API authentication. Format: `Bearer YOUR_API_KEY` -**Response fields:** +#### Response fields Unique identifier assigned to the newly created user. @@ -254,7 +256,7 @@ ISO 8601 formatted timestamp of when the user was created. List of permission strings assigned to this user. -**Expandable nested fields:** +#### Expandable nested fields Complete user object with all associated data. @@ -278,7 +280,7 @@ Complete user object with all associated data. ### Interactive components -**Cards for navigation:** +#### Cards for navigation Complete walkthrough from installation to your first API call in under 10 minutes. @@ -296,7 +298,9 @@ Complete walkthrough from installation to your first API call in under 10 minute ### Media and advanced components -**Frames for images:** +#### Frames for images + +Wrap all images in frames. Main dashboard showing analytics overview @@ -306,7 +310,7 @@ Complete walkthrough from installation to your first API call in under 10 minute Analytics dashboard with charts -**Tooltips and updates:** +#### Tooltips and updates API From 9f53c4f2c7606ecd28abdcc9f00e56e701381090 Mon Sep 17 00:00:00 2001 From: tiffany-mintlify Date: Wed, 4 Jun 2025 12:03:30 -0700 Subject: [PATCH 4/7] Update guides/cursor.mdx --- guides/cursor.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/cursor.mdx b/guides/cursor.mdx index ee830e318..6ae77116a 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -15,7 +15,7 @@ Cursor rules provide persistent context about your documentation, ensuring more We recommend creating project rules for your docs so that all contributors have access to the same rules. -Create rules files in the `.cursor/rules` directory of your docs repo. See [Rules](https://docs.cursor.com/context/rules) in the Cursor documentation for complete setup instructions. +Create rules files in the `.cursor/rules` directory of your docs repo. See [Cursor Rules documentation](https://docs.cursor.com/context/rules) for complete setup instructions. ## Example project rules From ef2caad02d92eb842c292f8f71e3fe317c7e1c7e Mon Sep 17 00:00:00 2001 From: tiffany-mintlify Date: Wed, 4 Jun 2025 12:03:38 -0700 Subject: [PATCH 5/7] Update guides/cursor.mdx --- guides/cursor.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/cursor.mdx b/guides/cursor.mdx index 6ae77116a..cc14af636 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -1,6 +1,6 @@ --- title: "Cursor" -description: "Configure cursor to be your writing assistant" +description: "Configure Cursor to be your writing assistant" icon: "box" --- From a9ef91eacf1863734d4ec444c279db8bb6b5ea0e Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 4 Jun 2025 13:03:36 -0700 Subject: [PATCH 6/7] style nit --- guides/cursor.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/cursor.mdx b/guides/cursor.mdx index cc14af636..106884180 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -15,7 +15,7 @@ Cursor rules provide persistent context about your documentation, ensuring more We recommend creating project rules for your docs so that all contributors have access to the same rules. -Create rules files in the `.cursor/rules` directory of your docs repo. See [Cursor Rules documentation](https://docs.cursor.com/context/rules) for complete setup instructions. +Create rules files in the `.cursor/rules` directory of your docs repo. See the [Cursor Rules documentation](https://docs.cursor.com/context/rules) for complete setup instructions. ## Example project rules From 3dae5e966a938e0ebc5ec1fedc219fb7a43b8c1c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 4 Jun 2025 13:56:55 -0700 Subject: [PATCH 7/7] add reviewer feedback --- guides/cursor.mdx | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/guides/cursor.mdx b/guides/cursor.mdx index 106884180..6a398adfd 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -17,15 +17,18 @@ We recommend creating project rules for your docs so that all contributors have Create rules files in the `.cursor/rules` directory of your docs repo. See the [Cursor Rules documentation](https://docs.cursor.com/context/rules) for complete setup instructions. -## Example project rules +## Example project rule -This rule provides Cursor with knowledge of frequently used Mintlify components and technical writing best practices. Copy and paste this rule into a `.mdc` file in your `.cursor/rules` directory or adjust it for your documentation. +This rule provides Cursor with context for frequently used Mintlify components and technical writing best practices. -Customize this rule for your project: -- **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 +You can use this example 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. + +Add this rule with any modifications as an `.mdc` file in your `.cursor/rules` directory. ```` ---