Skip to content

Commit a7f1270

Browse files
TC-MOTC-MO
authored
docs: add cursor rules (#1791)
1 parent a4bf9c7 commit a7f1270

File tree

5 files changed

+207
-0
lines changed

5 files changed

+207
-0
lines changed

‎.cursor/rules/api-documentation.mdc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
description: Standards for OpenAPI specifications and API code samples
3+
globs: ["apify-api/**/*.yaml", "apify-api/**/*.js"]
4+
alwaysApply: true
5+
---
6+
7+
# API Documentation Rules
8+
9+
## OpenAPI specifications
10+
11+
- Follow **RESTful conventions** for endpoint design
12+
- Use **descriptive operation IDs** following camelCase
13+
- Include **comprehensive examples** for all endpoints
14+
- Provide **clear parameter descriptions**
15+
16+
## Code samples
17+
18+
- Include examples in **multiple languages** (JavaScript, Python, cURL)
19+
- Use **realistic data** in examples
20+
- Show **error handling** where appropriate
21+
- Include **authentication examples**

‎.cursor/rules/content-formatting.mdc‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
description: Content formatting standards for MDX files and code examples
3+
globs: ["sources/**/*.md", "sources/**/*.mdx"]
4+
alwaysApply: true
5+
---
6+
7+
# Content Formatting Rules
8+
9+
## Front matter (MDX files)
10+
11+
```yaml
12+
---
13+
title: "Clear, action-oriented title"
14+
description: "140-160 character description that explains the value"
15+
sidebar_position: 1
16+
slug: /path/to/page
17+
---
18+
```
19+
20+
## Text emphasis
21+
22+
- **Bold** for UI elements, buttons, menu items
23+
- *Italics* for emphasis and new terms
24+
- `code` for inline code, file names, paths, variables
25+
- Use code blocks with language specification for examples
26+
27+
## Admonitions
28+
29+
Use admonitions to highlight important information:
30+
31+
```markdown
32+
:::note Important information
33+
Your note content here.
34+
:::
35+
36+
:::tip Pro tip
37+
Helpful tip for users.
38+
:::
39+
40+
:::info Additional context
41+
Background information.
42+
:::
43+
44+
:::caution Warning
45+
Something to be careful about.
46+
:::
47+
48+
:::danger Critical
49+
Critical information that could cause issues.
50+
:::
51+
```
52+
53+
## Code examples
54+
55+
- Use **code tabs** for multiple language examples
56+
- Include **complete, runnable examples**
57+
- Add **comments** to explain complex code
58+
- Use **syntax highlighting** for all code blocks

‎.cursor/rules/documentation-style.mdc‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
description: Documentation style guidelines and writing standards for Apify docs
3+
globs: ["sources/**/*.md", "sources/**/*.mdx"]
4+
alwaysApply: true
5+
---
6+
7+
# Documentation Style Guidelines
8+
9+
## Project overview
10+
11+
This is the Apify documentation repository containing platform documentation, academy content, and API reference. The project uses Docusaurus with MDX, OpenAPI specifications, and follows Microsoft style guide principles.
12+
13+
## Documentation structure
14+
15+
- **Platform docs**: `/sources/platform/` - Core platform features and functionality
16+
- **Academy**: `/sources/academy/` - Educational content, tutorials, and courses
17+
- **API reference**: `/apify-api/` - Generated from OpenAPI specifications
18+
19+
## Writing style & guidelines
20+
21+
### Language & tone
22+
23+
- Use **US English** spelling and grammar
24+
- Write in **inclusive language** - avoid gendered terms and assumptions
25+
- Use **active voice** whenever possible
26+
- Write for a **technical audience** but keep explanations clear and accessible
27+
- Avoid directional language (don't use "left/right")
28+
- Be **action-oriented** in descriptions and titles
29+
30+
### Technical writing best practices
31+
32+
- **Start with the user's goal** - what are they trying to accomplish?
33+
- **Use clear, concise sentences** - avoid unnecessary complexity
34+
- **Provide context** before diving into technical details
35+
- **Use consistent terminology** throughout the documentation
36+
- **Include examples** for complex concepts
37+
- **Structure content logically** - from basic to advanced concepts
38+
39+
### Microsoft style guide compliance
40+
41+
- Use **sentence case** for headings (except main titles)
42+
- Use **title case** for UI elements and proper nouns
43+
- **Bold** for UI elements, buttons, menu items
44+
- _Italics_ for emphasis and new terms
45+
- `code` for inline code, file names, and technical terms
46+
- Use **numbered lists** for sequential steps
47+
- Use **bullet points** for non-sequential items
48+
49+
## Common patterns
50+
51+
### Tutorial structure
52+
53+
1. **Introduction** - What will the user learn?
54+
2. **Prerequisites** - What do they need to know/have?
55+
3. **Step-by-step instructions** - Clear, numbered steps
56+
4. **Code examples** - Complete, working examples
57+
5. **Summary** - What they accomplished and next steps
58+
59+
### Troubleshooting sections
60+
61+
- **Common issues** and solutions
62+
- **Error messages** and their meanings
63+
- **Debugging steps** for complex problems
64+
- **Contact information** for additional help
65+
66+
## Accessibility guidelines
67+
68+
- Use **descriptive link text** (avoid "click here")
69+
- Include **alt text** for all images
70+
- Use **proper heading hierarchy** (H1 → H2 → H3)
71+
- Write **clear, concise content**
72+
73+
## SEO best practices
74+
75+
- Use **descriptive page titles**
76+
- Include **relevant keywords** naturally
77+
- Write **meta descriptions** (140-160 characters)
78+
- Use **proper heading structure**
79+
- Include **internal links** to related content
80+
81+
Remember: The goal is to help users succeed with Apify. Every piece of documentation should serve that purpose by being clear, accurate, and actionable.

‎.cursor/rules/file-organization.mdc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: File naming conventions and directory structure standards
3+
globs: ["sources/**/*"]
4+
alwaysApply: true
5+
---
6+
7+
# File Organization Rules
8+
9+
## Naming conventions
10+
11+
- Use **kebab-case** for file names: `web-scraping-basics.md`
12+
- Use **descriptive names** that reflect content
13+
- Group related files in **logical directories**
14+
15+
## Directory structure
16+
17+
```text
18+
sources/
19+
├── platform/ # Platform documentation
20+
│ ├── actors/ # Actor-related content
21+
│ ├── storage/ # Storage documentation
22+
│ └── integrations/ # Integration guides
23+
└── academy/ # Educational content
24+
├── tutorials/ # Step-by-step guides
25+
├── webscraping/ # Web scraping courses
26+
└── glossary/ # Terminology and definitions
27+
```

‎.cursor/rules/quality-standards.mdc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
description: Content quality checklist and review standards
3+
globs: ["sources/**/*.md", "sources/**/*.mdx"]
4+
alwaysApply: true
5+
---
6+
7+
# Quality Standards
8+
9+
## Content quality guidelines
10+
11+
When creating or editing content, ensure:
12+
13+
- [ ] Content follows Microsoft style guide (sentence case headings, proper emphasis)
14+
- [ ] Front matter includes proper title, description, and metadata
15+
- [ ] Code examples are complete and include proper syntax highlighting
16+
- [ ] All links use descriptive text (avoid "click here")
17+
- [ ] Images include meaningful alt text
18+
- [ ] Content uses inclusive language and active voice
19+
- [ ] Headings follow proper hierarchy (H1 → H2 → H3)
20+
- [ ] Content is clear, concise, and action-oriented

0 commit comments

Comments
 (0)