diff --git a/.cursor/rules/writing-standards.mdc b/.cursor/rules/writing-standards.mdc index 1b2cfd7e2..06720a90e 100644 --- a/.cursor/rules/writing-standards.mdc +++ b/.cursor/rules/writing-standards.mdc @@ -428,7 +428,7 @@ description: "Concise description explaining page purpose and value" - 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 +- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections. Do not use H1 (reserved for page title) - Ensure content flows logically from basic concepts to advanced topics - Check for consistency in terminology, formatting, and component usage - Include appropriate warnings for destructive or security-sensitive actions @@ -483,4 +483,30 @@ description: "Concise description explaining page purpose and value" - Regularly review and update outdated information - Remove deprecated features and references - Update screenshots when UI changes occur -- Maintain consistency across related documentation pages \ No newline at end of file +- Maintain consistency across related documentation pages + +## Request handling examples + +### When asked to "create a new page": +1. First, determine the appropriate location in the file structure +2. Create the file with proper frontmatter +3. Structure content using appropriate Mintlify components +4. Include relevant images and code examples + +### When asked to "improve existing content": +1. Review current structure and identify gaps +2. Suggest specific component improvements +3. Add missing callouts or examples +4. Ensure proper heading hierarchy + +## Component selection decision trees + +### For procedures: +- Use when: Sequential numbered instructions +- Use when: Platform-specific alternatives +- Use when: Optional supplementary info + +### For code examples: +- Use single ``` when: One language, simple example +- Use when: Same concept in multiple languages +- Use / when: API documentation \ No newline at end of file diff --git a/guides/cursor.mdx b/guides/cursor.mdx index 6a398adfd..7c8d6e689 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -19,7 +19,7 @@ Create rules files in the `.cursor/rules` directory of your docs repo. See the [ ## Example project rule -This rule provides Cursor with context for frequently used Mintlify components and technical writing best practices. +This rule provides Cursor with context to properly format Mintlify components and follow technical writing best practices. You can use this example as-is or customize it for your documentation: @@ -28,42 +28,43 @@ You can use this example as-is or customize it for your documentation: * **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. +Add this rule with any modifications as an `.mdc` file in the `.cursor/rules` directory of your docs repo. -```` ---- -description: Mintlify writing assistant guidelines -type: always ---- -# Mintlify technical writing assistant +````mdx wrap +# Mintlify technical writing rule 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 +- Avoid jargon unless necessary and define terms when first used - 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 +- Group related information logically with clear section breaks ### 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 +- Write for scannability with clear headings, lists, and white space +- Include verification steps to confirm success ## Mintlify component reference @@ -103,54 +104,60 @@ Positive confirmations, successful completions, or achievement indicators #### Single code block +Example of a single code block: + ```javascript config.js const apiConfig = { -baseURL: 'https://api.example.com', -timeout: 5000, -headers: { + baseURL: 'https://api.example.com', + timeout: 5000, + headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` -} + } }; ``` #### Code group with multiple languages +Example of a code group: + ```javascript Node.js const response = await fetch('/api/endpoint', { - headers: { Authorization: `Bearer ${apiKey}` } + headers: { Authorization: `Bearer ${apiKey}` } }); ``` ```python Python import requests response = requests.get('/api/endpoint', - headers={'Authorization': f'Bearer {api_key}'}) + headers={'Authorization': f'Bearer {api_key}'}) ``` ```curl cURL curl -X GET '/api/endpoint' \ - -H 'Authorization: Bearer YOUR_API_KEY' + -H 'Authorization: Bearer YOUR_API_KEY' ``` -#### Request/Response examples +#### Request/response examples + +Example of request/response documentation: ```bash cURL curl -X POST 'https://api.example.com/users' \ - -H 'Content-Type: application/json' \ - -d '{"name": "John Doe", "email": "john@example.com"}' + -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" + "id": "user_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2024-01-15T10:30:00Z" } ``` @@ -159,76 +166,102 @@ curl -X POST 'https://api.example.com/users' \ #### Steps for procedures +Example of step-by-step instructions: + - Run `npm install` to install required packages. - - - Verify installation by running `npm list`. - + 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. - + 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 +Example of tabbed content: + - ```bash - brew install node - npm install -g package-name - ``` + ```bash + brew install node + npm install -g package-name + ``` - ```powershell - choco install nodejs - 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 - ``` + ```bash + sudo apt install nodejs npm + npm install -g package-name + ``` #### Accordions for collapsible content +Example of accordion groups: + - - **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 + - **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 = { + ```javascript + const config = { performance: { cache: true, timeout: 30000 }, security: { encryption: 'AES-256' } - }; - ``` + }; + ``` +### Cards and columns for emphasizing information + +Example of cards and card groups: + + +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. + + + ### API documentation components #### Parameter fields +Example of parameter documentation: + Unique identifier for the user. Must be a valid UUID v4 format. @@ -247,6 +280,8 @@ Bearer token for API authentication. Format: `Bearer YOUR_API_KEY` #### Response fields +Example of response field documentation: + Unique identifier assigned to the newly created user. @@ -261,49 +296,33 @@ List of permission strings assigned to this user. #### Expandable nested fields +Example of nested field documentation: + Complete user object with all associated data. - - User profile information including personal details. + + User profile information including personal details. + + + + User's first name as entered during registration. + - - - User's first name as entered during registration. - - - - URL to user's profile picture. Returns null if no avatar is set. - - + + 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 -Wrap all images in frames. +Wrap all images in frames: Main dashboard showing analytics overview @@ -313,12 +332,39 @@ Wrap all images in frames. Analytics dashboard with charts -#### Tooltips and updates +#### Videos + +Use the HTML video element for self-hosted video content: + + + +Embed YouTube videos using iframe elements: + + + +#### Tooltips + +Example of tooltip usage: API +#### Updates + +Use updates for changelogs: + ## New features - Added bulk user import functionality @@ -343,6 +389,7 @@ 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 @@ -350,8 +397,10 @@ description: "Concise description explaining page purpose and value" - Test all code examples thoroughly before publishing - Specify language and include filename when relevant - Add explanatory comments for complex logic +- Never include real API keys or secrets in code examples ### 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 @@ -360,6 +409,7 @@ description: "Concise description explaining page purpose and value" - 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 @@ -367,31 +417,13 @@ description: "Concise description explaining page purpose and value" - Use sufficient color contrast in examples and visuals - Structure content for easy scanning with headers and lists -## AI assistant instructions +## Component selection logic -### Component selection logic -- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions +- Use **Steps** for procedures 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 **CodeGroup** when showing the same concept in multiple programming languages +- Use **Accordions** for progressive disclosure of information - 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 ````