diff --git a/.agents/skills/api-doc/SKILL.md b/.agents/skills/api-doc/SKILL.md index f676043b11..7c3d07d98b 100644 --- a/.agents/skills/api-doc/SKILL.md +++ b/.agents/skills/api-doc/SKILL.md @@ -19,7 +19,7 @@ argument-hint: endpoint-name - Operation IDs: `{objectName}_{httpMethod}` in camelCase - Code sample filenames must match `operationId` 4. **Register in main spec** - add path `$ref` to `apify-api/openapi/openapi.yaml` -5. **Validate** - `npm run openapi:lint` then `npm run api:rebuild` +5. **Validate** - `pnpm openapi:lint` then `pnpm api:rebuild` **CRITICAL**: API docs are generated, not hand-written. Never edit files in `apify-api/docs/` directly. diff --git a/.agents/skills/api-doc/references/openapi-patterns.md b/.agents/skills/api-doc/references/openapi-patterns.md index 1f26f8e320..30817e9903 100644 --- a/.agents/skills/api-doc/references/openapi-patterns.md +++ b/.agents/skills/api-doc/references/openapi-patterns.md @@ -127,4 +127,4 @@ print(queue) 1. Filename must match `operationId` from the OpenAPI spec 1. The `code-samples-decorator.mjs` Redocly plugin auto-detects files and adds `x-codeSamples` 1. Missing samples are logged during build - check console output -1. Run `npm run api:rebuild` to verify samples appear +1. Run `pnpm api:rebuild` to verify samples appear diff --git a/.agents/skills/api-doc/references/process.md b/.agents/skills/api-doc/references/process.md index 68c51a1524..4135ddc98e 100644 --- a/.agents/skills/api-doc/references/process.md +++ b/.agents/skills/api-doc/references/process.md @@ -50,21 +50,21 @@ paths: ## Step 5: Validate and test ```bash -npm run openapi:lint # Validate OpenAPI spec (Redocly + Spectral + YAML) -npm run api:rebuild # Regenerate API docs -npm start # Preview locally +pnpm openapi:lint # Validate OpenAPI spec (Redocly + Spectral + YAML) +pnpm api:rebuild # Regenerate API docs +pnpm start # Preview locally ``` ## Edge cases ### OpenAPI validation fails -Run `npm run openapi:lint` for detailed errors. Common issues: unclosed quotes in YAML, missing required fields (`summary`, `operationId`, `responses`), or `$ref` pointing to non-existent files. +Run `pnpm openapi:lint` for detailed errors. Common issues: unclosed quotes in YAML, missing required fields (`summary`, `operationId`, `responses`), or `$ref` pointing to non-existent files. ### Code samples not appearing in docs -Filename must exactly match the `operationId` from the path YAML. Check build console output - missing samples are logged during `npm run api:rebuild`. +Filename must exactly match the `operationId` from the path YAML. Check build console output - missing samples are logged during `pnpm api:rebuild`. ### Generated docs are stale after editing -Run `npm run api:rebuild` to clean and regenerate. The files in `apify-api/docs/` are gitignored and regenerated on every build. +Run `pnpm api:rebuild` to clean and regenerate. The files in `apify-api/docs/` are gitignored and regenerated on every build. diff --git a/.agents/skills/doc-write/SKILL.md b/.agents/skills/doc-write/SKILL.md index e0b9f743d6..e8ecab8992 100644 --- a/.agents/skills/doc-write/SKILL.md +++ b/.agents/skills/doc-write/SKILL.md @@ -16,7 +16,7 @@ argument-hint: topic - **Platform docs**: intro → prerequisites → main content → code examples → next steps - **Guides**: intro with goal → step-by-step instructions → verification → troubleshooting - **Reference**: brief description → parameters/options → examples → related pages -5. **Quality check** - run `npm run lint:md` and `vale` before finishing +5. **Quality check** - run `pnpm lint:md` and `vale` before finishing Key rules: US English, active voice, imperative tone, sentence case headings, bold for UI elements only, all admonitions need titles, code blocks need language tags. diff --git a/.agents/skills/doc-write/references/process.md b/.agents/skills/doc-write/references/process.md index d44948f98a..bfa932a59c 100644 --- a/.agents/skills/doc-write/references/process.md +++ b/.agents/skills/doc-write/references/process.md @@ -38,9 +38,9 @@ Follow the structure template for the doc type in `.agents/skills/doc-write/refe ## Step 5: Quality check -- Run `npm run lint:md` on the new or edited file +- Run `pnpm lint:md` on the new or edited file - Run `vale "" --minAlertLevel=error` -- Run `npm start` (or `npm run build`) to verify no broken links or slug conflicts +- Run `pnpm start` (or `pnpm build`) to verify no broken links or slug conflicts Key rules: US English, active voice, imperative tone, sentence case headings, bold for UI elements only, all admonitions need titles, code blocks need language tags. diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md index 3cd4069c70..f423a39d73 100644 --- a/.agents/skills/review-docs/SKILL.md +++ b/.agents/skills/review-docs/SKILL.md @@ -12,7 +12,7 @@ argument-hint: file-path 1. **Verify file version** - `git status` to confirm you have the latest 2. **Run deterministic checks** (main process) - these are objective, no judgment needed: - - `npm run lint:md` (heading hierarchy, list numbering, spacing) + - `pnpm lint:md` (heading hierarchy, list numbering, spacing) - `vale "" --minAlertLevel=error` (prose style, pronouns, dashes, code fences, admonitions) - `.agents/skills/review-docs/scripts/check-frontmatter.sh ""` (description char count) 3. **Delegated standards review** - spawn one subagent per standards file to check compliance. Each subagent reads the file being reviewed plus one standards file, and returns violations with line numbers and suggested fixes: diff --git a/.agents/skills/review-docs/references/process.md b/.agents/skills/review-docs/references/process.md index 4465112a2b..9fd4e7a6c6 100644 --- a/.agents/skills/review-docs/references/process.md +++ b/.agents/skills/review-docs/references/process.md @@ -11,7 +11,7 @@ Agent-agnostic workflow for reviewing Apify documentation. These are objective - no judgment needed. Report all failures. Run in the main process (not in subagents). -- `npm run lint:md` (markdownlint: heading hierarchy, double spaces, list numbering) +- `pnpm lint:md` (markdownlint: heading hierarchy, double spaces, list numbering) - `vale "" --minAlertLevel=error` (prose style, dashes, code fences, admonitions) - `.agents/skills/review-docs/scripts/check-frontmatter.sh ""` (description char count) diff --git a/.agents/skills/tutorial/SKILL.md b/.agents/skills/tutorial/SKILL.md index e5e433d387..c615c9d80d 100644 --- a/.agents/skills/tutorial/SKILL.md +++ b/.agents/skills/tutorial/SKILL.md @@ -21,7 +21,7 @@ argument-hint: topic 6. Troubleshooting (common issues + fixes) 7. Summary (what was learned) 8. Next steps (links to related content) -5. **Quality check** - run `npm run lint:md` and `vale` before finishing +5. **Quality check** - run `pnpm lint:md` and `vale` before finishing Each step should have a clear action verb, expected result, and verification. Code examples must be complete - no pseudocode. diff --git a/.agents/skills/tutorial/references/process.md b/.agents/skills/tutorial/references/process.md index 426bb8d9a2..3ebef05d83 100644 --- a/.agents/skills/tutorial/references/process.md +++ b/.agents/skills/tutorial/references/process.md @@ -44,15 +44,15 @@ Each step should have a clear action verb, expected result, and verification. Co ## Step 5: Quality check -- Run `npm run lint:md` on the new file +- Run `pnpm lint:md` on the new file - Run `vale "" --minAlertLevel=error` -- Run `npm start` (or `npm run build`) to verify no broken links or slug conflicts +- Run `pnpm start` (or `pnpm build`) to verify no broken links or slug conflicts ## Edge cases ### Build fails after adding tutorial -Verify front matter has all required fields. Run `npm run build` to catch broken links and slug issues. +Verify front matter has all required fields. Run `pnpm build` to catch broken links and slug issues. ### Code examples don't render correctly diff --git a/AGENTS.md b/AGENTS.md index b5f34444a4..0953ee42cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,17 +14,17 @@ One unified site built from multiple repositories. See `CONTRIBUTING.md` for mul ## Commands ```bash -npm install # Install dependencies (runs patch-package via postinstall) -npm start # Dev server (rebuilds API docs, port 3000) -npm run build # Production build (catches broken links, bad frontmatter) -npm run lint # Run all linters (markdownlint + ESLint) -npm run lint:md # Markdownlint only -npm run lint:code # ESLint only -npm run lint:fix # Auto-fix both linters -vale sync # Download Vale styles (first time only) +pnpm install # Install dependencies (runs patch-package via postinstall) +pnpm start # Dev server (rebuilds API docs, port 3000) +pnpm build # Production build (catches broken links, bad frontmatter) +pnpm lint # Run all linters (markdownlint + oxlint) +pnpm lint:md # Markdownlint only +pnpm lint:code # oxlint only +pnpm lint:fix # Auto-fix both linters +vale sync # Download Vale styles (first time only) vale "path/to/file.md" --minAlertLevel=error # Prose style check -npm run api:rebuild # Regenerate API docs from OpenAPI specs -npm run openapi:lint # Validate OpenAPI spec (Redocly + Spectral + YAML) +pnpm api:rebuild # Regenerate API docs from OpenAPI specs +pnpm openapi:lint # Validate OpenAPI spec (Redocly + Spectral + YAML) ``` ## Architecture @@ -38,7 +38,7 @@ API docs are generated, NOT hand-written. The workflow: - `code-samples-decorator.mjs` - Auto-adds code samples if files exist in `/code_samples/{js,curl}/` - `legacy-doc-url-decorator.mjs` - Adds backward-compatible URLs - `client-references-links-decorator.mjs` - Links to client library docs -1. **Build command**: `npm run api:rebuild` = clean + bundle with Redocly + generate with Docusaurus +1. **Build command**: `pnpm api:rebuild` = clean + bundle with Redocly + generate with Docusaurus 1. **Output**: Markdown files in `apify-api/docs/` (gitignored, regenerated on each build) Never edit generated API docs directly. Edit the OpenAPI YAML source or add code samples. @@ -133,7 +133,7 @@ Post-build scripts (`scripts/joinLlmsFiles.mjs` + `indentLlmsFile.mjs`) combine | apify-sdk-python | 3004 | Python SDK docs | | apify-cli | 3005 | CLI documentation | -Use `npm run start:dev` + nginx to serve all repos together locally. See `CONTRIBUTING.md` for setup. +Use `pnpm start:dev` + nginx to serve all repos together locally. See `CONTRIBUTING.md` for setup. ## Deployment @@ -147,12 +147,12 @@ Use `npm run start:dev` + nginx to serve all repos together locally. See `CONTRI 1. **Broken links on build** - `onBrokenLinks: 'throw'` fails CI. Check slugs match file paths 1. **Missing frontmatter** - Description or slug errors break SEO and navigation 1. **Missing code block language** - Always specify language for syntax highlighting -1. **Stale API docs locally** - Run `npm run api:rebuild` after changing OpenAPI specs +1. **Stale API docs locally** - Run `pnpm api:rebuild` after changing OpenAPI specs ## Quick reference - **Add new doc**: Create `.md` in `sources/{platform,academy}/`, add frontmatter with title/description/slug -- **Add API endpoint**: Edit `apify-api/openapi/paths/**/*.yaml`, add code samples, run `npm run api:rebuild` +- **Add API endpoint**: Edit `apify-api/openapi/paths/**/*.yaml`, add code samples, run `pnpm api:rebuild` - **Fix broken build**: Check `onBrokenLinks` errors, verify slugs match file paths, validate frontmatter --- @@ -200,4 +200,4 @@ When creating or reviewing documentation, verify: - [ ] Images have alt text, use light theme - [ ] Terminology matches rules above - [ ] US English, active voice, no sales language -- [ ] `npm run lint` passes +- [ ] `pnpm lint` passes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b40f13f99..eaaeb4b39f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,14 +13,14 @@ 1. **Git** 2. **Node.js 22** (see [.nvmrc](.nvmrc) file) 3. **GitHub access** -4. **npm** or **pnpm** package manager +4. **pnpm 10** package manager (pinned via `packageManager` in `package.json`; `corepack enable` picks it up automatically) ### Installation steps 1. Clone the repository -2. Run `npm install` -3. Start development server: `npm start` +2. Run `pnpm install` +3. Start development server: `pnpm start` This will be enough to work on Platform, Academy and OpenAPI. If you want to work on the entire documentation set, you need to join them using nginx. @@ -28,8 +28,8 @@ This will be enough to work on Platform, Academy and OpenAPI. If you want to wor #### Join all repositories with nginx 1. Clone all the repositories -2. Run `npm start:dev` instead of `npm start` from the main repository -3. Run `npm start -- --port ` to start Docusaurus instance on specific port, refer to the table for each repository port +2. Run `pnpm start:dev` instead of `pnpm start` from the main repository +3. Run `pnpm start -- --port ` to start Docusaurus instance on specific port, refer to the table for each repository port |Repository|Port| |:---|:---| @@ -189,9 +189,9 @@ We use the following tools for API documentation: ### Basic commands -- `npm start` - Starts docs preview server including API reference -- `npm run openapi:lint:redocly` - Validates OpenAPI spec with Redocly CLI -- `npm run api:rebuild` - Regenerates API docs from OpenAPI specs +- `pnpm start` - Starts docs preview server including API reference +- `pnpm openapi:lint:redocly` - Validates OpenAPI spec with Redocly CLI +- `pnpm api:rebuild` - Regenerates API docs from OpenAPI specs ### Adding new documentation @@ -277,7 +277,7 @@ Add languages by adding new folders at the appropriate path level. #### Submitting changes 1. Make your changes following the guidelines above -2. Test locally using provided npm commands +2. Test locally using provided pnpm commands 3. Submit a pull request to the `master` branch 4. Ensure all CI checks pass @@ -289,8 +289,8 @@ Add languages by adding new folders at the appropriate path level. ```bash - npm install - npm start + pnpm install + pnpm start ``` @@ -299,7 +299,7 @@ Add languages by adding new folders at the appropriate path level. - Clone all documentation repositories - Configure nginx server - Update hosts file - - Use `npm start:dev` + - Use `pnpm start:dev` ## Quality check @@ -308,15 +308,15 @@ Add languages by adding new folders at the appropriate path level. 1. **Markdown**: ```bash - npm run lint:md # Checks for any issues using markdownlint - npm run lint:md:fix # Applies fixes + pnpm lint:md # Checks for any issues using markdownlint + pnpm lint:md:fix # Applies fixes ``` 2. **Code**: ```bash - npm run lint:code # Checks .js & .ts files - npm run lint:code:fix # Applies fixes + pnpm lint:code # Checks .js & .ts files + pnpm lint:code:fix # Applies fixes ``` 3. **Prose**: @@ -329,7 +329,7 @@ Add languages by adding new folders at the appropriate path level. - **Broken links**: [Periodic GitHub Action](.github/workflows/lychee.yml) checks broken links by [lychee](https://lychee.cli.rs/). If the Action fails, we manually fix the issues. -- **Academy exercises**: At the end of each lesson in the academy courses, there are exercises that target real-world websites. Each exercise includes a solution, stored as a separate file containing executable code. These files are included in the docs using the `!!raw-loader` syntax. Each course has a [Bats](https://bats-core.readthedocs.io/) test file named `test.bats`. The tests run each solution as a standalone program and verify that it produces output matching the expected results. A [periodic GitHub Action](.github/workflows/test-academy.yml) runs all these tests using `npm run test:academy`. If the Action fails, we rework the exercises. +- **Academy exercises**: At the end of each lesson in the academy courses, there are exercises that target real-world websites. Each exercise includes a solution, stored as a separate file containing executable code. These files are included in the docs using the `!!raw-loader` syntax. Each course has a [Bats](https://bats-core.readthedocs.io/) test file named `test.bats`. The tests run each solution as a standalone program and verify that it produces output matching the expected results. A [periodic GitHub Action](.github/workflows/test-academy.yml) runs all these tests using `pnpm test:academy`. If the Action fails, we rework the exercises. ## Pull request process diff --git a/README.md b/README.md index 24a6770478..184b2a4bd3 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Documentation ecosystem consists of: ### Prerequisites - **Node.js 22** (see [.nvmrc](.nvmrc)) -- **npm** or **pnpm** +- **pnpm 10** (pinned via `packageManager` in `package.json`; `corepack enable` picks it up automatically) - **Git** ### Quick setup @@ -43,21 +43,21 @@ git clone https://github.com/apify/apify-docs.git cd apify-docs # Install dependencies -npm install +pnpm install # Start development server -npm start +pnpm start ``` The site will be available at `http://localhost:3000` ### Available scripts -- `npm start` - Start development server with API docs -- `npm run build` - Build for production -- `npm run lint` - Run all linting checks -- `npm run lint:fix` - Fix linting issues automatically -- `npm run api:rebuild` - Regenerate API documentation +- `pnpm start` - Start development server with API docs +- `pnpm build` - Build for production +- `pnpm lint` - Run all linting checks +- `pnpm lint:fix` - Fix linting issues automatically +- `pnpm api:rebuild` - Regenerate API documentation ## Documentation architecture