diff --git a/.claude/README.md b/.claude/README.md new file mode 100644 index 0000000000..65c80a5064 --- /dev/null +++ b/.claude/README.md @@ -0,0 +1,162 @@ +# Claude Code configuration for Apify docs + +This directory contains Claude Code configuration for the Apify documentation repository. + +## Structure + +```text +.claude/ +├── README.md # This file +├── instructions.md # Main instructions for Claude Code +└── skills/ # Reusable skills for common tasks + ├── doc-write.md # Documentation writing skill + ├── api-doc.md # API documentation skill + ├── tutorial.md # Tutorial creation skill + └── review-docs.md # Documentation review skill +``` + +## How to use + +### For Claude Code users + +1. **Start a new session**: Claude Code will automatically read `instructions.md` +2. **Use skills**: Type `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs` to use specific skills +3. **Reference standards**: Always refer to `AGENTS.md` in the repo root for core standards + +### Available skills + +#### `/doc-write` - Documentation writing + +Create or edit documentation following Apify style guide. + +- Use for: New pages, content updates, reformatting +- Handles: Style compliance, formatting, structure + +#### `/api-doc` - API documentation + +Work with OpenAPI specifications and API endpoints. + +- Use for: New endpoints, schema updates, code samples +- Handles: OpenAPI structure, operation IDs, examples + +#### `/tutorial` - Tutorial creation + +Build structured, educational tutorials. + +- Use for: New tutorials, tutorial restructuring +- Handles: Learning progression, examples, exercises + +#### `/review-docs` - Documentation review + +Review documentation for quality and compliance. + +- Use for: Pre-submission checks, audits, consistency +- Handles: Style guide compliance, accessibility, SEO + +## Quick start + +### Writing new documentation + +```text +Use /doc-write skill to create a new documentation page about [topic] +``` + +### Creating a tutorial + +```text +Use /tutorial skill to create a tutorial on [topic] +``` + +### Adding API endpoint + +```text +Use /api-doc skill to document the new [endpoint-name] endpoint +``` + +### Reviewing documentation + +```text +Use /review-docs skill to review sources/platform/[file-name].md +``` + +## Primary references + +Always reference these files from the repo root: + +1. **`AGENTS.md`** - Core documentation standards (READ FIRST) +2. **`CONTRIBUTING.md`** - Setup, workflows, style guide +3. **`.cursor/rules/*.mdc`** - Cursor-specific rules (reference only) + +## Key standards + +### Writing style + +- US English, active voice, inclusive language +- Sentence case for headings (not Title Case) +- Action-oriented phrasing +- No directional language (left/right) + +### Front matter + +Every file needs: + +```yaml +--- +title: "Action-oriented title" +description: "140-160 chars, no 'documentation' word" +sidebar_position: 1 +slug: /path/to/page +--- +``` + +### Formatting + +- **Bold** for UI elements +- _Italics_ for emphasis +- `code` for inline code/files +- Code blocks with language tags +- Admonitions for important info + +### Links & images + +- Descriptive link text (not "click here") +- Alt text for all images +- Light theme for screenshots +- Red indicators for highlighting + +## Testing + +Before submitting: + +```bash +npm run lint:md # Check markdown +npm run lint:code # Check code +npm start # Preview changes +npm test # Validate API specs +``` + +## Best practices + +1. **Read `AGENTS.md` first** - It's the source of truth +2. **Use the appropriate skill** - They're designed for specific tasks +3. **Test code examples** - All examples must work +4. **Check front matter** - Required for all files +5. **Run linters** - Before committing +6. **Review before submit** - Use `/review-docs` + +## Maintenance + +This configuration mirrors and extends the existing style guide: + +- `AGENTS.md` - Vendor-agnostic standards +- `CONTRIBUTING.md` - Contribution process +- `.cursor/rules/*.mdc` - Cursor-specific rules + +Keep these files in sync when updating documentation standards. + +## Need help? + +- Questions about style: Check `AGENTS.md` +- Setup issues: See `CONTRIBUTING.md` +- Skill usage: Read the specific skill file +- Claude Code general: Visit [Claude Code docs](https://github.com/anthropics/claude-code) diff --git a/.claude/claude.json b/.claude/claude.json new file mode 100644 index 0000000000..c4a417efb4 --- /dev/null +++ b/.claude/claude.json @@ -0,0 +1,29 @@ +{ + "skills": [ + { + "name": "doc-write", + "description": "Create or edit documentation following Apify style guide", + "path": "skills/doc-write.md" + }, + { + "name": "api-doc", + "description": "Work with OpenAPI specifications and API documentation", + "path": "skills/api-doc.md" + }, + { + "name": "tutorial", + "description": "Create structured tutorials with proper learning progression", + "path": "skills/tutorial.md" + }, + { + "name": "review-docs", + "description": "Review documentation for style guide compliance and quality", + "path": "skills/review-docs.md" + } + ], + "instructions": "instructions.md", + "context": [ + "../AGENTS.md", + "../CONTRIBUTING.md" + ] +} diff --git a/.claude/instructions.md b/.claude/instructions.md new file mode 100644 index 0000000000..fa10361fa7 --- /dev/null +++ b/.claude/instructions.md @@ -0,0 +1,386 @@ +# Claude Code instructions for Apify documentation + +## Project overview + +You are working on the Apify documentation repository, which contains: + +- **Platform documentation**: Core platform features and functionality (`/sources/platform/`) +- **Academy**: Educational content and tutorials (`/sources/academy/`) +- **API reference**: OpenAPI specifications (`/apify-api/`) + +The project uses Docusaurus with MDX, follows Microsoft style guide principles, and has comprehensive style guidelines. + +## Primary reference documents + +**Always reference these files when working on documentation**: + +1. `AGENTS.md` - Primary vendor-agnostic documentation standards (READ THIS FIRST) +2. `CONTRIBUTING.md` - Contribution guidelines, setup, and workflows +3. `.cursor/rules/*.mdc` - Cursor-specific rules (for reference) + +## Available skills + +Use these skills for specific documentation tasks: + +### `/doc-write` - Documentation writing + +**When to use**: Creating or editing documentation pages +**Handles**: Content creation, formatting, style guide compliance + +### `/api-doc` - API documentation + +**When to use**: Working with OpenAPI specifications +**Handles**: Creating endpoints, schemas, code samples + +### `/tutorial` - Tutorial creation + +**When to use**: Creating step-by-step tutorials +**Handles**: Tutorial structure, learning content, examples + +### `/review-docs` - Documentation review + +**When to use**: Reviewing documentation before submission +**Handles**: Style guide compliance, quality checks, consistency + +## Core documentation standards + +### Language & style + +- **US English** spelling and grammar (e.g., "color" not "colour") +- **Active voice** whenever possible +- **Inclusive language** - no gendered terms +- **Action-oriented** phrasing +- **Simple English** - prefer "use" over "utilize", favor simple sentence structures +- **Avoid directional language** (use "preceding/following" not "left/right") +- **Sentence case** for headings (not Title Case) +- **Simple present tense** for headings: "Create an Actor" (not "Creating an Actor") +- **Use Oxford commas** in lists +- **Never make assumptions about product features** - ask if unsure + +### Front matter requirements + +Every documentation file must include: + +```yaml +--- +title: "Sentence case title (action-oriented, simple present tense)" +description: "140-160 chars - explain value, not features (no 'documentation' word)" +sidebar_position: 1 +slug: /path/to/page +--- +``` + +**Important**: Match slug to file path + +- File: `/sources/platform/actors/running.md` +- Slug: `/platform/actors/running` + +### Text formatting standards + +- **Bold** ONLY for UI elements, buttons, tabs, menu items (e.g., "Click **Save & Run**"). NEVER use bold for emphasis. +- _Italics_ for emphasis (use sparingly) +- `code` for inline code, file names, paths, API parameters (e.g., "Set `timeout` in `INPUT.json`") +- Code blocks MUST specify language: ` ```javascript `, ` ```python `, ` ```bash ` +- **All admonitions MUST have a title** - Available types: `note`, `tip`, `info`, `caution`, `danger` + +### Code examples + +- Include complete, runnable examples +- Use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) for multiple languages (JavaScript, Python) +- Add syntax highlighting with language tags (REQUIRED) +- Include comments for complex logic +- Show realistic, meaningful examples + +### Admonition format + +**All admonitions MUST include a title:** + +```markdown +:::note Important information + +Your note content here. + +::: + +:::tip Pro tip + +Helpful advice for advanced users. + +::: + +:::caution Warning + +Something that could cause issues. + +::: +``` + +### Links + +- Use descriptive link text (never "click here") +- Use relative paths for internal links +- Verify all links work before committing + +### Images + +- Use light theme for screenshots +- Include meaningful alt text +- Use red indicators for highlighting +- Store in appropriate directories + +## File organization + +### Naming conventions + +- Use **kebab-case** for file names: `web-scraping-basics.md` (never camelCase or snake_case) +- Use descriptive names that reflect content +- Group related files in logical directories +- **Match slug to file path** for consistency + +### 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 +``` + +## API documentation specifics + +### OpenAPI structure + +```text +apify-api/openapi/ +├── openapi.yaml # Main spec file +├── components/schemas/ # Data model definitions +└── paths/ # API endpoint definitions +``` + +### Operation ID conventions + +Format: `{objectName}_{httpMethod}` + +- Use camelCase for object names +- Single object for paths with `{id}`, plural otherwise +- Examples: + - `/request-queues` GET → `requestQueues_get` + - `/request-queues/{queueId}` PUT → `requestQueue_put` + +### Path file naming + +Replace `/` with `@` in URL paths: + +- `/request-queues` → `request-queues.yaml` +- `/request-queues/{queueId}` → `request-queues@{queueId}.yaml` + +## Development workflow + +### Before starting work + +1. Read `AGENTS.md` for documentation standards +2. Review `CONTRIBUTING.md` for specific guidelines +3. Check existing similar documentation for patterns +4. Determine which skill to use for the task + +### During development + +1. Follow the appropriate skill instructions +2. Reference `AGENTS.md` for style questions +3. Use proper front matter in all files +4. Include complete, tested code examples +5. Add descriptive links and alt text + +### Before submitting + +1. Run linting checks: + + ```bash + npm run lint:md # Markdown linting + npm run lint:code # Code linting + + # Run locally for more detailed output: + npx markdownlint "path/to/file.md" # Check specific markdown files + vale sync # Download Vale styles (first time) + vale "path/to/file.md" --minAlertLevel=error # Check prose + ``` + +2. Use `/review-docs` skill to check compliance +3. Verify all code examples work +4. Check all links are valid +5. Ensure front matter is complete + +### Testing changes + +```bash +npm install # Install dependencies +npm start # Start development server +npm test # Validate OpenAPI specs (if applicable) +npm run build # Test production build +``` + +## Common patterns + +### Tutorial structure + +1. Introduction with learning objectives +2. Prerequisites +3. Step-by-step numbered instructions +4. Complete code examples +5. Testing/verification section +6. Troubleshooting +7. Summary and next steps + +### Platform documentation + +1. Clear description of feature +2. When to use it +3. How to configure/use it +4. Code examples +5. Best practices +6. Related features + +### API documentation + +1. Endpoint description +2. Parameters with types and descriptions +3. Request examples +4. Response schemas +5. Error responses +6. Code samples (JavaScript, Python, cURL) + +## Quality checklist + +Before considering any documentation complete: + +- [ ] Content follows Microsoft style guide +- [ ] Front matter complete (title, description 140-160 chars) +- [ ] Code examples complete with syntax highlighting +- [ ] Links use descriptive text +- [ ] Images include meaningful alt text +- [ ] Inclusive language and active voice used +- [ ] Proper heading hierarchy (H1 → H2 → H3) +- [ ] Content is clear, concise, action-oriented +- [ ] All automated linting passes +- [ ] Examples tested and working + +## Important notes + +### What NOT to do + +- Don't use Title Case for headings (use sentence case) +- Don't use gerunds in headings ("Creating" - use "Create" instead) +- Don't use bold for emphasis (ONLY for UI elements) +- Don't forget titles on admonitions (REQUIRED) +- Don't use "click here" or non-descriptive links +- Don't include the word "documentation" in descriptions +- Don't use directional language (left/right) +- Don't skip front matter +- Don't omit language tags on code blocks +- Don't use gendered language +- Don't commit without running linters +- Don't make assumptions about product features - ask instead +- Don't use incorrect Apify terminology (see terminology section) + +### Best practices + +- Start with user's goal/problem +- Provide context before technical details +- Use consistent Apify terminology (see terminology section) +- Use simple English - "use" not "utilize" +- Use Oxford commas in all lists +- Use simple present tense for headings +- Structure content logically (basic → advanced) +- Link to related content +- Keep descriptions within 140-160 characters explaining value, not features +- Match slug to file path for consistency +- Test all code examples before committing +- Use admonitions sparingly but effectively (always with titles) +- Never make assumptions about product features - ask if unsure +- For code review: check comments and obvious mistakes only + +## Apify-specific terminology + +**Always use exact capitalization and phrasing:** + +- **Apify Actor** (never "Apify actor" or "apify actor") +- **Apify Proxy** (never "Apify proxy") +- **Apify Console** (never "the Apify Console") +- **Apify Store** (never "the Apify Store") +- **the Apify team** (lowercase "the", lowercase "team") +- **the Apify platform** (lowercase "the", lowercase "platform") +- **AI agent** (lowercase for generic terms) +- **MCP server** (lowercase for generic terms) + +## Content review process + +### Before reviewing a PR + +- Check that the latest changes were pulled from the feature branch + +### Review checklist + +When reviewing or creating documentation, verify: + +- **Clarity**: Instructions are easy to understand +- **Consistency**: Uniform terminology (see word list above) and style throughout +- **Grammar & Spelling**: Correct errors, use American English with Oxford commas +- **Structure**: Logical flow, no duplicate content, appropriate headings/lists +- **Links**: Verify all links are functional and relevant, link key terms to their docs +- **Code snippets**: Developer-provided; check comments and obvious mistakes only (not full code review) + +## Getting help + +If you're unsure about: + +- **Style questions**: Check `AGENTS.md` first +- **Setup issues**: See `CONTRIBUTING.md` +- **API documentation**: See `/api-doc` skill +- **Tutorial structure**: See `/tutorial` skill +- **Review process**: See `/review-docs` skill +- **Product features**: Never make assumptions - ask if unsure + +## Project-specific context + +### Multiple repositories + +The full documentation ecosystem includes multiple repos: + +- apify-docs (this repo) - Platform, Academy, OpenAPI +- apify-client-js - JavaScript client docs +- apify-client-python - Python client docs +- apify-sdk-js - JavaScript SDK docs +- apify-sdk-python - Python SDK docs +- apify-cli - CLI documentation + +### Theme + +Uses `@apify/docs-theme` package - don't modify theme files directly. + +### Deployment + +- Automatic deployment on merge to `master` +- Preview builds available for pull requests +- Uses nginx for routing between repositories + +### Linting tools + +- **markdownlint** - Markdown formatting +- **eslint** - JavaScript/TypeScript code +- **Vale** - Prose linting (optional, download styles with `vale sync`) + +## Remember + +The goal is to help users succeed with Apify. Every piece of documentation should: + +- Be **clear** and easy to understand +- Be **accurate** and technically correct +- Be **actionable** with concrete examples +- Follow the **style guide** consistently +- Provide **real value** to users + +When in doubt, prioritize clarity and usefulness over strict adherence to rules. But always maintain consistency within the documentation set. diff --git a/.claude/skills/api-doc.md b/.claude/skills/api-doc.md new file mode 100644 index 0000000000..cb01007692 --- /dev/null +++ b/.claude/skills/api-doc.md @@ -0,0 +1,226 @@ +# API documentation skill + +## Purpose + +Help create or update OpenAPI specifications and API documentation for Apify API endpoints. + +## When to use + +- Adding new API endpoints +- Updating existing endpoint documentation +- Creating or modifying OpenAPI schemas +- Adding code samples for API endpoints + +## Context files + +- `CONTRIBUTING.md` - API documentation section +- `AGENTS.md` - API documentation rules +- `apify-api/openapi/openapi.yaml` - Main OpenAPI spec + +## Instructions + +### 1. OpenAPI file structure + +```text +apify-api/openapi/ +├── openapi.yaml # Main spec file +├── components/ +│ └── schemas/ # Data model definitions +└── paths/ # API endpoint definitions +``` + +### 2. Creating schema documentation + +**Location**: `apify-api/openapi/components/schemas/` + +**Steps**: + +1. Create a new YAML file named after your schema +2. Define the schema structure following OpenAPI 3.0 specification +3. Include comprehensive descriptions for all properties +4. Reference schema using `$ref` in other files + +**Example**: + +```yaml +type: object +properties: + id: + description: The resource ID + readOnly: true + allOf: + - $ref: ./ResourceId.yaml + name: + type: string + description: The resource name + example: "my-resource" +required: + - id + - name +``` + +### 3. Creating path documentation + +**Location**: `apify-api/openapi/paths/` + +**Naming Convention**: Replace `/` with `@` in the URL path + +- `/request-queues` → `request-queues.yaml` +- `/request-queues/{queueId}` → `request-queues@{queueId}.yaml` + +**Example Path File**: + +```yaml +get: + tags: + - Request Queues + summary: Get a Request Queue + operationId: requestQueue_get + description: | + Retrieves a specific request queue by ID. + + Returns detailed information about the queue including + its current state, item count, and metadata. + parameters: + - name: queueId + in: path + required: true + description: The unique identifier of the request queue + schema: + type: string + responses: + '200': + description: Request queue details + content: + application/json: + schema: + $ref: ../components/schemas/RequestQueue.yaml + '401': + description: Unauthorized + '404': + description: Queue not found + x-code-samples: + - lang: JavaScript + source: + $ref: ../code_samples/JavaScript/request-queues@{queueId}/get.js + - lang: Python + source: + $ref: ../code_samples/Python/request-queues@{queueId}/get.py +``` + +### 4. Operation ID conventions + +Format: `{objectName}_{httpMethod}` + +**Rules**: + +- Use camelCase for object names +- Single object for paths with `{id}`, plural otherwise +- Underscore separator between object name and action +- Method name in lowercase at the end + +**Examples**: + +- `/request-queues` GET → `requestQueues_get` +- `/request-queues/{queueId}` PUT → `requestQueue_put` +- `/acts/{actorId}/runs` POST → `act_runs_post` + +### 5. Adding code samples + +**Location**: `apify-api/openapi/code_samples/{language}/{path}/` + +**Steps**: + +1. Navigate to the appropriate language folder +2. Create path-based directory structure +3. Add code sample file +4. Reference in path documentation using `x-code-samples` + +**Example JavaScript Code Sample**: + +```javascript +// GET /v2/request-queues/{queueId} +const { ApifyClient } = require('apify-client'); + +const client = new ApifyClient({ + token: 'YOUR_API_TOKEN', +}); + +const queue = await client.requestQueue('QUEUE_ID').get(); +console.log(queue); +``` + +**Example Python Code Sample**: + +```python +# GET /v2/request-queues/{queueId} +from apify_client import ApifyClient + +client = ApifyClient('YOUR_API_TOKEN') + +queue = client.request_queue('QUEUE_ID').get() +print(queue) +``` + +### 6. Adding new endpoints to main spec + +**File**: `apify-api/openapi/openapi.yaml` + +Add path reference: + +```yaml +paths: + '/request-queues': + $ref: './paths/request-queues/request-queues.yaml' + '/request-queues/{queueId}': + $ref: './paths/request-queues/request-queues@{queueId}.yaml' +``` + +### 7. Testing and validation + +After making changes: + +```bash +npm test # Validates OpenAPI specification +npm start # Preview changes locally +``` + +### 8. Apify terminology + +Always use exact capitalization in descriptions and examples: + +- **Apify Actor** (never "Apify actor") +- **Apify Proxy** (never "Apify proxy") +- **Apify Console** (never "the Apify Console") +- **Apify Store** (never "the Apify Store") +- **the Apify team**, **the Apify platform** (lowercase) + +### 9. Best practices + +- **Descriptions**: Write clear, comprehensive descriptions using simple English +- **Examples**: Include realistic examples in schemas +- **Error responses**: Document all possible error responses +- **Authentication**: Document authentication requirements +- **Consistency**: Follow existing patterns in the codebase +- **Completeness**: Ensure all parameters and responses are documented +- **Terminology**: Use correct Apify terminology throughout +- **Never make assumptions**: About product features - ask if unsure + +### 10. Quality checklist + +Before submitting: + +- [ ] OpenAPI specification validates without errors +- [ ] Operation IDs follow naming conventions (camelCase_method) +- [ ] All parameters have clear descriptions using simple English +- [ ] Response schemas are complete +- [ ] Code samples are included for major languages (JS, Python, cURL) +- [ ] Examples use realistic data +- [ ] Path references are added to main openapi.yaml +- [ ] Error responses are documented +- [ ] Correct Apify terminology used throughout +- [ ] No assumptions made about product features + +## Output + +Provide the complete OpenAPI specification changes with proper formatting, ready to be tested and committed. diff --git a/.claude/skills/doc-write.md b/.claude/skills/doc-write.md new file mode 100644 index 0000000000..b67719498f --- /dev/null +++ b/.claude/skills/doc-write.md @@ -0,0 +1,167 @@ +# Documentation writer skill + +## Purpose + +Help write or edit Apify documentation following the established style guide and best practices. + +## When to use + +- Creating new documentation pages +- Editing existing documentation +- Converting drafts into proper documentation format +- Updating documentation content + +## Context files + +- `AGENTS.md` - Primary documentation standards +- `CONTRIBUTING.md` - Contribution guidelines + +## Instructions + +When writing or editing documentation: + +### 1. Content standards + +- Use **US English** spelling and grammar (e.g., "color" not "colour") +- Use **simple English** - prefer "use" over "utilize", favor simple sentence structures +- Write in **active voice** whenever possible +- Use **inclusive language** - avoid gendered terms +- Be **action-oriented** in descriptions and titles +- Use **simple present tense** for headings: "Create an Actor" (NOT "Creating an Actor") +- Use **Oxford commas** in all lists +- Avoid directional language (don't use "left/right", use "above/below" or "preceding/following") +- Write for a technical audience but keep explanations clear +- **Never make assumptions about product features** - ask if unsure + +### 2. Front matter + +Always include proper front matter in MDX/MD files: + +```yaml +--- +title: "Sentence case title (action-oriented, simple present tense)" +description: "140-160 chars - explain value, not features (no 'documentation' word)" +sidebar_position: 1 +slug: /path/to/page +--- +``` + +**Important**: Match slug to file path + +- File: `/sources/platform/actors/running.md` +- Slug: `/platform/actors/running` + +### 3. Text formatting + +- **Bold** ONLY for UI elements, buttons, tabs, menu items (e.g., "Click **Save & Run**"). NEVER use bold for emphasis. +- _Italics_ for emphasis (use sparingly) +- `code` for inline code, file names, paths, API parameters (e.g., "Set `timeout` in `INPUT.json`") +- Code blocks MUST specify language: ` ```javascript `, ` ```python `, ` ```bash ` + +### 4. Headings + +- Use **sentence case** for all headings (not Title Case) +- Use **simple present tense**: "Create an Actor" (NOT "Creating an Actor") +- Follow proper hierarchy: H1 → H2 → H3 +- Make headings descriptive and action-oriented + +### 5. Admonitions + +**All admonitions MUST have a title** (REQUIRED). Use Docusaurus 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. + +::: +``` + +### 6. Code examples + +- Include complete, runnable examples +- Use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) for multiple languages +- Add syntax highlighting with language tags (REQUIRED) +- Include comments for complex code + +### 7. Links + +- Use descriptive link text (avoid "click here") +- Verify all internal links are correct +- Use relative paths for internal links + +### 8. Images + +- Use light theme for screenshots +- Include meaningful alt text +- Use red indicators for highlighting + +### 9. Structure + +For tutorials and guides, follow this structure: + +1. **Introduction** - What will the user learn? +2. **Prerequisites** - What do they need? +3. **Step-by-step instructions** - Clear, numbered steps +4. **Code examples** - Complete, working examples +5. **Summary** - What they accomplished and next steps + +### 10. Apify terminology + +Always use exact capitalization and phrasing: + +- **Apify Actor** (never "Apify actor" or "apify actor") +- **Apify Proxy** (never "Apify proxy") +- **Apify Console** (never "the Apify Console") +- **Apify Store** (never "the Apify Store") +- **the Apify team** (lowercase "the", lowercase "team") +- **the Apify platform** (lowercase "the", lowercase "platform") +- **AI agent** (lowercase for generic terms) +- **MCP server** (lowercase for generic terms) + +### 11. Quality checklist + +Before finalizing, verify: + +- [ ] Content follows Microsoft style guide (sentence case, simple present tense) +- [ ] Front matter includes proper title, description (140-160 chars explaining value), and metadata +- [ ] Slug matches file path +- [ ] Code examples are complete with syntax highlighting (REQUIRED) +- [ ] All admonitions have titles (REQUIRED) +- [ ] Bold used ONLY for UI elements, never for emphasis +- [ ] Oxford commas used in all lists +- [ ] All links use descriptive text +- [ ] Images include meaningful alt text +- [ ] Content uses inclusive language, simple English, and active voice +- [ ] Headings follow proper hierarchy and use simple present tense +- [ ] Content is clear, concise, and action-oriented +- [ ] Correct Apify terminology used throughout +- [ ] No assumptions made about product features + +## Output + +Provide the complete documentation with proper formatting, ready to be committed to the repository. diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md new file mode 100644 index 0000000000..065d086174 --- /dev/null +++ b/.claude/skills/review-docs.md @@ -0,0 +1,577 @@ +# Documentation review skill + +## Purpose + +Review documentation for compliance with Apify style guide, quality standards, and best practices. + +## When to use + +- Before submitting pull requests + +- During documentation audits + +- When editing existing documentation + +- To ensure consistency across documentation + +## Context files + +- `AGENTS.md` - Documentation standards + +- `CONTRIBUTING.md` - Contribution guidelines + +- `.cursor/rules/*.mdc` - Cursor-specific rules + +## Review process + +### Before starting review + +**CRITICAL**: Check that the latest changes were pulled from the feature branch + +## Review checklist + +### 1. Style guide compliance + +**Microsoft Style Guide**: + +- [ ] Headings use sentence case (not Title Case) + +- [ ] Headings use simple present tense ("Create an Actor" NOT "Creating an Actor") + +- [ ] UI elements use **bold** formatting ONLY (never bold for emphasis) + +- [ ] Emphasis uses _italics_ (used sparingly) + +- [ ] Inline code uses `backticks` + +- [ ] Proper use of numbered lists vs. bullet points + +- [ ] Oxford commas used in all lists + +**Language Guidelines**: + +- [ ] Uses US English spelling (e.g., "color" not "colour") + +- [ ] Uses simple English ("use" not "utilize") + +- [ ] Written in active voice + +- [ ] Uses inclusive language (no gendered terms) + +- [ ] Avoids directional language ("left/right") + +- [ ] Action-oriented phrasing + +**Apify Terminology** (check exact capitalization): + +- [ ] **Apify Actor** (never "Apify actor") + +- [ ] **Apify Proxy** (never "Apify proxy") + +- [ ] **Apify Console** (never "the Apify Console") + +- [ ] **Apify Store** (never "the Apify Store") + +- [ ] **the Apify team** (lowercase) + +- [ ] **the Apify platform** (lowercase) + +- [ ] **AI agent** (lowercase for generic terms) + +- [ ] **MCP server** (lowercase for generic terms) + +### 2. Front matter validation + +Required fields present and correct: + +- [ ] `title` - Clear, action-oriented, sentence case, simple present tense + +- [ ] `description` - 140-160 characters + +- [ ] `description` - Explains value, not features + +- [ ] `description` - Avoids word "documentation" + +- [ ] `description` - Action-oriented phrasing + +- [ ] `sidebar_position` - Appropriate numbering + +- [ ] `slug` - Correct URL path and matches file path + +**Example**: + +```yaml + +--- + +title: "Create an Actor" # ✅ Sentence case, simple present tense +description: "Build and deploy your first Apify Actor with this guide covering setup, development, testing, and best practices." # ✅ 140-160 chars, explains value +sidebar_position: 1 +slug: /actors/development/create # ✅ Matches file path + +--- + +``` + +### 3. Content structure + +**Heading Hierarchy**: + +- [ ] Single H1 (page title) only + +- [ ] Proper H2 → H3 → H4 nesting + +- [ ] No skipped levels (H2 → H4) + +- [ ] Headings are descriptive and scannable + +**Document Flow**: + +- [ ] Clear introduction explaining purpose + +- [ ] Logical progression of topics + +- [ ] Summary or next steps at end + +- [ ] Related content linked appropriately + +### 4. Code examples + +**Quality**: + +- [ ] Complete and runnable examples + +- [ ] Proper syntax highlighting with language tag (REQUIRED) + +- [ ] Includes comments for complex logic + +- [ ] Uses realistic, meaningful variable names + +- [ ] Shows both input and output where applicable + +**Code Review Scope**: + +- [ ] Code snippets are developer-provided + +- [ ] Review comments and obvious mistakes only (not full code review) + +**Multiple Languages**: + +- [ ] Uses [Docusaurus code tabs](https://docusaurus.io/docs/markdown-features/tabs) when showing multiple languages + +- [ ] Consistent examples across languages + +- [ ] Includes JavaScript and Python where applicable + +### 5. Links + +**Internal Links**: + +- [ ] Use relative paths + +- [ ] Point to correct locations + +- [ ] Use descriptive link text (not "click here") + +- [ ] Link text makes sense out of context + +**External Links**: + +- [ ] Open in new tab if appropriate + +- [ ] Point to reliable, permanent resources + +- [ ] Include brief context about destination + +**Example**: + +```markdown +# ✅ Good + +Learn more about [Actor definition files](/actors/development/actor-definition). + +# ❌ Bad + +Click [here](link) to learn more. + +``` + +### 6. Images and media + +**Screenshots**: + +- [ ] Use light theme + +- [ ] Include meaningful alt text + +- [ ] Use red indicators for highlighting + +- [ ] Appropriate size and resolution + +- [ ] Stored in proper directory + +**Alt Text**: + +- [ ] Describes image content + +- [ ] Useful for screen readers + +- [ ] Not just "image" or "screenshot" + +**Example**: + +```markdown +# ✅ Good + +![Actor input schema configuration in Apify Console](./images/input-schema.png) + +# ❌ Bad + +![screenshot](./img.png) + +``` + +### 7. Admonitions + +**Usage**: + +- [ ] **MUST have a title** (REQUIRED - no exceptions) + +- [ ] Appropriate type (note, tip, info, caution, danger) + +- [ ] Title is descriptive + +- [ ] Content is concise and relevant + +- [ ] Not overused (max 2-3 per page) + +**Example**: + +```markdown +# ✅ Good - has title and correct spacing + +:::tip Performance optimization + +Use `requestHandlerTimeoutSecs` to prevent slow requests from blocking your Actor. + +::: + +# ❌ Bad - missing title (REQUIRED) + +:::info +Be careful with this setting. +::: + +# ❌ Bad - no title + +:::tip +This is a helpful tip. +::: + +``` + +### 8. Technical accuracy + +**Validation**: + +- [ ] Code examples tested and working + +- [ ] API endpoints are current + +- [ ] Configuration examples are valid + +- [ ] Version numbers are up to date + +- [ ] No deprecated features recommended + +### 9. Accessibility + +**Compliance**: + +- [ ] Proper heading hierarchy + +- [ ] Descriptive link text + +- [ ] Alt text for images + +- [ ] Color not used as only indicator + +- [ ] Sufficient contrast in custom elements + +### 10. SEO optimization + +**Elements**: + +- [ ] Descriptive, unique page title + +- [ ] Meta description (140-160 chars) + +- [ ] Relevant keywords used naturally + +- [ ] Internal linking to related content + +- [ ] Proper heading structure + +### 11. Formatting consistency + +**Text Elements**: + +- [ ] Consistent use of bold for UI elements + +- [ ] Consistent use of italics for emphasis + +- [ ] Consistent use of code formatting + +- [ ] No unnecessary ALL CAPS + +- [ ] Proper spacing and line breaks + +**Lists**: + +- [ ] Parallel structure in list items + +- [ ] Proper punctuation (periods for sentences) + +- [ ] Consistent capitalization + +- [ ] Numbered for sequential steps + +- [ ] Bullets for non-sequential items + +### 12. Specific content types + +**For Tutorials**: + +- [ ] Clear learning objectives stated + +- [ ] Prerequisites listed + +- [ ] Sequential, numbered steps + +- [ ] Complete working examples + +- [ ] Summary and next steps + +**For API Documentation**: + +- [ ] Operation IDs follow conventions + +- [ ] All parameters documented + +- [ ] Response schemas complete + +- [ ] Code samples included + +- [ ] Error responses documented + +**For Reference Pages**: + +- [ ] Comprehensive parameter tables + +- [ ] Default values specified + +- [ ] Type information included + +- [ ] Examples for complex options + +- [ ] Related pages linked + +## How to review + +### Step 1: Automated checks + +```bash +npm run lint:md # Markdown linting +npm run lint:code # Code linting +vale sync # Prose linting setup + +``` + +### Step 2: Manual review + +Go through each section of the checklist above, noting any issues. + +### Step 3: Provide feedback + +**Format your review as**: + +```markdown +## Documentation review: [File name] + +### ✅ Strengths + +- [What's done well] + +### ⚠️ Issues found + +#### Style guide + +- [ ] Issue 1: [Description] + + - Current: [Example] + + - Suggested: [Better example] + +#### Content + +- [ ] Issue 2: [Description] + +### 📝 Suggestions + +- [Optional improvement 1] + +- [Optional improvement 2] + +### 🎯 Priority issues + +1. [Critical issue to fix] + +2. [Important issue to fix] + +``` + +## Common issues + +### Issue: Title case or gerund headings + +```markdown +# ❌ Bad - Title Case +## How to create an Actor + +# ❌ Bad - Gerund +## Creating an Actor + +# ✅ Good - Sentence case, simple present tense +## How to create an Actor + +# ✅ Good - Simple present tense +## Create an Actor + +``` + +### Issue: Non-descriptive links + +```markdown +# ❌ Bad + +To learn more, click [here](link). + +# ✅ Good + +Learn more about [Actor input schemas](/actors/development/input-schema). + +``` + +### Issue: Missing front matter description + +```markdown +# ❌ Bad + +--- + +title: "Actors" + +--- + +# ✅ Good + +--- + +title: "Create an Actor" +description: "Learn how to build and deploy your first Actor with step-by-step instructions covering setup, development, and testing." + +--- + +``` + +### Issue: Long description or feature-focused + +```markdown +# ❌ Bad - Too long (190 chars) and feature-focused + +description: "This comprehensive documentation guide will teach you everything you need to know about creating, configuring, and deploying Actors on the Apify platform from start to finish." + +# ❌ Bad - Feature-focused, not value-focused + +description: "Documentation for Actor creation, configuration options, and deployment methods." + +# ✅ Good - Value-focused (145 chars) + +description: "Build and deploy Actors efficiently with this guide covering setup, development, testing, and best practices for production use." + +``` + +### Issue: Bold for emphasis + +```markdown +# ❌ Bad - bold used for emphasis + +Click the button and **ensure you verify** the settings. + +# ✅ Good - bold only for UI elements + +Click the **Save & Run** button and ensure you verify the settings. + +``` + +### Issue: Missing admonition title + +```markdown +# ❌ Bad - no title (REQUIRED) + +:::tip +Use pagination for large datasets. +::: + +# ✅ Good - has title + +:::tip Performance best practice +Use pagination for large datasets. +::: + +``` + +### Issue: Incorrect Apify terminology + +```markdown +# ❌ Bad + +The Apify Console allows you to manage your Apify actors. + +# ✅ Good + +Apify Console allows you to manage your Apify Actors. + +``` + +## Output format + +Provide a structured review using the format above, with: + +- Clear identification of issues + +- Specific examples from the content + +- Concrete suggestions for improvement + +- Priority ranking of issues + +## Quality standards + +A document is ready for publication when: + +- All checklist items pass + +- Automated linting passes + +- Content is technically accurate + +- Examples are tested and working + +- Style guide is followed consistently + +- No broken links + +- Proper front matter included + +- Accessibility standards met diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md new file mode 100644 index 0000000000..477316241c --- /dev/null +++ b/.claude/skills/tutorial.md @@ -0,0 +1,381 @@ +# Tutorial creator skill + +## Purpose + +Create comprehensive, structured tutorials for the Apify Academy or Platform documentation. + +## When to use + +- Creating new tutorials + +- Restructuring existing tutorials + +- Converting informal guides into proper tutorials + +- Building step-by-step learning content + +## Context files + +- `AGENTS.md` - Documentation standards + +- `CONTRIBUTING.md` - Style guide + +## Tutorial structure + +### 1. Front matter + +```yaml + +--- + +title: "Action-oriented tutorial title (sentence case, simple present tense)" +description: "Explain value, not features - what will user achieve (140-160 chars)" +sidebar_position: 1 +slug: /category/tutorial-name # Must match file path + +--- + +``` + +**Important**: + +- Use sentence case, NOT Title Case + +- Use simple present tense: "Create an Actor" NOT "Creating an Actor" + +- Match slug to file path + +### 2. Introduction section + +**Purpose**: Hook the reader and explain what they'll learn + +**Template**: + +```markdown +## [Tutorial title] + +**[Brief description of what the user will accomplish]** + +--- + +[Opening paragraph explaining the problem/use case this tutorial addresses] + +## What you'll learn + +In this tutorial, you'll learn how to: + +- [Learning objective 1] + +- [Learning objective 2] + +- [Learning objective 3] + +By the end, you'll be able to [specific outcome]. + +``` + +### 3. Prerequisites section + +**Purpose**: Set expectations for required knowledge and setup + +**Template**: + +```markdown +## Prerequisites + +Before starting this tutorial, make sure you have: + +- [ ] [Required knowledge/skill 1] + +- [ ] [Required tool/account 2] + +- [ ] [Required setup 3] + +**Time estimate**: [X] minutes + +``` + +### 4. Step-by-step instructions + +**Purpose**: Guide users through the process clearly and systematically + +**Guidelines**: + +- Use numbered lists for sequential steps + +- Start each step with an action verb + +- Include code examples for each major step + +- Add screenshots where helpful + +- Explain what each step accomplishes + +**Template**: + +```markdown +## Step 1: [Action verb] [what to do] + +[Brief explanation of what this step accomplishes] + +1. [First sub-step] + +2. [Second sub-step] + +​```language +// Code example with comments +const example = "code"; +​``` + +**Expected result**: [What should happen after this step] + +:::tip +[Helpful tip related to this step] +::: +``` + +### 5. Code examples section + +**Purpose**: Provide complete, working code that users can run + +**Guidelines**: + +- Include complete, runnable examples + +- Use code tabs for multiple languages + +- Add comprehensive comments + +- Show both input and output + +- Explain key parts of the code + +**Template**: + +```markdown +## Complete example + +Here's the complete code for this tutorial: + + + + +​```javascript +// Complete JavaScript example +// Comments explaining key sections +const example = "working code"; +​``` + + + + +​```python +"""Complete Python example with comments explaining key sections""" +example = "working code" +​``` + + + +``` + +### 6. Testing/verification section + +**Purpose**: Help users verify their implementation works + +**Template**: + +```markdown +## Testing your solution + +To verify everything works correctly: + +1. [Test step 1] + +2. [Test step 2] + +**Expected output**: + +​```text +[What the user should see] +​``` + +:::note +If you see [common error], check [solution]. +::: +``` + +### 7. Troubleshooting section + +**Purpose**: Address common issues users might encounter + +**Template**: + +```markdown +## Troubleshooting + +### [Common problem 1] + +**Symptom**: [What the user sees] + +**Solution**: [How to fix it] + +### [Common problem 2] + +**Symptom**: [What the user sees] + +**Solution**: [How to fix it] + +``` + +### 8. Summary/next steps + +**Purpose**: Reinforce learning and guide users forward + +**Template**: + +```markdown +## Summary + +In this tutorial, you learned how to: + +- ✅ [Accomplishment 1] + +- ✅ [Accomplishment 2] + +- ✅ [Accomplishment 3] + +## Next steps + +Now that you've completed this tutorial, you can: + +- [Related tutorial/topic 1] - [Link] + +- [Related tutorial/topic 2] - [Link] + +- [Advanced topic] - [Link] + +## Additional resources + +- [Related documentation link 1] + +- [Related documentation link 2] + +- [External resource link] + +``` + +## Tutorial types + +### Platform tutorial + +**Focus**: How to use Apify platform features +**Location**: `/sources/platform/` +**Style**: Practical, feature-focused + +### Academy tutorial + +**Focus**: Teaching web scraping or automation concepts +**Location**: `/sources/academy/tutorials/` +**Style**: Educational, concept-focused + +### Integration tutorial + +**Focus**: Connecting Apify with other tools +**Location**: `/sources/platform/integrations/` +**Style**: Step-by-step integration guide + +## Apify terminology + +Always use exact capitalization and phrasing: + +- **Apify Actor** (never "Apify actor") + +- **Apify Proxy** (never "Apify proxy") + +- **Apify Console** (never "the Apify Console") + +- **Apify Store** (never "the Apify Store") + +- **the Apify team** (lowercase) + +- **the Apify platform** (lowercase) + +- **AI agent**, **MCP server** (lowercase for generic terms) + +## Text formatting rules + +- **Bold** ONLY for UI elements (e.g., "Click **Save & Run**"). NEVER for emphasis. + +- Code blocks MUST specify language + +- **All admonitions MUST have a title** (REQUIRED) + +- Use Oxford commas in all lists + +- Use simple present tense for headings + +## Best practices + +1. **Start Simple**: Begin with basic concepts before advanced topics + +2. **Be Specific**: Use concrete examples rather than abstract explanations + +3. **Show, Don't Tell**: Include visual aids and code examples + +4. **Test Everything**: Ensure all code examples work + +5. **Anticipate Questions**: Address common points of confusion + +6. **Link Related Content**: Connect to other relevant tutorials + +7. **Keep Updated**: Mark tutorials with last-updated dates + +8. **User Perspective**: Write from the user's point of view + +9. **Never Make Assumptions**: About product features - ask if unsure + +10. **Use Simple English**: Prefer "use" over "utilize" + +## Quality checklist + +Before publishing: + +- [ ] Clear learning objectives stated upfront + +- [ ] Prerequisites clearly listed + +- [ ] All steps are numbered and action-oriented + +- [ ] Code examples are complete and tested + +- [ ] Screenshots included where helpful (light theme) + +- [ ] Common issues addressed in troubleshooting + +- [ ] Next steps and related content linked + +- [ ] Front matter complete with description (140-160 chars explaining value) + +- [ ] Slug matches file path + +- [ ] All code blocks have language specification (REQUIRED) + +- [ ] All admonitions have titles (REQUIRED) + +- [ ] Bold used ONLY for UI elements, never for emphasis + +- [ ] Oxford commas used in all lists + +- [ ] Proper heading hierarchy maintained (sentence case, simple present tense) + +- [ ] Active voice and simple English used throughout + +- [ ] Inclusive language verified + +- [ ] Correct Apify terminology used + +- [ ] No assumptions made about product features + +## Output + +Provide a complete tutorial following the structure above, ready to be added to the documentation. diff --git a/.markdownlintignore b/.markdownlintignore index dd87e2d73f..87b70a4bce 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -1,2 +1,3 @@ node_modules build +.claude diff --git a/.vale.ini b/.vale.ini index 282c31ca5a..b41626451e 100644 --- a/.vale.ini +++ b/.vale.ini @@ -32,3 +32,7 @@ Microsoft.GeneralURL = NO [{README.md,CONTRIBUTING.md}] Apify.H1 = NO + +[.claude/**/*.md] +# Ignore all Vale checks in .claude directory (infrastructure docs) +BasedOnStyles =