ci: add markdown, website, and image lint checks (#882)

Adds Markdown, website, and image lint checks to CI, mirroring the setup
in `apify-docs` and `apify-core`. The docs and website now go through
the same kind of automated checks as the Python code.

The website tooling moves from eslint + prettier (which weren't wired
into CI) to [oxlint](https://oxc.rs/) and [oxfmt](https://oxc.rs/), and
[markdownlint](https://github.com/DavidAnson/markdownlint) now covers
the Markdown files.

Three jobs run in the existing Checks workflow:

- **Markdown lint** — `markdownlint` over `README.md`,
`CONTRIBUTING.md`, and the `docs/` folder.
- **Website lint and format** — `oxlint` plus an `oxfmt --check`
formatting gate for the Docusaurus site.
- **Image lint** — fails when a PR adds unoptimized raster images, which
should be converted with `pnpm opt:images` first.

Notes:

- The website JS keeps single quotes, set via `.editorconfig`
(`quote_type`) and `.oxfmtrc.json` (`singleQuote`).
- The markdownlint config matches `apify-docs`: line length is disabled
and inline HTML is allowed.
- Minor doc and code fixes were applied where needed to pass the new
checks.

Closes #594

Author: vdusek

.editorconfig

@@ -7,6 +7,7 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 end_of_line = lf
+quote_type = single
 
 [Makefile]
 indent_style = tab

.github/workflows/_checks.yaml

@@ -17,6 +17,7 @@ permissions:
 
 env:
   PYTHON_VERSION: 3.14
+  NODE_VERSION: 24
 
 jobs:
   actions_lint_check:
@@ -72,6 +73,86 @@ jobs:
       - name: Async docstrings check
         run: uv run poe check-docstrings
 
+  markdown_lint_check:
+    name: Markdown lint check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install pnpm and website dependencies
+        uses: apify/actions/pnpm-install@v1.2.0
+        with:
+          working-directory: website
+
+      - name: Lint Markdown
+        run: pnpm lint:md
+        working-directory: website
+
+  website_lint_check:
+    name: Website lint check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install pnpm and website dependencies
+        uses: apify/actions/pnpm-install@v1.2.0
+        with:
+          working-directory: website
+
+      - name: Lint website code
+        run: pnpm lint:code
+        working-directory: website
+
+      - name: Check website formatting
+        run: pnpm format:check
+        working-directory: website
+
+  image_lint_check:
+    name: Image lint check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      # Doc images must be committed as optimized `.webp`. This fails when a PR adds raster
+      # images in another format so they get converted via `pnpm opt:images` first.
+      - name: Get changed unoptimized images
+        id: changed-files
+        uses: tj-actions/changed-files@v47
+        with:
+          files: |
+            docs/**/*.{png,jpg,jpeg,gif,bmp,tif,tiff,avif}
+            website/static/**/*.{png,jpg,jpeg,gif,bmp,tif,tiff,avif}
+          separator: "\n"
+
+      - name: Fail on unoptimized images
+        if: steps.changed-files.outputs.any_changed == 'true'
+        env:
+          UNOPTIMIZED_IMAGE_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
+        run: |
+          echo "Unoptimized images detected! Convert each one to WebP, e.g.:"
+          echo ""
+          while IFS= read -r file_path; do
+            echo "  (cd website && pnpm opt:images \"../$file_path\")"
+          done <<< "$UNOPTIMIZED_IMAGE_FILES"
+          echo ""
+          echo "Then reference the resulting .webp files in your Markdown."
+          exit 1
+
   unit_tests:
     name: Unit tests
     if: inputs.run_tests

.github/workflows/manual_release_docs.yaml

@@ -23,7 +23,7 @@ permissions:
   contents: read
 
 env:
-  NODE_VERSION: 22
+  NODE_VERSION: 24
   PYTHON_VERSION: 3.14
 
 jobs:

.github/workflows/manual_version_docs.yaml

@@ -27,7 +27,7 @@ permissions:
   contents: read
 
 env:
-  NODE_VERSION: "22"
+  NODE_VERSION: "24"
   PYTHON_VERSION: "3.14"
 
 jobs:

.markdownlint.yaml

@@ -1,5 +1,30 @@
+# markdownlint config for the docs and top-level Markdown files.
+# Run via `pnpm lint:md` / `pnpm lint:md:fix` from the `website/` directory.
 default: true
-line-length:
-  line_length: 150
-ul-style: dash
+
+# Prose is written one sentence per line, so line length is not enforced.
+line-length: false
+
+ul-style:
+  style: dash
+
+# Nested unordered lists use 4-space indentation.
+ul-indent:
+  indent: 4
+
+# Docs are MDX and embed JSX components.
 no-inline-html: false
+
+# MDX pages set their title via front matter, so multiple/duplicate H1s are fine.
+single-title: false
+no-duplicate-heading:
+  siblings_only: true
+
+# Anchor links into other pages can't be validated locally.
+link-fragments: false
+
+no-bare-urls: false
+no-trailing-punctuation:
+  punctuation: ".,;:。，；:"
+no-multiple-blanks:
+  maximum: 2

.rules.md

@@ -35,7 +35,7 @@ Integration tests require `APIFY_TEST_USER_API_TOKEN` and `APIFY_TEST_USER_2_API
 
 `ApifyClient`/`ApifyClientAsync` are the entry points. They provide methods that return resource sub-clients:
 
-```
+```text
 ApifyClient
 ├── .actor(id)    → ActorClient        (single resource operations)
 ├── .actors()     → ActorCollectionClient  (list/create)
@@ -80,8 +80,8 @@ Each input-side TypedDict ships in two casings: snake_case (`RequestDict`) and c
 - Generated by `datamodel-code-generator` from the OpenAPI spec at `https://docs.apify.com/api/openapi.json` (config in `pyproject.toml` under `[tool.datamodel-codegen]`, aliases in `datamodel_codegen_aliases.json`)
 - After generation, `scripts/postprocess_generated_models.py` is run to apply additional fixes
 - To regenerate locally:
-  - From the live published spec: `uv run poe generate-models`
-  - From a local spec file: `uv run poe generate-models-from-file path/to/openapi.json`
+    - From the live published spec: `uv run poe generate-models`
+    - From a local spec file: `uv run poe generate-models-from-file path/to/openapi.json`
 - In CI, model regeneration is triggered automatically by the `apify/apify-docs` repo when its OpenAPI spec changes (workflow `manual_regenerate_models.yaml`). It downloads the pre-built `openapi-bundles` artifact from the apify-docs workflow run, opens a PR titled `[TODO]: update generated models from apify-docs PR #N`, assigns it to the docs PR author, and posts a cross-repo comment on the original apify-docs PR
 - Manual regeneration is also possible from the GitHub Actions UI (`Regenerate models` workflow)
 
@@ -93,12 +93,12 @@ Each input-side TypedDict ships in two casings: snake_case (`RequestDict`) and c
 - **Docstrings**: Google style format, single backticks for inline code references (`` `ApifyClient` `` not ``` ``ApifyClient`` ```)
 - **Imports**: `from __future__ import annotations` used throughout
 - **Commits**: [Conventional Commits](https://www.conventionalcommits.org/) format. Choose the type based on *what* changed, not just *why*:
-  - `feat:` / `fix:` / `perf:` / `refactor:` / `style:` — **source code only**; these trigger a release and appear in the changelog
-  - `test:` — test additions or changes (no release triggered)
-  - `docs:` — documentation changes; also triggers a doc release on master
-  - `ci:` — CI/workflow changes
-  - `chore:` — dependency bumps, tooling, generated files (e.g. model regeneration PRs), and other housekeeping
-  - `build:` — build system changes
+    - `feat:` / `fix:` / `perf:` / `refactor:` / `style:` — **source code only**; these trigger a release and appear in the changelog
+    - `test:` — test additions or changes (no release triggered)
+    - `docs:` — documentation changes; also triggers a doc release on master
+    - `ci:` — CI/workflow changes
+    - `chore:` — dependency bumps, tooling, generated files (e.g. model regeneration PRs), and other housekeeping
+    - `build:` — build system changes
 
 ## Testing
 
@@ -108,6 +108,7 @@ Each input-side TypedDict ships in two casings: snake_case (`RequestDict`) and c
 - **Parallelism**: Tests run in parallel via `pytest-xdist`.
 
 Unit test pattern:
+
 ```python
 def test_example(httpserver: HTTPServer) -> None:
     httpserver.expect_request('/v2/endpoint').respond_with_json({'data': ...})

CONTRIBUTING.md

@@ -121,6 +121,22 @@ To run the documentation locally (requires Node.js):
 uv run poe run-docs
 ```
 
+### Linting the docs and website
+
+Markdown content (this guide, `README.md`, and the `docs/` folder) is checked with
+[markdownlint](https://github.com/DavidAnson/markdownlint). The Docusaurus website code is linted
+with [oxlint](https://oxc.rs/) and formatted with [oxfmt](https://oxc.rs/). All of them run in CI.
+To run them locally (requires Node.js 22.12 or newer and pnpm), from the `website/` directory:
+
+```sh
+pnpm lint          # lint Markdown and website code
+pnpm lint:fix      # auto-fix both
+pnpm format        # format the website code
+```
+
+Doc images are committed as optimized `.webp`. To convert a new image, run
+`pnpm opt:images <path-to-image>` from the `website/` directory.
+
 ## Commits
 
 We use [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages. This convention is used to automatically determine version bumps during the release process.
@@ -152,25 +168,22 @@ Publishing new versions to [PyPI](https://pypi.org/project/apify_client) is auto
 
 1. **Do not do this unless absolutely necessary.** In all conceivable scenarios, you should use the `release` workflow instead.
 2. **Make sure you know what you're doing.**
+3. Update the version number by modifying the `version` field under `project` in `pyproject.toml`:
 
-3. Update the version number:
-
-- Modify the `version` field under `project` in `pyproject.toml`.
-
-```toml
-[project]
-name = "apify_client"
-version = "x.z.y"
-```
+    ```toml
+    [project]
+    name = "apify_client"
+    version = "x.z.y"
+    ```
 
 4. Build the package:
 
-```sh
-uv run poe build
-```
+    ```sh
+    uv run poe build
+    ```
 
 5. Upload to PyPI:
 
-```sh
-uv publish --token YOUR_API_TOKEN
-```
+    ```sh
+    uv publish --token YOUR_API_TOKEN
+    ```

README.md

@@ -166,7 +166,7 @@ For end-to-end recipes — passing input, managing tasks for reusable input, ret
 The full documentation lives at **[docs.apify.com/api/client/python](https://docs.apify.com/api/client/python)**.
 
 | Section | What you'll find |
-|---|---|
+| --- | --- |
 | [Introduction](https://docs.apify.com/api/client/python/docs) | Overview, prerequisites, and a tour of the client. |
 | [Quick start](https://docs.apify.com/api/client/python/docs/quick-start) | Authenticate, run an Actor, and fetch its results step by step. |
 | [Concepts](https://docs.apify.com/api/client/python/docs/concepts/asyncio-support) | Asyncio, single vs. collection clients, nested clients, error handling, retries, logging, convenience methods, pagination, streaming, custom HTTP clients, timeouts. |

docs/02_concepts/04_error_handling.mdx

@@ -19,7 +19,7 @@ When you use the Apify client, it automatically extracts all relevant data from
 The Apify client provides dedicated error subclasses based on the HTTP status code of the failed response, so you can branch on error kind without inspecting `status_code` or `type`:
 
 | Status | Subclass |
-|---|---|
+| --- | --- |
 | 400 | <ApiLink to="class/InvalidRequestError">`InvalidRequestError`</ApiLink> |
 | 401 | <ApiLink to="class/UnauthorizedError">`UnauthorizedError`</ApiLink> |
 | 403 | <ApiLink to="class/ForbiddenError">`ForbiddenError`</ApiLink> |

docs/02_concepts/10_custom_http_clients.mdx

@@ -78,7 +78,7 @@ It must return an object satisfying the <ApiLink to="class/HttpResponse">`HttpRe
 <ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink> is not a concrete class. Any object with the following attributes and methods will work:
 
 | Property / Method | Description |
-|---|---|
+| --- | --- |
 | `status_code: int` | HTTP status code |
 | `text: str` | Response body as text |
 | `content: bytes` | Raw response body |