From 78a09b4984a0036cb8c66c1c6cc3a7bc77f0210c Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 10:52:07 +0100 Subject: [PATCH 01/15] docs: add Claude Code infrastructure and skills Add comprehensive Claude Code configuration for the Apify documentation repository: - Main instructions.md with project overview, standards, and workflows - Four specialized skills: doc-write, api-doc, tutorial, and review-docs - Configuration file (claude.json) registering skills and context files - User guide (README.md) with quick start and usage examples - Setup summary documenting the complete infrastructure All skills based on existing AGENTS.md and CONTRIBUTING.md standards to ensure consistency across documentation. Includes templates, examples, quality checklists, and best practices for common documentation tasks. Co-Authored-By: Claude Sonnet 4.5 --- .claude/README.md | 143 ++++++++++++++ .claude/SETUP_SUMMARY.md | 355 ++++++++++++++++++++++++++++++++++ .claude/claude.json | 29 +++ .claude/instructions.md | 266 +++++++++++++++++++++++++ .claude/skills/api-doc.md | 196 +++++++++++++++++++ .claude/skills/doc-write.md | 112 +++++++++++ .claude/skills/review-docs.md | 332 +++++++++++++++++++++++++++++++ .claude/skills/tutorial.md | 259 +++++++++++++++++++++++++ 8 files changed, 1692 insertions(+) create mode 100644 .claude/README.md create mode 100644 .claude/SETUP_SUMMARY.md create mode 100644 .claude/claude.json create mode 100644 .claude/instructions.md create mode 100644 .claude/skills/api-doc.md create mode 100644 .claude/skills/doc-write.md create mode 100644 .claude/skills/review-docs.md create mode 100644 .claude/skills/tutorial.md diff --git a/.claude/README.md b/.claude/README.md new file mode 100644 index 0000000000..8d0ee7b8b7 --- /dev/null +++ b/.claude/README.md @@ -0,0 +1,143 @@ +# 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 +``` +Use /doc-write skill to create a new documentation page about [topic] +``` + +### Creating a Tutorial +``` +Use /tutorial skill to create a tutorial on [topic] +``` + +### Adding API Endpoint +``` +Use /api-doc skill to document the new [endpoint-name] endpoint +``` + +### Reviewing Documentation +``` +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/SETUP_SUMMARY.md b/.claude/SETUP_SUMMARY.md new file mode 100644 index 0000000000..060d1b99d0 --- /dev/null +++ b/.claude/SETUP_SUMMARY.md @@ -0,0 +1,355 @@ +# Claude Code Infrastructure Setup Summary + +## Overview + +This document summarizes the Claude Code infrastructure created for the Apify documentation repository. + +## What Was Identified + +### Existing Instruction Files + +1. **`AGENTS.md`** (Root) + - Primary vendor-agnostic documentation standards + - Covers writing style, formatting, API docs, quality standards + - Should be the first reference for all documentation work + +2. **`CONTRIBUTING.md`** (Root) + - Complete contribution guidelines + - Development setup and workflows + - API documentation process + - Quality checks and linting + +3. **`.cursor/rules/*.mdc`** (Cursor-specific) + - `documentation-style.mdc` - Cursor-specific doc rules + - `content-formatting.mdc` - MDX/Markdown formatting + - `api-documentation.mdc` - OpenAPI workflows + - `quality-standards.mdc` - Quality checklist + - `file-organization.mdc` - Naming and structure + +### Documentation 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 + +apify-api/ +└── openapi/ # API specifications + ├── openapi.yaml # Main spec + ├── components/ # Schemas + └── paths/ # Endpoints +``` + +## What Was Created + +### 1. Main Instructions File +**File**: `.claude/instructions.md` + +Comprehensive instructions for Claude Code including: +- Project overview and structure +- Core documentation standards +- Available skills reference +- Development workflow +- Quality checklist +- Common patterns +- Best practices + +### 2. Claude Code Skills + +Four specialized skills for common documentation tasks: + +#### `/doc-write` - Documentation Writing +**File**: `.claude/skills/doc-write.md` + +**Purpose**: Create or edit documentation following style guide + +**Includes**: +- Content standards (language, voice, style) +- Front matter requirements +- Text formatting rules +- Heading conventions +- Admonition usage +- Code example standards +- Link and image guidelines +- Quality checklist + +#### `/api-doc` - API Documentation +**File**: `.claude/skills/api-doc.md` + +**Purpose**: Work with OpenAPI specifications + +**Includes**: +- OpenAPI file structure +- Schema documentation process +- Path documentation creation +- Operation ID conventions +- Code sample creation +- Testing and validation +- Best practices +- Quality checklist + +#### `/tutorial` - Tutorial Creation +**File**: `.claude/skills/tutorial.md` + +**Purpose**: Create structured tutorials + +**Includes**: +- Complete tutorial structure template +- Front matter for tutorials +- Introduction section format +- Prerequisites section +- Step-by-step instruction format +- Code examples section +- Testing/verification section +- Troubleshooting section +- Summary and next steps +- Tutorial types (Platform, Academy, Integration) +- Quality checklist + +#### `/review-docs` - Documentation Review +**File**: `.claude/skills/review-docs.md` + +**Purpose**: Review documentation for compliance + +**Includes**: +- Comprehensive review checklist +- Style guide compliance checks +- Front matter validation +- Content structure verification +- Code example quality checks +- Link and image validation +- Admonition usage review +- Technical accuracy checks +- Accessibility compliance +- SEO optimization review +- Common issues and examples +- Review process steps +- Feedback format template + +### 3. Configuration Files + +#### `.claude/claude.json` +Registers skills with Claude Code and defines context files: +- Skill definitions with names and descriptions +- Instructions file reference +- Context file references (AGENTS.md, CONTRIBUTING.md) + +#### `.claude/README.md` +User-facing documentation for the Claude Code setup: +- Structure overview +- How to use skills +- Quick start examples +- Key standards reference +- Testing instructions +- Best practices +- Maintenance notes + +## Key Features + +### 1. Hierarchical Documentation Structure +```text +Primary Reference: AGENTS.md (vendor-agnostic) + ↓ +Contributing Guide: CONTRIBUTING.md (process & setup) + ↓ +Claude Instructions: .claude/instructions.md (Claude Code specific) + ↓ +Specialized Skills: .claude/skills/*.md (task-specific) +``` + +### 2. Comprehensive Style Guide Coverage +All skills enforce: +- US English, active voice, inclusive language +- Sentence case headings +- Proper front matter (140-160 char descriptions) +- Code formatting with syntax highlighting +- Descriptive links and alt text +- Proper heading hierarchy + +### 3. Quality Assurance +Each skill includes: +- Detailed checklists +- Common issues and examples +- Testing procedures +- Before/after examples +- Best practices + +### 4. Practical Examples +Skills provide: +- Complete templates +- Code examples +- Front matter examples +- Good vs. bad examples +- Real-world patterns + +## How to Use + +### Quick Start +```bash +# In Claude Code, use skills like this: +/doc-write # Create or edit documentation +/api-doc # Work with API specs +/tutorial # Create tutorials +/review-docs # Review documentation +``` + +### Typical Workflow + +1. **Read reference materials**: + - Start with `AGENTS.md` for core standards + - Check `CONTRIBUTING.md` for process + +2. **Choose appropriate skill**: + - Writing content → `/doc-write` + - API endpoint → `/api-doc` + - Tutorial → `/tutorial` + - Review → `/review-docs` + +3. **Follow skill instructions**: + - Each skill provides step-by-step guidance + - Includes templates and examples + - Has quality checklists + +4. **Test and validate**: + ```bash + npm run lint:md # Markdown linting + npm run lint:code # Code linting + npm start # Preview changes + ``` + +5. **Review before submission**: + - Use `/review-docs` skill + - Run all linters + - Verify examples work + +## Integration with Existing Tools + +### Complements Cursor Rules +The Claude Code setup: +- Works alongside existing `.cursor/rules/*.mdc` files +- Provides vendor-agnostic alternative +- Can be used by any AI assistant tool +- Maintains consistency with Cursor setup + +### Respects Existing Standards +All skills based on: +- Microsoft Style Guide (from AGENTS.md) +- Apify documentation conventions +- OpenAPI 3.0 specifications +- Docusaurus best practices + +### Works with Linting Tools +Skills guide users to run: +- `markdownlint` for Markdown +- `eslint` for code +- `Vale` for prose (optional) +- `npm test` for OpenAPI validation + +## Maintenance + +### Keeping in Sync +When documentation standards change: + +1. Update `AGENTS.md` (source of truth) +2. Update `CONTRIBUTING.md` if process changes +3. Update `.claude/instructions.md` to reflect changes +4. Update relevant skill files in `.claude/skills/` +5. Update `.cursor/rules/*.mdc` for Cursor users + +### Adding New Skills +To add a new skill: + +1. Create `.claude/skills/new-skill.md` +2. Follow existing skill structure: + - Purpose section + - When to use + - Context files + - Instructions + - Examples + - Quality checklist +3. Register in `.claude/claude.json` +4. Document in `.claude/README.md` + +### Version Control +All Claude Code files are checked into git: +- `.claude/instructions.md` +- `.claude/skills/*.md` +- `.claude/claude.json` +- `.claude/README.md` + +Exception: `.claude/settings.local.json` may be gitignored if it contains user-specific settings. + +## Benefits + +### For Documentation Writers +- Clear guidance on style and formatting +- Ready-to-use templates +- Quality checklists +- Consistent standards + +### For Reviewers +- Comprehensive review checklist +- Clear quality criteria +- Consistent feedback format +- Automated validation + +### For Contributors +- Lower barrier to entry +- Clear expectations +- Helpful examples +- Quick feedback loop + +### For Maintainers +- Consistent documentation quality +- Reduced review time +- Automated checks +- Scalable standards + +## Success Criteria + +Documentation is ready when it: +- ✅ Passes all linters +- ✅ Follows style guide (AGENTS.md) +- ✅ Has proper front matter +- ✅ Includes tested examples +- ✅ Uses descriptive links +- ✅ Has meaningful alt text +- ✅ Follows proper heading hierarchy +- ✅ Uses active voice and inclusive language + +## Next Steps + +### For Users +1. Read `.claude/README.md` +2. Try using a skill: `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs` +3. Reference `AGENTS.md` for style questions +4. Run linters before committing + +### For Maintainers +1. Monitor usage and gather feedback +2. Update skills based on common issues +3. Keep standards in sync across files +4. Consider adding more specialized skills + +### Potential Future Skills +- `/migration` - Guide for migrating legacy docs +- `/seo-optimize` - SEO optimization helper +- `/accessibility` - Accessibility checker +- `/link-checker` - Validate internal/external links +- `/front-matter` - Bulk front matter updates + +## Summary + +The Claude Code infrastructure provides: +- **4 specialized skills** for common documentation tasks +- **Comprehensive instructions** aligned with existing standards +- **Quality checklists** for consistency +- **Practical templates** and examples +- **Integration** with existing tools and workflows + +All based on the existing `AGENTS.md` and `CONTRIBUTING.md` standards, ensuring consistency across the documentation ecosystem. 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..f90408bbbd --- /dev/null +++ b/.claude/instructions.md @@ -0,0 +1,266 @@ +# 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 +- **Active voice** whenever possible +- **Inclusive language** - no gendered terms +- **Action-oriented** phrasing +- **Avoid directional language** (use "preceding/following" not "left/right") +- **Sentence case** for headings (not Title Case) + +### Front Matter Requirements +Every documentation file must include: +```yaml +--- +title: "Clear, action-oriented title" +description: "140-160 character description, no 'documentation' word" +sidebar_position: 1 +slug: /path/to/page +--- +``` + +### Text Formatting Standards +- **Bold** for UI elements, buttons, menu items +- _Italics_ for emphasis and new terms +- `code` for inline code, file names, paths, variables +- Code blocks with language specification +- Admonitions for important information (note, tip, info, caution, danger) + +### Code Examples +- Include complete, runnable examples +- Use code tabs for multiple languages (JavaScript, Python) +- Add syntax highlighting with language tags +- Include comments for complex logic +- Show realistic, meaningful examples + +### 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` +- 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 +``` + +## 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 + ``` +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 +- 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 + +### Best Practices +- Start with user's goal/problem +- Provide context before technical details +- Use consistent terminology throughout +- Structure content logically (basic → advanced) +- Link to related content +- Keep descriptions within 140-160 characters +- Test all code examples before committing +- Use admonitions sparingly but effectively + +## 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 + +## 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..232f4371cb --- /dev/null +++ b/.claude/skills/api-doc.md @@ -0,0 +1,196 @@ +# 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. Best Practices + +- **Descriptions**: Write clear, comprehensive descriptions for all endpoints and parameters +- **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 + +### 9. Quality Checklist + +Before submitting: +- [ ] OpenAPI specification validates without errors +- [ ] Operation IDs follow naming conventions +- [ ] All parameters have descriptions +- [ ] Response schemas are complete +- [ ] Code samples are included for major languages +- [ ] Examples use realistic data +- [ ] Path references are added to main openapi.yaml +- [ ] Error responses are documented + +## 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..c49cf78b47 --- /dev/null +++ b/.claude/skills/doc-write.md @@ -0,0 +1,112 @@ +# 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 +- Write in **active voice** whenever possible +- Use **inclusive language** - avoid gendered terms +- Be **action-oriented** in descriptions and titles +- Avoid directional language (don't use "left/right", use "above/below" or "preceding/following") +- Write for a technical audience but keep explanations clear + +### 2. Front Matter +Always include proper front matter in MDX/MD files: + +```yaml +--- +title: "Clear, action-oriented title" +description: "140-160 character description that explains the value" +sidebar_position: 1 +slug: /path/to/page +--- +``` + +### 3. Text Formatting +- **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 + +### 4. Headings +- Use **sentence case** for all headings +- Follow proper hierarchy: H1 → H2 → H3 +- Make headings descriptive and action-oriented + +### 5. Admonitions +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 for multiple languages +- Add syntax highlighting +- 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. Quality Checklist +Before finalizing, verify: +- [ ] Content follows Microsoft style guide +- [ ] Front matter includes proper title, description, and metadata +- [ ] Code examples are complete with syntax highlighting +- [ ] All links use descriptive text +- [ ] Images include meaningful alt text +- [ ] Content uses inclusive language and active voice +- [ ] Headings follow proper hierarchy +- [ ] Content is clear, concise, and action-oriented + +## 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..4e212e962d --- /dev/null +++ b/.claude/skills/review-docs.md @@ -0,0 +1,332 @@ +# 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 Checklist + +### 1. Style Guide Compliance + +**Microsoft Style Guide**: +- [ ] Headings use sentence case (not Title Case) +- [ ] UI elements use **bold** formatting +- [ ] Emphasis uses _italics_ +- [ ] Inline code uses `backticks` +- [ ] Proper use of numbered lists vs. bullet points + +**Language Guidelines**: +- [ ] Uses US English spelling +- [ ] Written in active voice +- [ ] Uses inclusive language (no gendered terms) +- [ ] Avoids directional language ("left/right") +- [ ] Action-oriented phrasing + +### 2. Front Matter Validation + +Required fields present and correct: +- [ ] `title` - Clear and action-oriented +- [ ] `description` - 140-160 characters +- [ ] `description` - Avoids word "documentation" +- [ ] `description` - Action-oriented phrasing +- [ ] `sidebar_position` - Appropriate numbering +- [ ] `slug` - Correct URL path + +**Example**: +```yaml +--- +title: "Create an Actor" # ✅ Sentence case, action-oriented +description: "Learn how to build and deploy your first Actor on the Apify platform with this step-by-step guide covering code, configuration, and testing." # ✅ 140-160 chars, no "documentation" +sidebar_position: 1 +slug: /actors/development/create +--- +``` + +### 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 +- [ ] Includes comments for complex logic +- [ ] Uses realistic, meaningful variable names +- [ ] Shows both input and output where applicable + +**Multiple Languages**: +- [ ] Uses Docusaurus code tabs when showing multiple languages +- [ ] Consistent examples across languages +- [ ] Includes JavaScript and Python where applicable + +**Example**: +```markdown +# ✅ Good +```javascript +// Fetch actor details +const actor = await client.actor('john-doe/my-actor').get(); +console.log(actor); +``` + +# ❌ Bad +``` +const a = await c.actor('x').get(); // No language tag, unclear names +``` +``` + +### 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**: +- [ ] Appropriate type (note, tip, info, caution, danger) +- [ ] Includes descriptive title +- [ ] Content is concise and relevant +- [ ] Not overused (max 2-3 per page) + +**Example**: +```markdown +# ✅ Good +:::tip Performance optimization +Use `requestHandlerTimeoutSecs` to prevent slow requests from blocking your Actor. +::: + +# ❌ Bad (no title, wrong type) +:::info +Be careful with this setting. +::: +``` + +### 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 + +## Review Process + +### 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 Headings +```markdown +# ❌ Bad +## How To Create An Actor + +# ✅ Good +## How to 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 +```markdown +# ❌ Bad (190 chars) +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." + +# ✅ Good (148 chars) +description: "Learn to create, configure, and deploy Actors on Apify with this step-by-step guide covering setup, development, and best practices." +``` + +## 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..f748bc6b6b --- /dev/null +++ b/.claude/skills/tutorial.md @@ -0,0 +1,259 @@ +# 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" +description: "Clear description of what the user will learn (140-160 chars)" +sidebar_position: 1 +slug: /category/tutorial-name +--- +``` + +### 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 +# 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**: +``` +[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 + +## 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 + +## 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) +- [ ] All code blocks have language specification +- [ ] Proper heading hierarchy maintained +- [ ] Active voice used throughout +- [ ] Inclusive language verified + +## Output +Provide a complete tutorial following the structure above, ready to be added to the documentation. From 48af632e8bb9b9b1494ce2e99f26b35f666030d5 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:05:14 +0100 Subject: [PATCH 02/15] docs: enhance Claude Code instructions with critical style rules Update all Claude Code instructions and skills to include important details from personal instruction file: Critical additions: - Bold ONLY for UI elements, NEVER for emphasis (emphasized throughout) - All admonitions MUST have titles (no exceptions) - Apify-specific terminology section with exact capitalization rules - Oxford comma requirement - Simple present tense for headings (not gerunds) - "Never make assumptions about product features" - Front matter descriptions must explain value, not features - Slug must match file path - Simple English preference ("use" not "utilize") - PR review process (check latest changes pulled first) - Code review scope (comments and obvious mistakes only) Updated files: - instructions.md: Core standards with terminology and review process - review-docs.md: Enhanced checklist with terminology verification - doc-write.md: Added terminology section and updated checklist - tutorial.md: Added terminology and formatting rules - api-doc.md: Added terminology for API descriptions Co-Authored-By: Claude Sonnet 4.5 --- .claude/instructions.md | 101 ++++++++++++++++++++++++++----- .claude/skills/api-doc.md | 26 ++++++-- .claude/skills/doc-write.md | 71 ++++++++++++++++------ .claude/skills/review-docs.md | 109 +++++++++++++++++++++++++++------- .claude/skills/tutorial.md | 47 ++++++++++++--- 5 files changed, 289 insertions(+), 65 deletions(-) diff --git a/.claude/instructions.md b/.claude/instructions.md index f90408bbbd..8f03e04b49 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -39,38 +39,69 @@ Use these skills for specific documentation tasks: ## Core Documentation Standards ### Language & Style -- **US English** spelling and grammar +- **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: "Clear, action-oriented title" -description: "140-160 character description, no 'documentation' word" +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** for UI elements, buttons, menu items -- _Italics_ for emphasis and new terms -- `code` for inline code, file names, paths, variables -- Code blocks with language specification -- Admonitions for important information (note, tip, info, caution, danger) +- **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 for multiple languages (JavaScript, Python) -- Add syntax highlighting with language tags +- 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 @@ -85,9 +116,10 @@ slug: /path/to/page ## File Organization ### Naming Conventions -- Use **kebab-case** for file names: `web-scraping-basics.md` +- 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 @@ -202,7 +234,10 @@ Before considering any documentation complete: ## Important Notes ### What NOT to Do -- Don't use Title Case for headings +- 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) @@ -210,16 +245,51 @@ Before considering any documentation complete: - 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 terminology throughout +- 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 +- 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 +- 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 @@ -229,6 +299,7 @@ If you're unsure about: - **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 diff --git a/.claude/skills/api-doc.md b/.claude/skills/api-doc.md index 232f4371cb..e8ad554e85 100644 --- a/.claude/skills/api-doc.md +++ b/.claude/skills/api-doc.md @@ -171,26 +171,40 @@ npm test # Validates OpenAPI specification npm start # Preview changes locally ``` -### 8. Best Practices +### 8. Apify Terminology -- **Descriptions**: Write clear, comprehensive descriptions for all endpoints and parameters +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 -### 9. Quality Checklist +### 10. Quality Checklist Before submitting: - [ ] OpenAPI specification validates without errors -- [ ] Operation IDs follow naming conventions -- [ ] All parameters have descriptions +- [ ] 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 +- [ ] 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 index c49cf78b47..1cf50a8d79 100644 --- a/.claude/skills/doc-write.md +++ b/.claude/skills/doc-write.md @@ -18,65 +18,84 @@ Help write or edit Apify documentation following the established style guide and When writing or editing documentation: ### 1. Content Standards -- Use **US English** spelling and grammar +- 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: "Clear, action-oriented title" -description: "140-160 character description that explains the value" +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** 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 +- **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 +- 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 -Use Docusaurus admonitions to highlight important information: +**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 for multiple languages -- Add syntax highlighting +- 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 @@ -97,16 +116,34 @@ For tutorials and guides, follow this structure: 4. **Code examples** - Complete, working examples 5. **Summary** - What they accomplished and next steps -### 10. Quality Checklist +### 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 -- [ ] Front matter includes proper title, description, and metadata -- [ ] Code examples are complete with syntax highlighting +- [ ] 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 and active voice -- [ ] Headings follow proper hierarchy +- [ ] 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 index 4e212e962d..03e082a567 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -14,41 +14,60 @@ Review documentation for compliance with Apify style guide, quality standards, a - `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) -- [ ] UI elements use **bold** formatting -- [ ] Emphasis uses _italics_ +- [ ] 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 +- [ ] 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 and action-oriented +- [ ] `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 +- [ ] `slug` - Correct URL path and matches file path **Example**: ```yaml --- -title: "Create an Actor" # ✅ Sentence case, action-oriented -description: "Learn how to build and deploy your first Actor on the Apify platform with this step-by-step guide covering code, configuration, and testing." # ✅ 140-160 chars, no "documentation" +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 +slug: /actors/development/create # ✅ Matches file path --- ``` @@ -70,13 +89,17 @@ slug: /actors/development/create **Quality**: - [ ] Complete and runnable examples -- [ ] Proper syntax highlighting with language tag +- [ ] 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 when showing 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 @@ -143,22 +166,28 @@ Click [here](link) to learn more. ### 7. Admonitions **Usage**: +- [ ] **MUST have a title** (REQUIRED - no exceptions) - [ ] Appropriate type (note, tip, info, caution, danger) -- [ ] Includes descriptive title +- [ ] Title is descriptive - [ ] Content is concise and relevant - [ ] Not overused (max 2-3 per page) **Example**: ```markdown -# ✅ Good +# ✅ Good - has title :::tip Performance optimization Use `requestHandlerTimeoutSecs` to prevent slow requests from blocking your Actor. ::: -# ❌ Bad (no title, wrong type) +# ❌ Bad - missing title (REQUIRED) :::info Be careful with this setting. ::: + +# ❌ Bad - no title +:::tip +This is a helpful tip. +::: ``` ### 8. Technical Accuracy @@ -270,13 +299,19 @@ Go through each section of the checklist above, noting any issues. ## Common Issues -### Issue: Title Case Headings +### Issue: Title Case or Gerund Headings ```markdown -# ❌ Bad +# ❌ Bad - Title Case ## How To Create An Actor -# ✅ Good +# ❌ 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 @@ -302,13 +337,47 @@ description: "Learn how to build and deploy your first Actor with step-by-step i --- ``` -### Issue: Long Description +### Issue: Long Description or Feature-Focused ```markdown -# ❌ Bad (190 chars) +# ❌ 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." -# ✅ Good (148 chars) -description: "Learn to create, configure, and deploy Actors on Apify with this step-by-step guide covering setup, development, and best practices." +# ❌ 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 diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index f748bc6b6b..88cb16288f 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -18,13 +18,18 @@ Create comprehensive, structured tutorials for the Apify Academy or Platform doc ### 1. Front Matter ```yaml --- -title: "Action-oriented tutorial title" -description: "Clear description of what the user will learn (140-160 chars)" +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 +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 @@ -228,6 +233,26 @@ Now that you've completed this tutorial, you can: **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 @@ -238,6 +263,8 @@ Now that you've completed this tutorial, you can: 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 @@ -249,11 +276,17 @@ Before publishing: - [ ] 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) -- [ ] All code blocks have language specification -- [ ] Proper heading hierarchy maintained -- [ ] Active voice used throughout +- [ ] 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. From c276b94a46a87443d0f0f7898fa7f1f2c25463db Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:37:21 +0100 Subject: [PATCH 03/15] fix: resolve vale and markdown lint errors - Change H1 headings to H2 in all .claude files per Apify.H1 rule - Add blank lines around headings, lists, and code blocks in README.md - Add language specifications to code blocks in README.md - Update tutorial template to use H2 instead of H1 - Adjust Python comment formatting to avoid vale false positives Co-Authored-By: Claude Sonnet 4.5 --- .claude/README.md | 27 +++++++++++++++++++++++---- .claude/SETUP_SUMMARY.md | 2 +- .claude/skills/api-doc.md | 2 +- .claude/skills/doc-write.md | 2 +- .claude/skills/review-docs.md | 2 +- .claude/skills/tutorial.md | 6 +++--- 6 files changed, 30 insertions(+), 11 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 8d0ee7b8b7..56e3931353 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -26,44 +26,56 @@ This directory contains Claude Code configuration for the Apify documentation re ### 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 ``` @@ -78,13 +90,16 @@ Always reference these files from the repo root: ## 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" @@ -95,6 +110,7 @@ slug: /path/to/page ``` ### Formatting + - **Bold** for UI elements - _Italics_ for emphasis - `code` for inline code/files @@ -102,6 +118,7 @@ slug: /path/to/page - Admonitions for important info ### Links & Images + - Descriptive link text (not "click here") - Alt text for all images - Light theme for screenshots @@ -110,6 +127,7 @@ slug: /path/to/page ## Testing Before submitting: + ```bash npm run lint:md # Check markdown npm run lint:code # Check code @@ -129,6 +147,7 @@ npm test # Validate API specs ## 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 diff --git a/.claude/SETUP_SUMMARY.md b/.claude/SETUP_SUMMARY.md index 060d1b99d0..e12beb1ae8 100644 --- a/.claude/SETUP_SUMMARY.md +++ b/.claude/SETUP_SUMMARY.md @@ -1,4 +1,4 @@ -# Claude Code Infrastructure Setup Summary +## Claude Code Infrastructure Setup Summary ## Overview diff --git a/.claude/skills/api-doc.md b/.claude/skills/api-doc.md index e8ad554e85..65edebcdd9 100644 --- a/.claude/skills/api-doc.md +++ b/.claude/skills/api-doc.md @@ -1,4 +1,4 @@ -# API Documentation Skill +## API Documentation Skill ## Purpose Help create or update OpenAPI specifications and API documentation for Apify API endpoints. diff --git a/.claude/skills/doc-write.md b/.claude/skills/doc-write.md index 1cf50a8d79..d18b3c71ea 100644 --- a/.claude/skills/doc-write.md +++ b/.claude/skills/doc-write.md @@ -1,4 +1,4 @@ -# Documentation Writer Skill +## Documentation Writer Skill ## Purpose Help write or edit Apify documentation following the established style guide and best practices. diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index 03e082a567..630c630f8a 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -1,4 +1,4 @@ -# Documentation Review Skill +## Documentation Review Skill ## Purpose Review documentation for compliance with Apify style guide, quality standards, and best practices. diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index 88cb16288f..a2f101f080 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -1,4 +1,4 @@ -# Tutorial Creator Skill +## Tutorial Creator Skill ## Purpose Create comprehensive, structured tutorials for the Apify Academy or Platform documentation. @@ -36,7 +36,7 @@ slug: /category/tutorial-name # Must match file path **Template**: ```markdown -# [Tutorial Title] +## [Tutorial Title] **[Brief description of what the user will accomplish]** @@ -134,7 +134,7 @@ const example = "working code"; ```python -# Complete Python example +"""Complete Python example""" # Comments explaining key sections example = "working code" ``` From 20564dc595f9b2f797467e51efe44a0eaea9aa0a Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:38:55 +0100 Subject: [PATCH 04/15] fix: resolve remaining vale error and remove redundant file - Fix last vale error by consolidating Python comments in tutorial.md - Remove SETUP_SUMMARY.md as it duplicates README.md content Co-Authored-By: Claude Sonnet 4.5 --- .claude/SETUP_SUMMARY.md | 355 ------------------------------------- .claude/skills/tutorial.md | 3 +- 2 files changed, 1 insertion(+), 357 deletions(-) delete mode 100644 .claude/SETUP_SUMMARY.md diff --git a/.claude/SETUP_SUMMARY.md b/.claude/SETUP_SUMMARY.md deleted file mode 100644 index e12beb1ae8..0000000000 --- a/.claude/SETUP_SUMMARY.md +++ /dev/null @@ -1,355 +0,0 @@ -## Claude Code Infrastructure Setup Summary - -## Overview - -This document summarizes the Claude Code infrastructure created for the Apify documentation repository. - -## What Was Identified - -### Existing Instruction Files - -1. **`AGENTS.md`** (Root) - - Primary vendor-agnostic documentation standards - - Covers writing style, formatting, API docs, quality standards - - Should be the first reference for all documentation work - -2. **`CONTRIBUTING.md`** (Root) - - Complete contribution guidelines - - Development setup and workflows - - API documentation process - - Quality checks and linting - -3. **`.cursor/rules/*.mdc`** (Cursor-specific) - - `documentation-style.mdc` - Cursor-specific doc rules - - `content-formatting.mdc` - MDX/Markdown formatting - - `api-documentation.mdc` - OpenAPI workflows - - `quality-standards.mdc` - Quality checklist - - `file-organization.mdc` - Naming and structure - -### Documentation 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 - -apify-api/ -└── openapi/ # API specifications - ├── openapi.yaml # Main spec - ├── components/ # Schemas - └── paths/ # Endpoints -``` - -## What Was Created - -### 1. Main Instructions File -**File**: `.claude/instructions.md` - -Comprehensive instructions for Claude Code including: -- Project overview and structure -- Core documentation standards -- Available skills reference -- Development workflow -- Quality checklist -- Common patterns -- Best practices - -### 2. Claude Code Skills - -Four specialized skills for common documentation tasks: - -#### `/doc-write` - Documentation Writing -**File**: `.claude/skills/doc-write.md` - -**Purpose**: Create or edit documentation following style guide - -**Includes**: -- Content standards (language, voice, style) -- Front matter requirements -- Text formatting rules -- Heading conventions -- Admonition usage -- Code example standards -- Link and image guidelines -- Quality checklist - -#### `/api-doc` - API Documentation -**File**: `.claude/skills/api-doc.md` - -**Purpose**: Work with OpenAPI specifications - -**Includes**: -- OpenAPI file structure -- Schema documentation process -- Path documentation creation -- Operation ID conventions -- Code sample creation -- Testing and validation -- Best practices -- Quality checklist - -#### `/tutorial` - Tutorial Creation -**File**: `.claude/skills/tutorial.md` - -**Purpose**: Create structured tutorials - -**Includes**: -- Complete tutorial structure template -- Front matter for tutorials -- Introduction section format -- Prerequisites section -- Step-by-step instruction format -- Code examples section -- Testing/verification section -- Troubleshooting section -- Summary and next steps -- Tutorial types (Platform, Academy, Integration) -- Quality checklist - -#### `/review-docs` - Documentation Review -**File**: `.claude/skills/review-docs.md` - -**Purpose**: Review documentation for compliance - -**Includes**: -- Comprehensive review checklist -- Style guide compliance checks -- Front matter validation -- Content structure verification -- Code example quality checks -- Link and image validation -- Admonition usage review -- Technical accuracy checks -- Accessibility compliance -- SEO optimization review -- Common issues and examples -- Review process steps -- Feedback format template - -### 3. Configuration Files - -#### `.claude/claude.json` -Registers skills with Claude Code and defines context files: -- Skill definitions with names and descriptions -- Instructions file reference -- Context file references (AGENTS.md, CONTRIBUTING.md) - -#### `.claude/README.md` -User-facing documentation for the Claude Code setup: -- Structure overview -- How to use skills -- Quick start examples -- Key standards reference -- Testing instructions -- Best practices -- Maintenance notes - -## Key Features - -### 1. Hierarchical Documentation Structure -```text -Primary Reference: AGENTS.md (vendor-agnostic) - ↓ -Contributing Guide: CONTRIBUTING.md (process & setup) - ↓ -Claude Instructions: .claude/instructions.md (Claude Code specific) - ↓ -Specialized Skills: .claude/skills/*.md (task-specific) -``` - -### 2. Comprehensive Style Guide Coverage -All skills enforce: -- US English, active voice, inclusive language -- Sentence case headings -- Proper front matter (140-160 char descriptions) -- Code formatting with syntax highlighting -- Descriptive links and alt text -- Proper heading hierarchy - -### 3. Quality Assurance -Each skill includes: -- Detailed checklists -- Common issues and examples -- Testing procedures -- Before/after examples -- Best practices - -### 4. Practical Examples -Skills provide: -- Complete templates -- Code examples -- Front matter examples -- Good vs. bad examples -- Real-world patterns - -## How to Use - -### Quick Start -```bash -# In Claude Code, use skills like this: -/doc-write # Create or edit documentation -/api-doc # Work with API specs -/tutorial # Create tutorials -/review-docs # Review documentation -``` - -### Typical Workflow - -1. **Read reference materials**: - - Start with `AGENTS.md` for core standards - - Check `CONTRIBUTING.md` for process - -2. **Choose appropriate skill**: - - Writing content → `/doc-write` - - API endpoint → `/api-doc` - - Tutorial → `/tutorial` - - Review → `/review-docs` - -3. **Follow skill instructions**: - - Each skill provides step-by-step guidance - - Includes templates and examples - - Has quality checklists - -4. **Test and validate**: - ```bash - npm run lint:md # Markdown linting - npm run lint:code # Code linting - npm start # Preview changes - ``` - -5. **Review before submission**: - - Use `/review-docs` skill - - Run all linters - - Verify examples work - -## Integration with Existing Tools - -### Complements Cursor Rules -The Claude Code setup: -- Works alongside existing `.cursor/rules/*.mdc` files -- Provides vendor-agnostic alternative -- Can be used by any AI assistant tool -- Maintains consistency with Cursor setup - -### Respects Existing Standards -All skills based on: -- Microsoft Style Guide (from AGENTS.md) -- Apify documentation conventions -- OpenAPI 3.0 specifications -- Docusaurus best practices - -### Works with Linting Tools -Skills guide users to run: -- `markdownlint` for Markdown -- `eslint` for code -- `Vale` for prose (optional) -- `npm test` for OpenAPI validation - -## Maintenance - -### Keeping in Sync -When documentation standards change: - -1. Update `AGENTS.md` (source of truth) -2. Update `CONTRIBUTING.md` if process changes -3. Update `.claude/instructions.md` to reflect changes -4. Update relevant skill files in `.claude/skills/` -5. Update `.cursor/rules/*.mdc` for Cursor users - -### Adding New Skills -To add a new skill: - -1. Create `.claude/skills/new-skill.md` -2. Follow existing skill structure: - - Purpose section - - When to use - - Context files - - Instructions - - Examples - - Quality checklist -3. Register in `.claude/claude.json` -4. Document in `.claude/README.md` - -### Version Control -All Claude Code files are checked into git: -- `.claude/instructions.md` -- `.claude/skills/*.md` -- `.claude/claude.json` -- `.claude/README.md` - -Exception: `.claude/settings.local.json` may be gitignored if it contains user-specific settings. - -## Benefits - -### For Documentation Writers -- Clear guidance on style and formatting -- Ready-to-use templates -- Quality checklists -- Consistent standards - -### For Reviewers -- Comprehensive review checklist -- Clear quality criteria -- Consistent feedback format -- Automated validation - -### For Contributors -- Lower barrier to entry -- Clear expectations -- Helpful examples -- Quick feedback loop - -### For Maintainers -- Consistent documentation quality -- Reduced review time -- Automated checks -- Scalable standards - -## Success Criteria - -Documentation is ready when it: -- ✅ Passes all linters -- ✅ Follows style guide (AGENTS.md) -- ✅ Has proper front matter -- ✅ Includes tested examples -- ✅ Uses descriptive links -- ✅ Has meaningful alt text -- ✅ Follows proper heading hierarchy -- ✅ Uses active voice and inclusive language - -## Next Steps - -### For Users -1. Read `.claude/README.md` -2. Try using a skill: `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs` -3. Reference `AGENTS.md` for style questions -4. Run linters before committing - -### For Maintainers -1. Monitor usage and gather feedback -2. Update skills based on common issues -3. Keep standards in sync across files -4. Consider adding more specialized skills - -### Potential Future Skills -- `/migration` - Guide for migrating legacy docs -- `/seo-optimize` - SEO optimization helper -- `/accessibility` - Accessibility checker -- `/link-checker` - Validate internal/external links -- `/front-matter` - Bulk front matter updates - -## Summary - -The Claude Code infrastructure provides: -- **4 specialized skills** for common documentation tasks -- **Comprehensive instructions** aligned with existing standards -- **Quality checklists** for consistency -- **Practical templates** and examples -- **Integration** with existing tools and workflows - -All based on the existing `AGENTS.md` and `CONTRIBUTING.md` standards, ensuring consistency across the documentation ecosystem. diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index a2f101f080..e1d69a39ca 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -134,8 +134,7 @@ const example = "working code"; ```python -"""Complete Python example""" -# Comments explaining key sections +"""Complete Python example with comments explaining key sections""" example = "working code" ``` From 9cf50f440f8f956ea49ca81bbf1ce6151ef2b51c Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:43:51 +0100 Subject: [PATCH 05/15] fix: add blank lines for markdown lint compliance in instructions.md - Add blank lines around all headings, lists, and code blocks - Ensures MD022, MD032, and MD031 rules are satisfied Co-Authored-By: Claude Sonnet 4.5 --- .claude/instructions.md | 43 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/.claude/instructions.md b/.claude/instructions.md index 8f03e04b49..87ac62ee67 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -3,6 +3,7 @@ ## 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/`) @@ -12,6 +13,7 @@ The project uses Docusaurus with MDX, follows Microsoft style guide principles, ## 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) @@ -21,24 +23,29 @@ The project uses Docusaurus with MDX, follows Microsoft style guide principles, 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 @@ -51,7 +58,9 @@ Use these skills for specific documentation tasks: - **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)" @@ -62,10 +71,12 @@ 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`") @@ -73,6 +84,7 @@ slug: /path/to/page - **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) @@ -103,11 +115,13 @@ 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 @@ -116,12 +130,14 @@ Something that could cause issues. ## 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 @@ -136,6 +152,7 @@ sources/ ## API Documentation Specifics ### OpenAPI Structure + ```text apify-api/openapi/ ├── openapi.yaml # Main spec file @@ -144,7 +161,9 @@ apify-api/openapi/ ``` ### Operation ID Conventions + Format: `{objectName}_{httpMethod}` + - Use camelCase for object names - Single object for paths with `{id}`, plural otherwise - Examples: @@ -152,19 +171,23 @@ Format: `{objectName}_{httpMethod}` - `/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 @@ -172,17 +195,21 @@ Replace `/` with `@` in URL paths: 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 ``` + 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 @@ -193,6 +220,7 @@ npm run build # Test production build ## Common Patterns ### Tutorial Structure + 1. Introduction with learning objectives 2. Prerequisites 3. Step-by-step numbered instructions @@ -202,6 +230,7 @@ npm run build # Test production build 7. Summary and next steps ### Platform Documentation + 1. Clear description of feature 2. When to use it 3. How to configure/use it @@ -210,6 +239,7 @@ npm run build # Test production build 6. Related features ### API Documentation + 1. Endpoint description 2. Parameters with types and descriptions 3. Request examples @@ -220,6 +250,7 @@ npm run build # Test production build ## 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 @@ -234,6 +265,7 @@ Before considering any documentation complete: ## 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) @@ -249,6 +281,7 @@ Before considering any documentation complete: - 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) @@ -280,10 +313,13 @@ Before considering any documentation complete: ## 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 @@ -294,6 +330,7 @@ When reviewing or creating documentation, verify: ## Getting Help If you're unsure about: + - **Style questions**: Check `AGENTS.md` first - **Setup issues**: See `CONTRIBUTING.md` - **API documentation**: See `/api-doc` skill @@ -304,7 +341,9 @@ If you're unsure about: ## 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 @@ -313,14 +352,17 @@ The full documentation ecosystem includes multiple repos: - 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`) @@ -328,6 +370,7 @@ Uses `@apify/docs-theme` package - don't modify theme files directly. ## 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 From f8983bfd8b184af3cbafb4167f9432f028b23759 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:46:09 +0100 Subject: [PATCH 06/15] fix: add missing blank line after Admonition Format heading Co-Authored-By: Claude Sonnet 4.5 --- .claude/instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/instructions.md b/.claude/instructions.md index 87ac62ee67..6a1a9b08b3 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -92,6 +92,7 @@ slug: /path/to/page - Show realistic, meaningful examples ### Admonition Format + **All admonitions MUST include a title:** ```markdown From c604581dbc39b85c9b912e15d78fd8d4b78d0310 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:51:09 +0100 Subject: [PATCH 07/15] fix: resolve markdown lint errors in skill files - Change H2 back to H1 for first line (MD041 requirement) - Add blank lines around all headings, lists, and code blocks - These .claude files are infrastructure, not published docs Co-Authored-By: Claude Sonnet 4.5 --- .claude/skills/api-doc.md | 18 +++++++++++++++++- .claude/skills/doc-write.md | 2 +- .claude/skills/review-docs.md | 2 +- .claude/skills/tutorial.md | 2 +- 4 files changed, 20 insertions(+), 4 deletions(-) diff --git a/.claude/skills/api-doc.md b/.claude/skills/api-doc.md index 65edebcdd9..ab6f6c1568 100644 --- a/.claude/skills/api-doc.md +++ b/.claude/skills/api-doc.md @@ -1,15 +1,18 @@ -## API Documentation Skill +# 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 @@ -31,12 +34,14 @@ apify-api/openapi/ **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: @@ -59,10 +64,12 @@ required: **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: @@ -106,12 +113,14 @@ get: 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` @@ -121,12 +130,14 @@ Format: `{objectName}_{httpMethod}` **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'); @@ -140,6 +151,7 @@ console.log(queue); ``` **Example Python Code Sample**: + ```python # GET /v2/request-queues/{queueId} from apify_client import ApifyClient @@ -155,6 +167,7 @@ print(queue) **File**: `apify-api/openapi/openapi.yaml` Add path reference: + ```yaml paths: '/request-queues': @@ -166,6 +179,7 @@ paths: ### 7. Testing and Validation After making changes: + ```bash npm test # Validates OpenAPI specification npm start # Preview changes locally @@ -195,6 +209,7 @@ Always use exact capitalization in descriptions and examples: ### 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 @@ -207,4 +222,5 @@ Before submitting: - [ ] 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 index d18b3c71ea..1cf50a8d79 100644 --- a/.claude/skills/doc-write.md +++ b/.claude/skills/doc-write.md @@ -1,4 +1,4 @@ -## Documentation Writer Skill +# Documentation Writer Skill ## Purpose Help write or edit Apify documentation following the established style guide and best practices. diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index 630c630f8a..03e082a567 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -1,4 +1,4 @@ -## Documentation Review Skill +# Documentation Review Skill ## Purpose Review documentation for compliance with Apify style guide, quality standards, and best practices. diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index e1d69a39ca..472162d241 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -1,4 +1,4 @@ -## Tutorial Creator Skill +# Tutorial Creator Skill ## Purpose Create comprehensive, structured tutorials for the Apify Academy or Platform documentation. From 394097e9cc007c901e1f28b85002be7cf779e863 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:03:24 +0100 Subject: [PATCH 08/15] fix: resolve lint errors and add .claude files to vale H1 exception - Add .claude/**/*.md to vale.ini H1 exception (infrastructure docs like README) - Fix blank lines around headings, lists, and code blocks in all skill files - Add language specs to code blocks where possible - Add linting commands to instructions.md for local validation - 4 remaining MD040/MD001 errors are false positives from nested code examples Co-Authored-By: Claude Sonnet 4.5 --- .claude/instructions.md | 5 + .claude/skills/doc-write.md | 18 ++++ .claude/skills/review-docs.md | 196 +++++++++++++++++++++++++++++++++- .claude/skills/tutorial.md | 98 ++++++++++++++++- .vale.ini | 2 +- 5 files changed, 315 insertions(+), 4 deletions(-) diff --git a/.claude/instructions.md b/.claude/instructions.md index 6a1a9b08b3..8a322df09b 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -202,6 +202,11 @@ Replace `/` with `@` in URL paths: ```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 diff --git a/.claude/skills/doc-write.md b/.claude/skills/doc-write.md index 1cf50a8d79..158f860fdf 100644 --- a/.claude/skills/doc-write.md +++ b/.claude/skills/doc-write.md @@ -1,15 +1,18 @@ # 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 @@ -18,6 +21,7 @@ Help write or edit Apify documentation following the established style guide and 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 @@ -30,6 +34,7 @@ When writing or editing documentation: - **Never make assumptions about product features** - ask if unsure ### 2. Front Matter + Always include proper front matter in MDX/MD files: ```yaml @@ -42,22 +47,26 @@ 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 @@ -93,23 +102,28 @@ 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 @@ -117,6 +131,7 @@ For tutorials and guides, follow this structure: 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") @@ -129,7 +144,9 @@ Always use exact capitalization and phrasing: - **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 @@ -146,4 +163,5 @@ Before finalizing, verify: - [ ] 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 index 03e082a567..036498c01d 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -1,22 +1,31 @@ # 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 @@ -24,248 +33,378 @@ Review documentation for compliance with Apify style guide, quality standards, a ### 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 **Example**: + ```markdown # ✅ Good + ```javascript // Fetch actor details const actor = await client.actor('john-doe/my-actor').get(); console.log(actor); + ``` # ❌ Bad -``` + +```text const a = await c.actor('x').get(); // No language tag, unclear names ``` -``` ### 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 + :::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 ## Review Process ### 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 @@ -276,30 +415,41 @@ Go through each section of the checklist above, noting any issues. ## 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 @@ -312,90 +462,132 @@ Go through each section of the checklist above, noting any issues. # ✅ 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 index 472162d241..3af7050987 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -1,33 +1,48 @@ # 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 @@ -35,6 +50,7 @@ slug: /category/tutorial-name # Must match file path **Purpose**: Hook the reader and explain what they'll learn **Template**: + ```markdown ## [Tutorial Title] @@ -49,10 +65,13 @@ slug: /category/tutorial-name # Must match file path 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 @@ -60,16 +79,20 @@ By the end, you'll be able to [specific outcome]. **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 @@ -77,24 +100,32 @@ Before starting this tutorial, make sure you have: **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] @@ -102,6 +133,7 @@ const example = "code"; :::tip [Helpful tip related to this step] ::: + ``` ### 5. Code Examples Section @@ -109,13 +141,19 @@ const example = "code"; **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 @@ -128,6 +166,7 @@ Here's the complete code for this tutorial: // Complete JavaScript example // Comments explaining key sections const example = "working code"; + ``` @@ -136,10 +175,12 @@ const example = "working code"; ```python """Complete Python example with comments explaining key sections""" example = "working code" + ``` + ``` ### 6. Testing/Verification Section @@ -147,22 +188,26 @@ example = "working code" **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 @@ -170,6 +215,7 @@ If you see [common error], check [solution]. **Purpose**: Address common issues users might encounter **Template**: + ```markdown ## Troubleshooting @@ -184,6 +230,7 @@ If you see [common error], check [solution]. **Symptom**: [What the user sees] **Solution**: [How to fix it] + ``` ### 8. Summary/Next Steps @@ -191,13 +238,16 @@ If you see [common error], check [solution]. **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 @@ -205,29 +255,37 @@ In this tutorial, you learned how to: 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 @@ -237,55 +295,93 @@ Now that you've completed this tutorial, you can: 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/.vale.ini b/.vale.ini index 282c31ca5a..8a47fb56ba 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,5 +30,5 @@ Microsoft.Units = NO Microsoft.URLFormat = NO Microsoft.GeneralURL = NO -[{README.md,CONTRIBUTING.md}] +[{README.md,CONTRIBUTING.md,.claude/**/*.md}] Apify.H1 = NO From e2c86dc918c2edd04f8cdfa9d66e6431c33f6eaa Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:36:08 +0100 Subject: [PATCH 09/15] fix: add closing fence to markdown code block example - Close markdown code block in review-docs.md properly - Reduces linting errors to 5 false positives from nested examples Co-Authored-By: Claude Sonnet 4.5 --- .claude/skills/review-docs.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index 036498c01d..9e0a23a407 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -181,6 +181,8 @@ console.log(actor); const a = await c.actor('x').get(); // No language tag, unclear names ``` +``` + ### 5. Links **Internal Links**: From 3c85e689ac5c24dd9a927a8788b0ad39e593b234 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:43:44 +0100 Subject: [PATCH 10/15] chore: ignore .claude directory in markdown and prose linting - Add .claude to .markdownlintignore (infrastructure docs) - Configure vale to skip all checks for .claude/**/*.md files - These files are Claude Code configuration, not published documentation Co-Authored-By: Claude Sonnet 4.5 --- .markdownlintignore | 1 + .vale.ini | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) 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 8a47fb56ba..b41626451e 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,5 +30,9 @@ Microsoft.Units = NO Microsoft.URLFormat = NO Microsoft.GeneralURL = NO -[{README.md,CONTRIBUTING.md,.claude/**/*.md}] +[{README.md,CONTRIBUTING.md}] Apify.H1 = NO + +[.claude/**/*.md] +# Ignore all Vale checks in .claude directory (infrastructure docs) +BasedOnStyles = From 107b89ca0bb854d6c726b33e56c24c6512f3c644 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:49:16 +0100 Subject: [PATCH 11/15] fix: remove outdated examples and improve clarity in documentation review skill --- .claude/skills/review-docs.md | 24 +++--------------------- 1 file changed, 3 insertions(+), 21 deletions(-) diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index 9e0a23a407..c30142d098 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -163,26 +163,6 @@ slug: /actors/development/create # ✅ Matches file path - [ ] Includes JavaScript and Python where applicable -**Example**: - -```markdown -# ✅ Good - -```javascript -// Fetch actor details -const actor = await client.actor('john-doe/my-actor').get(); -console.log(actor); - -``` - -# ❌ Bad - -```text -const a = await c.actor('x').get(); // No language tag, unclear names -``` - -``` - ### 5. Links **Internal Links**: @@ -268,10 +248,12 @@ Click [here](link) to learn more. **Example**: ```markdown -# ✅ Good - has title +# ✅ Good - has title and correct spacing :::tip Performance optimization + Use `requestHandlerTimeoutSecs` to prevent slow requests from blocking your Actor. + ::: # ❌ Bad - missing title (REQUIRED) From 9b366e6ae152b320574b5df11d091611db256070 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 14:57:31 +0100 Subject: [PATCH 12/15] fix headings --- .claude/README.md | 28 +++++++-------- .claude/instructions.md | 68 +++++++++++++++++------------------ .claude/skills/api-doc.md | 22 ++++++------ .claude/skills/doc-write.md | 14 ++++---- .claude/skills/review-docs.md | 38 ++++++++++---------- .claude/skills/tutorial.md | 36 +++++++++---------- 6 files changed, 103 insertions(+), 103 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 56e3931353..78fe3629cc 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -15,15 +15,15 @@ This directory contains Claude Code configuration for the Apify documentation re └── review-docs.md # Documentation review skill ``` -## How to Use +## How to use -### For Claude Code Users +### 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 +### Available skills #### `/doc-write` - Documentation Writing @@ -53,33 +53,33 @@ Review documentation for quality and compliance. - Use for: Pre-submission checks, audits, consistency - Handles: Style guide compliance, accessibility, SEO -## Quick Start +## Quick start -### Writing New Documentation +### Writing new documentation ```text Use /doc-write skill to create a new documentation page about [topic] ``` -### Creating a Tutorial +### Creating a tutorial ```text Use /tutorial skill to create a tutorial on [topic] ``` -### Adding API Endpoint +### Adding API endpoint ```text Use /api-doc skill to document the new [endpoint-name] endpoint ``` -### Reviewing Documentation +### Reviewing documentation ```text Use /review-docs skill to review sources/platform/[file-name].md ``` -## Primary References +## Primary references Always reference these files from the repo root: @@ -87,16 +87,16 @@ Always reference these files from the repo root: 2. **`CONTRIBUTING.md`** - Setup, workflows, style guide 3. **`.cursor/rules/*.mdc`** - Cursor-specific rules (reference only) -## Key Standards +## Key standards -### Writing Style +### 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 +### Front matter Every file needs: @@ -135,7 +135,7 @@ npm start # Preview changes npm test # Validate API specs ``` -## Best Practices +## Best practices 1. **Read `AGENTS.md` first** - It's the source of truth 2. **Use the appropriate skill** - They're designed for specific tasks @@ -154,7 +154,7 @@ This configuration mirrors and extends the existing style guide: Keep these files in sync when updating documentation standards. -## Need Help? +## Need help? - Questions about style: Check `AGENTS.md` - Setup issues: See `CONTRIBUTING.md` diff --git a/.claude/instructions.md b/.claude/instructions.md index 8a322df09b..4770fec54f 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -1,6 +1,6 @@ # Claude Code Instructions for Apify Documentation -## Project Overview +## Project overview You are working on the Apify documentation repository, which contains: @@ -10,7 +10,7 @@ You are working on the Apify documentation repository, which contains: The project uses Docusaurus with MDX, follows Microsoft style guide principles, and has comprehensive style guidelines. -## Primary Reference Documents +## Primary reference documents **Always reference these files when working on documentation**: @@ -18,7 +18,7 @@ The project uses Docusaurus with MDX, follows Microsoft style guide principles, 2. `CONTRIBUTING.md` - Contribution guidelines, setup, and workflows 3. `.cursor/rules/*.mdc` - Cursor-specific rules (for reference) -## Available Skills +## Available skills Use these skills for specific documentation tasks: @@ -42,7 +42,7 @@ Use these skills for specific documentation tasks: **When to use**: Reviewing documentation before submission **Handles**: Style guide compliance, quality checks, consistency -## Core Documentation Standards +## Core documentation standards ### Language & Style @@ -57,7 +57,7 @@ Use these skills for specific documentation tasks: - **Use Oxford commas** in lists - **Never make assumptions about product features** - ask if unsure -### Front Matter Requirements +### Front matter requirements Every documentation file must include: @@ -75,7 +75,7 @@ slug: /path/to/page - File: `/sources/platform/actors/running.md` - Slug: `/platform/actors/running` -### Text Formatting Standards +### 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) @@ -83,7 +83,7 @@ slug: /path/to/page - Code blocks MUST specify language: ` ```javascript `, ` ```python `, ` ```bash ` - **All admonitions MUST have a title** - Available types: `note`, `tip`, `info`, `caution`, `danger` -### Code Examples +### Code examples - Include complete, runnable examples - Use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) for multiple languages (JavaScript, Python) @@ -91,7 +91,7 @@ slug: /path/to/page - Include comments for complex logic - Show realistic, meaningful examples -### Admonition Format +### Admonition format **All admonitions MUST include a title:** @@ -128,16 +128,16 @@ Something that could cause issues. - Use red indicators for highlighting - Store in appropriate directories -## File Organization +## File organization -### Naming Conventions +### 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 +### Directory structure ```text sources/ @@ -150,7 +150,7 @@ sources/ └── webscraping/ # Web scraping courses ``` -## API Documentation Specifics +## API documentation specifics ### OpenAPI Structure @@ -161,7 +161,7 @@ apify-api/openapi/ └── paths/ # API endpoint definitions ``` -### Operation ID Conventions +### Operation ID conventions Format: `{objectName}_{httpMethod}` @@ -171,23 +171,23 @@ Format: `{objectName}_{httpMethod}` - `/request-queues` GET → `requestQueues_get` - `/request-queues/{queueId}` PUT → `requestQueue_put` -### Path File Naming +### Path file naming Replace `/` with `@` in URL paths: - `/request-queues` → `request-queues.yaml` - `/request-queues/{queueId}` → `request-queues@{queueId}.yaml` -## Development Workflow +## Development workflow -### Before Starting Work +### 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 +### During development 1. Follow the appropriate skill instructions 2. Reference `AGENTS.md` for style questions @@ -195,7 +195,7 @@ Replace `/` with `@` in URL paths: 4. Include complete, tested code examples 5. Add descriptive links and alt text -### Before Submitting +### Before submitting 1. Run linting checks: @@ -214,7 +214,7 @@ Replace `/` with `@` in URL paths: 4. Check all links are valid 5. Ensure front matter is complete -### Testing Changes +### Testing changes ```bash npm install # Install dependencies @@ -223,9 +223,9 @@ npm test # Validate OpenAPI specs (if applicable) npm run build # Test production build ``` -## Common Patterns +## Common patterns -### Tutorial Structure +### Tutorial structure 1. Introduction with learning objectives 2. Prerequisites @@ -235,7 +235,7 @@ npm run build # Test production build 6. Troubleshooting 7. Summary and next steps -### Platform Documentation +### Platform documentation 1. Clear description of feature 2. When to use it @@ -253,7 +253,7 @@ npm run build # Test production build 5. Error responses 6. Code samples (JavaScript, Python, cURL) -## Quality Checklist +## Quality checklist Before considering any documentation complete: @@ -268,9 +268,9 @@ Before considering any documentation complete: - [ ] All automated linting passes - [ ] Examples tested and working -## Important Notes +## Important notes -### What NOT to Do +### What NOT to do - Don't use Title Case for headings (use sentence case) - Don't use gerunds in headings ("Creating" - use "Create" instead) @@ -286,7 +286,7 @@ Before considering any documentation complete: - Don't make assumptions about product features - ask instead - Don't use incorrect Apify terminology (see terminology section) -### Best Practices +### Best practices - Start with user's goal/problem - Provide context before technical details @@ -303,7 +303,7 @@ Before considering any documentation complete: - Never make assumptions about product features - ask if unsure - For code review: check comments and obvious mistakes only -## Apify-Specific Terminology +## Apify-specific terminology **Always use exact capitalization and phrasing:** @@ -316,13 +316,13 @@ Before considering any documentation complete: - **AI agent** (lowercase for generic terms) - **MCP server** (lowercase for generic terms) -## Content Review Process +## Content review process -### Before Reviewing a PR +### Before reviewing a PR - Check that the latest changes were pulled from the feature branch -### Review Checklist +### Review checklist When reviewing or creating documentation, verify: @@ -333,7 +333,7 @@ When reviewing or creating documentation, verify: - **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 +## Getting help If you're unsure about: @@ -344,9 +344,9 @@ If you're unsure about: - **Review process**: See `/review-docs` skill - **Product features**: Never make assumptions - ask if unsure -## Project-Specific Context +## Project-specific context -### Multiple Repositories +### Multiple repositories The full documentation ecosystem includes multiple repos: @@ -367,7 +367,7 @@ Uses `@apify/docs-theme` package - don't modify theme files directly. - Preview builds available for pull requests - Uses nginx for routing between repositories -### Linting Tools +### Linting tools - **markdownlint** - Markdown formatting - **eslint** - JavaScript/TypeScript code diff --git a/.claude/skills/api-doc.md b/.claude/skills/api-doc.md index ab6f6c1568..bf0d90bf08 100644 --- a/.claude/skills/api-doc.md +++ b/.claude/skills/api-doc.md @@ -11,7 +11,7 @@ Help create or update OpenAPI specifications and API documentation for Apify API - Creating or modifying OpenAPI schemas - Adding code samples for API endpoints -## Context Files +## Context files - `CONTRIBUTING.md` - API documentation section - `AGENTS.md` - API documentation rules @@ -19,7 +19,7 @@ Help create or update OpenAPI specifications and API documentation for Apify API ## Instructions -### 1. OpenAPI File Structure +### 1. OpenAPI file structure ```text apify-api/openapi/ @@ -29,7 +29,7 @@ apify-api/openapi/ └── paths/ # API endpoint definitions ``` -### 2. Creating Schema Documentation +### 2. Creating schema documentation **Location**: `apify-api/openapi/components/schemas/` @@ -59,7 +59,7 @@ required: - name ``` -### 3. Creating Path Documentation +### 3. Creating path documentation **Location**: `apify-api/openapi/paths/` @@ -108,7 +108,7 @@ get: $ref: ../code_samples/Python/request-queues@{queueId}/get.py ``` -### 4. Operation ID Conventions +### 4. Operation ID conventions Format: `{objectName}_{httpMethod}` @@ -125,7 +125,7 @@ Format: `{objectName}_{httpMethod}` - `/request-queues/{queueId}` PUT → `requestQueue_put` - `/acts/{actorId}/runs` POST → `act_runs_post` -### 5. Adding Code Samples +### 5. Adding code samples **Location**: `apify-api/openapi/code_samples/{language}/{path}/` @@ -162,7 +162,7 @@ queue = client.request_queue('QUEUE_ID').get() print(queue) ``` -### 6. Adding New Endpoints to Main Spec +### 6. Adding new endpoints to main spec **File**: `apify-api/openapi/openapi.yaml` @@ -176,7 +176,7 @@ paths: $ref: './paths/request-queues/request-queues@{queueId}.yaml' ``` -### 7. Testing and Validation +### 7. Testing and validation After making changes: @@ -185,7 +185,7 @@ npm test # Validates OpenAPI specification npm start # Preview changes locally ``` -### 8. Apify Terminology +### 8. Apify terminology Always use exact capitalization in descriptions and examples: @@ -195,7 +195,7 @@ Always use exact capitalization in descriptions and examples: - **Apify Store** (never "the Apify Store") - **the Apify team**, **the Apify platform** (lowercase) -### 9. Best Practices +### 9. Best practices - **Descriptions**: Write clear, comprehensive descriptions using simple English - **Examples**: Include realistic examples in schemas @@ -206,7 +206,7 @@ Always use exact capitalization in descriptions and examples: - **Terminology**: Use correct Apify terminology throughout - **Never make assumptions**: About product features - ask if unsure -### 10. Quality Checklist +### 10. Quality checklist Before submitting: diff --git a/.claude/skills/doc-write.md b/.claude/skills/doc-write.md index 158f860fdf..928832d0bf 100644 --- a/.claude/skills/doc-write.md +++ b/.claude/skills/doc-write.md @@ -11,7 +11,7 @@ Help write or edit Apify documentation following the established style guide and - Converting drafts into proper documentation format - Updating documentation content -## Context Files +## Context files - `AGENTS.md` - Primary documentation standards - `CONTRIBUTING.md` - Contribution guidelines @@ -20,7 +20,7 @@ Help write or edit Apify documentation following the established style guide and When writing or editing documentation: -### 1. Content Standards +### 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 @@ -33,7 +33,7 @@ When writing or editing documentation: - Write for a technical audience but keep explanations clear - **Never make assumptions about product features** - ask if unsure -### 2. Front Matter +### 2. Front matter Always include proper front matter in MDX/MD files: @@ -51,7 +51,7 @@ slug: /path/to/page - File: `/sources/platform/actors/running.md` - Slug: `/platform/actors/running` -### 3. Text Formatting +### 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) @@ -101,7 +101,7 @@ Critical information that could cause issues. ::: ``` -### 6. Code Examples +### 6. Code examples - Include complete, runnable examples - Use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) for multiple languages @@ -130,7 +130,7 @@ For tutorials and guides, follow this structure: 4. **Code examples** - Complete, working examples 5. **Summary** - What they accomplished and next steps -### 10. Apify Terminology +### 10. Apify terminology Always use exact capitalization and phrasing: @@ -143,7 +143,7 @@ Always use exact capitalization and phrasing: - **AI agent** (lowercase for generic terms) - **MCP server** (lowercase for generic terms) -### 11. Quality Checklist +### 11. Quality checklist Before finalizing, verify: diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index c30142d098..e17be60b5b 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -14,7 +14,7 @@ Review documentation for compliance with Apify style guide, quality standards, a - To ensure consistency across documentation -## Context Files +## Context files - `AGENTS.md` - Documentation standards @@ -22,15 +22,15 @@ Review documentation for compliance with Apify style guide, quality standards, a - `.cursor/rules/*.mdc` - Cursor-specific rules -## Review Process +## Review process -### Before Starting Review +### Before starting review **CRITICAL**: Check that the latest changes were pulled from the feature branch -## Review Checklist +## Review checklist -### 1. Style Guide Compliance +### 1. Style guide compliance **Microsoft Style Guide**: @@ -80,7 +80,7 @@ Review documentation for compliance with Apify style guide, quality standards, a - [ ] **MCP server** (lowercase for generic terms) -### 2. Front Matter Validation +### 2. Front matter validation Required fields present and correct: @@ -113,7 +113,7 @@ slug: /actors/development/create # ✅ Matches file path ``` -### 3. Content Structure +### 3. Content structure **Heading Hierarchy**: @@ -135,7 +135,7 @@ slug: /actors/development/create # ✅ Matches file path - [ ] Related content linked appropriately -### 4. Code Examples +### 4. Code examples **Quality**: @@ -196,7 +196,7 @@ Click [here](link) to learn more. ``` -### 6. Images and Media +### 6. Images and media **Screenshots**: @@ -270,7 +270,7 @@ This is a helpful tip. ``` -### 8. Technical Accuracy +### 8. Technical accuracy **Validation**: @@ -298,7 +298,7 @@ This is a helpful tip. - [ ] Sufficient contrast in custom elements -### 10. SEO Optimization +### 10. SEO optimization **Elements**: @@ -312,7 +312,7 @@ This is a helpful tip. - [ ] Proper heading structure -### 11. Formatting Consistency +### 11. Formatting consistency **Text Elements**: @@ -338,7 +338,7 @@ This is a helpful tip. - [ ] Bullets for non-sequential items -### 12. Specific Content Types +### 12. Specific content types **For Tutorials**: @@ -376,7 +376,7 @@ This is a helpful tip. - [ ] Related pages linked -## Review Process +## Review process ### Step 1: Automated Checks @@ -396,7 +396,7 @@ Go through each section of the checklist above, noting any issues. **Format your review as**: ```markdown -## Documentation Review: [File Name] +## Documentation review: [File Name] ### ✅ Strengths @@ -430,13 +430,13 @@ Go through each section of the checklist above, noting any issues. ``` -## Common Issues +## Common issues ### Issue: Title Case or Gerund Headings ```markdown # ❌ Bad - Title Case -## How To Create An Actor +## How to create an Actor # ❌ Bad - Gerund ## Creating an Actor @@ -544,7 +544,7 @@ Apify Console allows you to manage your Apify Actors. ``` -## Output Format +## Output format Provide a structured review using the format above, with: @@ -556,7 +556,7 @@ Provide a structured review using the format above, with: - Priority ranking of issues -## Quality Standards +## Quality standards A document is ready for publication when: diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index 3af7050987..2560499cc8 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -14,15 +14,15 @@ Create comprehensive, structured tutorials for the Apify Academy or Platform doc - Building step-by-step learning content -## Context Files +## Context files - `AGENTS.md` - Documentation standards - `CONTRIBUTING.md` - Style guide -## Tutorial Structure +## Tutorial structure -### 1. Front Matter +### 1. Front matter ```yaml @@ -45,7 +45,7 @@ slug: /category/tutorial-name # Must match file path - Match slug to file path -### 2. Introduction Section +### 2. Introduction section **Purpose**: Hook the reader and explain what they'll learn @@ -74,7 +74,7 @@ By the end, you'll be able to [specific outcome]. ``` -### 3. Prerequisites Section +### 3. Prerequisites section **Purpose**: Set expectations for required knowledge and setup @@ -95,7 +95,7 @@ Before starting this tutorial, make sure you have: ``` -### 4. Step-by-Step Instructions +### 4. Step-by-step instructions **Purpose**: Guide users through the process clearly and systematically @@ -136,7 +136,7 @@ const example = "code"; ``` -### 5. Code Examples Section +### 5. Code examples section **Purpose**: Provide complete, working code that users can run @@ -183,7 +183,7 @@ example = "working code" ``` -### 6. Testing/Verification Section +### 6. Testing/verification section **Purpose**: Help users verify their implementation works @@ -210,7 +210,7 @@ If you see [common error], check [solution]. ``` -### 7. Troubleshooting Section +### 7. Troubleshooting section **Purpose**: Address common issues users might encounter @@ -233,7 +233,7 @@ If you see [common error], check [solution]. ``` -### 8. Summary/Next Steps +### 8. Summary/next steps **Purpose**: Reinforce learning and guide users forward @@ -270,27 +270,27 @@ Now that you've completed this tutorial, you can: ``` -## Tutorial Types +## Tutorial types -### Platform Tutorial +### Platform tutorial **Focus**: How to use Apify platform features **Location**: `/sources/platform/` **Style**: Practical, feature-focused -### Academy Tutorial +### Academy tutorial **Focus**: Teaching web scraping or automation concepts **Location**: `/sources/academy/tutorials/` **Style**: Educational, concept-focused -### Integration Tutorial +### Integration tutorial **Focus**: Connecting Apify with other tools **Location**: `/sources/platform/integrations/` **Style**: Step-by-step integration guide -## Apify Terminology +## Apify terminology Always use exact capitalization and phrasing: @@ -308,7 +308,7 @@ Always use exact capitalization and phrasing: - **AI agent**, **MCP server** (lowercase for generic terms) -## Text Formatting Rules +## Text formatting rules - **Bold** ONLY for UI elements (e.g., "Click **Save & Run**"). NEVER for emphasis. @@ -320,7 +320,7 @@ Always use exact capitalization and phrasing: - Use simple present tense for headings -## Best Practices +## Best practices 1. **Start Simple**: Begin with basic concepts before advanced topics @@ -342,7 +342,7 @@ Always use exact capitalization and phrasing: 10. **Use Simple English**: Prefer "use" over "utilize" -## Quality Checklist +## Quality checklist Before publishing: From 408b575d35c7d8c62ba9ac4b2b405af00d20a94f Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 15:06:07 +0100 Subject: [PATCH 13/15] fix heading casing --- .claude/README.md | 10 +++++----- .claude/instructions.md | 14 +++++++------- .claude/skills/api-doc.md | 4 ++-- .claude/skills/doc-write.md | 4 ++-- .claude/skills/review-docs.md | 30 +++++++++++++++--------------- .claude/skills/tutorial.md | 4 ++-- 6 files changed, 33 insertions(+), 33 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 78fe3629cc..e910b79da4 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -25,28 +25,28 @@ This directory contains Claude Code configuration for the Apify documentation re ### Available skills -#### `/doc-write` - Documentation Writing +#### `/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 +#### `/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 +#### `/tutorial` - Tutorial creation Build structured, educational tutorials. - Use for: New tutorials, tutorial restructuring - Handles: Learning progression, examples, exercises -#### `/review-docs` - Documentation Review +#### `/review-docs` - Documentation review Review documentation for quality and compliance. @@ -117,7 +117,7 @@ slug: /path/to/page - Code blocks with language tags - Admonitions for important info -### Links & Images +### Links & images - Descriptive link text (not "click here") - Alt text for all images diff --git a/.claude/instructions.md b/.claude/instructions.md index 4770fec54f..7b21928841 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -22,29 +22,29 @@ The project uses Docusaurus with MDX, follows Microsoft style guide principles, Use these skills for specific documentation tasks: -### `/doc-write` - Documentation Writing +### `/doc-write` - Documentation writing **When to use**: Creating or editing documentation pages **Handles**: Content creation, formatting, style guide compliance -### `/api-doc` - API Documentation +### `/api-doc` - API documentation **When to use**: Working with OpenAPI specifications **Handles**: Creating endpoints, schemas, code samples -### `/tutorial` - Tutorial Creation +### `/tutorial` - Tutorial creation **When to use**: Creating step-by-step tutorials **Handles**: Tutorial structure, learning content, examples -### `/review-docs` - Documentation Review +### `/review-docs` - Documentation review **When to use**: Reviewing documentation before submission **Handles**: Style guide compliance, quality checks, consistency ## Core documentation standards -### Language & Style +### Language & style - **US English** spelling and grammar (e.g., "color" not "colour") - **Active voice** whenever possible @@ -152,7 +152,7 @@ sources/ ## API documentation specifics -### OpenAPI Structure +### OpenAPI structure ```text apify-api/openapi/ @@ -244,7 +244,7 @@ npm run build # Test production build 5. Best practices 6. Related features -### API Documentation +### API documentation 1. Endpoint description 2. Parameters with types and descriptions diff --git a/.claude/skills/api-doc.md b/.claude/skills/api-doc.md index bf0d90bf08..cb01007692 100644 --- a/.claude/skills/api-doc.md +++ b/.claude/skills/api-doc.md @@ -1,10 +1,10 @@ -# API Documentation Skill +# API documentation skill ## Purpose Help create or update OpenAPI specifications and API documentation for Apify API endpoints. -## When to Use +## When to use - Adding new API endpoints - Updating existing endpoint documentation diff --git a/.claude/skills/doc-write.md b/.claude/skills/doc-write.md index 928832d0bf..b67719498f 100644 --- a/.claude/skills/doc-write.md +++ b/.claude/skills/doc-write.md @@ -1,10 +1,10 @@ -# Documentation Writer Skill +# Documentation writer skill ## Purpose Help write or edit Apify documentation following the established style guide and best practices. -## When to Use +## When to use - Creating new documentation pages - Editing existing documentation diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index e17be60b5b..36a27aef4f 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -1,10 +1,10 @@ -# Documentation Review Skill +# Documentation review skill ## Purpose Review documentation for compliance with Apify style guide, quality standards, and best practices. -## When to Use +## When to use - Before submitting pull requests @@ -378,7 +378,7 @@ This is a helpful tip. ## Review process -### Step 1: Automated Checks +### Step 1: Automated checks ```bash npm run lint:md # Markdown linting @@ -387,11 +387,11 @@ vale sync # Prose linting setup ``` -### Step 2: Manual Review +### Step 2: Manual review Go through each section of the checklist above, noting any issues. -### Step 3: Provide Feedback +### Step 3: Provide feedback **Format your review as**: @@ -402,9 +402,9 @@ Go through each section of the checklist above, noting any issues. - [What's done well] -### ⚠️ Issues Found +### ⚠️ Issues found -#### Style Guide +#### Style guide - [ ] Issue 1: [Description] @@ -422,7 +422,7 @@ Go through each section of the checklist above, noting any issues. - [Optional improvement 2] -### 🎯 Priority Issues +### 🎯 Priority issues 1. [Critical issue to fix] @@ -432,7 +432,7 @@ Go through each section of the checklist above, noting any issues. ## Common issues -### Issue: Title Case or Gerund Headings +### Issue: Title case or gerund headings ```markdown # ❌ Bad - Title Case @@ -449,7 +449,7 @@ Go through each section of the checklist above, noting any issues. ``` -### Issue: Non-Descriptive Links +### Issue: Non-descriptive links ```markdown # ❌ Bad @@ -462,7 +462,7 @@ Learn more about [Actor input schemas](/actors/development/input-schema). ``` -### Issue: Missing Front Matter Description +### Issue: Missing front matter description ```markdown # ❌ Bad @@ -484,7 +484,7 @@ description: "Learn how to build and deploy your first Actor with step-by-step i ``` -### Issue: Long Description or Feature-Focused +### Issue: Long description or feature-focused ```markdown # ❌ Bad - Too long (190 chars) and feature-focused @@ -501,7 +501,7 @@ description: "Build and deploy Actors efficiently with this guide covering setup ``` -### Issue: Bold for Emphasis +### Issue: Bold for emphasis ```markdown # ❌ Bad - bold used for emphasis @@ -514,7 +514,7 @@ Click the **Save & Run** button and ensure you verify the settings. ``` -### Issue: Missing Admonition Title +### Issue: Missing admonition title ```markdown # ❌ Bad - no title (REQUIRED) @@ -531,7 +531,7 @@ Use pagination for large datasets. ``` -### Issue: Incorrect Apify Terminology +### Issue: Incorrect Apify terminology ```markdown # ❌ Bad diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index 2560499cc8..a79f065b39 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -1,10 +1,10 @@ -# Tutorial Creator Skill +# Tutorial creator skill ## Purpose Create comprehensive, structured tutorials for the Apify Academy or Platform documentation. -## When to Use +## When to use - Creating new tutorials From 84742142879a8a08c447a234c3d2de772459d7c6 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 15:08:56 +0100 Subject: [PATCH 14/15] fix headings_final --- .claude/skills/review-docs.md | 2 +- .claude/skills/tutorial.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index 36a27aef4f..09baa6eb49 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -396,7 +396,7 @@ Go through each section of the checklist above, noting any issues. **Format your review as**: ```markdown -## Documentation review: [File Name] +## Documentation review: [File name] ### ✅ Strengths diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index a79f065b39..b604ed729d 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -52,7 +52,7 @@ slug: /category/tutorial-name # Must match file path **Template**: ```markdown -## [Tutorial Title] +## [Tutorial title] **[Brief description of what the user will accomplish]** From 8f76bf5884ee735789b2c99f4c6f863f78422bd0 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 15:19:27 +0100 Subject: [PATCH 15/15] fix: standardize heading casing and improve clarity in documentation --- .claude/README.md | 2 +- .claude/instructions.md | 2 +- .claude/skills/review-docs.md | 2 +- .claude/skills/tutorial.md | 22 ++++++++-------------- 4 files changed, 11 insertions(+), 17 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index e910b79da4..65c80a5064 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -1,4 +1,4 @@ -# Claude Code Configuration for Apify Docs +# Claude Code configuration for Apify docs This directory contains Claude Code configuration for the Apify documentation repository. diff --git a/.claude/instructions.md b/.claude/instructions.md index 7b21928841..fa10361fa7 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -1,4 +1,4 @@ -# Claude Code Instructions for Apify Documentation +# Claude Code instructions for Apify documentation ## Project overview diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index 09baa6eb49..065d086174 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -376,7 +376,7 @@ This is a helpful tip. - [ ] Related pages linked -## Review process +## How to review ### Step 1: Automated checks diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index b604ed729d..477316241c 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -122,18 +122,16 @@ Before starting this tutorial, make sure you have: 2. [Second sub-step] -```language +​```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 @@ -162,25 +160,22 @@ Here's the complete code for this tutorial: -```javascript +​```javascript // Complete JavaScript example // Comments explaining key sections const example = "working code"; - -``` +​``` -```python +​```python """Complete Python example with comments explaining key sections""" example = "working code" - -``` +​``` - ``` ### 6. Testing/verification section @@ -200,14 +195,13 @@ To verify everything works correctly: **Expected output**: -```text +​```text [What the user should see] -``` +​``` :::note If you see [common error], check [solution]. ::: - ``` ### 7. Troubleshooting section