Merge remote-tracking branch 'origin' into feat/n8n-wcc-docs

Author: protoss70

.cursor/rules/api-documentation.mdc

@@ -0,0 +1,21 @@
+---
+description: Standards for OpenAPI specifications and API code samples
+globs: ["apify-api/**/*.yaml", "apify-api/**/*.js"]
+alwaysApply: true
+---
+
+# API Documentation Rules
+
+## OpenAPI specifications
+
+- Follow **RESTful conventions** for endpoint design
+- Use **descriptive operation IDs** following camelCase
+- Include **comprehensive examples** for all endpoints
+- Provide **clear parameter descriptions**
+
+## Code samples
+
+- Include examples in **multiple languages** (JavaScript, Python, cURL)
+- Use **realistic data** in examples
+- Show **error handling** where appropriate
+- Include **authentication examples**

.cursor/rules/content-formatting.mdc

@@ -0,0 +1,58 @@
+---
+description: Content formatting standards for MDX files and code examples
+globs: ["sources/**/*.md", "sources/**/*.mdx"]
+alwaysApply: true
+---
+
+# Content Formatting Rules
+
+## Front matter (MDX files)
+
+```yaml
+---
+title: "Clear, action-oriented title"
+description: "140-160 character description that explains the value"
+sidebar_position: 1
+slug: /path/to/page
+---
+```
+
+## Text emphasis
+
+- **Bold** for UI elements, buttons, menu items
+- *Italics* for emphasis and new terms
+- `code` for inline code, file names, paths, variables
+- Use code blocks with language specification for examples
+
+## Admonitions
+
+Use admonitions to highlight important information:
+
+```markdown
+:::note Important information
+Your note content here.
+:::
+
+:::tip Pro tip
+Helpful tip for users.
+:::
+
+:::info Additional context
+Background information.
+:::
+
+:::caution Warning
+Something to be careful about.
+:::
+
+:::danger Critical
+Critical information that could cause issues.
+:::
+```
+
+## Code examples
+
+- Use **code tabs** for multiple language examples
+- Include **complete, runnable examples**
+- Add **comments** to explain complex code
+- Use **syntax highlighting** for all code blocks

.cursor/rules/documentation-style.mdc

@@ -0,0 +1,81 @@
+---
+description: Documentation style guidelines and writing standards for Apify docs
+globs: ["sources/**/*.md", "sources/**/*.mdx"]
+alwaysApply: true
+---
+
+# Documentation Style Guidelines
+
+## Project overview
+
+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.
+
+## Documentation structure
+
+- **Platform docs**: `/sources/platform/` - Core platform features and functionality
+- **Academy**: `/sources/academy/` - Educational content, tutorials, and courses
+- **API reference**: `/apify-api/` - Generated from OpenAPI specifications
+
+## Writing style & guidelines
+
+### Language & tone
+
+- Use **US English** spelling and grammar
+- Write in **inclusive language** - avoid gendered terms and assumptions
+- Use **active voice** whenever possible
+- Write for a **technical audience** but keep explanations clear and accessible
+- Avoid directional language (don't use "left/right")
+- Be **action-oriented** in descriptions and titles
+
+### Technical writing best practices
+
+- **Start with the user's goal** - what are they trying to accomplish?
+- **Use clear, concise sentences** - avoid unnecessary complexity
+- **Provide context** before diving into technical details
+- **Use consistent terminology** throughout the documentation
+- **Include examples** for complex concepts
+- **Structure content logically** - from basic to advanced concepts
+
+### Microsoft style guide compliance
+
+- Use **sentence case** for headings (except main titles)
+- Use **title case** for UI elements and proper nouns
+- **Bold** for UI elements, buttons, menu items
+- _Italics_ for emphasis and new terms
+- `code` for inline code, file names, and technical terms
+- Use **numbered lists** for sequential steps
+- Use **bullet points** for non-sequential items
+
+## Common patterns
+
+### Tutorial structure
+
+1. **Introduction** - What will the user learn?
+2. **Prerequisites** - What do they need to know/have?
+3. **Step-by-step instructions** - Clear, numbered steps
+4. **Code examples** - Complete, working examples
+5. **Summary** - What they accomplished and next steps
+
+### Troubleshooting sections
+
+- **Common issues** and solutions
+- **Error messages** and their meanings
+- **Debugging steps** for complex problems
+- **Contact information** for additional help
+
+## Accessibility guidelines
+
+- Use **descriptive link text** (avoid "click here")
+- Include **alt text** for all images
+- Use **proper heading hierarchy** (H1 → H2 → H3)
+- Write **clear, concise content**
+
+## SEO best practices
+
+- Use **descriptive page titles**
+- Include **relevant keywords** naturally
+- Write **meta descriptions** (140-160 characters)
+- Use **proper heading structure**
+- Include **internal links** to related content
+
+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

@@ -0,0 +1,27 @@
+---
+description: File naming conventions and directory structure standards
+globs: ["sources/**/*"]
+alwaysApply: true
+---
+
+# File Organization Rules
+
+## Naming conventions
+
+- Use **kebab-case** for file names: `web-scraping-basics.md`
+- Use **descriptive names** that reflect content
+- Group related files in **logical directories**
+
+## Directory structure
+
+```text
+sources/
+├── platform/          # Platform documentation
+│   ├── actors/        # Actor-related content
+│   ├── storage/       # Storage documentation
+│   └── integrations/  # Integration guides
+└── academy/           # Educational content
+    ├── tutorials/     # Step-by-step guides
+    ├── webscraping/   # Web scraping courses
+    └── glossary/      # Terminology and definitions
+```

.cursor/rules/quality-standards.mdc

@@ -0,0 +1,20 @@
+---
+description: Content quality checklist and review standards
+globs: ["sources/**/*.md", "sources/**/*.mdx"]
+alwaysApply: true
+---
+
+# Quality Standards
+
+## Content quality guidelines
+
+When creating or editing content, ensure:
+
+- [ ] Content follows Microsoft style guide (sentence case headings, proper emphasis)
+- [ ] Front matter includes proper title, description, and metadata
+- [ ] Code examples are complete and include proper syntax highlighting
+- [ ] All links use descriptive text (avoid "click here")
+- [ ] Images include meaningful alt text
+- [ ] Content uses inclusive language and active voice
+- [ ] Headings follow proper hierarchy (H1 → H2 → H3)
+- [ ] Content is clear, concise, and action-oriented

.github/styles/Apify/Capitalization.yml

@@ -3,18 +3,5 @@ message: "The word '%s' should always be capitalized."
 ignorecase: false
 level: error
 tokens:
-  # Before the word there should be no: /, -, #, word character
-  # (avoids anchors, URLs, identifiers, and words like 'factors')
-  #
-  # After the word there should be no: /, } (avoids paths or URLs)
-  # Also no . followed by a word character (avoids 'actors.md')
-  - '(?<![\/\-#\w])actors(?![\/\}])(?!\.\w)'
-
-  # Before the word there should be no: /, -, #, ., `, word character
-  # (avoids anchors, URLs, identifiers, code, and words like 'factors')
-  #
-  # After the word there should be no: /, }, -, word character (avoids paths or URLs)
-  # Also no " =" (avoids code like "actor = ...")
-  # Also no . followed by a word character (avoids 'actor.md' or 'actor.update()')
-  - '(?<![\/\-#\.`\w])actor(?![\/\}\-\w])(?! =)(?!\.\w)'
-nonword: false
+  - '\bactor\b'
+  - '\bactors\b'

.github/styles/Microsoft/Accessibility.yml

@@ -6,20 +6,25 @@ ignorecase: true
 tokens:
   - a victim of
   - able-bodied
-  - affected by
   - an epileptic
+  - birth defect
   - crippled
+  - differently abled
   - disabled
   - dumb
   - handicapped
   - handicaps
-  - healthy
+  - healthy person
+  - hearing-impaired
   - lame
   - maimed
+  - mentally handicapped
   - missing a limb
   - mute
-  - normal
+  - non-verbal
+  - normal person
   - sight-impaired
+  - slow learner
   - stricken with
   - suffers from
   - vision-impaired

.github/styles/Microsoft/Adverbs.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Consider removing '%s'."
+message: "Remove '%s' if it's not important to the meaning of the statement."
 link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences
 ignorecase: true
 level: warning
@@ -54,6 +54,7 @@ tokens:
   - doubtfully
   - dreamily
   - easily
+  - effectively
   - elegantly
   - energetically
   - enormously
@@ -164,6 +165,7 @@ tokens:
   - quickly
   - quietly
   - quirkily
+  - quite
   - quizzically
   - randomly
   - rapidly