From 17a933b3eb3a4ff1e87c9d86dde16cd17e4ed5d2 Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 21:16:41 +0100 Subject: [PATCH 01/27] docs: Add Claude Code writing style guide Add .claude/rules/writing-style.md with documentation writing guidelines for AI assistants. Based on Apify style guide and TC-MO's technical writer feedback from PR #2185. Includes: - Core principles (simple, factual, technical) - Formatting rules (headings, bold, lists) - Grammar guidelines (articles, Oxford comma) - Terminology standards (Actor capitalization, word choice) - Common mistakes to avoid Co-Authored-By: Claude Opus 4.5 --- .claude/rules/writing-style.md | 207 +++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 .claude/rules/writing-style.md diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md new file mode 100644 index 0000000000..fe7f55f38c --- /dev/null +++ b/.claude/rules/writing-style.md @@ -0,0 +1,207 @@ +# Apify Documentation Writing Style + +Instructions for AI assistants writing Apify documentation. Based on Apify style guide and technical writer feedback. + +## Core Principles + +1. **Simple** - Get to the point. No sentence over 30 words. Every sentence delivers information. +1. **Factual** - Back up claims with evidence. Use numbers, not vague qualifiers. +1. **Technical** - Write for developers. Don't oversimplify. Link to fill knowledge gaps. + +> Write the same way you would explain something to a person sitting next to you. + +## Language & Tone + +### US English + +Use "analyze" not "analyse", "color" not "colour". + +### Imperative tone + +Use direct instructions, not soft recommendations: + +| Avoid | Prefer | +|-------|--------| +| We recommend pinning the version | Pin the version | +| You should use the latest SDK | Use the latest SDK | +| It's best to avoid hardcoding | Avoid hardcoding | + +### No sales language + +| Avoid | Prefer | +|-------|--------| +| Experience Apify, the ultimate platform! | Welcome to Apify, the cloud web scraping platform. | +| Our highly efficient system | Apify's system handles 500K requests per minute | + +### Avoid first person + +Use "you" to focus on the reader. Avoid "I", "me", "myself" in docs. + +| Avoid | Prefer | +|-------|--------| +| I recommend using version 22 | Use version 22 | +| In my experience, this works better | This approach is more reliable | + +## Formatting + +### Headings + +**Sentence case only.** No title case. + +| Avoid | Prefer | +|-------|--------| +| Store And Manage Data | Store and manage data | + +**No gerunds (-ing forms).** Use noun phrases or imperatives. + +| Avoid | Prefer | +|-------|--------| +| Finding available tags | Available tags | +| Getting started with Actors | Get started with Actors | +| Understanding the API | API overview | + +Rationale: Noun-phrase headings are more scannable and search-friendly (Microsoft style guide). + +### Bold + +Use bold sparingly. Don't bold: +- List introductions +- Code block introductions +- Section labels when context is clear + +| Avoid | Prefer | +|-------|--------| +| **Examples:** | Examples: | +| **In your Dockerfile**, use... | In your `Dockerfile`, use... | + +Bold is for critical warnings or key terms, not routine structure. + +### Ordered lists + +Use `1.` for all items (not sequential numbers). Easier to maintain: + +```markdown +1. First step +1. Second step +1. Third step +``` + +### Parallel structure + +All items in a list must follow the same grammatical pattern: + +```markdown +# Avoid - mixed patterns +1. Reproducibility - your builds behave the same +1. Predictability - you know which version +1. Easier to track down issues + +# Prefer - consistent pattern +1. Reproducibility - Your builds behave the same way +1. Predictability - You know exactly which version you're running +1. Debugging - Version-specific issues are easier to track down +``` + +### Em dashes + +**Don't use em dashes (—).** LLMs overuse them. Use hyphen with spaces ( - ) instead. + +## Grammar + +### Articles in definitions + +Include "a/an" before nouns in definition lists: + +| Avoid | Prefer | +|-------|--------| +| `{version}` - Node.js version only | `{version}` - A Node.js version only | + +### Oxford comma + +Always use the serial comma: + +| Avoid | Prefer | +|-------|--------| +| pencil, eraser and notebook | pencil, eraser, and notebook | + +### "the" before products + +Use "the" before "Apify platform", "Apify SDK", etc. + +| Avoid | Prefer | +|-------|--------| +| I use Apify platform | I use the Apify platform | + +## Terminology + +### Capitalization + +- **Actor** - Always uppercase when referring to Apify Actors +- **Apify Proxy**, **Apify Console**, **Apify Store** - Product names, capitalized +- **the Apify platform** - Lowercase "platform", include "the" +- **task**, **schedule** - Lowercase + +### Word choice + +| Word | When to use | +|------|-------------| +| legacy | Feature is deprecated or will be removed | +| alternative | Valid approach, but not the preferred one | +| deprecated | Feature will be removed in a future version | + +## Links + +### Action-oriented text + +| Avoid | Prefer | +|-------|--------| +| [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | +| See the [documentation](url) | [Read the documentation](url) | + +### Trim filler words + +| Avoid | Prefer | +|-------|--------| +| visit the Docker Hub tags page | visit Docker Hub | +| check out the official docs | see the documentation | + +### Actor references + +First mention: Actor name with link, capitalized. + +```markdown +[Website Content Crawler](https://apify.com/apify/website-content-crawler) +can crawl websites and extract text content. +``` + +## Code Examples + +- Use backticks for file names, commands, config keys +- Prefer complete, runnable examples +- Add comments only when code isn't self-explanatory +- Match versions in examples (e.g., Dockerfile tag matches package.json version) + +## Numbers & Formatting + +- Thousands: comma separator ($1,000) +- Decimals: period ($9.8) +- Money: symbol before amount ($49, not 49$) +- Dates: August 5, 2024 (never 5.8.2024) +- Time: 5 pm or 5 PM (space after number) + +## Common Mistakes + +Patterns to avoid: +- "Happy scraping!" closings +- Em dashes +- Title case headings +- Gerunds in headings +- Bold for routine structure +- "Ok" (use "OK" or "okay") +- Missing "the" before "Apify platform" +- Sales language ("ultimate", "cutting-edge", "supercharge") +- Vague claims without numbers + +## Reference + +Full Apify style guide: https://www.notion.so/apify/de9fbb99dcd84665b6d3f790fc88b3b6 From eeba13dc45c35db3640352b119679008580b4d41 Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 21:29:41 +0100 Subject: [PATCH 02/27] Enhance writing style guide with accessibility and content type rules Add missing rules from CONTRIBUTING.md/AGENTS.md and TC-MO review patterns: - Content Types section: Match CTA verbs to content type (tutorials vs reference) - Active & Inclusive Voice: Active voice, gender-neutral, no directional UI language - Bold: Clarify bold IS for UI elements, NOT for structural labels - Italics: Guidance for emphasis and new term introduction - List types: When to use numbered vs bullet lists - Admonitions: Docusaurus admonition types and usage - Accessible links: Avoid "click here", use descriptive text - Navigable tool mentions: Link external tools/resources - Reference section: Point to CONTRIBUTING.md and AGENTS.md for structural guidelines Co-Authored-By: Claude Opus 4.5 --- .claude/rules/writing-style.md | 83 ++++++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 5 deletions(-) diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index fe7f55f38c..1288967acb 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -10,6 +10,18 @@ Instructions for AI assistants writing Apify documentation. Based on Apify style > Write the same way you would explain something to a person sitting next to you. +## Content Types + +Match language to content type: + +| Content type | CTA verbs | Example | +|--------------|-----------|---------| +| Tutorials/guides | Learn, Build, Create | "Learn how to build a web scraper" | +| Reference docs | Access, Integrate, Use | "Access the Apify platform programmatically" | +| Discovery pages | Explore, Discover, Browse | "Explore available Actors" | + +Don't use "Learn" for pure reference documentation - it sets tutorial expectations. + ## Language & Tone ### US English @@ -42,6 +54,16 @@ Use "you" to focus on the reader. Avoid "I", "me", "myself" in docs. | I recommend using version 22 | Use version 22 | | In my experience, this works better | This approach is more reliable | +### Active & inclusive voice + +Use active voice. Avoid gendered terms. Don't use directional language ("left/right") for UI - it breaks with different layouts. + +| Avoid | Prefer | +|-------|--------| +| The Actor is started by the user | The user starts the Actor | +| He can configure his settings | You can configure your settings | +| Click the button on the left | Click the **Settings** button | + ## Formatting ### Headings @@ -64,7 +86,11 @@ Rationale: Noun-phrase headings are more scannable and search-friendly (Microsof ### Bold -Use bold sparingly. Don't bold: +**Do use bold for:** +- UI elements (buttons, menus, fields): Click the **Actors** button +- Critical warnings or key terms + +**Don't use bold for:** - List introductions - Code block introductions - Section labels when context is clear @@ -74,11 +100,23 @@ Use bold sparingly. Don't bold: | **Examples:** | Examples: | | **In your Dockerfile**, use... | In your `Dockerfile`, use... | -Bold is for critical warnings or key terms, not routine structure. +Bold for UI elements helps users scan for clickable items. Bold for structure creates visual noise. + +### Italics + +Use italics for emphasis and introducing new terms: -### Ordered lists +| Use case | Example | +|----------|---------| +| New term introduction | An *Actor* is a serverless program... | +| Emphasis | This step is *required* for the Actor to work | -Use `1.` for all items (not sequential numbers). Easier to maintain: +### List types + +**Numbered lists** - Sequential steps where order matters +**Bullet points** - Non-sequential items, features, options + +In numbered lists, use `1.` for all items (not sequential numbers). Easier to maintain: ```markdown 1. First step @@ -106,6 +144,20 @@ All items in a list must follow the same grammatical pattern: **Don't use em dashes (—).** LLMs overuse them. Use hyphen with spaces ( - ) instead. +### Admonitions + +Use Docusaurus admonitions for important information: + +| Type | Use for | +|------|---------| +| `:::note` | General callouts | +| `:::tip` | Helpful suggestions | +| `:::info` | Background context | +| `:::caution` | Warnings about gotchas | +| `:::danger` | Critical warnings that could cause issues | + +Prefer admonitions over block quotes for highlighted content. + ## Grammar ### Articles in definitions @@ -158,6 +210,23 @@ Use "the" before "Apify platform", "Apify SDK", etc. | [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | | See the [documentation](url) | [Read the documentation](url) | +### Accessible link text + +Use descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. + +| Avoid | Prefer | +|-------|--------| +| [Click here](url) to learn more | [Learn about Actor pricing](url) | +| Read more about it [here](url) | Read the [Actor development guide](url) | + +### Make tool mentions navigable + +When mentioning tools, languages, or external resources, link them to help readers explore: + +| Avoid | Prefer | +|-------|--------| +| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | + ### Trim filler words | Avoid | Prefer | @@ -204,4 +273,8 @@ Patterns to avoid: ## Reference -Full Apify style guide: https://www.notion.so/apify/de9fbb99dcd84665b6d3f790fc88b3b6 +This guide covers writing patterns. For structural guidelines (file naming, screenshots, tutorial structure, SEO), see: + +- [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution workflow and repository standards +- [AGENTS.md](../../AGENTS.md) - Comprehensive documentation guidelines for AI assistants +- Full Apify style guide: https://www.notion.so/apify/de9fbb99dcd84665b6d3f790fc88b3b6 From 65ad77eaa8385f9c92b2d8eadb11dea0dcff1824 Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 21:40:33 +0100 Subject: [PATCH 03/27] Fix linting errors in writing style guide - Fix Vale AM/PM error: use uppercase "5 PM" - Fix MD060: align all table columns properly - Fix MD032: add blank lines around lists - Fix MD059: wrap bad link examples in code backticks Co-Authored-By: Claude Opus 4.5 --- .claude/rules/writing-style.md | 149 +++++++++++++++++---------------- 1 file changed, 76 insertions(+), 73 deletions(-) diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index 1288967acb..f55e160d1d 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -14,11 +14,11 @@ Instructions for AI assistants writing Apify documentation. Based on Apify style Match language to content type: -| Content type | CTA verbs | Example | -|--------------|-----------|---------| -| Tutorials/guides | Learn, Build, Create | "Learn how to build a web scraper" | -| Reference docs | Access, Integrate, Use | "Access the Apify platform programmatically" | -| Discovery pages | Explore, Discover, Browse | "Explore available Actors" | +| Content type | CTA verbs | Example | +| ---------------- | ---------------------- | ------------------------------------------ | +| Tutorials/guides | Learn, Build, Create | "Learn how to build a web scraper" | +| Reference docs | Access, Integrate, Use | "Access the Apify platform programmatically" | +| Discovery pages | Explore, Discover, Browse | "Explore available Actors" | Don't use "Learn" for pure reference documentation - it sets tutorial expectations. @@ -32,37 +32,37 @@ Use "analyze" not "analyse", "color" not "colour". Use direct instructions, not soft recommendations: -| Avoid | Prefer | -|-------|--------| -| We recommend pinning the version | Pin the version | -| You should use the latest SDK | Use the latest SDK | -| It's best to avoid hardcoding | Avoid hardcoding | +| Avoid | Prefer | +| --------------------------------- | ------------------- | +| We recommend pinning the version | Pin the version | +| You should use the latest SDK | Use the latest SDK | +| It's best to avoid hardcoding | Avoid hardcoding | ### No sales language -| Avoid | Prefer | -|-------|--------| -| Experience Apify, the ultimate platform! | Welcome to Apify, the cloud web scraping platform. | -| Our highly efficient system | Apify's system handles 500K requests per minute | +| Avoid | Prefer | +| ------------------------------------------ | --------------------------------------------------- | +| Experience Apify, the ultimate platform! | Welcome to Apify, the cloud web scraping platform. | +| Our highly efficient system | Apify's system handles 500K requests per minute | ### Avoid first person Use "you" to focus on the reader. Avoid "I", "me", "myself" in docs. -| Avoid | Prefer | -|-------|--------| -| I recommend using version 22 | Use version 22 | -| In my experience, this works better | This approach is more reliable | +| Avoid | Prefer | +| ------------------------------------- | -------------------------------- | +| I recommend using version 22 | Use version 22 | +| In my experience, this works better | This approach is more reliable | ### Active & inclusive voice Use active voice. Avoid gendered terms. Don't use directional language ("left/right") for UI - it breaks with different layouts. -| Avoid | Prefer | -|-------|--------| -| The Actor is started by the user | The user starts the Actor | -| He can configure his settings | You can configure your settings | -| Click the button on the left | Click the **Settings** button | +| Avoid | Prefer | +| --------------------------------- | -------------------------------- | +| The Actor is started by the user | The user starts the Actor | +| He can configure his settings | You can configure your settings | +| Click the button on the left | Click the **Settings** button | ## Formatting @@ -70,35 +70,37 @@ Use active voice. Avoid gendered terms. Don't use directional language ("left/ri **Sentence case only.** No title case. -| Avoid | Prefer | -|-------|--------| +| Avoid | Prefer | +| --------------------- | --------------------- | | Store And Manage Data | Store and manage data | **No gerunds (-ing forms).** Use noun phrases or imperatives. -| Avoid | Prefer | -|-------|--------| -| Finding available tags | Available tags | -| Getting started with Actors | Get started with Actors | -| Understanding the API | API overview | +| Avoid | Prefer | +| ----------------------------- | -------------------------- | +| Finding available tags | Available tags | +| Getting started with Actors | Get started with Actors | +| Understanding the API | API overview | Rationale: Noun-phrase headings are more scannable and search-friendly (Microsoft style guide). ### Bold **Do use bold for:** + - UI elements (buttons, menus, fields): Click the **Actors** button - Critical warnings or key terms **Don't use bold for:** + - List introductions - Code block introductions - Section labels when context is clear -| Avoid | Prefer | -|-------|--------| -| **Examples:** | Examples: | -| **In your Dockerfile**, use... | In your `Dockerfile`, use... | +| Avoid | Prefer | +| ------------------------------- | ----------------------------- | +| **Examples:** | Examples: | +| **In your Dockerfile**, use... | In your `Dockerfile`, use... | Bold for UI elements helps users scan for clickable items. Bold for structure creates visual noise. @@ -106,10 +108,10 @@ Bold for UI elements helps users scan for clickable items. Bold for structure cr Use italics for emphasis and introducing new terms: -| Use case | Example | -|----------|---------| -| New term introduction | An *Actor* is a serverless program... | -| Emphasis | This step is *required* for the Actor to work | +| Use case | Example | +| ------------------------ | --------------------------------------------- | +| New term introduction | An *Actor* is a serverless program... | +| Emphasis | This step is *required* for the Actor to work | ### List types @@ -148,13 +150,13 @@ All items in a list must follow the same grammatical pattern: Use Docusaurus admonitions for important information: -| Type | Use for | -|------|---------| -| `:::note` | General callouts | -| `:::tip` | Helpful suggestions | -| `:::info` | Background context | -| `:::caution` | Warnings about gotchas | -| `:::danger` | Critical warnings that could cause issues | +| Type | Use for | +| -------------- | --------------------------------------- | +| `:::note` | General callouts | +| `:::tip` | Helpful suggestions | +| `:::info` | Background context | +| `:::caution` | Warnings about gotchas | +| `:::danger` | Critical warnings that could cause issues | Prefer admonitions over block quotes for highlighted content. @@ -164,25 +166,25 @@ Prefer admonitions over block quotes for highlighted content. Include "a/an" before nouns in definition lists: -| Avoid | Prefer | -|-------|--------| +| Avoid | Prefer | +| -------------------------------- | -------------------------------------- | | `{version}` - Node.js version only | `{version}` - A Node.js version only | ### Oxford comma Always use the serial comma: -| Avoid | Prefer | -|-------|--------| -| pencil, eraser and notebook | pencil, eraser, and notebook | +| Avoid | Prefer | +| ---------------------------- | -------------------------------- | +| pencil, eraser and notebook | pencil, eraser, and notebook | ### "the" before products Use "the" before "Apify platform", "Apify SDK", etc. -| Avoid | Prefer | -|-------|--------| -| I use Apify platform | I use the Apify platform | +| Avoid | Prefer | +| -------------------- | ------------------------- | +| I use Apify platform | I use the Apify platform | ## Terminology @@ -195,44 +197,44 @@ Use "the" before "Apify platform", "Apify SDK", etc. ### Word choice -| Word | When to use | -|------|-------------| -| legacy | Feature is deprecated or will be removed | +| Word | When to use | +| ----------- | ----------------------------------------- | +| legacy | Feature is deprecated or will be removed | | alternative | Valid approach, but not the preferred one | -| deprecated | Feature will be removed in a future version | +| deprecated | Feature will be removed in a future version | ## Links ### Action-oriented text -| Avoid | Prefer | -|-------|--------| -| [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | -| See the [documentation](url) | [Read the documentation](url) | +| Avoid | Prefer | +| --------------------------------- | --------------------------------------- | +| [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | +| See the [documentation](url) | [Read the documentation](url) | ### Accessible link text Use descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. -| Avoid | Prefer | -|-------|--------| -| [Click here](url) to learn more | [Learn about Actor pricing](url) | -| Read more about it [here](url) | Read the [Actor development guide](url) | +| Avoid | Prefer | +| ---------------------------------- | ----------------------------------------- | +| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` | +| Read more about it `[here](url)` | Read the `[Actor development guide](url)` | ### Make tool mentions navigable When mentioning tools, languages, or external resources, link them to help readers explore: -| Avoid | Prefer | -|-------|--------| -| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | +| Avoid | Prefer | +| ----------------------------------- | ----------------------------------------------------------- | +| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | ### Trim filler words -| Avoid | Prefer | -|-------|--------| -| visit the Docker Hub tags page | visit Docker Hub | -| check out the official docs | see the documentation | +| Avoid | Prefer | +| ------------------------------ | -------------------- | +| visit the Docker Hub tags page | visit Docker Hub | +| check out the official docs | see the documentation | ### Actor references @@ -256,11 +258,12 @@ can crawl websites and extract text content. - Decimals: period ($9.8) - Money: symbol before amount ($49, not 49$) - Dates: August 5, 2024 (never 5.8.2024) -- Time: 5 pm or 5 PM (space after number) +- Time: 5 PM (space before, uppercase) ## Common Mistakes Patterns to avoid: + - "Happy scraping!" closings - Em dashes - Title case headings From 9200730289cc2a61732fdaf3f1527fd7b42fbac0 Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 21:44:18 +0100 Subject: [PATCH 04/27] Fix remaining table alignment issues Ensure all table columns are properly aligned: - Content Types table - Admonitions table - Articles in definitions table - Word choice table - Trim filler words table Co-Authored-By: Claude Opus 4.5 --- .claude/rules/writing-style.md | 42 +++++++++++++++++----------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index f55e160d1d..dd1de7a94e 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -14,11 +14,11 @@ Instructions for AI assistants writing Apify documentation. Based on Apify style Match language to content type: -| Content type | CTA verbs | Example | -| ---------------- | ---------------------- | ------------------------------------------ | -| Tutorials/guides | Learn, Build, Create | "Learn how to build a web scraper" | -| Reference docs | Access, Integrate, Use | "Access the Apify platform programmatically" | -| Discovery pages | Explore, Discover, Browse | "Explore available Actors" | +| Content type | CTA verbs | Example | +| ---------------- | ------------------------- | -------------------------------------------- | +| Tutorials/guides | Learn, Build, Create | "Learn how to build a web scraper" | +| Reference docs | Access, Integrate, Use | "Access the Apify platform programmatically" | +| Discovery pages | Explore, Discover, Browse | "Explore available Actors" | Don't use "Learn" for pure reference documentation - it sets tutorial expectations. @@ -150,13 +150,13 @@ All items in a list must follow the same grammatical pattern: Use Docusaurus admonitions for important information: -| Type | Use for | -| -------------- | --------------------------------------- | -| `:::note` | General callouts | -| `:::tip` | Helpful suggestions | -| `:::info` | Background context | -| `:::caution` | Warnings about gotchas | -| `:::danger` | Critical warnings that could cause issues | +| Type | Use for | +| ------------ | ------------------------------------------- | +| `:::note` | General callouts | +| `:::tip` | Helpful suggestions | +| `:::info` | Background context | +| `:::caution` | Warnings about gotchas | +| `:::danger` | Critical warnings that could cause issues | Prefer admonitions over block quotes for highlighted content. @@ -166,8 +166,8 @@ Prefer admonitions over block quotes for highlighted content. Include "a/an" before nouns in definition lists: -| Avoid | Prefer | -| -------------------------------- | -------------------------------------- | +| Avoid | Prefer | +| ---------------------------------- | ------------------------------------ | | `{version}` - Node.js version only | `{version}` - A Node.js version only | ### Oxford comma @@ -197,10 +197,10 @@ Use "the" before "Apify platform", "Apify SDK", etc. ### Word choice -| Word | When to use | -| ----------- | ----------------------------------------- | -| legacy | Feature is deprecated or will be removed | -| alternative | Valid approach, but not the preferred one | +| Word | When to use | +| ----------- | ------------------------------------------- | +| legacy | Feature is deprecated or will be removed | +| alternative | Valid approach, but not the preferred one | | deprecated | Feature will be removed in a future version | ## Links @@ -231,9 +231,9 @@ When mentioning tools, languages, or external resources, link them to help reade ### Trim filler words -| Avoid | Prefer | -| ------------------------------ | -------------------- | -| visit the Docker Hub tags page | visit Docker Hub | +| Avoid | Prefer | +| ------------------------------ | --------------------- | +| visit the Docker Hub tags page | visit Docker Hub | | check out the official docs | see the documentation | ### Actor references From 91bc31377e3079e35a692b441c1e121b329aa72f Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 22:03:04 +0100 Subject: [PATCH 05/27] Move writing-style rules to .cursor/rules, symlink from .claude/rules Consolidates documentation rules into a single canonical source in .cursor/rules/writing-style.mdc with Cursor frontmatter. Claude Code reads the same rules via symlink, ensuring both tools stay in sync. Co-Authored-By: Claude Opus 4.5 --- .claude/rules/writing-style.mdc | 1 + .../writing-style.md => .cursor/rules/writing-style.mdc | 6 ++++++ 2 files changed, 7 insertions(+) create mode 120000 .claude/rules/writing-style.mdc rename .claude/rules/writing-style.md => .cursor/rules/writing-style.mdc (98%) diff --git a/.claude/rules/writing-style.mdc b/.claude/rules/writing-style.mdc new file mode 120000 index 0000000000..5da31644d8 --- /dev/null +++ b/.claude/rules/writing-style.mdc @@ -0,0 +1 @@ +../../.cursor/rules/writing-style.mdc \ No newline at end of file diff --git a/.claude/rules/writing-style.md b/.cursor/rules/writing-style.mdc similarity index 98% rename from .claude/rules/writing-style.md rename to .cursor/rules/writing-style.mdc index dd1de7a94e..53265b1634 100644 --- a/.claude/rules/writing-style.md +++ b/.cursor/rules/writing-style.mdc @@ -1,3 +1,9 @@ +--- +description: Comprehensive writing style rules for Apify documentation +globs: ["sources/**/*.md", "sources/**/*.mdx"] +alwaysApply: true +--- + # Apify Documentation Writing Style Instructions for AI assistants writing Apify documentation. Based on Apify style guide and technical writer feedback. From 0547c5e2a25f04056502ee9be4ffcd1ae82536bb Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 22:05:02 +0100 Subject: [PATCH 06/27] Add symlinks for file-organization and quality-standards rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Symlinks additional rule files from .cursor/rules to .claude/rules, keeping both tools in sync for documentation rules. ## Recommendation for TC-MO review Analysis found `quality-standards.mdc` is mostly redundant with `writing-style.mdc` (5 of 8 checklist items are duplicates). Three items in quality-standards are NOT in writing-style: - Front matter requirements - Alt text for images - Heading hierarchy (H1 → H2 → H3) Suggested consolidation: 1. Add missing 3 items to writing-style.mdc 2. Remove quality-standards.mdc (or keep as optional quick-reference) 3. Keep file-organization.mdc separate (different scope) This would give a cleaner split: - writing-style.mdc = how to write content - file-organization.mdc = how to name/organize files Co-Authored-By: Claude Opus 4.5 --- .claude/rules/file-organization.mdc | 1 + .claude/rules/quality-standards.mdc | 1 + 2 files changed, 2 insertions(+) create mode 120000 .claude/rules/file-organization.mdc create mode 120000 .claude/rules/quality-standards.mdc diff --git a/.claude/rules/file-organization.mdc b/.claude/rules/file-organization.mdc new file mode 120000 index 0000000000..1e76aa9c49 --- /dev/null +++ b/.claude/rules/file-organization.mdc @@ -0,0 +1 @@ +../../.cursor/rules/file-organization.mdc \ No newline at end of file diff --git a/.claude/rules/quality-standards.mdc b/.claude/rules/quality-standards.mdc new file mode 120000 index 0000000000..1f513889ba --- /dev/null +++ b/.claude/rules/quality-standards.mdc @@ -0,0 +1 @@ +../../.cursor/rules/quality-standards.mdc \ No newline at end of file From a8f4b3869da5fe69d9ac1b011f859146735e0866 Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 22:14:19 +0100 Subject: [PATCH 07/27] Fix symlink direction: .claude/rules is now canonical source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem Claude Code only reads `.md` files from `.claude/rules/`. Cursor IDE requires `.mdc` extension for rules to be recognized. The previous approach (canonical in .cursor/rules/, symlinks to .claude/) meant Claude Code would never read the rules because they had .mdc extension. ## Solution Reverse the symlink direction: ``` # Canonical files (Claude Code reads .md) .claude/rules/writing-style.md .claude/rules/file-organization.md .claude/rules/quality-standards.md # Symlinks for Cursor (.mdc extension required) .cursor/rules/writing-style.mdc → .claude/rules/writing-style.md .cursor/rules/file-organization.mdc → .claude/rules/file-organization.md .cursor/rules/quality-standards.mdc → .claude/rules/quality-standards.md ``` The YAML frontmatter in .md files is harmless to Claude Code - it just sees it as extra context. Cursor reads the symlinked content and the .mdc extension satisfies its format requirement. ## Result - Single source of truth in .claude/rules/*.md - Both Claude Code and Cursor can read the rules - Future edits happen in one place Co-Authored-By: Claude Opus 4.5 --- .claude/rules/file-organization.md | 26 +++ .claude/rules/file-organization.mdc | 1 - .claude/rules/quality-standards.md | 20 ++ .claude/rules/quality-standards.mdc | 1 - .claude/rules/writing-style.md | 289 +++++++++++++++++++++++++++ .claude/rules/writing-style.mdc | 1 - .cursor/rules/file-organization.mdc | 27 +-- .cursor/rules/quality-standards.mdc | 21 +- .cursor/rules/writing-style.mdc | 290 +--------------------------- 9 files changed, 338 insertions(+), 338 deletions(-) create mode 100644 .claude/rules/file-organization.md delete mode 120000 .claude/rules/file-organization.mdc create mode 100644 .claude/rules/quality-standards.md delete mode 120000 .claude/rules/quality-standards.mdc create mode 100644 .claude/rules/writing-style.md delete mode 120000 .claude/rules/writing-style.mdc mode change 100644 => 120000 .cursor/rules/file-organization.mdc mode change 100644 => 120000 .cursor/rules/quality-standards.mdc mode change 100644 => 120000 .cursor/rules/writing-style.mdc diff --git a/.claude/rules/file-organization.md b/.claude/rules/file-organization.md new file mode 100644 index 0000000000..55cee71f1f --- /dev/null +++ b/.claude/rules/file-organization.md @@ -0,0 +1,26 @@ +--- +description: File naming conventions and directory structure standards +globs: ["sources/**/*"] +alwaysApply: true +--- + +# File Organization Rules + +## Naming conventions + +- Use **kebab-case** for file names: `web-scraping-basics.md` +- Use **descriptive names** that reflect content +- Group related files in **logical directories** + +## Directory structure + +```text +sources/ +├── platform/ # Platform documentation +│ ├── actors/ # Actor-related content +│ ├── storage/ # Storage documentation +│ └── integrations/ # Integration guides +└── academy/ # Educational content + ├── tutorials/ # Step-by-step guides + ├── webscraping/ # Web scraping courses +``` diff --git a/.claude/rules/file-organization.mdc b/.claude/rules/file-organization.mdc deleted file mode 120000 index 1e76aa9c49..0000000000 --- a/.claude/rules/file-organization.mdc +++ /dev/null @@ -1 +0,0 @@ -../../.cursor/rules/file-organization.mdc \ No newline at end of file diff --git a/.claude/rules/quality-standards.md b/.claude/rules/quality-standards.md new file mode 100644 index 0000000000..dbc3d6c6f1 --- /dev/null +++ b/.claude/rules/quality-standards.md @@ -0,0 +1,20 @@ +--- +description: Content quality checklist and review standards +globs: ["sources/**/*.md", "sources/**/*.mdx"] +alwaysApply: true +--- + +# Quality Standards + +## Content quality guidelines + +When creating or editing content, ensure: + +- [ ] Content follows Microsoft style guide (sentence case headings, proper emphasis) +- [ ] Front matter includes proper title, description, and metadata +- [ ] Code examples are complete and include proper syntax highlighting +- [ ] All links use descriptive text (avoid "click here") +- [ ] Images include meaningful alt text +- [ ] Content uses inclusive language and active voice +- [ ] Headings follow proper hierarchy (H1 → H2 → H3) +- [ ] Content is clear, concise, and action-oriented diff --git a/.claude/rules/quality-standards.mdc b/.claude/rules/quality-standards.mdc deleted file mode 120000 index 1f513889ba..0000000000 --- a/.claude/rules/quality-standards.mdc +++ /dev/null @@ -1 +0,0 @@ -../../.cursor/rules/quality-standards.mdc \ No newline at end of file diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md new file mode 100644 index 0000000000..53265b1634 --- /dev/null +++ b/.claude/rules/writing-style.md @@ -0,0 +1,289 @@ +--- +description: Comprehensive writing style rules for Apify documentation +globs: ["sources/**/*.md", "sources/**/*.mdx"] +alwaysApply: true +--- + +# Apify Documentation Writing Style + +Instructions for AI assistants writing Apify documentation. Based on Apify style guide and technical writer feedback. + +## Core Principles + +1. **Simple** - Get to the point. No sentence over 30 words. Every sentence delivers information. +1. **Factual** - Back up claims with evidence. Use numbers, not vague qualifiers. +1. **Technical** - Write for developers. Don't oversimplify. Link to fill knowledge gaps. + +> Write the same way you would explain something to a person sitting next to you. + +## Content Types + +Match language to content type: + +| Content type | CTA verbs | Example | +| ---------------- | ------------------------- | -------------------------------------------- | +| Tutorials/guides | Learn, Build, Create | "Learn how to build a web scraper" | +| Reference docs | Access, Integrate, Use | "Access the Apify platform programmatically" | +| Discovery pages | Explore, Discover, Browse | "Explore available Actors" | + +Don't use "Learn" for pure reference documentation - it sets tutorial expectations. + +## Language & Tone + +### US English + +Use "analyze" not "analyse", "color" not "colour". + +### Imperative tone + +Use direct instructions, not soft recommendations: + +| Avoid | Prefer | +| --------------------------------- | ------------------- | +| We recommend pinning the version | Pin the version | +| You should use the latest SDK | Use the latest SDK | +| It's best to avoid hardcoding | Avoid hardcoding | + +### No sales language + +| Avoid | Prefer | +| ------------------------------------------ | --------------------------------------------------- | +| Experience Apify, the ultimate platform! | Welcome to Apify, the cloud web scraping platform. | +| Our highly efficient system | Apify's system handles 500K requests per minute | + +### Avoid first person + +Use "you" to focus on the reader. Avoid "I", "me", "myself" in docs. + +| Avoid | Prefer | +| ------------------------------------- | -------------------------------- | +| I recommend using version 22 | Use version 22 | +| In my experience, this works better | This approach is more reliable | + +### Active & inclusive voice + +Use active voice. Avoid gendered terms. Don't use directional language ("left/right") for UI - it breaks with different layouts. + +| Avoid | Prefer | +| --------------------------------- | -------------------------------- | +| The Actor is started by the user | The user starts the Actor | +| He can configure his settings | You can configure your settings | +| Click the button on the left | Click the **Settings** button | + +## Formatting + +### Headings + +**Sentence case only.** No title case. + +| Avoid | Prefer | +| --------------------- | --------------------- | +| Store And Manage Data | Store and manage data | + +**No gerunds (-ing forms).** Use noun phrases or imperatives. + +| Avoid | Prefer | +| ----------------------------- | -------------------------- | +| Finding available tags | Available tags | +| Getting started with Actors | Get started with Actors | +| Understanding the API | API overview | + +Rationale: Noun-phrase headings are more scannable and search-friendly (Microsoft style guide). + +### Bold + +**Do use bold for:** + +- UI elements (buttons, menus, fields): Click the **Actors** button +- Critical warnings or key terms + +**Don't use bold for:** + +- List introductions +- Code block introductions +- Section labels when context is clear + +| Avoid | Prefer | +| ------------------------------- | ----------------------------- | +| **Examples:** | Examples: | +| **In your Dockerfile**, use... | In your `Dockerfile`, use... | + +Bold for UI elements helps users scan for clickable items. Bold for structure creates visual noise. + +### Italics + +Use italics for emphasis and introducing new terms: + +| Use case | Example | +| ------------------------ | --------------------------------------------- | +| New term introduction | An *Actor* is a serverless program... | +| Emphasis | This step is *required* for the Actor to work | + +### List types + +**Numbered lists** - Sequential steps where order matters +**Bullet points** - Non-sequential items, features, options + +In numbered lists, use `1.` for all items (not sequential numbers). Easier to maintain: + +```markdown +1. First step +1. Second step +1. Third step +``` + +### Parallel structure + +All items in a list must follow the same grammatical pattern: + +```markdown +# Avoid - mixed patterns +1. Reproducibility - your builds behave the same +1. Predictability - you know which version +1. Easier to track down issues + +# Prefer - consistent pattern +1. Reproducibility - Your builds behave the same way +1. Predictability - You know exactly which version you're running +1. Debugging - Version-specific issues are easier to track down +``` + +### Em dashes + +**Don't use em dashes (—).** LLMs overuse them. Use hyphen with spaces ( - ) instead. + +### Admonitions + +Use Docusaurus admonitions for important information: + +| Type | Use for | +| ------------ | ------------------------------------------- | +| `:::note` | General callouts | +| `:::tip` | Helpful suggestions | +| `:::info` | Background context | +| `:::caution` | Warnings about gotchas | +| `:::danger` | Critical warnings that could cause issues | + +Prefer admonitions over block quotes for highlighted content. + +## Grammar + +### Articles in definitions + +Include "a/an" before nouns in definition lists: + +| Avoid | Prefer | +| ---------------------------------- | ------------------------------------ | +| `{version}` - Node.js version only | `{version}` - A Node.js version only | + +### Oxford comma + +Always use the serial comma: + +| Avoid | Prefer | +| ---------------------------- | -------------------------------- | +| pencil, eraser and notebook | pencil, eraser, and notebook | + +### "the" before products + +Use "the" before "Apify platform", "Apify SDK", etc. + +| Avoid | Prefer | +| -------------------- | ------------------------- | +| I use Apify platform | I use the Apify platform | + +## Terminology + +### Capitalization + +- **Actor** - Always uppercase when referring to Apify Actors +- **Apify Proxy**, **Apify Console**, **Apify Store** - Product names, capitalized +- **the Apify platform** - Lowercase "platform", include "the" +- **task**, **schedule** - Lowercase + +### Word choice + +| Word | When to use | +| ----------- | ------------------------------------------- | +| legacy | Feature is deprecated or will be removed | +| alternative | Valid approach, but not the preferred one | +| deprecated | Feature will be removed in a future version | + +## Links + +### Action-oriented text + +| Avoid | Prefer | +| --------------------------------- | --------------------------------------- | +| [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | +| See the [documentation](url) | [Read the documentation](url) | + +### Accessible link text + +Use descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. + +| Avoid | Prefer | +| ---------------------------------- | ----------------------------------------- | +| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` | +| Read more about it `[here](url)` | Read the `[Actor development guide](url)` | + +### Make tool mentions navigable + +When mentioning tools, languages, or external resources, link them to help readers explore: + +| Avoid | Prefer | +| ----------------------------------- | ----------------------------------------------------------- | +| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | + +### Trim filler words + +| Avoid | Prefer | +| ------------------------------ | --------------------- | +| visit the Docker Hub tags page | visit Docker Hub | +| check out the official docs | see the documentation | + +### Actor references + +First mention: Actor name with link, capitalized. + +```markdown +[Website Content Crawler](https://apify.com/apify/website-content-crawler) +can crawl websites and extract text content. +``` + +## Code Examples + +- Use backticks for file names, commands, config keys +- Prefer complete, runnable examples +- Add comments only when code isn't self-explanatory +- Match versions in examples (e.g., Dockerfile tag matches package.json version) + +## Numbers & Formatting + +- Thousands: comma separator ($1,000) +- Decimals: period ($9.8) +- Money: symbol before amount ($49, not 49$) +- Dates: August 5, 2024 (never 5.8.2024) +- Time: 5 PM (space before, uppercase) + +## Common Mistakes + +Patterns to avoid: + +- "Happy scraping!" closings +- Em dashes +- Title case headings +- Gerunds in headings +- Bold for routine structure +- "Ok" (use "OK" or "okay") +- Missing "the" before "Apify platform" +- Sales language ("ultimate", "cutting-edge", "supercharge") +- Vague claims without numbers + +## Reference + +This guide covers writing patterns. For structural guidelines (file naming, screenshots, tutorial structure, SEO), see: + +- [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution workflow and repository standards +- [AGENTS.md](../../AGENTS.md) - Comprehensive documentation guidelines for AI assistants +- Full Apify style guide: https://www.notion.so/apify/de9fbb99dcd84665b6d3f790fc88b3b6 diff --git a/.claude/rules/writing-style.mdc b/.claude/rules/writing-style.mdc deleted file mode 120000 index 5da31644d8..0000000000 --- a/.claude/rules/writing-style.mdc +++ /dev/null @@ -1 +0,0 @@ -../../.cursor/rules/writing-style.mdc \ No newline at end of file diff --git a/.cursor/rules/file-organization.mdc b/.cursor/rules/file-organization.mdc deleted file mode 100644 index 55cee71f1f..0000000000 --- a/.cursor/rules/file-organization.mdc +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: File naming conventions and directory structure standards -globs: ["sources/**/*"] -alwaysApply: true ---- - -# File Organization Rules - -## Naming conventions - -- Use **kebab-case** for file names: `web-scraping-basics.md` -- Use **descriptive names** that reflect content -- Group related files in **logical directories** - -## Directory structure - -```text -sources/ -├── platform/ # Platform documentation -│ ├── actors/ # Actor-related content -│ ├── storage/ # Storage documentation -│ └── integrations/ # Integration guides -└── academy/ # Educational content - ├── tutorials/ # Step-by-step guides - ├── webscraping/ # Web scraping courses -``` diff --git a/.cursor/rules/file-organization.mdc b/.cursor/rules/file-organization.mdc new file mode 120000 index 0000000000..b434263850 --- /dev/null +++ b/.cursor/rules/file-organization.mdc @@ -0,0 +1 @@ +../../.claude/rules/file-organization.md \ No newline at end of file diff --git a/.cursor/rules/quality-standards.mdc b/.cursor/rules/quality-standards.mdc deleted file mode 100644 index dbc3d6c6f1..0000000000 --- a/.cursor/rules/quality-standards.mdc +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: Content quality checklist and review standards -globs: ["sources/**/*.md", "sources/**/*.mdx"] -alwaysApply: true ---- - -# Quality Standards - -## Content quality guidelines - -When creating or editing content, ensure: - -- [ ] Content follows Microsoft style guide (sentence case headings, proper emphasis) -- [ ] Front matter includes proper title, description, and metadata -- [ ] Code examples are complete and include proper syntax highlighting -- [ ] All links use descriptive text (avoid "click here") -- [ ] Images include meaningful alt text -- [ ] Content uses inclusive language and active voice -- [ ] Headings follow proper hierarchy (H1 → H2 → H3) -- [ ] Content is clear, concise, and action-oriented diff --git a/.cursor/rules/quality-standards.mdc b/.cursor/rules/quality-standards.mdc new file mode 120000 index 0000000000..a7640b2aa0 --- /dev/null +++ b/.cursor/rules/quality-standards.mdc @@ -0,0 +1 @@ +../../.claude/rules/quality-standards.md \ No newline at end of file diff --git a/.cursor/rules/writing-style.mdc b/.cursor/rules/writing-style.mdc deleted file mode 100644 index 53265b1634..0000000000 --- a/.cursor/rules/writing-style.mdc +++ /dev/null @@ -1,289 +0,0 @@ ---- -description: Comprehensive writing style rules for Apify documentation -globs: ["sources/**/*.md", "sources/**/*.mdx"] -alwaysApply: true ---- - -# Apify Documentation Writing Style - -Instructions for AI assistants writing Apify documentation. Based on Apify style guide and technical writer feedback. - -## Core Principles - -1. **Simple** - Get to the point. No sentence over 30 words. Every sentence delivers information. -1. **Factual** - Back up claims with evidence. Use numbers, not vague qualifiers. -1. **Technical** - Write for developers. Don't oversimplify. Link to fill knowledge gaps. - -> Write the same way you would explain something to a person sitting next to you. - -## Content Types - -Match language to content type: - -| Content type | CTA verbs | Example | -| ---------------- | ------------------------- | -------------------------------------------- | -| Tutorials/guides | Learn, Build, Create | "Learn how to build a web scraper" | -| Reference docs | Access, Integrate, Use | "Access the Apify platform programmatically" | -| Discovery pages | Explore, Discover, Browse | "Explore available Actors" | - -Don't use "Learn" for pure reference documentation - it sets tutorial expectations. - -## Language & Tone - -### US English - -Use "analyze" not "analyse", "color" not "colour". - -### Imperative tone - -Use direct instructions, not soft recommendations: - -| Avoid | Prefer | -| --------------------------------- | ------------------- | -| We recommend pinning the version | Pin the version | -| You should use the latest SDK | Use the latest SDK | -| It's best to avoid hardcoding | Avoid hardcoding | - -### No sales language - -| Avoid | Prefer | -| ------------------------------------------ | --------------------------------------------------- | -| Experience Apify, the ultimate platform! | Welcome to Apify, the cloud web scraping platform. | -| Our highly efficient system | Apify's system handles 500K requests per minute | - -### Avoid first person - -Use "you" to focus on the reader. Avoid "I", "me", "myself" in docs. - -| Avoid | Prefer | -| ------------------------------------- | -------------------------------- | -| I recommend using version 22 | Use version 22 | -| In my experience, this works better | This approach is more reliable | - -### Active & inclusive voice - -Use active voice. Avoid gendered terms. Don't use directional language ("left/right") for UI - it breaks with different layouts. - -| Avoid | Prefer | -| --------------------------------- | -------------------------------- | -| The Actor is started by the user | The user starts the Actor | -| He can configure his settings | You can configure your settings | -| Click the button on the left | Click the **Settings** button | - -## Formatting - -### Headings - -**Sentence case only.** No title case. - -| Avoid | Prefer | -| --------------------- | --------------------- | -| Store And Manage Data | Store and manage data | - -**No gerunds (-ing forms).** Use noun phrases or imperatives. - -| Avoid | Prefer | -| ----------------------------- | -------------------------- | -| Finding available tags | Available tags | -| Getting started with Actors | Get started with Actors | -| Understanding the API | API overview | - -Rationale: Noun-phrase headings are more scannable and search-friendly (Microsoft style guide). - -### Bold - -**Do use bold for:** - -- UI elements (buttons, menus, fields): Click the **Actors** button -- Critical warnings or key terms - -**Don't use bold for:** - -- List introductions -- Code block introductions -- Section labels when context is clear - -| Avoid | Prefer | -| ------------------------------- | ----------------------------- | -| **Examples:** | Examples: | -| **In your Dockerfile**, use... | In your `Dockerfile`, use... | - -Bold for UI elements helps users scan for clickable items. Bold for structure creates visual noise. - -### Italics - -Use italics for emphasis and introducing new terms: - -| Use case | Example | -| ------------------------ | --------------------------------------------- | -| New term introduction | An *Actor* is a serverless program... | -| Emphasis | This step is *required* for the Actor to work | - -### List types - -**Numbered lists** - Sequential steps where order matters -**Bullet points** - Non-sequential items, features, options - -In numbered lists, use `1.` for all items (not sequential numbers). Easier to maintain: - -```markdown -1. First step -1. Second step -1. Third step -``` - -### Parallel structure - -All items in a list must follow the same grammatical pattern: - -```markdown -# Avoid - mixed patterns -1. Reproducibility - your builds behave the same -1. Predictability - you know which version -1. Easier to track down issues - -# Prefer - consistent pattern -1. Reproducibility - Your builds behave the same way -1. Predictability - You know exactly which version you're running -1. Debugging - Version-specific issues are easier to track down -``` - -### Em dashes - -**Don't use em dashes (—).** LLMs overuse them. Use hyphen with spaces ( - ) instead. - -### Admonitions - -Use Docusaurus admonitions for important information: - -| Type | Use for | -| ------------ | ------------------------------------------- | -| `:::note` | General callouts | -| `:::tip` | Helpful suggestions | -| `:::info` | Background context | -| `:::caution` | Warnings about gotchas | -| `:::danger` | Critical warnings that could cause issues | - -Prefer admonitions over block quotes for highlighted content. - -## Grammar - -### Articles in definitions - -Include "a/an" before nouns in definition lists: - -| Avoid | Prefer | -| ---------------------------------- | ------------------------------------ | -| `{version}` - Node.js version only | `{version}` - A Node.js version only | - -### Oxford comma - -Always use the serial comma: - -| Avoid | Prefer | -| ---------------------------- | -------------------------------- | -| pencil, eraser and notebook | pencil, eraser, and notebook | - -### "the" before products - -Use "the" before "Apify platform", "Apify SDK", etc. - -| Avoid | Prefer | -| -------------------- | ------------------------- | -| I use Apify platform | I use the Apify platform | - -## Terminology - -### Capitalization - -- **Actor** - Always uppercase when referring to Apify Actors -- **Apify Proxy**, **Apify Console**, **Apify Store** - Product names, capitalized -- **the Apify platform** - Lowercase "platform", include "the" -- **task**, **schedule** - Lowercase - -### Word choice - -| Word | When to use | -| ----------- | ------------------------------------------- | -| legacy | Feature is deprecated or will be removed | -| alternative | Valid approach, but not the preferred one | -| deprecated | Feature will be removed in a future version | - -## Links - -### Action-oriented text - -| Avoid | Prefer | -| --------------------------------- | --------------------------------------- | -| [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | -| See the [documentation](url) | [Read the documentation](url) | - -### Accessible link text - -Use descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. - -| Avoid | Prefer | -| ---------------------------------- | ----------------------------------------- | -| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` | -| Read more about it `[here](url)` | Read the `[Actor development guide](url)` | - -### Make tool mentions navigable - -When mentioning tools, languages, or external resources, link them to help readers explore: - -| Avoid | Prefer | -| ----------------------------------- | ----------------------------------------------------------- | -| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | - -### Trim filler words - -| Avoid | Prefer | -| ------------------------------ | --------------------- | -| visit the Docker Hub tags page | visit Docker Hub | -| check out the official docs | see the documentation | - -### Actor references - -First mention: Actor name with link, capitalized. - -```markdown -[Website Content Crawler](https://apify.com/apify/website-content-crawler) -can crawl websites and extract text content. -``` - -## Code Examples - -- Use backticks for file names, commands, config keys -- Prefer complete, runnable examples -- Add comments only when code isn't self-explanatory -- Match versions in examples (e.g., Dockerfile tag matches package.json version) - -## Numbers & Formatting - -- Thousands: comma separator ($1,000) -- Decimals: period ($9.8) -- Money: symbol before amount ($49, not 49$) -- Dates: August 5, 2024 (never 5.8.2024) -- Time: 5 PM (space before, uppercase) - -## Common Mistakes - -Patterns to avoid: - -- "Happy scraping!" closings -- Em dashes -- Title case headings -- Gerunds in headings -- Bold for routine structure -- "Ok" (use "OK" or "okay") -- Missing "the" before "Apify platform" -- Sales language ("ultimate", "cutting-edge", "supercharge") -- Vague claims without numbers - -## Reference - -This guide covers writing patterns. For structural guidelines (file naming, screenshots, tutorial structure, SEO), see: - -- [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution workflow and repository standards -- [AGENTS.md](../../AGENTS.md) - Comprehensive documentation guidelines for AI assistants -- Full Apify style guide: https://www.notion.so/apify/de9fbb99dcd84665b6d3f790fc88b3b6 diff --git a/.cursor/rules/writing-style.mdc b/.cursor/rules/writing-style.mdc new file mode 120000 index 0000000000..502fd404ed --- /dev/null +++ b/.cursor/rules/writing-style.mdc @@ -0,0 +1 @@ +../../.claude/rules/writing-style.md \ No newline at end of file From ab441444d34d1b6edc1dbed40eb41e12b17356ed Mon Sep 17 00:00:00 2001 From: Ondra Urban Date: Wed, 21 Jan 2026 22:19:34 +0100 Subject: [PATCH 08/27] Exclude AI assistant config files from Vale linting .claude/rules/ and .cursor/rules/ contain configuration files for AI assistants, not user-facing documentation. These files weren't checked before because .cursor/rules/ used .mdc extension (not in Vale's scope). Now that canonical files are .md in .claude/rules/, they need explicit exclusion since they don't follow documentation conventions (e.g., H1 headings are fine in config files). Co-Authored-By: Claude Opus 4.5 --- .github/workflows/vale.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/vale.yaml b/.github/workflows/vale.yaml index 8a626e0f0e..89cbc8fffc 100644 --- a/.github/workflows/vale.yaml +++ b/.github/workflows/vale.yaml @@ -23,6 +23,8 @@ jobs: apify-api/openapi/paths/README.md apify-api/openapi/components/README.md sources/legal/**/*.{md,mdx} + .claude/rules/**/*.{md,mdx} + .cursor/rules/**/*.{md,mdx} separator: ',' - uses: errata-ai/vale-action@reviewdog From 8f99fdd231e26237ec549b3433024e30827a6e64 Mon Sep 17 00:00:00 2001 From: Ondra Urban <23726914+mnmkng@users.noreply.github.com> Date: Mon, 26 Jan 2026 17:52:36 +0100 Subject: [PATCH 09/27] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com> --- .claude/rules/writing-style.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index 53265b1634..1a4cf04792 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -48,7 +48,7 @@ Use direct instructions, not soft recommendations: | Avoid | Prefer | | ------------------------------------------ | --------------------------------------------------- | -| Experience Apify, the ultimate platform! | Welcome to Apify, the cloud web scraping platform. | +| Experience Apify, the ultimate platform! | Welcome to Apify, the full-stack web scraping platform. | | Our highly efficient system | Apify's system handles 500K requests per minute | ### Avoid first person @@ -205,9 +205,9 @@ Use "the" before "Apify platform", "Apify SDK", etc. | Word | When to use | | ----------- | ------------------------------------------- | -| legacy | Feature is deprecated or will be removed | -| alternative | Valid approach, but not the preferred one | -| deprecated | Feature will be removed in a future version | +| legacy | Old approach still supported for backward compatibility, no announced removal | +| alternative | Valid approach, but not the preferred one | +| deprecated | Feature officially marked for removal in a future version | ## Links @@ -240,7 +240,7 @@ When mentioning tools, languages, or external resources, link them to help reade | Avoid | Prefer | | ------------------------------ | --------------------- | | visit the Docker Hub tags page | visit Docker Hub | -| check out the official docs | see the documentation | +| check out the official docs | check the documentation | ### Actor references @@ -286,4 +286,4 @@ This guide covers writing patterns. For structural guidelines (file naming, scre - [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution workflow and repository standards - [AGENTS.md](../../AGENTS.md) - Comprehensive documentation guidelines for AI assistants -- Full Apify style guide: https://www.notion.so/apify/de9fbb99dcd84665b6d3f790fc88b3b6 +- Full Apify style guide: https://www.notion.so/apify/Apify-style-guide-1b9f39950a2280d49e5be69ce2961a79 From 20300a373dc38eb57a7084ac5c2ce18af0b9692f Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 10:52:07 +0100 Subject: [PATCH 10/27] 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 6e65d160ca9ad8af65ad5f9debc980bba9911c34 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:05:14 +0100 Subject: [PATCH 11/27] 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 1171a0b3c0494ea51817641538620d8a371589af Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:37:21 +0100 Subject: [PATCH 12/27] 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 08710d70da2fc91e9cfb98ebccddcde03381d96c Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:38:55 +0100 Subject: [PATCH 13/27] 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 34bfee22b95f43c6b9234aaedcdc1dab9304496d Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:43:51 +0100 Subject: [PATCH 14/27] 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 cde5c63d0a8c6fff1ab228fe02bbd879275effb5 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:46:09 +0100 Subject: [PATCH 15/27] 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 db0cf0b9bd896e1214ead4422b04e7bffadbf113 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 11:51:09 +0100 Subject: [PATCH 16/27] 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 be52311d45842bc7eff693a104ff6c858944d0a8 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:03:24 +0100 Subject: [PATCH 17/27] 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 fc49082ff624dda43e3c26f746e162823519aa96 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:36:08 +0100 Subject: [PATCH 18/27] 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 d1c4b8cf8c114ce534e7885b3ce63ce1807d3d8f Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:43:44 +0100 Subject: [PATCH 19/27] 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 5b6dcd6dd6657a53becdc5af276f67c479eb355c Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 12:49:16 +0100 Subject: [PATCH 20/27] 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 cc09b76773341226da6d4387ad3732c2b709deb6 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 14:57:31 +0100 Subject: [PATCH 21/27] 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 38ddbd62016a078d7e0166eeb799112000c09f60 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 15:06:07 +0100 Subject: [PATCH 22/27] 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 cb3e6c76295e02b9e669977943e5167fedf22b2b Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 15:08:56 +0100 Subject: [PATCH 23/27] 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 9b130f91c523f932ffd0adfa67aabd5bfb8aa232 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 21 Jan 2026 15:19:27 +0100 Subject: [PATCH 24/27] 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 From 4607e234ef4c19eb7395c9011a8d08d4386bda52 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Mon, 26 Jan 2026 19:07:02 +0100 Subject: [PATCH 25/27] refactor: consolidate and reorganize .claude/ documentation Remove duplicate content and improve organization across Claude Code documentation: - instructions.md: Remove duplicated sections (API specifics, common patterns, quality checklist), replace with references to skills - README.md: Simplify skill descriptions from verbose multi-line to concise one-liners - review-docs.md: Reorganize 11-item checklist into 3 categories (writing quality, content formatting, technical validation) - writing-style.md: Remove terminology section that duplicates terminology.md, add cross-reference Result: 103 lines reduced, better scannability, single source of truth maintained. Co-Authored-By: Claude Sonnet 4.5 --- .claude/README.md | 124 +++------ .claude/instructions.md | 233 +++-------------- .claude/rules/writing-style.md | 15 +- .claude/skills/review-docs.md | 443 +++++++-------------------------- 4 files changed, 166 insertions(+), 649 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 65c80a5064..91827fb73e 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -6,13 +6,19 @@ This directory contains Claude Code configuration for the Apify documentation re ```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 +├── README.md # This file - Quick start guide +├── instructions.md # Main instructions for Claude Code +├── rules/ # Canonical standards (auto-loaded) +│ ├── writing-style.md # Language, tone, grammar +│ ├── content-standards.md # Formatting, front matter, code +│ ├── terminology.md # Apify-specific terms +│ ├── file-organization.md # Naming conventions +│ └── quality-standards.md # Quality checklist +└── 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 @@ -25,33 +31,17 @@ This directory contains Claude Code configuration for the Apify documentation re ### Available skills -#### `/doc-write` - Documentation writing +#### /doc-write +Documentation writing - Create or edit pages following style guide -Create or edit documentation following Apify style guide. +#### /api-doc +API documentation - Work with OpenAPI specifications and endpoints -- Use for: New pages, content updates, reformatting -- Handles: Style compliance, formatting, structure +#### /tutorial +Tutorial creation - Build structured, educational tutorials -#### `/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 +#### /review-docs +Documentation review - Check quality and compliance before submission ## Quick start @@ -79,50 +69,21 @@ Use /api-doc skill to document the new [endpoint-name] endpoint 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 +## Documentation standards -### Writing style +All documentation standards are in `.claude/rules/` (auto-loaded): -- US English, active voice, inclusive language -- Sentence case for headings (not Title Case) -- Action-oriented phrasing -- No directional language (left/right) +1. **`writing-style.md`** - Language, tone, grammar, headings, word choice +2. **`content-standards.md`** - Front matter, formatting, code examples, links, images +3. **`terminology.md`** - Apify-specific capitalization and product names +4. **`file-organization.md`** - File naming and directory structure +5. **`quality-standards.md`** - Comprehensive pre-submission checklist -### Front matter +Also reference: -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 +- **`AGENTS.md`** - Vendor-agnostic documentation standards (in repo root) +- **`CONTRIBUTING.md`** - Setup, workflows, contribution process +- **`instructions.md`** - Full Claude Code instructions (in this directory) ## Testing @@ -137,22 +98,11 @@ 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. +1. **Read `AGENTS.md` first** - Vendor-agnostic documentation standards +2. **Check `.claude/rules/`** - Auto-loaded standards for writing, formatting, terminology +3. **Use the appropriate skill** - Designed for specific documentation tasks +4. **Run linters before committing** - `npm run lint:md` and `npm run lint:code` +5. **Review before submit** - Use `/review-docs` skill for final checks ## Need help? diff --git a/.claude/instructions.md b/.claude/instructions.md index fa10361fa7..a98b59ccae 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -14,9 +14,15 @@ The project uses Docusaurus with MDX, follows Microsoft style guide principles, **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) +1. **AGENTS.md** - Primary vendor-agnostic documentation standards (READ THIS FIRST) +2. **.claude/rules/** - Claude Code-specific standards (AUTO-LOADED) + - `writing-style.md` - Language, tone, grammar, and writing guidelines + - `content-standards.md` - Formatting, front matter, code examples, links, images + - `terminology.md` - Apify-specific capitalization and terminology + - `file-organization.md` - File naming and directory structure + - `quality-standards.md` - Comprehensive quality checklist +3. **CONTRIBUTING.md** - Contribution guidelines, setup, and workflows +4. `.cursor/rules/*.mdc` - Cursor-specific rules (for reference) ## Available skills @@ -42,91 +48,24 @@ Use these skills for specific documentation tasks: **When to use**: Reviewing documentation before submission **Handles**: Style guide compliance, quality checks, consistency -## Core documentation standards +## Documentation standards -### Language & style +All documentation standards are defined in `.claude/rules/` and are auto-loaded by Claude Code: -- **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 +- **Writing style**: See `writing-style.md` for language, tone, grammar, headings, and word choice +- **Content formatting**: See `content-standards.md` for front matter, text formatting, admonitions, code examples, links, and images +- **Terminology**: See `terminology.md` for Apify-specific capitalization and product names +- **File organization**: See `file-organization.md` for naming conventions and directory structure +- **Quality assurance**: See `quality-standards.md` for comprehensive pre-submission checklist -### Front matter requirements - -Every documentation file must include: - -```yaml ---- -title: "Sentence case title (action-oriented, simple present tense)" -description: "140-160 chars - explain value, not features (no 'documentation' word)" -sidebar_position: 1 -slug: /path/to/page ---- -``` - -**Important**: Match slug to file path - -- File: `/sources/platform/actors/running.md` -- Slug: `/platform/actors/running` - -### Text formatting standards - -- **Bold** ONLY for UI elements, buttons, tabs, menu items (e.g., "Click **Save & Run**"). NEVER use bold for emphasis. -- _Italics_ for emphasis (use sparingly) -- `code` for inline code, file names, paths, API parameters (e.g., "Set `timeout` in `INPUT.json`") -- Code blocks MUST specify language: ` ```javascript `, ` ```python `, ` ```bash ` -- **All admonitions MUST have a title** - Available types: `note`, `tip`, `info`, `caution`, `danger` - -### Code examples - -- Include complete, runnable examples -- Use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) for multiple languages (JavaScript, Python) -- Add syntax highlighting with language tags (REQUIRED) -- Include comments for complex logic -- Show realistic, meaningful examples - -### Admonition format - -**All admonitions MUST include a title:** - -```markdown -:::note Important information - -Your note content here. - -::: - -:::tip Pro tip - -Helpful advice for advanced users. - -::: - -:::caution Warning - -Something that could cause issues. - -::: -``` - -### Links +**Quick reference**: +- Use sentence case for headings (not Title Case) +- Bold only for UI elements (not emphasis) +- All admonitions must have titles +- Front matter required (title, description 140-160 chars, sidebar_position, slug) - 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 +- All code blocks must specify language ## File organization @@ -152,31 +91,7 @@ sources/ ## 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` +See the `/api-doc` skill for comprehensive OpenAPI specification standards, operation ID conventions, and path file naming. ## Development workflow @@ -200,13 +115,13 @@ Replace `/` with `@` in URL paths: 1. Run linting checks: ```bash - npm run lint:md # Markdown linting - npm run lint:code # Code linting + npm run lint:md # Markdownlint - Markdown syntax/formatting + npm run lint:code # ESLint - 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 + npx markdownlint "path/to/file.md" # Markdownlint - Check specific files + vale sync # Vale - Download styles (first time) + vale "path/to/file.md" --minAlertLevel=error # Vale - Check prose style ``` 2. Use `/review-docs` skill to check compliance @@ -225,97 +140,27 @@ 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 +See respective skills for content-type specific patterns: -### 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) +- **Tutorials**: See `/tutorial` skill for 8-section tutorial structure +- **Platform documentation**: See `/doc-write` skill for feature documentation patterns +- **API documentation**: See `/api-doc` skill for endpoint documentation patterns ## Quality checklist -Before considering any documentation complete: - -- [ ] Content follows Microsoft style guide -- [ ] Front matter complete (title, description 140-160 chars) -- [ ] Code examples complete with syntax highlighting -- [ ] Links use descriptive text -- [ ] Images include meaningful alt text -- [ ] Inclusive language and active voice used -- [ ] Proper heading hierarchy (H1 → H2 → H3) -- [ ] Content is clear, concise, action-oriented -- [ ] All automated linting passes -- [ ] Examples tested and working - -## Important notes - -### What NOT to do - -- Don't use Title Case for headings (use sentence case) -- Don't use gerunds in headings ("Creating" - use "Create" instead) -- Don't use bold for emphasis (ONLY for UI elements) -- Don't forget titles on admonitions (REQUIRED) -- Don't use "click here" or non-descriptive links -- Don't include the word "documentation" in descriptions -- Don't use directional language (left/right) -- Don't skip front matter -- Don't omit language tags on code blocks -- Don't use gendered language -- Don't commit without running linters -- Don't make assumptions about product features - ask instead -- Don't use incorrect Apify terminology (see terminology section) - -### Best practices +Before considering any documentation complete, see `quality-standards.md` for the comprehensive checklist and use the `/review-docs` skill for final review. + +## Best practices - Start with user's goal/problem - Provide context before technical details -- Use consistent Apify terminology (see terminology section) -- Use simple English - "use" not "utilize" -- Use Oxford commas in all lists -- Use simple present tense for headings +- Use consistent Apify terminology (see `terminology.md`) - Structure content logically (basic → advanced) - Link to related content -- Keep descriptions within 140-160 characters explaining value, not features -- Match slug to file path for consistency - Test all code examples before committing -- Use admonitions sparingly but effectively (always with titles) - Never make assumptions about product features - ask if unsure - For code review: check comments and obvious mistakes only -## Apify-specific terminology - -**Always use exact capitalization and phrasing:** - -- **Apify Actor** (never "Apify actor" or "apify actor") -- **Apify Proxy** (never "Apify proxy") -- **Apify Console** (never "the Apify Console") -- **Apify Store** (never "the Apify Store") -- **the Apify team** (lowercase "the", lowercase "team") -- **the Apify platform** (lowercase "the", lowercase "platform") -- **AI agent** (lowercase for generic terms) -- **MCP server** (lowercase for generic terms) - ## Content review process ### Before reviewing a PR @@ -369,9 +214,9 @@ Uses `@apify/docs-theme` package - don't modify theme files directly. ### Linting tools -- **markdownlint** - Markdown formatting -- **eslint** - JavaScript/TypeScript code -- **Vale** - Prose linting (optional, download styles with `vale sync`) +- **markdownlint** - Markdown syntax and formatting validation +- **eslint** - JavaScript/TypeScript code linting +- **Vale** - Prose style checking (optional, download styles with `vale sync`) ## Remember diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index 1a4cf04792..bb02713b20 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -194,20 +194,7 @@ Use "the" before "Apify platform", "Apify SDK", etc. ## Terminology -### Capitalization - -- **Actor** - Always uppercase when referring to Apify Actors -- **Apify Proxy**, **Apify Console**, **Apify Store** - Product names, capitalized -- **the Apify platform** - Lowercase "platform", include "the" -- **task**, **schedule** - Lowercase - -### Word choice - -| Word | When to use | -| ----------- | ------------------------------------------- | -| legacy | Old approach still supported for backward compatibility, no announced removal | -| alternative | Valid approach, but not the preferred one | -| deprecated | Feature officially marked for removal in a future version | +See `terminology.md` for complete Apify-specific terminology and capitalization rules. ## Links diff --git a/.claude/skills/review-docs.md b/.claude/skills/review-docs.md index 065d086174..1e368489d7 100644 --- a/.claude/skills/review-docs.md +++ b/.claude/skills/review-docs.md @@ -7,20 +7,27 @@ Review documentation for compliance with Apify style guide, quality standards, a ## 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 +- `AGENTS.md` - Vendor-agnostic documentation standards +- `CONTRIBUTING.md` - Contribution guidelines and workflows +- `.claude/rules/` - Claude Code-specific standards (auto-loaded) -- `CONTRIBUTING.md` - Contribution guidelines +## Standards reference -- `.cursor/rules/*.mdc` - Cursor-specific rules +This skill follows all standards defined in `.claude/rules/`: + +- **writing-style.md** - Language, tone, grammar (sentence case, no gerunds, active voice) +- **content-standards.md** - Front matter, formatting, admonitions (must have titles), code examples, links, images +- **terminology.md** - Apify-specific capitalization (Apify Actor not actor, the Apify platform) +- **file-organization.md** - File naming and directory structure +- **quality-standards.md** - Complete quality checklist + +**Review-specific process** and common issues are documented in this skill file below. ## Review process @@ -30,360 +37,88 @@ Review documentation for compliance with Apify style guide, quality standards, a ## Review checklist -### 1. Style guide compliance - -**Microsoft Style Guide**: - -- [ ] Headings use sentence case (not Title Case) - -- [ ] Headings use simple present tense ("Create an Actor" NOT "Creating an Actor") - -- [ ] UI elements use **bold** formatting ONLY (never bold for emphasis) - -- [ ] Emphasis uses _italics_ (used sparingly) - -- [ ] Inline code uses `backticks` - -- [ ] Proper use of numbered lists vs. bullet points - -- [ ] Oxford commas used in all lists - -**Language Guidelines**: - -- [ ] Uses US English spelling (e.g., "color" not "colour") - -- [ ] Uses simple English ("use" not "utilize") - -- [ ] Written in active voice - -- [ ] Uses inclusive language (no gendered terms) - -- [ ] Avoids directional language ("left/right") - -- [ ] Action-oriented phrasing - -**Apify Terminology** (check exact capitalization): - -- [ ] **Apify Actor** (never "Apify actor") - -- [ ] **Apify Proxy** (never "Apify proxy") - -- [ ] **Apify Console** (never "the Apify Console") - -- [ ] **Apify Store** (never "the Apify Store") - -- [ ] **the Apify team** (lowercase) - -- [ ] **the Apify platform** (lowercase) - -- [ ] **AI agent** (lowercase for generic terms) - -- [ ] **MCP server** (lowercase for generic terms) - -### 2. Front matter validation - -Required fields present and correct: - -- [ ] `title` - Clear, action-oriented, sentence case, simple present tense - -- [ ] `description` - 140-160 characters - -- [ ] `description` - Explains value, not features - -- [ ] `description` - Avoids word "documentation" - -- [ ] `description` - Action-oriented phrasing - -- [ ] `sidebar_position` - Appropriate numbering - -- [ ] `slug` - Correct URL path and matches file path - -**Example**: - -```yaml - ---- - -title: "Create an Actor" # ✅ Sentence case, simple present tense -description: "Build and deploy your first Apify Actor with this guide covering setup, development, testing, and best practices." # ✅ 140-160 chars, explains value -sidebar_position: 1 -slug: /actors/development/create # ✅ Matches file path - ---- - -``` - -### 3. Content structure - -**Heading Hierarchy**: - -- [ ] Single H1 (page title) only - -- [ ] Proper H2 → H3 → H4 nesting - -- [ ] No skipped levels (H2 → H4) - -- [ ] Headings are descriptive and scannable - -**Document Flow**: - -- [ ] Clear introduction explaining purpose - -- [ ] Logical progression of topics - -- [ ] Summary or next steps at end - -- [ ] Related content linked appropriately - -### 4. Code examples - -**Quality**: - -- [ ] Complete and runnable examples - -- [ ] Proper syntax highlighting with language tag (REQUIRED) - -- [ ] Includes comments for complex logic - -- [ ] Uses realistic, meaningful variable names - -- [ ] Shows both input and output where applicable - -**Code Review Scope**: - -- [ ] Code snippets are developer-provided - -- [ ] Review comments and obvious mistakes only (not full code review) - -**Multiple Languages**: - -- [ ] Uses [Docusaurus code tabs](https://docusaurus.io/docs/markdown-features/tabs) when showing multiple languages - -- [ ] Consistent examples across languages - -- [ ] Includes JavaScript and Python where applicable - -### 5. Links - -**Internal Links**: - -- [ ] Use relative paths - -- [ ] Point to correct locations - -- [ ] Use descriptive link text (not "click here") - -- [ ] Link text makes sense out of context - -**External Links**: - -- [ ] Open in new tab if appropriate - -- [ ] Point to reliable, permanent resources - -- [ ] Include brief context about destination - -**Example**: - -```markdown -# ✅ Good - -Learn more about [Actor definition files](/actors/development/actor-definition). - -# ❌ Bad - -Click [here](link) to learn more. - -``` - -### 6. Images and media - -**Screenshots**: - -- [ ] Use light theme - -- [ ] Include meaningful alt text - -- [ ] Use red indicators for highlighting - -- [ ] Appropriate size and resolution - -- [ ] Stored in proper directory - -**Alt Text**: - -- [ ] Describes image content - -- [ ] Useful for screen readers - -- [ ] Not just "image" or "screenshot" - -**Example**: - -```markdown -# ✅ Good - -![Actor input schema configuration in Apify Console](./images/input-schema.png) - -# ❌ Bad - -![screenshot](./img.png) - -``` - -### 7. Admonitions - -**Usage**: - -- [ ] **MUST have a title** (REQUIRED - no exceptions) - -- [ ] Appropriate type (note, tip, info, caution, danger) - -- [ ] Title is descriptive - -- [ ] Content is concise and relevant - -- [ ] Not overused (max 2-3 per page) - -**Example**: - -```markdown -# ✅ Good - has title and correct spacing - -:::tip Performance optimization - -Use `requestHandlerTimeoutSecs` to prevent slow requests from blocking your Actor. - -::: - -# ❌ Bad - missing title (REQUIRED) - -:::info -Be careful with this setting. -::: - -# ❌ Bad - no title - -:::tip -This is a helpful tip. -::: - -``` - -### 8. Technical accuracy - -**Validation**: - -- [ ] Code examples tested and working - -- [ ] API endpoints are current - -- [ ] Configuration examples are valid - -- [ ] Version numbers are up to date - -- [ ] No deprecated features recommended - -### 9. Accessibility - -**Compliance**: - -- [ ] Proper heading hierarchy - -- [ ] Descriptive link text - -- [ ] Alt text for images - -- [ ] Color not used as only indicator - -- [ ] Sufficient contrast in custom elements - -### 10. SEO optimization - -**Elements**: - -- [ ] Descriptive, unique page title - -- [ ] Meta description (140-160 chars) - -- [ ] Relevant keywords used naturally - -- [ ] Internal linking to related content - -- [ ] Proper heading structure - -### 11. Formatting consistency - -**Text Elements**: - -- [ ] Consistent use of bold for UI elements - -- [ ] Consistent use of italics for emphasis - -- [ ] Consistent use of code formatting - -- [ ] No unnecessary ALL CAPS - -- [ ] Proper spacing and line breaks - -**Lists**: - -- [ ] Parallel structure in list items - -- [ ] Proper punctuation (periods for sentences) - -- [ ] Consistent capitalization - -- [ ] Numbered for sequential steps - -- [ ] Bullets for non-sequential items - -### 12. Specific content types - -**For Tutorials**: - -- [ ] Clear learning objectives stated - -- [ ] Prerequisites listed - -- [ ] Sequential, numbered steps - -- [ ] Complete working examples - -- [ ] Summary and next steps - -**For API Documentation**: - -- [ ] Operation IDs follow conventions - -- [ ] All parameters documented - -- [ ] Response schemas complete - -- [ ] Code samples included - -- [ ] Error responses documented - -**For Reference Pages**: - -- [ ] Comprehensive parameter tables - -- [ ] Default values specified - -- [ ] Type information included - -- [ ] Examples for complex options - -- [ ] Related pages linked +Use this streamlined checklist for reviews. For detailed standards, see `.claude/rules/`: + +### Writing quality + +- [ ] **Style guide compliance** (see `writing-style.md` + `content-standards.md`) + - Headings: Sentence case, no gerunds ("Create" not "Creating") + - Bold: ONLY for UI elements (not emphasis) + - Language: US English, active voice, inclusive, simple + - Terminology: Check `terminology.md` for exact capitalization + +- [ ] **Front matter** (see `content-standards.md`) + - `title` - Sentence case, simple present tense + - `description` - 140-160 chars, value-focused (not feature list) + - `slug` - Matches file path + - `sidebar_position` - Appropriate numbering + +- [ ] **Content structure** + - Clear introduction + - Proper heading hierarchy (H1 → H2 → H3, no skips) + - Logical topic progression + - Summary/next steps at end + - Related content linked + +### Content formatting + +- [ ] **Code examples** (see `content-standards.md`) + - Complete and runnable + - Language tag specified (REQUIRED) + - Realistic examples + - Code tabs for multiple languages + - **Review scope**: Comments and obvious mistakes only (not full code review) + +- [ ] **Links** (see `content-standards.md`) + - Descriptive text (not "click here") + - Internal links use relative paths + - External links point to reliable sources + - Link text makes sense out of context + +- [ ] **Images** (see `content-standards.md`) + - Meaningful alt text + - Light theme for screenshots + - Red indicators for highlighting + - Stored in proper directory structure + +- [ ] **Admonitions** (see `content-standards.md`) + - **MUST have a title** (REQUIRED - no exceptions) + - Appropriate type (note/tip/info/caution/danger) + - Not overused (max 2-3 per page) + +### Technical validation + +- [ ] **Technical accuracy** + - Code examples tested and working + - API endpoints current + - Version numbers up to date + - No deprecated features recommended + +- [ ] **Accessibility** + - Proper heading hierarchy + - Descriptive link text + - Alt text for images + - Color not sole indicator + +- [ ] **SEO optimization** + - Descriptive, unique title + - Meta description 140-160 chars + - Internal linking to related content + - Keywords used naturally + +- [ ] **Content-type specific checks** + - **Tutorials** (see `tutorial.md` skill): Clear learning objectives, prerequisites listed, sequential numbered steps, summary and next steps + - **API docs** (see `api-doc.md` skill): Operation IDs follow conventions, all parameters documented, code samples included (JS, Python, cURL), error responses documented + - **Reference pages**: Comprehensive parameter tables, default values specified, type information included ## How to review ### Step 1: Automated checks ```bash -npm run lint:md # Markdown linting -npm run lint:code # Code linting -vale sync # Prose linting setup +npm run lint:md # Markdownlint - Markdown syntax/formatting +npm run lint:code # ESLint - Code linting +vale sync # Vale - Prose style checking (optional) ``` From b2719eb670d8efdc2052c9c53fadfed0a38524e0 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Mon, 26 Jan 2026 19:10:32 +0100 Subject: [PATCH 26/27] feat: add comprehensive Claude Code documentation standards Add new canonical standards files and update all skills to reference them: New files: - rules/content-standards.md: Formatting, front matter, code examples, links, images - rules/terminology.md: Apify-specific capitalization and word choice Updated files: - rules/quality-standards.md: Complete rewrite with comprehensive checklist by category - skills/api-doc.md: Add standards reference, remove duplicated terminology - skills/doc-write.md: Add standards reference, focus on doc-specific patterns - skills/tutorial.md: Add standards reference, remove duplicated formatting rules Result: All skills now reference centralized standards instead of duplicating rules. Co-Authored-By: Claude Sonnet 4.5 --- .claude/rules/content-standards.md | 392 +++++++++++++++++++++++++++++ .claude/rules/quality-standards.md | 126 +++++++++- .claude/rules/terminology.md | 122 +++++++++ .claude/skills/api-doc.md | 51 ++-- .claude/skills/doc-write.md | 188 +++++--------- .claude/skills/tutorial.md | 95 ++----- 6 files changed, 740 insertions(+), 234 deletions(-) create mode 100644 .claude/rules/content-standards.md create mode 100644 .claude/rules/terminology.md diff --git a/.claude/rules/content-standards.md b/.claude/rules/content-standards.md new file mode 100644 index 0000000000..a5414dd680 --- /dev/null +++ b/.claude/rules/content-standards.md @@ -0,0 +1,392 @@ +--- +description: Standard formatting rules for all Apify documentation +globs: ["sources/**/*.md", "sources/**/*.mdx"] +alwaysApply: true +--- + +# Content Standards + +Canonical formatting standards for all Apify documentation. These rules ensure consistency across platform docs, academy tutorials, and API references. + +## Front matter requirements + +All documentation files must include YAML front matter with these fields: + +```yaml +--- +title: Page title +description: A clear description of the page content (140-160 characters) +sidebar_position: 1.0 +slug: /path/to/page +--- +``` + +### Required fields + +- **title**: Sentence case, present tense (e.g., "Create your first Actor") +- **description**: 140-160 characters for SEO, clear and actionable +- **sidebar_position**: Decimal number for ordering (1.0, 1.1, 2.0, etc.) +- **slug**: URL path starting with `/` (e.g., `/platform/actors/running`) + +### Optional fields + +- **sidebar_label**: Shorter version of title for sidebar navigation +- **toc_min_heading_level**: Minimum heading level in table of contents (default: 2) +- **toc_max_heading_level**: Maximum heading level in table of contents (default: 3) + +### Front matter examples + +Documentation page: +```yaml +--- +title: Store and manage data +description: Learn how to store and manage data in Apify datasets, key-value stores, and request queues. +sidebar_position: 3.0 +slug: /platform/storage +--- +``` + +Tutorial: +```yaml +--- +title: Build a web scraper +description: Step-by-step guide to building your first web scraper with Apify and Playwright. +sidebar_position: 1.0 +slug: /academy/tutorials/web-scraper +--- +``` + +## Headings + +### Casing + +**Sentence case only.** Capitalize only the first word and proper nouns. + +| Avoid | Prefer | +|-------|--------| +| Store And Manage Data | Store and manage data | +| Getting Started With Actors | Get started with Actors | + +### Form + +**No gerunds (-ing forms).** Use noun phrases or imperatives. + +| Avoid | Prefer | +|-------|--------| +| Finding available tags | Available tags | +| Getting started with Actors | Get started with Actors | +| Understanding the API | API overview | + +### Hierarchy + +Follow proper heading hierarchy: H1 → H2 → H3. Never skip levels. + +```markdown +# Page Title (H1 - only one per page, usually from front matter) + +## Main Section (H2) + +### Subsection (H3) + +#### Detail (H4 - use sparingly) +``` + +## Text formatting + +### Bold + +**Do use bold for:** +- UI elements (buttons, menus, fields, tabs) +- Critical warnings or key terms that must stand out + +**Don't use bold for:** +- List introductions or section labels +- Code block introductions +- General emphasis (use italics instead) +- Structural labels when context is clear + +| Avoid | Prefer | +|-------|--------| +| **Examples:** | Examples: | +| **In your Dockerfile**, use... | In your `Dockerfile`, use... | + +### Italics + +Use italics for emphasis and introducing new terms: + +| Use case | Example | +|----------|---------| +| New term introduction | An *Actor* is a serverless program... | +| Emphasis | This step is *required* for the Actor to work | + +### Code formatting + +Use backticks for inline code: + +- File names: `Dockerfile`, `package.json`, `.actor/actor.json` +- Commands: `npm install`, `docker build` +- Config keys: `actorSpecification`, `dockerfile` +- Variable names: `API_TOKEN`, `userId` +- Code values: `true`, `null`, `"string"` + +## Admonitions + +Use Docusaurus admonitions for important information. **All admonitions MUST have titles.** + +### Admonition types + +| Type | Use for | +|------|---------| +| `:::note` | General callouts and additional context | +| `:::tip` | Helpful suggestions and best practices | +| `:::info` | Background information and explanations | +| `:::caution` | Warnings about potential issues or gotchas | +| `:::danger` | Critical warnings that could cause data loss or errors | + +### Format + +```markdown +:::note Title Here +Content of the admonition. +::: +``` + +### Examples + +```markdown +:::note Actor versions +Actors can have multiple versions. Pin to a specific version for production use. +::: + +:::tip Performance optimization +Use the `maxRequestsPerCrawl` option to limit the number of requests for testing. +::: + +:::caution Breaking changes +Version 3.0 introduces breaking changes. Review the migration guide before upgrading. +::: + +:::danger Data loss risk +Deleting a dataset is permanent. All data will be lost and cannot be recovered. +::: +``` + +## Code examples + +### Completeness + +Code examples should be: +- **Complete**: Runnable without modifications +- **Realistic**: Solve real problems, not toy examples +- **Tested**: Verified to work with current versions +- **Commented**: Only when logic isn't self-evident + +### Syntax highlighting + +Always specify the language for syntax highlighting: + +````markdown +```javascript +import { Actor } from 'apify'; + +await Actor.init(); +// Your code here +await Actor.exit(); +``` +```` + +### Common languages + +- `javascript` - JavaScript code +- `typescript` - TypeScript code +- `python` - Python code +- `bash` - Shell commands +- `json` - JSON data +- `yaml` - YAML configuration +- `html` - HTML markup +- `css` - CSS styles + +### Code tabs + +Use tabs for multiple language examples: + +````markdown +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```javascript +const result = await client.actor('apify/web-scraper').call(); +``` + + + + +```python +result = client.actor('apify/web-scraper').call() +``` + + + +```` + +### Version matching + +When showing Dockerfile tags and package versions, ensure they match: + +```dockerfile +FROM apify/actor-node-playwright:22 +``` + +```json +{ + "dependencies": { + "playwright": "^1.40.0" + } +} +``` + +## Links + +### Descriptive link text + +Use action-oriented, descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. + +| Avoid | Prefer | +|-------|--------| +| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` | +| Read more about it `[here](url)` | Read the `[Actor development guide](url)` | +| See the `[documentation](url)` | `[Read the API documentation](url)` | + +### Action verbs for links + +Match the verb to the content type: + +| Content type | Verbs | +|--------------|-------| +| Documentation | Read, View, Check, See | +| Tutorials | Learn, Build, Follow | +| Reference | Access, Browse, Explore | +| Examples | View, Try, Clone | + +### Internal vs external links + +**Internal links** (within apify-docs): +- Use relative paths: `[Storage](/platform/storage)` +- Never include the domain + +**External links** (to other sites): +- Use full URLs: `[Playwright](https://playwright.dev)` +- Make tool mentions navigable + +### Actor references + +First mention: Actor name with link, capitalized. + +```markdown +[Website Content Crawler](https://apify.com/apify/website-content-crawler) +can crawl websites and extract text content. +``` + +Subsequent mentions: Just the name, no link needed. + +## Images + +### Alt text + +All images must include meaningful alt text describing the content: + +```markdown +![Apify Console showing the Actor creation dialog](./images/create-actor.png) +``` + +### Theme + +Screenshots should use: +- **Light theme** as default +- **Light background** for diagrams +- Consistent UI language (English) + +### Visual indicators + +Use red boxes or arrows to highlight important UI elements: +- **Red border**: Highlight clickable elements (buttons, fields) +- **Red arrow**: Point to specific areas +- **Red circle**: Highlight small elements + +### Image format + +- **PNG** for screenshots and diagrams +- **JPG** for photos +- **SVG** for logos and icons (when available) + +### File organization + +Store images in an `images/` subdirectory next to the markdown file: + +```text +platform/ +├── actors/ +│ ├── running.md +│ └── images/ +│ └── run-button.png +``` + +## Numbers and formatting + +### Thousands and decimals + +- Thousands: comma separator ($1,000) +- Decimals: period ($9.8) + +### Money + +- Symbol before amount: $49 (not 49$) +- Include currency: $49 USD for international context + +### Dates + +- Format: Month Day, Year +- Example: August 5, 2024 +- Never: 5.8.2024 or 2024-08-05 in prose (ISO format OK in code) + +### Time + +- Format: 12-hour with space before AM/PM +- Example: 5 PM, 11:30 AM +- Uppercase: PM (not pm or p.m.) + +## Parallel structure + +All items in a list must follow the same grammatical pattern: + +**Avoid - mixed patterns:** +```markdown +1. Reproducibility - your builds behave the same +1. Predictability - you know which version +1. Easier to track down issues +``` + +**Prefer - consistent pattern:** +```markdown +1. Reproducibility - Your builds behave the same way +1. Predictability - You know exactly which version you're running +1. Debugging - Version-specific issues are easier to track down +``` + +## List types + +- **Numbered lists**: Sequential steps where order matters +- **Bullet points**: Non-sequential items, features, options + +In numbered lists, use `1.` for all items (not sequential numbers): + +```markdown +1. First step +1. Second step +1. Third step +``` + +This makes reordering easier during editing. diff --git a/.claude/rules/quality-standards.md b/.claude/rules/quality-standards.md index dbc3d6c6f1..fb122efb34 100644 --- a/.claude/rules/quality-standards.md +++ b/.claude/rules/quality-standards.md @@ -6,15 +6,117 @@ alwaysApply: true # Quality Standards -## Content quality guidelines - -When creating or editing content, ensure: - -- [ ] Content follows Microsoft style guide (sentence case headings, proper emphasis) -- [ ] Front matter includes proper title, description, and metadata -- [ ] Code examples are complete and include proper syntax highlighting -- [ ] All links use descriptive text (avoid "click here") -- [ ] Images include meaningful alt text -- [ ] Content uses inclusive language and active voice -- [ ] Headings follow proper hierarchy (H1 → H2 → H3) -- [ ] Content is clear, concise, and action-oriented +Comprehensive quality checklist for all Apify documentation. Use this before submitting any content for review. + +## Complete quality checklist + +Before submitting documentation, verify: + +### Writing and style + +- [ ] Content follows **writing-style.md** (sentence case headings, active voice, no sales language) +- [ ] Language is US English (analyze, color, not analyse, colour) +- [ ] Tone is imperative and direct (use "Install the package" not "You should install") +- [ ] No first person (avoid "I recommend", use "we" for Apify team only) +- [ ] Content is simple (no sentence over 30 words, gets to the point) +- [ ] No em dashes (use hyphen with spaces: ` - ` instead of `—`) + +### Formatting and structure + +- [ ] Front matter follows **content-standards.md** (title, description 140-160 chars, sidebar_position, slug) +- [ ] Headings use sentence case (not title case) and no gerunds (-ing forms) +- [ ] Heading hierarchy is correct (H1 → H2 → H3, no skipped levels) +- [ ] Bold used only for UI elements and critical warnings (not for structure or list intros) +- [ ] Code formatting uses backticks for file names, commands, config keys +- [ ] All admonitions have titles (required by **content-standards.md**) +- [ ] Lists use parallel structure (all items follow same grammatical pattern) +- [ ] Numbered lists use `1.` for all items (not sequential numbers) + +### Terminology + +- [ ] Apify product names follow **terminology.md** (Apify Actor, Apify Proxy, not actor/proxy) +- [ ] Platform terms use lowercase with "the" (the Apify platform, not Platform) +- [ ] Feature terms use lowercase (task, schedule, dataset, not Task/Schedule/Dataset) +- [ ] Word choice is precise (legacy vs alternative vs deprecated used correctly) + +### Code examples + +- [ ] Code examples are complete and runnable +- [ ] Syntax highlighting specified for all code blocks +- [ ] Code tabs used for multi-language examples +- [ ] Dockerfile tags match package.json versions +- [ ] Examples tested and working with current versions +- [ ] Comments only where logic isn't self-evident + +### Links and references + +- [ ] Link text is descriptive and action-oriented (no "click here" or "here") +- [ ] Internal links use relative paths (not full URLs) +- [ ] External tool mentions are linked to official sites +- [ ] Actor references include link on first mention +- [ ] No broken links (verify all URLs) + +### Images and media + +- [ ] All images include meaningful alt text +- [ ] Screenshots use light theme +- [ ] Red indicators used to highlight UI elements +- [ ] Images stored in `images/` subdirectory +- [ ] Image format is appropriate (PNG for screenshots, SVG for logos) + +### File organization + +- [ ] File naming follows **file-organization.md** (kebab-case) +- [ ] File placed in correct directory (platform/, academy/, api-reference/) +- [ ] Images in appropriate images/ subdirectory + +### Technical validation + +- [ ] Markdownlint passes (`npm run lint:md`) - Markdown syntax and formatting +- [ ] Vale style checks pass (no critical errors) - Prose and style validation +- [ ] No spelling errors in content + +## Content type-specific standards + +### For documentation pages + +Use the **doc-write** skill for comprehensive guidance on: +- Content structure (introduction, prerequisites, steps, examples, summary) +- Documentation type distinction (tutorials vs guides vs reference) +- Platform-specific or Academy-specific requirements + +### For tutorials + +Use the **tutorial** skill for comprehensive guidance on: +- Tutorial structure template (8-section format) +- Learning objectives and expected outcomes +- Step-by-step instructions with verification +- Troubleshooting section + +### For API documentation + +Use the **api-doc** skill for comprehensive guidance on: +- OpenAPI specification standards +- Operation ID conventions +- Code sample requirements (JavaScript and Python) +- Schema and path documentation + +### For documentation review + +Use the **review-docs** skill for comprehensive guidance on: +- Review process and priority ranking +- Common issues and how to fix them +- Output format for review feedback + +## Pre-submission checklist + +Final verification before creating a pull request: + +1. [ ] All items in quality checklist above are verified +1. [ ] Content reviewed against appropriate skill standards (if applicable) +1. [ ] Changes tested locally (preview looks correct) +1. [ ] All linting and validation passes +1. [ ] No console errors in local preview +1. [ ] Navigation works correctly (sidebar, breadcrumbs, links) +1. [ ] Search functionality works for new content +1. [ ] Cross-references to other pages are accurate diff --git a/.claude/rules/terminology.md b/.claude/rules/terminology.md new file mode 100644 index 0000000000..484c0c7b61 --- /dev/null +++ b/.claude/rules/terminology.md @@ -0,0 +1,122 @@ +--- +description: Official Apify product and technical terminology +globs: ["sources/**/*.md", "sources/**/*.mdx", "apify-api/**/*.yaml"] +alwaysApply: true +--- + +# Apify Terminology + +Official capitalization and usage rules for Apify-specific terms. Use these exact forms throughout all documentation. + +## Product names + +Always capitalize these Apify product names: + +- **Apify Actor** (never "Apify actor" or "actor") +- **Apify Proxy** (never "Apify proxy" or "proxy") +- **Apify Console** (never "Apify console" or "console") +- **Apify Store** (never "Apify store" or "store") +- **Apify SDK** (never "Apify sdk") +- **Apify CLI** (never "Apify cli") +- **Apify API** (never "Apify api") + +## Platform terms + +Use lowercase for general platform references (include "the"): + +- **the Apify platform** (never "Apify Platform" or "the Platform") +- **the Apify team** (never "the Apify Team") +- **the Apify ecosystem** (never "the Apify Ecosystem") + +## Feature and concept terms + +Use lowercase for platform features and concepts: + +- **task** (never "Task") +- **schedule** (never "Schedule") +- **run** (never "Run") +- **build** (never "Build") +- **dataset** (never "Dataset") +- **key-value store** (never "Key-Value Store") +- **request queue** (never "Request Queue") +- **web scraping** (never "Web Scraping") + +## Generic technical terms + +Use lowercase for generic technical terms: + +- **AI agent** (never "AI Agent") +- **MCP server** (never "MCP Server") +- **API endpoint** (never "API Endpoint") +- **web scraper** (never "Web Scraper") +- **proxy server** (never "Proxy Server") + +## Usage examples + +### Correct usage + +```markdown +The Apify Actor runs on the Apify platform and stores data in a dataset. +You can configure your task to run on a schedule using Apify Proxy. +``` + +### Incorrect usage + +```markdown +The Apify actor runs on the Apify Platform and stores data in a Dataset. +You can configure your Task to run on a Schedule using Apify proxy. +``` + +## Word choice guidelines + +### Legacy vs alternative vs deprecated + +Use precise terms to describe feature status: + +| Word | When to use | +|------|-------------| +| **legacy** | Old approach still supported for backward compatibility, no announced removal | +| **alternative** | Valid approach, but not the preferred one | +| **deprecated** | Feature officially marked for removal in a future version | + +### Examples + +```markdown +The legacy Docker Compose approach is still supported. +You can use the alternative REST API instead of the GraphQL API. +The `Apify.main()` function is deprecated. Use `Actor.main()` instead. +``` + +## Special cases + +### Actor names + +When referring to specific Actors in the Apify Store: + +- First mention: Full name with link, capitalized + - Example: `[Website Content Crawler](https://apify.com/apify/website-content-crawler)` +- Subsequent mentions: Just the name, no link needed + - Example: `Website Content Crawler can extract text content.` + +### Version numbers + +- Use "version" not "ver" or "v" in prose +- Example: "Node.js version 22" (not "Node.js v22" or "Node.js ver 22") +- Exception: Tags and code can use abbreviations (`node:22`, `v3.0.0`) + +### Acronyms and abbreviations + +First use: Spell out with acronym in parentheses +```markdown +Application Programming Interface (API) +``` + +Subsequent uses: Just the acronym +```markdown +The API returns a JSON response. +``` + +Common acronyms (no need to spell out): +- API, SDK, CLI, URL, HTTP, HTTPS, JSON, YAML, HTML, CSS, JS +- AWS, GCP, Azure +- npm, pip, Docker diff --git a/.claude/skills/api-doc.md b/.claude/skills/api-doc.md index cb01007692..735991d4d9 100644 --- a/.claude/skills/api-doc.md +++ b/.claude/skills/api-doc.md @@ -13,9 +13,21 @@ Help create or update OpenAPI specifications and API documentation for Apify API ## Context files -- `CONTRIBUTING.md` - API documentation section +- `CONTRIBUTING.md` - API documentation section and workflows - `AGENTS.md` - API documentation rules - `apify-api/openapi/openapi.yaml` - Main OpenAPI spec +- `.claude/rules/` - Claude Code-specific standards (auto-loaded) + +## Standards reference + +This skill follows all standards defined in `.claude/rules/`: + +- **writing-style.md** - Clear, simple descriptions (US English, active voice) +- **content-standards.md** - Code examples formatting +- **terminology.md** - Apify-specific capitalization in descriptions (Apify Actor, the Apify platform) +- **quality-standards.md** - General quality checklist + +**API-specific standards** are documented in this skill file below. ## Instructions @@ -185,17 +197,7 @@ npm test # Validates OpenAPI specification npm start # Preview changes locally ``` -### 8. Apify terminology - -Always use exact capitalization in descriptions and examples: - -- **Apify Actor** (never "Apify actor") -- **Apify Proxy** (never "Apify proxy") -- **Apify Console** (never "the Apify Console") -- **Apify Store** (never "the Apify Store") -- **the Apify team**, **the Apify platform** (lowercase) - -### 9. Best practices +### 8. Best practices - **Descriptions**: Write clear, comprehensive descriptions using simple English - **Examples**: Include realistic examples in schemas @@ -206,20 +208,21 @@ 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 +### 9. API-specific quality checklist + +Before submitting, verify these API-specific items: -Before submitting: +- [ ] OpenAPI specification validates without errors (`npm test`) +- [ ] Operation IDs follow naming conventions (`objectName_method` in camelCase) +- [ ] All parameters have clear descriptions +- [ ] Response schemas are complete with examples +- [ ] Code samples included for JavaScript, Python, and cURL +- [ ] Examples use realistic data (not placeholder values) +- [ ] Path references added to main `openapi.yaml` +- [ ] All error responses documented (401, 404, etc.) +- [ ] Authentication requirements documented -- [ ] OpenAPI specification validates without errors -- [ ] Operation IDs follow naming conventions (camelCase_method) -- [ ] All parameters have clear descriptions using simple English -- [ ] Response schemas are complete -- [ ] Code samples are included for major languages (JS, Python, cURL) -- [ ] Examples use realistic data -- [ ] Path references are added to main openapi.yaml -- [ ] Error responses are documented -- [ ] Correct Apify terminology used throughout -- [ ] No assumptions made about product features +For general quality standards (terminology, language, formatting), see `quality-standards.md` ## Output diff --git a/.claude/skills/doc-write.md b/.claude/skills/doc-write.md index b67719498f..eda3da04a4 100644 --- a/.claude/skills/doc-write.md +++ b/.claude/skills/doc-write.md @@ -13,154 +13,86 @@ Help write or edit Apify documentation following the established style guide and ## Context files -- `AGENTS.md` - Primary documentation standards +- `AGENTS.md` - Primary vendor-agnostic documentation standards - `CONTRIBUTING.md` - Contribution guidelines +- `.claude/rules/` - Claude Code-specific standards (auto-loaded) -## Instructions +## Standards reference -When writing or editing documentation: +This skill follows all standards defined in `.claude/rules/`: -### 1. Content standards +- **writing-style.md** - Language, tone, grammar, headings, word choice (US English, active voice, sentence case, no gerunds) +- **content-standards.md** - Front matter, text formatting, admonitions (must have titles), code examples, links, images +- **terminology.md** - Apify-specific capitalization (Apify Actor, the Apify platform, etc.) +- **quality-standards.md** - Complete pre-submission quality checklist -- 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 +**Key reminders**: +- Sentence case for headings (not Title Case) +- No gerunds in headings (use "Create" not "Creating") +- Bold ONLY for UI elements (not for emphasis) +- All admonitions MUST have titles +- Front matter required (title, description 140-160 chars, sidebar_position, slug) +- Match slug to file path -### 2. Front matter +## Documentation structure -Always include proper front matter in MDX/MD files: +### For platform documentation -```yaml ---- -title: "Sentence case title (action-oriented, simple present tense)" -description: "140-160 chars - explain value, not features (no 'documentation' word)" -sidebar_position: 1 -slug: /path/to/page ---- -``` +1. **Introduction** - Clear description of the feature or concept +2. **When to use** - Explain when this feature is appropriate +3. **How to configure/use** - Step-by-step instructions with code examples +4. **Best practices** - Recommendations and tips +5. **Related features** - Links to related documentation -**Important**: Match slug to file path +### For tutorials and guides -- File: `/sources/platform/actors/running.md` -- Slug: `/platform/actors/running` +1. **Introduction** - What will the user learn? (Include learning objectives) +2. **Prerequisites** - Required knowledge, setup, accounts +3. **Step-by-step instructions** - Clear, numbered steps with explanations +4. **Code examples** - Complete, runnable examples (test before submitting) +5. **Testing/verification** - How to verify it works +6. **Summary** - What they accomplished and suggested next steps -### 3. Text formatting +### For reference documentation -- **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 ` +1. **Overview** - Brief description of the topic +2. **Parameters/options** - Detailed list with types and descriptions +3. **Examples** - Practical usage examples +4. **Related information** - Links to related topics -### 4. Headings +## Documentation types -- 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 +### Tutorials +- **Goal**: Teach users how to accomplish a specific task +- **Tone**: Instructional, encouraging, step-by-step +- **Examples**: "Build your first web scraper", "Deploy an Actor to production" +- **Use**: Complete code examples, screenshots, expected results at each step -### 5. Admonitions +### Guides +- **Goal**: Explain how to use a feature or solve a problem +- **Tone**: Informative, practical, solution-oriented +- **Examples**: "Actor configuration", "Working with datasets" +- **Use**: Focused code snippets, best practices, common patterns -**All admonitions MUST have a title** (REQUIRED). Use Docusaurus admonitions to highlight important information: +### Reference +- **Goal**: Document technical specifications and API details +- **Tone**: Precise, comprehensive, technical +- **Examples**: "Actor configuration schema", "API endpoints" +- **Use**: Complete parameter lists, type definitions, return values -```markdown -:::note Important information +## Skill-specific checklist -Your note content here. +Before finalizing documentation, verify these doc-write-specific items: -::: +- [ ] Structure matches documentation type (tutorial/guide/reference) +- [ ] Introduction clearly states what the user will learn +- [ ] Prerequisites are listed if needed +- [ ] Code examples are complete and tested +- [ ] Each step in tutorials has clear instructions +- [ ] Related documentation is linked +- [ ] No assumptions made about product features (ask if unsure) -:::tip Pro tip - -Helpful tip for users. - -::: - -:::info Additional context - -Background information. - -::: - -:::caution Warning - -Something to be careful about. - -::: - -:::danger Critical - -Critical information that could cause issues. - -::: -``` - -### 6. Code examples - -- Include complete, runnable examples -- Use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) for multiple languages -- Add syntax highlighting with language tags (REQUIRED) -- Include comments for complex code - -### 7. Links - -- Use descriptive link text (avoid "click here") -- Verify all internal links are correct -- Use relative paths for internal links - -### 8. Images - -- Use light theme for screenshots -- Include meaningful alt text -- Use red indicators for highlighting - -### 9. Structure - -For tutorials and guides, follow this structure: - -1. **Introduction** - What will the user learn? -2. **Prerequisites** - What do they need? -3. **Step-by-step instructions** - Clear, numbered steps -4. **Code examples** - Complete, working examples -5. **Summary** - What they accomplished and next steps - -### 10. Apify terminology - -Always use exact capitalization and phrasing: - -- **Apify Actor** (never "Apify actor" or "apify actor") -- **Apify Proxy** (never "Apify proxy") -- **Apify Console** (never "the Apify Console") -- **Apify Store** (never "the Apify Store") -- **the Apify team** (lowercase "the", lowercase "team") -- **the Apify platform** (lowercase "the", lowercase "platform") -- **AI agent** (lowercase for generic terms) -- **MCP server** (lowercase for generic terms) - -### 11. Quality checklist - -Before finalizing, verify: - -- [ ] Content follows Microsoft style guide (sentence case, simple present tense) -- [ ] Front matter includes proper title, description (140-160 chars explaining value), and metadata -- [ ] Slug matches file path -- [ ] Code examples are complete with syntax highlighting (REQUIRED) -- [ ] All admonitions have titles (REQUIRED) -- [ ] Bold used ONLY for UI elements, never for emphasis -- [ ] Oxford commas used in all lists -- [ ] All links use descriptive text -- [ ] Images include meaningful alt text -- [ ] Content uses inclusive language, simple English, and active voice -- [ ] Headings follow proper hierarchy and use simple present tense -- [ ] Content is clear, concise, and action-oriented -- [ ] Correct Apify terminology used throughout -- [ ] No assumptions made about product features +For general quality standards, see `quality-standards.md` ## Output diff --git a/.claude/skills/tutorial.md b/.claude/skills/tutorial.md index 477316241c..a5b0210a07 100644 --- a/.claude/skills/tutorial.md +++ b/.claude/skills/tutorial.md @@ -7,18 +7,26 @@ Create comprehensive, structured tutorials for the Apify Academy or Platform doc ## 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 and contribution workflows +- `.claude/rules/` - Claude Code-specific standards (auto-loaded) + +## Standards reference + +This skill follows all standards defined in `.claude/rules/`: -- `CONTRIBUTING.md` - Style guide +- **writing-style.md** - Language, tone, grammar (US English, active voice, sentence case, simple present tense) +- **content-standards.md** - Front matter, text formatting, admonitions (must have titles), code examples +- **terminology.md** - Apify-specific capitalization (Apify Actor, the Apify platform) +- **quality-standards.md** - General quality checklist + +**Tutorial-specific structure** and best practices are documented in this skill file below. ## Tutorial structure @@ -284,37 +292,7 @@ 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 +## Tutorial best practices 1. **Start Simple**: Begin with basic concepts before advanced topics @@ -336,45 +314,22 @@ Always use exact capitalization and phrasing: 10. **Use Simple English**: Prefer "use" over "utilize" -## Quality checklist - -Before publishing: - -- [ ] Clear learning objectives stated upfront - -- [ ] Prerequisites clearly listed +## Tutorial-specific quality checklist -- [ ] All steps are numbered and action-oriented - -- [ ] Code examples are complete and tested - -- [ ] Screenshots included where helpful (light theme) - -- [ ] Common issues addressed in troubleshooting +Before publishing, verify these tutorial-specific items: +- [ ] Clear learning objectives stated in introduction +- [ ] Prerequisites clearly listed with time estimate +- [ ] All steps are numbered and start with action verbs +- [ ] Code examples are complete, tested, and runnable +- [ ] Screenshots included where helpful (light theme, red indicators) +- [ ] Expected results shown after each major step +- [ ] Common issues addressed in troubleshooting section +- [ ] Summary lists what user accomplished - [ ] Next steps and related content linked +- [ ] Tutorial type matches content (platform/academy/integration) -- [ ] 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 +For general quality standards (front matter, formatting, terminology, language), see `quality-standards.md` ## Output From 2c49bbfd10f91f8ef1362122c1501e58876c583d Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 28 Jan 2026 13:33:21 +0100 Subject: [PATCH 27/27] fix: clarify heading hierarchy and admonition title requirements in quality and writing style guidelines --- .claude/rules/quality-standards.md | 2 +- .claude/rules/writing-style.md | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.claude/rules/quality-standards.md b/.claude/rules/quality-standards.md index fb122efb34..bfdf5b554a 100644 --- a/.claude/rules/quality-standards.md +++ b/.claude/rules/quality-standards.md @@ -25,7 +25,7 @@ Before submitting documentation, verify: - [ ] Front matter follows **content-standards.md** (title, description 140-160 chars, sidebar_position, slug) - [ ] Headings use sentence case (not title case) and no gerunds (-ing forms) -- [ ] Heading hierarchy is correct (H1 → H2 → H3, no skipped levels) +- [ ] Heading hierarchy is correct (H2 → H3 → H4, no skipped levels; H1 comes from front matter title) - [ ] Bold used only for UI elements and critical warnings (not for structure or list intros) - [ ] Code formatting uses backticks for file names, commands, config keys - [ ] All admonitions have titles (required by **content-standards.md**) diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index bb02713b20..28185443bc 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -164,6 +164,14 @@ Use Docusaurus admonitions for important information: | `:::caution` | Warnings about gotchas | | `:::danger` | Critical warnings that could cause issues | +**All admonitions require titles.** Use 2-3 words that are scannable and summarize the content. + +| Avoid | Prefer | +| --------------------------------------- | -------------------------- | +| `:::note Note` | `:::note Actor versions` | +| `:::caution Be careful when deleting` | `:::caution Data loss` | +| `:::tip` (no title) | `:::tip Performance` | + Prefer admonitions over block quotes for highlighted content. ## Grammar