|
| 1 | +# Claude Code Configuration for Apify Docs |
| 2 | + |
| 3 | +This directory contains Claude Code configuration for the Apify documentation repository. |
| 4 | + |
| 5 | +## Structure |
| 6 | + |
| 7 | +```text |
| 8 | +.claude/ |
| 9 | +├── README.md # This file |
| 10 | +├── instructions.md # Main instructions for Claude Code |
| 11 | +└── skills/ # Reusable skills for common tasks |
| 12 | + ├── doc-write.md # Documentation writing skill |
| 13 | + ├── api-doc.md # API documentation skill |
| 14 | + ├── tutorial.md # Tutorial creation skill |
| 15 | + └── review-docs.md # Documentation review skill |
| 16 | +``` |
| 17 | + |
| 18 | +## How to Use |
| 19 | + |
| 20 | +### For Claude Code Users |
| 21 | + |
| 22 | +1. **Start a new session**: Claude Code will automatically read `instructions.md` |
| 23 | +2. **Use skills**: Type `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs` to use specific skills |
| 24 | +3. **Reference standards**: Always refer to `AGENTS.md` in the repo root for core standards |
| 25 | + |
| 26 | +### Available Skills |
| 27 | + |
| 28 | +#### `/doc-write` - Documentation Writing |
| 29 | +Create or edit documentation following Apify style guide. |
| 30 | +- Use for: New pages, content updates, reformatting |
| 31 | +- Handles: Style compliance, formatting, structure |
| 32 | + |
| 33 | +#### `/api-doc` - API Documentation |
| 34 | +Work with OpenAPI specifications and API endpoints. |
| 35 | +- Use for: New endpoints, schema updates, code samples |
| 36 | +- Handles: OpenAPI structure, operation IDs, examples |
| 37 | + |
| 38 | +#### `/tutorial` - Tutorial Creation |
| 39 | +Build structured, educational tutorials. |
| 40 | +- Use for: New tutorials, tutorial restructuring |
| 41 | +- Handles: Learning progression, examples, exercises |
| 42 | + |
| 43 | +#### `/review-docs` - Documentation Review |
| 44 | +Review documentation for quality and compliance. |
| 45 | +- Use for: Pre-submission checks, audits, consistency |
| 46 | +- Handles: Style guide compliance, accessibility, SEO |
| 47 | + |
| 48 | +## Quick Start |
| 49 | + |
| 50 | +### Writing New Documentation |
| 51 | +``` |
| 52 | +Use /doc-write skill to create a new documentation page about [topic] |
| 53 | +``` |
| 54 | + |
| 55 | +### Creating a Tutorial |
| 56 | +``` |
| 57 | +Use /tutorial skill to create a tutorial on [topic] |
| 58 | +``` |
| 59 | + |
| 60 | +### Adding API Endpoint |
| 61 | +``` |
| 62 | +Use /api-doc skill to document the new [endpoint-name] endpoint |
| 63 | +``` |
| 64 | + |
| 65 | +### Reviewing Documentation |
| 66 | +``` |
| 67 | +Use /review-docs skill to review sources/platform/[file-name].md |
| 68 | +``` |
| 69 | + |
| 70 | +## Primary References |
| 71 | + |
| 72 | +Always reference these files from the repo root: |
| 73 | + |
| 74 | +1. **`AGENTS.md`** - Core documentation standards (READ FIRST) |
| 75 | +2. **`CONTRIBUTING.md`** - Setup, workflows, style guide |
| 76 | +3. **`.cursor/rules/*.mdc`** - Cursor-specific rules (reference only) |
| 77 | + |
| 78 | +## Key Standards |
| 79 | + |
| 80 | +### Writing Style |
| 81 | +- US English, active voice, inclusive language |
| 82 | +- Sentence case for headings (not Title Case) |
| 83 | +- Action-oriented phrasing |
| 84 | +- No directional language (left/right) |
| 85 | + |
| 86 | +### Front Matter |
| 87 | +Every file needs: |
| 88 | +```yaml |
| 89 | +--- |
| 90 | +title: "Action-oriented title" |
| 91 | +description: "140-160 chars, no 'documentation' word" |
| 92 | +sidebar_position: 1 |
| 93 | +slug: /path/to/page |
| 94 | +--- |
| 95 | +``` |
| 96 | + |
| 97 | +### Formatting |
| 98 | +- **Bold** for UI elements |
| 99 | +- _Italics_ for emphasis |
| 100 | +- `code` for inline code/files |
| 101 | +- Code blocks with language tags |
| 102 | +- Admonitions for important info |
| 103 | + |
| 104 | +### Links & Images |
| 105 | +- Descriptive link text (not "click here") |
| 106 | +- Alt text for all images |
| 107 | +- Light theme for screenshots |
| 108 | +- Red indicators for highlighting |
| 109 | + |
| 110 | +## Testing |
| 111 | + |
| 112 | +Before submitting: |
| 113 | +```bash |
| 114 | +npm run lint:md # Check markdown |
| 115 | +npm run lint:code # Check code |
| 116 | +npm start # Preview changes |
| 117 | +npm test # Validate API specs |
| 118 | +``` |
| 119 | + |
| 120 | +## Best Practices |
| 121 | + |
| 122 | +1. **Read `AGENTS.md` first** - It's the source of truth |
| 123 | +2. **Use the appropriate skill** - They're designed for specific tasks |
| 124 | +3. **Test code examples** - All examples must work |
| 125 | +4. **Check front matter** - Required for all files |
| 126 | +5. **Run linters** - Before committing |
| 127 | +6. **Review before submit** - Use `/review-docs` |
| 128 | + |
| 129 | +## Maintenance |
| 130 | + |
| 131 | +This configuration mirrors and extends the existing style guide: |
| 132 | +- `AGENTS.md` - Vendor-agnostic standards |
| 133 | +- `CONTRIBUTING.md` - Contribution process |
| 134 | +- `.cursor/rules/*.mdc` - Cursor-specific rules |
| 135 | + |
| 136 | +Keep these files in sync when updating documentation standards. |
| 137 | + |
| 138 | +## Need Help? |
| 139 | + |
| 140 | +- Questions about style: Check `AGENTS.md` |
| 141 | +- Setup issues: See `CONTRIBUTING.md` |
| 142 | +- Skill usage: Read the specific skill file |
| 143 | +- Claude Code general: Visit [Claude Code docs](https://github.com/anthropics/claude-code) |
0 commit comments