diff --git a/.cursor/rules/api-documentation.mdc b/.cursor/rules/api-documentation.mdc index 4aa2733663..2086f69a60 100644 --- a/.cursor/rules/api-documentation.mdc +++ b/.cursor/rules/api-documentation.mdc @@ -1,21 +1,62 @@ --- -description: Standards for OpenAPI specifications and API code samples +description: Cursor-specific rules for OpenAPI specifications and API documentation globs: ["apify-api/**/*.yaml", "apify-api/**/*.js"] alwaysApply: true --- -# API Documentation Rules +# Cursor-Specific API Documentation Rules -## OpenAPI specifications +## Cursor OpenAPI Workflow -- Follow **RESTful conventions** for endpoint design -- Use **descriptive operation IDs** following camelCase -- Include **comprehensive examples** for all endpoints -- Provide **clear parameter descriptions** +### Using Cursor for OpenAPI Editing -## Code samples +- 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 -- Include examples in **multiple languages** (JavaScript, Python, cURL) -- Use **realistic data** in examples -- Show **error handling** where appropriate -- Include **authentication examples** +### 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 diff --git a/.cursor/rules/content-formatting.mdc b/.cursor/rules/content-formatting.mdc index 8056e0f351..400d9f8d63 100644 --- a/.cursor/rules/content-formatting.mdc +++ b/.cursor/rules/content-formatting.mdc @@ -1,58 +1,82 @@ --- -description: Content formatting standards for MDX files and code examples +description: Cursor-specific content formatting rules for MDX and markdown files globs: ["sources/**/*.md", "sources/**/*.mdx"] alwaysApply: true --- -# Content Formatting Rules +# Cursor-Specific Content Formatting -## Front matter (MDX files) +## 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: "Clear, action-oriented title" -description: "140-160 character description that explains the value" -sidebar_position: 1 -slug: /path/to/page +title: "Example" +description: "Description" --- ``` -## Text emphasis +# For API examples -- **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 +```bash +curl -X GET "https://api.apify.com/v2/acts" +``` -## Admonitions -Use admonitions to highlight important information: +## Cursor Workflow for Formatting -```markdown -:::note Important information -Your note content here. -::: +### Using Cursor Chat for Formatting Help -:::tip Pro tip -Helpful tip for users. -::: +- Ask "format this markdown table properly" +- Request "add syntax highlighting to this code block" +- Use "check this frontmatter for proper YAML syntax" -:::info Additional context -Background information. -::: +### 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: -:::caution Warning -Something to be careful about. +```markdown +:::note Cursor Tip +Use Cursor's markdown preview to verify admonition formatting ::: -:::danger Critical -Critical information that could cause issues. +:::tip Cursor Feature +Leverage Cursor's autocomplete for consistent admonition syntax ::: ``` -## Code examples +## 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 **code tabs** for multiple language examples -- Include **complete, runnable examples** -- Add **comments** to explain complex code -- Use **syntax highlighting** for all code blocks +- Use Cursor's markdown preview for formatting verification +- Leverage Cursor's spell check for content quality +- Use Cursor's link validation for internal references diff --git a/.cursor/rules/documentation-style.mdc b/.cursor/rules/documentation-style.mdc index 46aaa84e18..515124052c 100644 --- a/.cursor/rules/documentation-style.mdc +++ b/.cursor/rules/documentation-style.mdc @@ -1,81 +1,55 @@ --- -description: Documentation style guidelines and writing standards for Apify docs +description: Cursor-specific documentation style rules for Apify docs globs: ["sources/**/*.md", "sources/**/*.mdx"] alwaysApply: true --- -# Documentation Style Guidelines +# Cursor-Specific Documentation Rules -## Project overview +## Context-Aware Writing -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. +When editing documentation in Cursor, consider the broader context: -## Documentation structure +- **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 -- **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 +## Cursor-Specific Workflows -## Writing style & guidelines +### Using Cursor Chat for Documentation -### Language & tone +- 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" -- 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 +### Using Cmd+K for Quick Edits -### Technical writing best practices +- 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 -- **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 +## File-Specific Guidance -### Microsoft style guide compliance +### For Platform Documentation (`sources/platform/**/*.md`) -- 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 +- Focus on practical, actionable guidance +- Include real-world examples and use cases +- Reference related API endpoints when applicable -## Common patterns +### For Academy Content (`sources/academy/**/*.md`) -### Tutorial structure +- Structure content for learning progression +- Include hands-on exercises and examples +- Provide clear prerequisites and next steps -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 +### For MDX Files -### Troubleshooting sections +- Leverage Cursor's MDX syntax highlighting +- Use component imports and JSX syntax appropriately +- Ensure proper frontmatter formatting -- **Common issues** and solutions -- **Error messages** and their meanings -- **Debugging steps** for complex problems -- **Contact information** for additional help +## Quality Assurance in Cursor -## 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. +- 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 diff --git a/.cursorignore b/.cursorignore new file mode 100644 index 0000000000..bff2cfec08 --- /dev/null +++ b/.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 diff --git a/.github/styles/config/vocabularies/Docs/accept.txt b/.github/styles/config/vocabularies/Docs/accept.txt index 674dbd323f..59514bdd83 100644 --- a/.github/styles/config/vocabularies/Docs/accept.txt +++ b/.github/styles/config/vocabularies/Docs/accept.txt @@ -82,6 +82,7 @@ preconfigured [Tt]rello [Pp]refill [Gg]umloop +[Rr]edocly [Aa]pify [Mm]ultiselect @@ -122,3 +123,4 @@ walkthroughs? ul [Aa]gno +pnpm diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..8938ad051e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,179 @@ +# Apify Documentation Standards + +## 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 +- 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 + +## Content Formatting Standards + +### 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 + +## 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** + +## 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 + +## 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 +``` + +## Quality Standards + +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 + +Remember: The goal is to help users succeed with Apify. Every piece of documentation should serve that purpose by being clear, accurate, and actionable. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22f357f6a7..f7d22312da 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,9 +10,10 @@ ### Prerequisites -1. Git -2. Node.js -3. GitHub access +1. **Git** +2. **Node.js 22** (see [.nvmrc](.nvmrc) file) +3. **GitHub access** +4. **npm** or **pnpm** package manager ### Installation steps @@ -88,7 +89,7 @@ You should be able to open https://docs.apify.loc in your browser and run all th 1. Text emphasis: - use **Bold** for UI elements - - use *Italics* for emphasis + - use _Italics_ for emphasis - use `code` for inline code, by using back-ticks (\`\`\) - use code blocks with language specification - use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) whenever you want to include examples of implementation in more than one language @@ -127,6 +128,46 @@ You should be able to open https://docs.apify.loc in your browser and run all th - Avoid repetitive keywords - Avoid the word "documentation" in descriptions +## AI Assistant rules structure + +This project uses a hybrid approach for AI assistant rules to ensure consistency across different tools while leveraging Cursor-specific features. + +### Structure overview + +#### Vendor-agnostic rules + +- **`AGENTS.md`** - Primary vendor-agnostic rules file containing core documentation standards + +#### Cursor-specific rules + +- **`.cursor/rules/documentation-style.mdc`** - Cursor-specific documentation guidelines +- **`.cursor/rules/content-formatting.mdc`** - Cursor-specific formatting rules +- **`.cursor/rules/api-documentation.mdc`** - Cursor-specific API documentation rules +- **`.cursor/rules/quality-standards.mdc`** - Cursor-specific quality guidelines +- **`.cursor/rules/file-organization.mdc`** - Cursor-specific file organization rules + +To verify rule application, hover over attached rules in the Cursor chat window. + +### Usage + +#### For general AI assistants + +- Reference `AGENTS.md` for vendor-agnostic documentation standards + +#### For Cursor-specific features + +- Use `.cursor/rules/*.mdc` files for Cursor-specific workflows +- Leverage glob patterns and `alwaysApply` settings +- Use Cursor Chat and Cmd+K with `@AGENTS.md` references + +### File targeting + +Each `.mdc` file uses glob patterns to target specific file types: + +- **`documentation-style.mdc`**: `["sources/**/*.md", "sources/**/*.mdx"]` +- **`content-formatting.mdc`**: `["sources/**/*.md", "sources/**/*.mdx"]` +- **`api-documentation.mdc`**: `["apify-api/**/*.yaml", "apify-api/**/*.js"]` + ## Repository structure ### Theme management @@ -274,21 +315,21 @@ Add languages by adding new folders at the appropriate path level. ### Linting -1. Markdown: +1. **Markdown**: ```bash npm run lint:md # Checks for any issues using markdownlint npm run lint:md:fix # Applies fixes ``` -2. Code: +2. **Code**: ```bash npm run lint:code # Checks .js & .ts files npm run lint:code:fix # Applies fixes ``` -3. Prose: +3. **Prose**: - Use [Vale](https://vale.sh/) for content linting - Configure exceptions in `accepts.txt` @@ -309,3 +350,5 @@ Add languages by adding new folders at the appropriate path level. - [Docusaurus documentation](https://docusaurus.io/docs) - [Vale style guide](https://vale.sh/docs) +- [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0) +- [Redocly documentation](https://redocly.com/docs/) diff --git a/README.md b/README.md index 5d6aa91f6d..e1fdbf2f5b 100644 --- a/README.md +++ b/README.md @@ -21,12 +21,43 @@ Our documentation ecosystem consists of: - [Python](https://docs.apify.com/sdk/python/) - **CLI documentation** - [CLI docs](https://docs.apify.com/cli/) -## Getting started +## Getting Started -Before contributing, read these essential resources: +**Before contributing, read these essential resources:** -- [Contributing guidelines](CONTRIBUTING.md) -- [Documentation style guide](CONTRIBUTING.md#documentation-style-guide) +- [Contributing guidelines](CONTRIBUTING.md) - Complete setup and contribution process +- [Documentation style guide](CONTRIBUTING.md#documentation-style-guide) - Writing standards and formatting +- [AI Assistant Rules Structure](CONTRIBUTING.md#ai-assistant-rules-structure) - AI tool configuration + +### Prerequisites + +- **Node.js 22** (see [.nvmrc](.nvmrc)) +- **npm** or **pnpm** +- **Git** + +### Quick Setup + +```bash +# Clone the repository +git clone https://github.com/apify/apify-docs.git +cd apify-docs + +# Install dependencies +npm install + +# Start development server +npm start +``` + +The site will be available at `http://localhost:3000` + +### Available Scripts + +- `npm start` - Start development server with API docs +- `npm run build` - Build for production +- `npm run lint` - Run all linting checks +- `npm run lint:fix` - Fix linting issues automatically +- `npm run api:rebuild` - Regenerate API documentation ## Documentation architecture @@ -56,7 +87,7 @@ Our documentation is built using: - **Automated Deployment**: CI/CD pipeline for continuous updates - **nginx routing**: Handles subdomain routing and redirects -## Need help +### Need help - For contribution questions, see our [Contributing Guidelines](CONTRIBUTING.md) - For technical issues, [create a GitHub issue](https://github.com/apify/apify-docs/issues/new)