Skip to content

Commit 5a86054

Browse files
authored
New cursor rules (#477)
* chore: delete unused video asset * chore: add `.cursorignore` * feat: new cursor rules
1 parent 7a7226f commit 5a86054

13 files changed

+1208
-250
lines changed
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
description: Core documentation principles and writing standards
3+
globs:
4+
alwaysApply: true
5+
---
6+
7+
# Core Documentation Principles
8+
9+
Provide developers with documentation that is quick to read, easy to follow, and immediately actionable.
10+
11+
## Writing Style & Tone
12+
13+
| Guideline | Why it matters |
14+
|-----------|---------------|
15+
| **Active voice** | "Connect the SDK" is clearer than "The SDK should be connected." |
16+
| **Present tense** | Keeps instructions straightforward (e.g., "Run" not "You will run"). |
17+
| **Second‑person ("you")** | Speaks directly to the reader. Reserve "we" for collaborative tutorials. |
18+
| **Explain intent before action** | Briefly state *why* a step is needed, then show *how*. |
19+
| **Concrete examples over theory** | Code snippets and visuals anchor concepts. |
20+
| **Consistent terminology** | Define a term once; reuse it exactly the same everywhere. |
21+
| **Parallel structure** | Lists and headings should follow consistent grammatical patterns. |
22+
| **Descriptive link text** | Use "view the guide" rather than "click here." |
23+
| **Comment code sparsely** | Only where intent isn't obvious from variable/function names. |
24+
25+
> **Rule of thumb**: every sentence should either clarify *why* or *how*—if it does neither, remove or rewrite it.
26+
27+
## Style Rules
28+
29+
- **Tone**: Direct, professional, friendly
30+
- Break up large blocks of text with line‑breaks
31+
- Avoid marketing or promotional wording
32+
- Link to related pages when helpful, especially the **API reference** at `/fern/api-reference`
33+
- Use **bold** text to emphasize key names or concepts
34+
- **Titles**: Capitalize only the first word unless a proper noun is used
35+
- **Subtitles**: Begin with *Learn to …* for guides; otherwise keep them concise and factual
36+
- **Emojis / decorative icons**: Use only when essential for comprehension
Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
description: Fern documentation framework components and features
3+
globs:
4+
alwaysApply: true
5+
---
6+
7+
# Fern Components & Framework Features
8+
9+
Fern is our documentation framework. Use Fern-specific components and features for enhanced functionality.
10+
11+
## Code Blocks & Syntax Highlighting
12+
13+
### Multi-language Code Blocks with Tabs
14+
Use `<CodeBlocks>` for multiple language examples that automatically synchronize:
15+
16+
```mdx
17+
<CodeBlocks>
18+
```typescript title="TypeScript SDK"
19+
import { VapiClient } from "@vapi-ai/server-sdk";
20+
21+
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
22+
```
23+
```python title="Python SDK"
24+
from vapi import Vapi
25+
26+
client = Vapi(token=os.getenv("VAPI_API_KEY"))
27+
```
28+
```bash title="cURL"
29+
curl -X POST "https://api.vapi.ai/assistant" \
30+
-H "Authorization: Bearer $VAPI_API_KEY"
31+
```
32+
</CodeBlocks>
33+
```
34+
35+
### Code Block Features
36+
Enhance code blocks with these attributes:
37+
- `title="filename.ext"` - Add file title
38+
- `{2-4}` - Highlight specific lines
39+
- `focus` - Focus on specific lines
40+
- `maxLines=10` - Limit visible lines (default: 20)
41+
- `wordWrap` - Wrap long lines instead of scrolling
42+
43+
```mdx
44+
```typescript title="example.ts" {2-3} maxLines=15 wordWrap
45+
const config = {
46+
apiKey: process.env.VAPI_API_KEY, // highlighted
47+
timeout: 30000 // highlighted
48+
};
49+
```
50+
```
51+
52+
## Callouts & Alerts
53+
54+
Use semantic callouts to highlight important information:
55+
56+
```mdx
57+
<Tip>Helpful tips and best practices</Tip>
58+
<Note>Important information to remember</Note>
59+
<Warning>Cautions and potential issues</Warning>
60+
<Error>Critical errors and troubleshooting</Error>
61+
<Info>Additional context and explanations</Info>
62+
<Check>Success confirmations and completed tasks</Check>
63+
```
64+
65+
## Interactive Components
66+
67+
### Accordions for Collapsible Content
68+
Perfect for FAQs and optional details:
69+
70+
```mdx
71+
<AccordionGroup>
72+
<Accordion title="Common question">
73+
Detailed answer with searchable content (Cmd+F works even when collapsed)
74+
</Accordion>
75+
<Accordion title="Another question">
76+
More detailed explanations
77+
</Accordion>
78+
</AccordionGroup>
79+
```
80+
81+
### Tabs for Related Content
82+
Use for different approaches or languages:
83+
84+
```mdx
85+
<Tabs>
86+
<Tab title="Dashboard">
87+
Visual, no-code approach with screenshots
88+
</Tab>
89+
<Tab title="SDK">
90+
Programmatic implementation
91+
</Tab>
92+
</Tabs>
93+
```
94+
95+
### Steps for Sequential Processes
96+
Automatically numbered with anchor links:
97+
98+
```mdx
99+
<Steps>
100+
<Step title="Set up your account">
101+
Create your Vapi account and get your API key
102+
</Step>
103+
<Step title="Install the SDK">
104+
Install using your preferred package manager
105+
</Step>
106+
<Step title="Make your first call">
107+
Create your first assistant
108+
</Step>
109+
</Steps>
110+
```
111+
112+
## Cards & Navigation
113+
114+
### Individual Cards
115+
```mdx
116+
<Card title="Python SDK" icon="brands python" href="/docs/sdks/python">
117+
Get started with Vapi's Python SDK
118+
</Card>
119+
```
120+
121+
### Card Groups for Options
122+
```mdx
123+
<CardGroup cols={2}>
124+
<Card title="Quickstart" icon="rocket" href="/docs/quickstart">
125+
**Best for:** First-time users
126+
127+
Get up and running in 5 minutes
128+
</Card>
129+
<Card title="Advanced Setup" icon="cog" href="/docs/advanced">
130+
**Best for:** Production deployments
131+
132+
Configure advanced features
133+
</Card>
134+
</CardGroup>
135+
```
136+
137+
## Content Layout
138+
139+
### Aside for Sticky Content
140+
Push content to the right in a sticky container:
141+
142+
```mdx
143+
<Aside>
144+
<EndpointRequestSnippet endpoint='POST /assistant' />
145+
</Aside>
146+
```
147+
148+
### Frames for Images
149+
Wrap images in a styled container:
150+
151+
```mdx
152+
<Frame caption="Assistant configuration dashboard">
153+
<img src="/assets/images/dashboard.png" alt="Dashboard screenshot" />
154+
</Frame>
155+
```
156+
157+
## API Reference Components
158+
159+
### Endpoint Snippets
160+
Reference API endpoints directly:
161+
162+
```mdx
163+
<EndpointRequestSnippet endpoint='POST /assistant' />
164+
<EndpointResponseSnippet endpoint='POST /assistant' />
165+
<EndpointSchemaSnippet endpoint='POST /assistant' />
166+
```
167+
168+
### Parameter Documentation
169+
Use structured parameter tables:
170+
171+
```mdx
172+
<ParamField path="name" type="string" required>
173+
The name of your assistant
174+
</ParamField>
175+
<ParamField path="model" type="string" default="gpt-4">
176+
The LLM model to use
177+
</ParamField>
178+
```
179+
180+
## Advanced Features
181+
182+
### Embeds for Rich Media
183+
```mdx
184+
<Embed src="/assets/demo-video.mp4" />
185+
<Embed src="/assets/api-spec.pdf" />
186+
```
187+
188+
### Icons from Font Awesome
189+
```mdx
190+
<Icon icon="rocket" />
191+
<Icon icon="brands github" />
192+
```
193+
194+
### Tooltips for Contextual Help
195+
```mdx
196+
<Tooltip tip="Your API key from the dashboard">
197+
API Key
198+
</Tooltip>
199+
```
200+
201+
## Best Practices
202+
203+
### Component Selection
204+
- **CodeBlocks** - For multi-language examples that should sync
205+
- **Tabs** - For different approaches to the same task
206+
- **Steps** - For sequential procedures
207+
- **Cards** - For navigation and option selection
208+
- **Accordions** - For optional details and FAQs
209+
- **Callouts** - For important information that needs attention
210+
211+
### Content Organization
212+
- Use **Aside** for complementary content that shouldn't interrupt the main flow
213+
- Use **Frames** for important screenshots and diagrams
214+
- Use **CardGroups** to present multiple options clearly
215+
- Use **AccordionGroups** for comprehensive FAQ sections
216+
217+
### Accessibility & Search
218+
- All accordion content is searchable even when collapsed
219+
- Components are built with accessibility in mind
220+
- Proper semantic HTML is generated for SEO
221+
222+
---
223+
224+
**Framework Note:** Fern automatically handles syntax highlighting, responsive design, and search indexing for all components.

0 commit comments

Comments
 (0)