Cursor rule

1---
2globs:
3  - "**/*.md"
4---
5 
6# Documentation Standards
7 
8## Markdown Formatting
9 
10### Headings
11- Use ATX-style: `#`, `##`, etc.
12- Start with single `#` for title
13- Use hierarchical structure
14- Keep concise and descriptive
15 
16### Code Blocks
17Always specify language:
18 
19```markdown
20```python
21def hello_world():
22    print("Hello, World!")
23```
24 
25```typescript
26function greet(name: string): string {
27  return `Hello, ${name}!`;
28}
29```
30 
31```bash
32docker compose up -d
33```
34```
35 
36### Lists
37 
38Unordered:
39```markdown
40- First item
41- Second item
42  - Nested item
43- Third item
44```
45 
46Ordered:
47```markdown
481. First step
491. Second step
50   1. Sub-step
511. Third step
52```
53 
54### Links
55```markdown
56✅ Good:
57See the [Configuration Guide](docs/CONFIGURATION.md) for details.
58 
59❌ Bad:
60Click [here](docs/CONFIGURATION.md).
61```
62 
63### Emphasis
64- `**bold**` for strong emphasis or UI elements
65- `*italic*` for light emphasis
66- `` `code` `` for inline code, commands, file names
67 
68## Document Structure
69 
70### Project README
71Required sections:
721. Title and description
732. Key features
743. Quick start
754. Usage examples
765. Documentation links
776. Contributing
787. License
79 
80### Package README
81Required sections:
821. Package purpose
832. Installation
843. API/Usage
854. Configuration
865. Development setup
87 
88### Configuration Docs
89 
90Structure:
91```markdown
92# Configuration Guide
93 
94## Environment Variables
95 
96### `HERMES_SECRET_KEY`
97- **Type:** String
98- **Required:** Yes
99- **Description:** Secret key for JWT
100- **Example:** `openssl rand -base64 32`
101 
102### `LOG_LEVEL`
103- **Type:** String
104- **Required:** No
105- **Default:** `info`
106- **Options:** `debug`, `info`, `warning`, `error`
107```
108 
109### API Documentation
110 
111```markdown
112### `POST /api/v1/downloads`
113 
114Create a new download task.
115 
116**Authentication:** Required (Bearer token)
117 
118**Request:**
119```json
120{
121  "url": "https://example.com/video",
122  "profile_id": "default"
123}
124```
125 
126**Response:** `201 Created`
127```json
128{
129  "id": "abc123",
130  "status": "queued",
131  "created_at": "2024-01-01T00:00:00Z"
132}
133```
134 
135**Errors:**
136- `400` - Invalid URL
137- `401` - Invalid token
138- `429` - Rate limit exceeded
139```
140 
141## Code Examples
142 
143Keep examples:
144- Concise and focused
145- Include necessary imports
146- Show realistic use cases
147- Add comments for complex logic
148 
149```markdown
150### Creating a Download
151
152```python
153async def create_download(url: str, token: str):
154    """Create a new download task."""
155    async with httpx.AsyncClient() as client:
156        response = await client.post(
157            "http://localhost:8000/api/v1/downloads",
158            json={"url": url},
159            headers={"Authorization": f"Bearer {token}"}
160        )
161        return response.json()
162```
163```
164 
165## Tables
166 
167```markdown
168| Method | Endpoint | Description |
169|--------|----------|-------------|
170| GET | `/api/v1/downloads` | List downloads |
171| POST | `/api/v1/downloads` | Create download |
172| DELETE | `/api/v1/downloads/{id}` | Delete download |
173```
174 
175## Badges
176 
177```markdown
178![License](https://img.shields.io/badge/license-MIT-blue.svg)
179![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
180```
181 
182## Admonitions
183 
184```markdown
185> **Note:** This feature is experimental.
186 
187> **Warning:** Never commit `.env` files.
188 
189> **Tip:** Use `docker compose logs -f` for live logs.
190```
191 
192## Changelog
193 
194Follow [Keep a Changelog](https://keepachangelog.com/):
195 
196```markdown
197# Changelog
198 
199## [1.2.0] - 2024-01-15
200 
201### Added
202- Playlist download feature
203- Custom output formats
204 
205### Changed
206- Improved error handling
207 
208### Fixed
209- Memory leak in worker
210 
211### Deprecated
212- Legacy API endpoints
213```
214 
215## Documentation Maintenance
216 
217- Update docs with code changes
218- Review docs in PRs
219- Mark deprecated features
220- Remove outdated info
221 
222### Docstrings
223 
224Python (Google-style):
225```python
226def fetch_data(url: str, timeout: int = 30) -> dict:
227    """Fetch data from URL.
228    
229    Args:
230        url: The URL to fetch from
231        timeout: Request timeout in seconds
232        
233    Returns:
234        Dictionary containing response data
235        
236    Raises:
237        ValueError: If URL is invalid
238        TimeoutError: If request times out
239    """
240    pass
241```
242 
243TypeScript (JSDoc):
244```typescript
245/**
246 * Fetch data from URL
247 * 
248 * @param url - The URL to fetch from
249 * @param timeout - Request timeout in seconds
250 * @returns Promise resolving to response data
251 * @throws {Error} If URL is invalid
252 */
253async function fetchData(url: string, timeout: number = 30): Promise<Data> {
254  // ...
255}
256```
257 
258## Writing Style
259 
260### Guidelines
261- Use clear, simple language
262- Define acronyms on first use
263- Use active voice
264- Keep sentences concise
265- Use inclusive language
266 
267### Commands
268```markdown
269✅ Good:
270Run `docker compose up` to start services.
271 
272❌ Bad:
273You should probably run docker compose up.
274```
275 
276## Images
277 
278```markdown
279![Architecture diagram](./images/architecture.png)
280 
281*Figure 1: System architecture*
282```
283 
284- Store in `docs/images/` or `assets/`
285- Use descriptive file names
286- Optimize sizes
287- Provide alt text
288