apify · patrikbraborec · Jan 16, 2026
diff --git a/docs/01_overview/code/01_introduction.py → docs/01_introduction/code/01_introduction.py b/docs/01_overview/code/01_introduction.py → docs/01_introduction/code/01_introduction.py
diff --git a/...overview/code/actor_structure/__init__.py → ...oduction/code/actor_structure/__init__.py b/...overview/code/actor_structure/__init__.py → ...oduction/code/actor_structure/__init__.py
diff --git a/...overview/code/actor_structure/__main__.py → ...oduction/code/actor_structure/__main__.py b/...overview/code/actor_structure/__main__.py → ...oduction/code/actor_structure/__main__.py
diff --git a/.../01_overview/code/actor_structure/main.py → ...introduction/code/actor_structure/main.py b/.../01_overview/code/actor_structure/main.py → ...introduction/code/actor_structure/main.py
diff --git a/...01_overview/code/actor_structure/py.typed → ...ntroduction/code/actor_structure/py.typed b/...01_overview/code/actor_structure/py.typed → ...ntroduction/code/actor_structure/py.typed
diff --git a/docs/01_overview/images/apify-create.gif → docs/01_introduction/images/apify-create.gif b/docs/01_overview/images/apify-create.gif → docs/01_introduction/images/apify-create.gif
diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx
@@ -0,0 +1,45 @@
+---
+id: overview
+title: Introduction
+sidebar_label: Introduction
+description: 'The official library for creating Apify Actors in Python, providing tools for web scraping, automation, and data storage integration.'
+---
+
+The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python.
+
+It provides tools and classes for web scraping and automation, allowing you to manage Actor lifecycles, handle data storage, work with proxies, and integrate with popular Python libraries.
+
+## Example
+
+Here's a simple example of an Actor that scrapes a web page and stores the result:
+
+```py
+from apify import Actor
+from bs4 import BeautifulSoup
+import requests
+
+async def main():
+    async with Actor:
+        input = await Actor.get_input()
+        response = requests.get(input['url'])
+        soup = BeautifulSoup(response.content, 'html.parser')
+        await Actor.push_data({ 'url': input['url'], 'title': soup.title.string })
+```
+
+## Features
+
+The Apify SDK for Python provides:
+
+- **Actor lifecycle management** - Handle initialization, teardown, and graceful shutdowns
+- **Storage management** - Work with Datasets, Key-Value Stores, and Request Queues
+- **Event handling** - Respond to Actor events like migration, abort, and system info
+- **Proxy management** - Rotate and manage proxies for web scraping
+- **Platform integration** - Interact with other Actors, webhooks, and the Apify API
+- **Framework compatibility** - Integrate with BeautifulSoup, Playwright, Selenium, Scrapy, and Crawlee
+
+## Next steps
+
+- **[Installation](./installation)** - Install the SDK and set up your development environment
+- **[Quick start](./quick-start)** - Create and run your first Actor
+- **[Concepts](../concepts/actor-lifecycle)** - Learn about core SDK concepts
+- **[Guides](../guides/beautiful-soup)** - See how to integrate with popular libraries
diff --git a/docs/01_introduction/installation.mdx b/docs/01_introduction/installation.mdx
@@ -0,0 +1,51 @@
+---
+title: Installation
+sidebar_label: Installation
+description: 'Learn how to install the Apify SDK for Python using pip and manage dependencies for your Actor projects.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+## Requirements
+
+The Apify SDK requires Python version 3.10 or above to run Python Actors locally.
+
+## Installation
+
+The Apify Python SDK is available as [`apify`](https://pypi.org/project/apify/) package on PyPi. To install it, run:
+
+```bash
+pip install apify
+```
+
+When you create an Actor using the Apify CLI, the Apify SDK for Python is installed for you automatically.
+
+If you are not developing Apify Actors and you just need to access the Apify API from Python,
+consider using the [Apify API client for Python](/api/client/python) directly.
+
+## Adding dependencies
+
+First, add the dependencies in the [`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file in the Actor source folder.
+
+Then activate the virtual environment in `.venv`:
+
+<Tabs groupId="operating-systems">
+    <TabItem value="unix" label="Linux / macOS" default>
+        <CodeBlock language="bash">{
+`source .venv/bin/activate`
+        }</CodeBlock>
+    </TabItem>
+    <TabItem value="win" label="Windows">
+        <CodeBlock language="powershell">{
+`.venv\\Scripts\\activate`
+        }</CodeBlock>
+    </TabItem>
+</Tabs>
+
+Finally, install the dependencies:
+
+```bash
+python -m pip install -r requirements.txt
+```
diff --git a/docs/01_overview/index.mdx → docs/01_introduction/quick-start.mdx b/docs/01_overview/index.mdx → docs/01_introduction/quick-start.mdx
@@ -1,47 +1,18 @@
 ---
-title: Overview
-sidebar_label: Overview
+title: Quick start
+sidebar_label: Quick start
+description: 'Get started with the Apify SDK for Python by creating your first Actor and learning the basics.'
+---
+
+Learn how to create and run Actors using the Apify SDK for Python.
+
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
 
-The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python.
-
-```py
-from apify import Actor
-from bs4 import BeautifulSoup
-import requests
-
-async def main():
-    async with Actor:
-        input = await Actor.get_input()
-        response = requests.get(input['url'])
-        soup = BeautifulSoup(response.content, 'html.parser')
-        await Actor.push_data({ 'url': input['url'], 'title': soup.title.string })
-```
-
-## Requirements
-
-The Apify SDK requires Python version 3.10 or above to run Python Actors locally.
-
-## Installation
-
-The Apify Python SDK is available as [`apify`](https://pypi.org/project/apify/) package on PyPi. To install it, run:
-
-```bash
-pip install apify
-```
-
-When you create an Actor using the Apify CLI, the Apify SDK for Python is installed for you automatically.
-
-If you are not developing Apify Actors and you just need to access the Apify API from Python,
-consider using the [Apify API client for Python](/api/client/python) directly.
-
-## Quick start
-
-### Creating Actors
+## Step 1: Creating Actors
 
 To create and run Actors in Apify Console, refer to the [Console documentation](/platform/actors/development/quick-start/web-ide).
 
@@ -55,9 +26,9 @@ apify create my-first-actor --template python-start
 
 This will create a new folder called `my-first-actor`, download and extract the "Getting started with Python" Actor template there, create a virtual environment in `my-first-actor/.venv`, and install the Actor dependencies in it.
 
-![actor create command run](../01_overview/images/apify-create.gif)
+![actor create command run](./images/apify-create.gif)
 
-#### Running the Actor
+## Step 2: Running the Actor
 
 To run the Actor, you can use the [`apify run` command](/cli/docs/reference#apify-run):
 
@@ -74,7 +45,7 @@ This command:
 
 The Actor input, for example, will be in `storage/key_value_stores/default/INPUT.json`.
 
-## Actor structure
+## Step 3: Understanding Actor structure
 
 All Python Actor templates follow the same structure.
 
@@ -122,31 +93,6 @@ asyncio.run(main())`
 If you want to modify the Actor structure, you need to make sure that your Actor is executable as a module, via `python -m src`, as that is the command started by `apify run` in the Apify CLI.
 We recommend keeping the entrypoint for the Actor in the `src/__main__.py` file.
 
-## Adding dependencies
-
-First, add the dependencies in the [`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file in the Actor source folder.
-
-Then activate the virtual environment in `.venv`:
-
-<Tabs groupId="operating-systems">
-    <TabItem value="unix" label="Linux / macOS" default>
-        <CodeBlock language="bash">{
-`source .venv/bin/activate`
-        }</CodeBlock>
-    </TabItem>
-    <TabItem value="win" label="Windows">
-        <CodeBlock language="powershell">{
-`.venv\\Scripts\\activate`
-        }</CodeBlock>
-    </TabItem>
-</Tabs>
-
-Finally, install the dependencies:
-
-```bash
-python -m pip install -r requirements.txt
-```
-
 ## Next steps
 
 ### Guides

diff --git a/docs/02_concepts/10_logging.mdx → docs/02_concepts/09_logging.mdx b/docs/02_concepts/10_logging.mdx → docs/02_concepts/09_logging.mdx
@@ -5,10 +5,10 @@ title: Logging
 
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 
-import LogConfigExample from '!!raw-loader!roa-loader!./code/10_log_config.py';
-import LoggerUsageExample from '!!raw-loader!roa-loader!./code/10_logger_usage.py';
-import RedirectLog from '!!raw-loader!roa-loader!./code/10_redirect_log.py';
-import RedirectLogExistingRun from '!!raw-loader!roa-loader!./code/10_redirect_log_existing_run.py';
+import LogConfigExample from '!!raw-loader!roa-loader!./code/09_log_config.py';
+import LoggerUsageExample from '!!raw-loader!roa-loader!./code/09_logger_usage.py';
+import RedirectLog from '!!raw-loader!roa-loader!./code/09_redirect_log.py';
+import RedirectLogExistingRun from '!!raw-loader!roa-loader!./code/09_redirect_log_existing_run.py';
 
 The Apify SDK is logging useful information through the [`logging`](https://docs.python.org/3/library/logging.html) module from Python's standard library, into the logger with the name `apify`.
 

diff --git a/docs/02_concepts/11_configuration.mdx → docs/02_concepts/10_configuration.mdx b/docs/02_concepts/11_configuration.mdx → docs/02_concepts/10_configuration.mdx
@@ -5,7 +5,7 @@ title: Actor configuration
 
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 
-import ConfigExample from '!!raw-loader!roa-loader!./code/11_config.py';
+import ConfigExample from '!!raw-loader!roa-loader!./code/10_config.py';
 
 The [`Actor`](../../reference/class/Actor) class gets configured using the [`Configuration`](../../reference/class/Configuration) class, which initializes itself based on the provided environment variables.
 

diff --git a/docs/02_concepts/12_pay_per_event.mdx → docs/02_concepts/11_pay_per_event.mdx b/docs/02_concepts/12_pay_per_event.mdx → docs/02_concepts/11_pay_per_event.mdx
@@ -4,8 +4,8 @@ title: Pay-per-event monetization
 description: Monetize your Actors using the pay-per-event pricing model
 ---
 
-import ActorChargeSource from '!!raw-loader!roa-loader!./code/12_actor_charge.py';
-import ConditionalActorChargeSource from '!!raw-loader!roa-loader!./code/12_conditional_actor_charge.py';
+import ActorChargeSource from '!!raw-loader!roa-loader!./code/11_actor_charge.py';
+import ConditionalActorChargeSource from '!!raw-loader!roa-loader!./code/11_conditional_actor_charge.py';
 import ApiLink from '@site/src/components/ApiLink';
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 

diff --git a/docs/02_concepts/code/10_log_config.py → docs/02_concepts/code/09_log_config.py b/docs/02_concepts/code/10_log_config.py → docs/02_concepts/code/09_log_config.py
diff --git a/docs/02_concepts/code/10_logger_usage.py → docs/02_concepts/code/09_logger_usage.py b/docs/02_concepts/code/10_logger_usage.py → docs/02_concepts/code/09_logger_usage.py
diff --git a/docs/02_concepts/code/10_redirect_log.py → docs/02_concepts/code/09_redirect_log.py b/docs/02_concepts/code/10_redirect_log.py → docs/02_concepts/code/09_redirect_log.py
diff --git a/...epts/code/10_redirect_log_existing_run.py → ...epts/code/09_redirect_log_existing_run.py b/...epts/code/10_redirect_log_existing_run.py → ...epts/code/09_redirect_log_existing_run.py
diff --git a/docs/02_concepts/code/11_config.py → docs/02_concepts/code/10_config.py b/docs/02_concepts/code/11_config.py → docs/02_concepts/code/10_config.py
diff --git a/docs/02_concepts/code/12_actor_charge.py → docs/02_concepts/code/11_actor_charge.py b/docs/02_concepts/code/12_actor_charge.py → docs/02_concepts/code/11_actor_charge.py
diff --git a/...cepts/code/12_conditional_actor_charge.py → ...cepts/code/11_conditional_actor_charge.py b/...cepts/code/12_conditional_actor_charge.py → ...cepts/code/11_conditional_actor_charge.py
diff --git a/docs/02_concepts/09_running_webserver.mdx → docs/03_guides/07_running_webserver.mdx b/docs/02_concepts/09_running_webserver.mdx → docs/03_guides/07_running_webserver.mdx
@@ -5,7 +5,7 @@ title: Running webserver in your Actor
 
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 
-import WebserverExample from '!!raw-loader!roa-loader!./code/09_webserver.py';
+import WebserverExample from '!!raw-loader!roa-loader!./code/07_webserver.py';
 
 Each Actor run on the Apify platform is assigned a unique hard-to-guess URL (for example `https://8segt5i81sokzm.runs.apify.net`), which enables HTTP access to an optional web server running inside the Actor run's container.
 

diff --git a/docs/02_concepts/code/09_webserver.py → docs/03_guides/code/07_webserver.py b/docs/02_concepts/code/09_webserver.py → docs/03_guides/code/07_webserver.py
diff --git a/website/sidebars.js b/website/sidebars.js
@@ -1,8 +1,15 @@
 module.exports = {
     sidebar: [
         {
-            type: 'doc',
-            id: 'overview/index',
+            type: 'category',
+            label: 'Introduction',
+            collapsed: false,
+            items: [
+                {
+                    type: 'autogenerated',
+                    dirName: '01_introduction',
+                },
+            ],
         },
         {
             type: 'category',