-
-Use Cursor to help write and maintain your documentation. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components.Prerequisites
- Cursor editor installed
-- Access to your documentation repository
Project rules
Create project rules that all team members can use. In your documentation repository root:
`bash
-
mkdir -p .cursor
-`Create .cursor/rules.md:
``markdown
-
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 proceduresContent 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
-- Use descriptive, keyword-rich headings for navigation and SEO
-- Group related information logically with clear section breaksUser-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
-- Write for scannability with clear headings, lists, and white space
-- Include verification steps to confirm successMintlify 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
Example of a 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
Example of a code group:
-`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
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"}'
-`
-
-`json Success
-{
- "id": "user_123",
- "name": "John Doe",
- "email": "john@example.com",
- "created_at": "2024-01-15T10:30:00Z"
-}
-`
-
Structural components
#### Steps for procedures
Example of step-by-step instructions:
-
- 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
Example of tabbed 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
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
-
- `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.
-
-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
Example of response field documentation:
-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
Example of nested field documentation:
-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.
-
-
-
-
-Media and advanced components
#### Frames for images
Wrap all images in frames:
-
-
-
-#### Videos
Use the HTML video element for self-hosted video content:
- className="w-full aspect-video rounded-xl"
- src="link-to-your-video.com"
->Embed YouTube videos using iframe elements:
#### Tooltips
Example of tooltip usage:
-API
-
#### Updates
Use updates for changelogs:
-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
-- Never include real API keys or secrets in code examplesAPI 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 cyclesAccessibility 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 listsComponent selection logic
- 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 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
-``
-
- 
