vdusek · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/README.md b/README.md
@@ -167,7 +167,7 @@ if __name__ == '__main__':
 
 ### More examples
 
-Explore our [Examples](https://crawlee.dev/python/docs/examples) page in the Crawlee documentation for a wide range of additional use cases and demonstrations.
+Explore the [Guides](https://crawlee.dev/python/docs/guides) section of the Crawlee documentation for a wide range of additional use cases and demonstrations.
 
 ## Features
 

diff --git a/...examples/beautifulsoup_crawler_example.py → ...examples/beautifulsoup_crawler_example.py b/...examples/beautifulsoup_crawler_example.py → ...examples/beautifulsoup_crawler_example.py
diff --git a/...t/code_examples/parsel_crawler_example.py → ...t/code_examples/parsel_crawler_example.py b/...t/code_examples/parsel_crawler_example.py → ...t/code_examples/parsel_crawler_example.py
diff --git a/...de_examples/playwright_crawler_example.py → ...de_examples/playwright_crawler_example.py b/...de_examples/playwright_crawler_example.py → ...de_examples/playwright_crawler_example.py
diff --git a/...les/playwright_crawler_headful_example.py → ...les/playwright_crawler_headful_example.py b/...les/playwright_crawler_headful_example.py → ...les/playwright_crawler_headful_example.py
diff --git a/docs/01_quick-start/index.mdx b/docs/01_quick-start/index.mdx
@@ -0,0 +1,134 @@
+---
+id: quick-start
+title: Quick start
+description: Build and run your first Crawlee crawler in a few minutes, and pick the crawler type that fits your project.
+---
+
+import ApiLink from '@site/src/components/ApiLink';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
+
+import BeautifulsoupCrawlerExample from '!!raw-loader!roa-loader!./code_examples/beautifulsoup_crawler_example.py';
+import ParselCrawlerExample from '!!raw-loader!roa-loader!./code_examples/parsel_crawler_example.py';
+import PlaywrightCrawlerExample from '!!raw-loader!roa-loader!./code_examples/playwright_crawler_example.py';
+
+import PlaywrightCrawlerHeadfulExample from '!!raw-loader!./code_examples/playwright_crawler_headful_example.py';
+
+This page gets you from installation to a running crawler in a few minutes. To build a complete scraper step by step, follow the [Introduction](./introduction).
+
+## Choose your crawler
+
+Crawlee's main crawler classes are <ApiLink to="class/BeautifulSoupCrawler">`BeautifulSoupCrawler`</ApiLink>, <ApiLink to="class/ParselCrawler">`ParselCrawler`</ApiLink>, and <ApiLink to="class/PlaywrightCrawler">`PlaywrightCrawler`</ApiLink>. All crawlers share the same interface, so you can switch between them without rewriting your handlers.
+
+:::caution Minimum Python version
+
+Crawlee requires Python 3.10 or higher.
+
+:::
+
+### BeautifulSoupCrawler
+
+The <ApiLink to="class/BeautifulSoupCrawler">`BeautifulSoupCrawler`</ApiLink> is a plain HTTP crawler that parses HTML using the well-known [BeautifulSoup](https://pypi.org/project/beautifulsoup4/) library. It fetches pages with an HTTP client that mimics a browser. It's fast and light, but it can't render JavaScript.
+
+### ParselCrawler
+
+The <ApiLink to="class/ParselCrawler">`ParselCrawler`</ApiLink> is similar to the <ApiLink to="class/BeautifulSoupCrawler">`BeautifulSoupCrawler`</ApiLink> but uses the [Parsel](https://pypi.org/project/parsel/) library for HTML parsing. Parsel extracts data from HTML with CSS selectors and XPath, and it's the selector library [Scrapy](https://scrapy.org/) uses. Like the <ApiLink to="class/BeautifulSoupCrawler">`BeautifulSoupCrawler`</ApiLink>, the <ApiLink to="class/ParselCrawler">`ParselCrawler`</ApiLink> can't render JavaScript.
+
+### PlaywrightCrawler
+
+The <ApiLink to="class/PlaywrightCrawler">`PlaywrightCrawler`</ApiLink> uses a headless browser controlled by the [Playwright](https://playwright.dev/) library. It can drive Chromium, Firefox, and WebKit. Choose it when the target pages render their content with JavaScript.
+
+## Installation
+
+Crawlee is available as the [`crawlee`](https://pypi.org/project/crawlee/) package on PyPI. The package includes the core functionality, and additional features are available as optional extras to keep dependencies small.
+
+To install Crawlee with all extras using [pip](https://pip.pypa.io/en/stable/), run:
+
+```sh
+python -m pip install 'crawlee[all]'
+```
+
+Verify that Crawlee is successfully installed:
+
+```sh
+python -c 'import crawlee; print(crawlee.__version__)'
+```
+
+If you plan to use the <ApiLink to="class/PlaywrightCrawler">`PlaywrightCrawler`</ApiLink>, also install the Playwright browser binaries:
+
+```sh
+playwright install
+```
+
+For detailed installation instructions, see [Setting up](./introduction/setting-up).
+
+## Crawling
+
+Run the following example to perform a recursive crawl of the Crawlee website using the selected crawler.
+
+<Tabs groupId="quickStart">
+    <TabItem value="BeautifulSoupCrawler" label="BeautifulSoupCrawler" default>
+        <RunnableCodeBlock className="language-python" language="python">
+            {BeautifulsoupCrawlerExample}
+        </RunnableCodeBlock>
+    </TabItem>
+    <TabItem value="ParselCrawler" label="ParselCrawler">
+        <RunnableCodeBlock className="language-python" language="python">
+            {ParselCrawlerExample}
+        </RunnableCodeBlock>
+    </TabItem>
+    <TabItem value="PlaywrightCrawler" label="PlaywrightCrawler">
+        <RunnableCodeBlock className="language-python" language="python">
+            {PlaywrightCrawlerExample}
+        </RunnableCodeBlock>
+    </TabItem>
+</Tabs>
+
+When you run the example, the crawler logs its progress to your terminal.
+
+{/*TODO: improve the logging and add here a sample*/}
+
+## Running headful browser
+
+By default, browsers controlled by Playwright run in headless mode, without a visible window. During development, it helps to run the browser in headful mode and watch what it does. You can also switch from the default Chromium browser to Firefox or WebKit.
+
+<CodeBlock language="python">
+    {PlaywrightCrawlerHeadfulExample}
+</CodeBlock>
+
+When you run the example, a browser window opens and navigates through the Crawlee website.
+
+{/*TODO: add video example*/}
+
+## Results
+
+By default, Crawlee stores data in the `./storage` directory within your current working directory. The crawl results are saved as JSON files under `./storage/datasets/default/`.
+
+To view the results, use the `cat` command:
+
+```sh
+cat ./storage/datasets/default/000000001.json
+```
+
+The JSON file contains data similar to the following:
+
+```json
+{
+    "url": "https://crawlee.dev/",
+    "title": "Crawlee · Build reliable crawlers. Fast. | Crawlee"
+}
+```
+
+:::tip
+
+To change the storage directory, set the `CRAWLEE_STORAGE_DIR` environment variable to your preferred path.
+
+:::
+
+## Next steps
+
+- To build a complete scraper for a real website step by step, follow the [Introduction](./introduction).
+- To learn how crawlers, requests, storages, and other parts of Crawlee work, read the [Concepts](./concepts).
+- For solutions to specific tasks, see the [Guides](./guides).
diff --git a/docs/introduction/01_setting_up.mdx → docs/02_introduction/01_setting_up.mdx b/docs/introduction/01_setting_up.mdx → docs/02_introduction/01_setting_up.mdx
@@ -1,14 +1,15 @@
 ---
 id: setting-up
 title: Setting up
+description: How to install Crawlee, set up your environment, and bootstrap a new project.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';
 import CodeBlock from '@theme/CodeBlock';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-This guide will help you get started with Crawlee by setting it up on your computer. Follow the steps below to ensure a smooth installation process.
+This tutorial takes you from the simplest crawler, which prints a page title, to a scraper that crawls a real website and extracts product data. The first step is setting up Crawlee on your computer.
 
 ## Prerequisites
 

diff --git a/docs/introduction/02_first_crawler.mdx → docs/02_introduction/02_first_crawler.mdx b/docs/introduction/02_first_crawler.mdx → docs/02_introduction/02_first_crawler.mdx
@@ -1,6 +1,7 @@
 ---
 id: first-crawler
 title: First crawler
+description: Build your first Crawlee crawler - set up a request queue, write a request handler, and crawl your first page.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';

diff --git a/docs/introduction/03_adding_more_urls.mdx → docs/02_introduction/03_adding_more_urls.mdx b/docs/introduction/03_adding_more_urls.mdx → docs/02_introduction/03_adding_more_urls.mdx
@@ -1,6 +1,7 @@
 ---
 id: adding-more-urls
 title: Adding more URLs
+description: Grow the crawl by discovering and enqueuing new links, with filtering and deduplication handled for you.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';

diff --git a/docs/introduction/04_real_world_project.mdx → ...02_introduction/04_real_world_project.mdx b/docs/introduction/04_real_world_project.mdx → ...02_introduction/04_real_world_project.mdx
@@ -1,6 +1,7 @@
 ---
 id: real-world-project
 title: Real-world project
+description: Plan a real scraping project - choose the data to collect and analyze the target website before writing code.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';

diff --git a/docs/introduction/05_crawling.mdx → docs/02_introduction/05_crawling.mdx b/docs/introduction/05_crawling.mdx → docs/02_introduction/05_crawling.mdx
@@ -1,6 +1,7 @@
 ---
 id: crawling
 title: Crawling
+description: Crawl the example Warehouse store - visit the category listings and enqueue the product detail pages.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';

diff --git a/docs/introduction/06_scraping.mdx → docs/02_introduction/06_scraping.mdx b/docs/introduction/06_scraping.mdx → docs/02_introduction/06_scraping.mdx
@@ -1,6 +1,7 @@
 ---
 id: scraping
 title: Scraping
+description: Extract structured data such as titles, prices, and stock information from the product detail pages.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';

diff --git a/docs/introduction/07_saving_data.mdx → docs/02_introduction/07_saving_data.mdx b/docs/introduction/07_saving_data.mdx → docs/02_introduction/07_saving_data.mdx
@@ -1,6 +1,7 @@
 ---
 id: saving-data
 title: Saving data
+description: Persist the scraped results into a dataset and find them on disk.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';
@@ -88,19 +89,10 @@ A helper <ApiLink to="class/PushDataFunction">`context.push_data`</ApiLink> save
 
 :::info Automatic dataset initialization
 
-Each time you start Crawlee a default <ApiLink to="class/Dataset">`Dataset`</ApiLink> is automatically created, so there's no need to initialize it or create an instance first. You can create as many datasets as you want and even give them names. For more details see the <ApiLink to="class/Dataset#open">`Dataset.open`</ApiLink> function.
+Each time you start Crawlee a default <ApiLink to="class/Dataset">`Dataset`</ApiLink> is automatically created, so there's no need to initialize it or create an instance first. You can create as many datasets as you want and even give them names. For more details see the [Storages](../concepts/storages#dataset) page and the <ApiLink to="class/Dataset#open">`Dataset.open`</ApiLink> function.
 
 :::
 
-{/* TODO: mention result storage guide once it's done
-
-:::info Automatic dataset initialization
-
-Each time you start Crawlee a default <ApiLink to="class/Dataset">`Dataset`</ApiLink> is automatically created, so there's no need to initialize it or create an instance first. You can create as many datasets as you want and even give them names. For more details see the [Result storage guide](../guides/result-storage#dataset) and the `Dataset.open()` function.
-
-:::
-*/}
-
 ## Finding saved data
 
 Unless you changed the configuration that Crawlee uses locally, which would suggest that you knew what you were doing, and you didn't need this tutorial anyway, you'll find your data in the storage directory that Crawlee creates in the working directory of the running script:
@@ -111,16 +103,12 @@ Unless you changed the configuration that Crawlee uses locally, which would sugg
 
 The above folder will hold all your saved data in numbered files, as they were pushed into the dataset. Each file represents one invocation of <ApiLink to="class/Dataset#push_data">`Dataset.push_data`</ApiLink> or one table row.
 
-{/* TODO: add mention of "Result storage guide" once it's ready:
-
 :::tip Single file data storage options
 
-If you would like to store your data in a single big file, instead of many small ones, see the [Result storage guide](../guides/result-storage#key-value-store) for Key-value stores.
+If you would like to store your data in a single big file, instead of many small ones, see how to [export the whole dataset](../concepts/storages#exporting-the-dataset) to JSON or CSV, or use a [key-value store](../concepts/storages#key-value-store).
 
 :::
 
-*/}
-
 ## Next steps
 
 Next, you'll see some improvements that you can add to your crawler code that will make it more readable and maintainable in the long run.
diff --git a/docs/introduction/08_refactoring.mdx → docs/02_introduction/08_refactoring.mdx b/docs/introduction/08_refactoring.mdx → docs/02_introduction/08_refactoring.mdx
@@ -1,6 +1,7 @@
 ---
 id: refactoring
 title: Refactoring
+description: Clean up the crawler code with a router and separate handlers to keep the project maintainable.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';
@@ -21,7 +22,7 @@ You might be wondering about the **anti-blocking, bot-protection avoiding stealt
 
 However, the default configuration, while powerful, may not cover every scenario.
 
-If you want to learn more, browse the [Avoid getting blocked](../guides/avoid-blocking), [Proxy management](../guides/proxy-management) and [Session management](../guides/session-management) guides.
+To learn more, see [Avoid getting blocked](../guides/avoid-blocking), [Proxy management](../concepts/proxy-management), and [Session management](../concepts/session-management).
 */}
 
 To promote good coding practices, let's look at how you can use a <ApiLink to="class/Router">`Router`</ApiLink> class to better structure your crawler code.

diff --git a/docs/introduction/09_running_in_cloud.mdx → docs/02_introduction/09_running_in_cloud.mdx b/docs/introduction/09_running_in_cloud.mdx → docs/02_introduction/09_running_in_cloud.mdx
@@ -2,7 +2,7 @@
 id: deployment
 title: Running your crawler in the Cloud
 sidebar_label: Running in the Cloud
-description: Deploying Crawlee-python projects to the Apify platform
+description: Deploy your Crawlee for Python project to the Apify platform and run it in the cloud.
 ---
 
 import CodeBlock from '@theme/CodeBlock';
@@ -12,13 +12,13 @@ import MainExample from '!!raw-loader!./code_examples/09_apify_sdk.py';
 
 Crawlee is developed by [**Apify**](https://apify.com), the web scraping and automation platform. You could say it is the **home of Crawlee projects**. In this section you'll see how to deploy the crawler there with just a few simple steps. You can deploy a **Crawlee** project wherever you want, but using the [**Apify platform**](https://console.apify.com) will give you the best experience.
 
-{/*In case you want to deploy your Crawlee project to other platforms, check out the [**Deployment**](../deployment) section.*/}
+To deploy your project to other platforms, see the [Deployment](../deployment) section.
 
 With a few simple steps, you can convert your Crawlee project into a so-called **Actor**. Actors are serverless micro-apps that are easy to develop, run, share, and integrate. The infra, proxies, and storages are ready to go. [Learn more about Actors](https://apify.com/actors).
 
 {/*:::info Choosing between Crawlee CLI and Apify CLI for project setup
 
-We started this guide by using the Crawlee CLI to bootstrap the project - it offers the basic Crawlee templates, including a ready-made `Dockerfile`. If you know you will be deploying your project to the Apify platform, you might want to start with the Apify CLI instead. It also offers several project templates, and those are all set up to be used on the Apify platform right ahead.
+We started this tutorial by using the Crawlee CLI to bootstrap the project - it offers the basic Crawlee templates, including a ready-made `Dockerfile`. If you know you will be deploying your project to the Apify platform, you might want to start with the Apify CLI instead. It also offers several project templates, and those are all set up to be used on the Apify platform right ahead.
 
 :::*/}
 
@@ -98,4 +98,4 @@ If you want to learn more about web scraping and browser automation, check out t
 
 ## Thank you! 🎉
 
-That's it! Thanks for reading the whole introduction and if there's anything wrong, please 🙏 let us know on [GitHub](https://github.com/apify/crawlee-python) or in our [Discord community](https://discord.com/invite/jyEM2PRvMU). Happy scraping! 👋
+That's it! Thanks for reading the whole tutorial and if there's anything wrong, please 🙏 let us know on [GitHub](https://github.com/apify/crawlee-python) or in our [Discord community](https://discord.com/invite/jyEM2PRvMU). Happy scraping! 👋
diff --git a/docs/introduction/code_examples/02_bs.py → docs/02_introduction/code_examples/02_bs.py b/docs/introduction/code_examples/02_bs.py → docs/02_introduction/code_examples/02_bs.py
diff --git a/...ntroduction/code_examples/02_bs_better.py → ...ntroduction/code_examples/02_bs_better.py b/...ntroduction/code_examples/02_bs_better.py → ...ntroduction/code_examples/02_bs_better.py
diff --git a/...duction/code_examples/02_request_queue.py → ...duction/code_examples/02_request_queue.py b/...duction/code_examples/02_request_queue.py → ...duction/code_examples/02_request_queue.py
diff --git a/...tion/code_examples/03_enqueue_strategy.py → ...tion/code_examples/03_enqueue_strategy.py b/...tion/code_examples/03_enqueue_strategy.py → ...tion/code_examples/03_enqueue_strategy.py
diff --git a/...ion/code_examples/03_finding_new_links.py → ...ion/code_examples/03_finding_new_links.py b/...ion/code_examples/03_finding_new_links.py → ...ion/code_examples/03_finding_new_links.py
diff --git a/docs/introduction/code_examples/03_globs.py → ...02_introduction/code_examples/03_globs.py b/docs/introduction/code_examples/03_globs.py → ...02_introduction/code_examples/03_globs.py
diff --git a/...duction/code_examples/03_original_code.py → ...duction/code_examples/03_original_code.py b/...duction/code_examples/03_original_code.py → ...duction/code_examples/03_original_code.py
diff --git a/...ion/code_examples/03_transform_request.py → ...ion/code_examples/03_transform_request.py b/...ion/code_examples/03_transform_request.py → ...ion/code_examples/03_transform_request.py
diff --git a/...oduction/code_examples/04_sanity_check.py → ...oduction/code_examples/04_sanity_check.py b/...oduction/code_examples/04_sanity_check.py → ...oduction/code_examples/04_sanity_check.py
diff --git a/...ction/code_examples/05_crawling_detail.py → ...ction/code_examples/05_crawling_detail.py b/...ction/code_examples/05_crawling_detail.py → ...ction/code_examples/05_crawling_detail.py
diff --git a/...tion/code_examples/05_crawling_listing.py → ...tion/code_examples/05_crawling_listing.py b/...tion/code_examples/05_crawling_listing.py → ...tion/code_examples/05_crawling_listing.py
diff --git a/...introduction/code_examples/06_scraping.py → ...introduction/code_examples/06_scraping.py b/...introduction/code_examples/06_scraping.py → ...introduction/code_examples/06_scraping.py
diff --git a/...troduction/code_examples/07_final_code.py → ...troduction/code_examples/07_final_code.py b/...troduction/code_examples/07_final_code.py → ...troduction/code_examples/07_final_code.py
diff --git a/...troduction/code_examples/07_first_code.py → ...troduction/code_examples/07_first_code.py b/...troduction/code_examples/07_first_code.py → ...troduction/code_examples/07_first_code.py
diff --git a/docs/introduction/code_examples/08_main.py → .../02_introduction/code_examples/08_main.py b/docs/introduction/code_examples/08_main.py → .../02_introduction/code_examples/08_main.py
diff --git a/docs/introduction/code_examples/08_routes.py → ...2_introduction/code_examples/08_routes.py b/docs/introduction/code_examples/08_routes.py → ...2_introduction/code_examples/08_routes.py
diff --git a/...ntroduction/code_examples/09_apify_sdk.py → ...ntroduction/code_examples/09_apify_sdk.py b/...ntroduction/code_examples/09_apify_sdk.py → ...ntroduction/code_examples/09_apify_sdk.py
diff --git a/...s/code_examples/http_crawlers/__init__.py → ...02_introduction/code_examples/__init__.py b/...s/code_examples/http_crawlers/__init__.py → ...02_introduction/code_examples/__init__.py
diff --git a/docs/introduction/code_examples/routes.py → docs/02_introduction/code_examples/routes.py b/docs/introduction/code_examples/routes.py → docs/02_introduction/code_examples/routes.py
diff --git a/docs/introduction/index.mdx → docs/02_introduction/index.mdx b/docs/introduction/index.mdx → docs/02_introduction/index.mdx
@@ -1,6 +1,7 @@
 ---
 id: introduction
 title: Introduction
+description: A step-by-step tutorial that takes you from your first crawler to a production-ready scraper for a real website.
 ---
 
 import ApiLink from '@site/src/components/ApiLink';