docs: add guide on building custom extensions

[shixi-li]

Description

Refs #1936. Adds docs/guides/extending_crawlee.mdx, a page that maps Crawlee's extension points.

The four extension points you listed in the issue each already document their own contract in the guide that owns them: crawlers in the HTTP crawlers guide, HTTP clients and storage clients in theirs, and browser plugins in the Playwright crawler guide (#2089). What is still missing is the map, so someone who wants to extend Crawlee has to already know which guide to open, and a third-party project has no single page to point its users at for "here is the interface this integration implements".

This page is that map. For each extension point it states when to subclass rather than configure, names the base class and what its contract covers, and links to the guide that goes deep. It deliberately does not restate those guides.

Contents

• Extension points — a class diagram plus one section each for crawlers (AbstractHttpCrawler), HTTP clients (HttpClient), storage clients (StorageClient), and browser plugins (PlaywrightBrowserPlugin), each linking to its detailed guide.
• Choosing an extension point — matches the layer to what actually differs in an integration, and says to prefer configuration over a subclass where the built-in class already exposes the knob.
• Framing for third-party integrations, per the issue's rationale: they host their own guide and reference the contract here.

Notes

• Placed as its own guide rather than a section inside an existing one, since it spans all four extension points. The sidebar picks it up automatically (autogenerated over docs/guides).
• No new code examples: each linked guide already carries a runnable one for its own extension point, so duplicating them here would mean two copies to keep in sync.
• Happy to adjust the placement, depth, or wording, especially if you would rather this live under a different section or carry a worked example of its own.

Testing

• uv run poe build-docs — build succeeds, the page renders at /docs/next/guides/extending-crawlee, and the build reports no broken links or anchors for it (the broken anchors in the log are pre-existing ones on API pages).
• Verified every link target resolves before building: the five doc ids (http-crawlers, http-clients, storage-clients, playwright-crawler, architecture-overview), the playwright-crawler-with-camoufox example, and each ApiLink class (AbstractHttpCrawler, BasicCrawler, HttpClient, StorageClient, PlaywrightBrowserPlugin, PlaywrightBrowserController, BrowserPool) against src/crawlee/.

AI assistance

Written with AI assistance (Claude). The scoping decision was mine to check first what each extension point already documents, which is why this is a map rather than four new sections; the browser-plugin quarter was covered by my earlier #2089.

[Copilot]

Pull request overview

Adds a new documentation guide that serves as a “map” of Crawlee’s primary extension points (crawlers, HTTP clients, storage clients, and browser plugins), briefly describing when to subclass vs configure and linking to the deeper, existing guides for each contract.

Changes:

• Add docs/guides/extending_crawlee.mdx with an overview of extension points and links to the relevant detailed guides/examples.
• Include a high-level Mermaid class diagram summarizing the main extensibility surfaces.
• Add a short “Choosing an extension point” decision checklist to help integrators pick the right layer.

Suppressed comments (1)

docs/guides/extending_crawlee.mdx:73

• This section describes PlaywrightBrowserPlugin as the base for browser plugins, but the abstract contract is BrowserPlugin (with PlaywrightBrowserPlugin being the built-in Playwright implementation). Updating the wording avoids confusion about which class defines the core interface vs which class is the default implementation to configure/subclass.

Subclass a browser plugin when an integration launches browsers through an API other than the standard Playwright one. Configuration options on <ApiLink to="class/PlaywrightBrowserPlugin">`PlaywrightBrowserPlugin`</ApiLink> cover the cases where the standard launch API is enough, so reach for a subclass only when the launch path itself differs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.