Merge branch 'master' into master

Author: jancurn

.cursor/rules/api-documentation.mdc

@@ -0,0 +1,62 @@
+---
+description: Cursor-specific rules for OpenAPI specifications and API documentation
+globs: ["apify-api/**/*.yaml", "apify-api/**/*.js"]
+alwaysApply: true
+---
+
+# Cursor-Specific API Documentation Rules
+
+## Cursor OpenAPI Workflow
+
+### Using Cursor for OpenAPI Editing
+
+- Leverage Cursor's YAML syntax highlighting for OpenAPI files
+- Use Cursor's JSON schema validation for OpenAPI specifications
+- Use Cursor's autocomplete for OpenAPI keywords and properties
+
+### Cursor-Specific API Documentation Tasks
+
+- Use Cursor Chat to "validate this OpenAPI specification"
+- Ask "generate code examples for this endpoint"
+- Request "check for consistency across similar endpoints"
+
+## Cursor Code Sample Generation
+
+### Using Cmd+K for API References
+
+- Use `@apify-api/openapi/paths/**/*.yaml` to reference endpoint definitions
+- Use `@apify-api/openapi/components/schemas/**/*.yaml` to reference data models
+- Use `@AGENTS.md` to reference API documentation standards
+
+### Cursor-Specific Code Sample Workflow
+
+```yaml
+# When editing OpenAPI files in Cursor:
+# 1. Use Cursor's YAML validation
+# 2. Leverage autocomplete for OpenAPI keywords
+# 3. Use Cursor Chat to generate examples
+# 4. Use Cursor's search to find similar patterns
+```
+
+## File-Specific Cursor Rules
+
+### For OpenAPI Specification Files (`apify-api/openapi/**/*.yaml`)
+
+- Use Cursor's YAML syntax highlighting and validation
+- Leverage Cursor's autocomplete for OpenAPI 3.0 keywords
+- Use Cursor's search to find similar endpoint patterns
+- Use Cursor Chat to validate OpenAPI compliance
+
+### For Generated Code Samples (`apify-api/openapi/code_samples/**/*.js`)
+
+- Use Cursor's JavaScript syntax highlighting
+- Leverage Cursor's autocomplete for JavaScript APIs
+- Use Cursor's search to find similar code patterns
+- Use Cursor Chat to improve code examples
+
+## Cursor Quality Assurance for APIs
+
+- Use Cursor's YAML validation for OpenAPI files
+- Leverage Cursor's search to ensure endpoint naming consistency
+- Use Cursor Chat to review API documentation completeness
+- Use Cursor's autocomplete to maintain OpenAPI specification standards

.cursor/rules/content-formatting.mdc

@@ -0,0 +1,82 @@
+---
+description: Cursor-specific content formatting rules for MDX and markdown files
+globs: ["sources/**/*.md", "sources/**/*.mdx"]
+alwaysApply: true
+---
+
+# Cursor-Specific Content Formatting
+
+## Cursor MDX/Markdown Features
+
+### Syntax Highlighting in Cursor
+
+- Use language-specific code blocks for proper syntax highlighting
+- Leverage Cursor's MDX component autocomplete
+- Use Cursor's markdown preview for real-time formatting verification
+
+### Cursor-Specific Code Block Handling
+
+```markdown
+# For JavaScript examples
+```javascript
+// Cursor will provide syntax highlighting and autocomplete
+const example = "properly formatted";
+```
+
+# For YAML frontmatter
+
+```yaml
+---
+title: "Example"
+description: "Description"
+---
+```
+
+# For API examples
+
+```bash
+curl -X GET "https://api.apify.com/v2/acts"
+```
+
+
+## Cursor Workflow for Formatting
+
+### Using Cursor Chat for Formatting Help
+
+- Ask "format this markdown table properly"
+- Request "add syntax highlighting to this code block"
+- Use "check this frontmatter for proper YAML syntax"
+
+### Using Cmd+K for Quick Formatting
+
+- Use `@` to reference formatting standards
+- Use `@sources/**/*.mdx` to find similar MDX patterns
+- Use `@apify-api/**/*.yaml` to reference API examples
+
+## Cursor-Specific Admonition Handling
+
+When using admonitions in Cursor:
+
+```markdown
+:::note Cursor Tip
+Use Cursor's markdown preview to verify admonition formatting
+:::
+
+:::tip Cursor Feature
+Leverage Cursor's autocomplete for consistent admonition syntax
+:::
+```
+
+## File-Specific Formatting Rules
+
+### For MDX Files (`sources/**/*.mdx`)
+
+- Use Cursor's MDX syntax highlighting
+- Leverage component imports with proper TypeScript support
+- Use Cursor's JSX autocomplete for custom components
+
+### For Markdown Files (`sources/**/*.md`)
+
+- Use Cursor's markdown preview for formatting verification
+- Leverage Cursor's spell check for content quality
+- Use Cursor's link validation for internal references

.cursor/rules/documentation-style.mdc

@@ -0,0 +1,55 @@
+---
+description: Cursor-specific documentation style rules for Apify docs
+globs: ["sources/**/*.md", "sources/**/*.mdx"]
+alwaysApply: true
+---
+
+# Cursor-Specific Documentation Rules
+
+## Context-Aware Writing
+
+When editing documentation in Cursor, consider the broader context:
+
+- **Cross-references**: When mentioning other pages, use Cursor's file navigation to verify links
+- **Consistency checks**: Use Cursor's search to ensure terminology consistency across files
+- **Code examples**: Leverage Cursor's syntax highlighting and validation for code blocks
+
+## Cursor-Specific Workflows
+
+### Using Cursor Chat for Documentation
+
+- Ask Cursor to "review this documentation for clarity and completeness"
+- Use "explain this technical concept in simpler terms" for complex topics
+- Request "suggest improvements for this tutorial structure"
+
+### Using Cmd+K for Quick Edits
+
+- Use `@AGENTS.md` to reference the main documentation standards
+- Use `@sources/**/*.md` to search across all documentation files
+- Use `@apify-api/**/*.yaml` to reference API specifications
+
+## File-Specific Guidance
+
+### For Platform Documentation (`sources/platform/**/*.md`)
+
+- Focus on practical, actionable guidance
+- Include real-world examples and use cases
+- Reference related API endpoints when applicable
+
+### For Academy Content (`sources/academy/**/*.md`)
+
+- Structure content for learning progression
+- Include hands-on exercises and examples
+- Provide clear prerequisites and next steps
+
+### For MDX Files
+
+- Leverage Cursor's MDX syntax highlighting
+- Use component imports and JSX syntax appropriately
+- Ensure proper frontmatter formatting
+
+## Quality Assurance in Cursor
+
+- Use Cursor's spell check for documentation files
+- Leverage Cursor's markdown preview for formatting verification
+- Use Cursor's search to find similar content and maintain consistency

.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

.cursorignore

@@ -0,0 +1,78 @@
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+apify-docs-theme/package-lock.json
+
+# Build artifacts and generated content
+build/
+dist/
+build-docs/
+.docusaurus/
+static/api/
+apify-api.yaml
+apify-api/openapi/code_samples/
+apify-api/docs/
+
+# Large generated files
+*.log
+*.pid
+*.seed
+*.tsbuildinfo
+
+# IDE and editor files
+.vscode/
+.idea/
+.history/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+pids/
+coverage/
+.nyc_output/
+
+# Generated types
+types/
+
+# Turbo cache
+.turbo/
+
+# Generated documentation
+# These are typically auto-generated, but require editing from time to time
+# sources/api/*
+# !sources/api/sidebars.js
+# !sources/api/getting-started.mdx
+
+# Large static files that are auto-generated
+static/api/openapi.json
+static/api/openapi.yaml
+
+# Generated routes and registry files
+.docusaurus/routes.js
+.docusaurus/routesChunkNames.json
+.docusaurus/registry.js
+.docusaurus/globalData.json
+.docusaurus/site-metadata.json
+.docusaurus/client-modules.js
+.docusaurus/docusaurus.config.mjs
+
+# Generated plugin directories
+.docusaurus/docusaurus-plugin-*/
+.docusaurus/docusaurus-theme-*/
+.docusaurus/@apify/
+
+# Generated code samples (these are auto-generated from OpenAPI specs)
+# Note: These are typically auto-generated, but you may need to edit them occasionally
+# Uncomment the lines below if you want to ignore them completely:
+# apify-api/openapi/code_samples/javascript/*.js
+# apify-api/openapi/code_samples/curl/*.sh
+
+# Generated requirements files
+apify-api/scripts/requirements.bin
+
+# AGENTS.md is the primary vendor-agnostic rules file
+# .cursor/rules/ contains Cursor-specific rules with advanced features

.github/styles/Apify/Apify.yml

@@ -1,10 +1,24 @@
 extends: substitution
 message: "Use '%s' instead of '%s'."
-ignorecase: false
+ignorecase: true
 level: warning
+scope: text
 swap:
-    Apify Dashboard: Apify Console
-    apify freelancers: Apify freelancers
-    Apify Platform: Apify platform
-    '(?:[Tt]he\s)?[Aa]pify\sproxy': Apify Proxy
+    # Product name changes
+    'apify dashboard': Apify Console
+    'apify console': Apify Console
+    'apify store': Apify Store
+    'the apify console': Apify Console
+    'the apify store': Apify Store
+
+    # Capitalization fixes
+    'apify freelancers': Apify freelancers
+    'apify platform': Apify platform
+
+    # Proxy variations (simplified)
+    'apify proxy': Apify Proxy
+    'the apify proxy': Apify Proxy
+
+    # Common abbreviations
     circa: approx.
+    'ca\.': circa

.github/styles/Apify/Capitalization.yml

@@ -1,20 +1,9 @@
-extends: existence
-message: "The word '%s' should always be capitalized."
+extends: substitution
+message: "Use '%s' instead of '%s'."
 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
+nonword: true
+scope: text,~alt,~code
+swap:
+  '\bactor\b': Actor
+  '\bactors\b': Actors

.github/styles/Apify/H1.yml

@@ -0,0 +1,6 @@
+extends: existence
+message: 'Do not use H1 headings (#). The main title is generated automatically. Please use H2 (##) or lower.'
+level: error
+scope: heading.h1
+tokens:
+  - '.+'