refactor: overhaul website with new design and improved user experience

.gitignore

@@ -15,6 +15,9 @@ src/styles/uno.css
 .env.test.local
 .env.production.local
 
+# Claude local settings (machine-specific)
+.claude/settings.local.json
+
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*

blog/2025-07-05-Export-Workflow-as-Image/index.mdx

@@ -305,8 +305,9 @@ After running, you can find the image:
 
 Since the image runs outside OOMOL Studio, we cannot identify the user running the container. The current Workflow uses AI for translation, and OOMOL will convert the translation cost into credits. Using an API-key allows the credits to be deducted from the corresponding user's account, enabling the Workflow to run normally.
 
-::info
+:::info
 If the Workflow does not use built-in services like AI, or uses your own AI service, you still need to pass in the API-key when starting the container, but no credits will be deducted.
+:::
 
 You can generate an API-key in the [OOMOL Console](https://console.oomol.com/panel/api-key).
 

docs/advanced-guide/universal-block-settings.mdx

@@ -177,9 +177,11 @@ Universal Block configuration includes executor and Handle configuration.
 
 ### Executor
 
-The executor is used to specify the entry file and invocation method when the current Block runs.
+The executor is the runtime engine that loads and executes Block code. It acts as the bridge between OOMOL's workflow orchestration system and the actual code execution environment.
 
-Each code language environment has an executor for running code.
+Each code language environment has a corresponding executor implementation. When configuring a Block, you specify which executor to use and how it should invoke your code.
+
+For a comprehensive understanding of executors, see [Executor Concepts](/docs/concepts/executor).
 
 <Image
   sources={{
@@ -197,24 +199,90 @@ Each code language environment has an executor for running code.
 
 Currently, executors are implemented internally by the oomol team and support Python and Node.js runtime environments, so there are two corresponding options.
 
+**Python Executor:**
+- Executes Python code in a Python runtime environment
+- Default entry function name: `main`
+- Supports standard Python libraries and packages installed via Poetry
+- Can pass complex Python objects (DataFrame, pandas instances, etc.) using [Variable type Handles](#variable)
+
+**Node.js Executor:**
+- Executes JavaScript/TypeScript code in a Node.js runtime environment
+- Default entry function name: `default export function`
+- Supports npm packages with full TypeScript support
+- Can pass complex JavaScript objects using [Variable type Handles](#variable)
+
 #### Entry
 
 Select the code entry file. The default file is generated when users create scriptlet Blocks. If there are no special requirements, no changes are needed. Users can also specify any file, but must ensure implementation according to the code template, otherwise it won't run properly.
 
-Refer to [Node.js template](/docs/workflow-engine/nodejs-sdk-api#scriptlet-template) and [Python template](/docs/workflow-engine/python-sdk-api#scriptlet-template)
+**Important considerations:**
+
+- The entry file must implement the required function signature with two parameters:
+  1. Input parameters (dictionary/object containing Handle values)
+  2. Context object (providing runtime utilities)
+- The function must return output values as a dictionary/object
+- For async operations in Node.js, return a Promise
+
+Refer to [Node.js template](/docs/workflow-engine/nodejs-sdk-api#scriptlet-template) and [Python template](/docs/workflow-engine/python-sdk-api#scriptlet-template) for implementation details.
 
 #### Function
 
 Specify the code entry method name. Default is the main method of the entry file (Python code) or default export function (Node.js code). You can specify custom methods if needed, but must include method parameters from the template code.
 
+**Custom function example:**
+
+For Python:
+```python
+def custom_function_name(params: dict, context: Context):
+    # Your implementation
+    return {"output": result}
+```
+
+For Node.js:
+```typescript
+export async function customFunctionName(params, context) {
+    // Your implementation
+    return { output: result };
+}
+```
+
 #### Spawn
 
-When oomol studio runs workflows, it performs automatic detection. If upstream and downstream Blocks are implemented in the same code language (for shared Blocks, they must also belong to the same package), the internal scheduler will place both Block codes in the same process for invocation. The benefits are:
+The Spawn setting controls whether a Block runs in an independent process or shares a process with adjacent Blocks.
 
-1. Resource saving
-2. Allows upstream and downstream to directly pass code variables, eliminating serialization and deserialization steps for output Handle values, simplifying code.
+**Automatic Optimization:**
+
+When oomol studio runs workflows, it performs automatic detection. If upstream and downstream Blocks meet the following conditions, the internal scheduler will place both Block codes in the same process for invocation:
+
+1. Implemented in the same code language (both Python or both Node.js)
+2. For shared Blocks, they must also belong to the same package
+
+**Benefits of same-process execution:**
+
+1. **Resource efficiency**: Reduces memory overhead and eliminates process startup time
+2. **Direct variable passing**: Upstream and downstream Blocks can pass code variables directly using [Variable type Handles](#variable), eliminating serialization and deserialization steps
+3. **Performance improvement**: Eliminates inter-process communication overhead
+
+**When to enable Spawn (independent process):**
+
+You may want to manually enable independent process execution in these scenarios:
+
+- **Isolation**: The Block contains potentially unstable code that might crash
+- **Memory management**: The Block performs memory-intensive operations that should be isolated
+- **Resource limits**: You need strict resource limits for this specific Block
+- **Debugging**: You want to debug this Block in isolation from others
+- **Concurrency**: The Block uses threading or async operations that might interfere with other Blocks
+
+**Performance implications:**
+
+- **Same process**: Fastest execution, can use Variable Handles, shared memory
+- **Independent process**: Slight performance overhead for process creation and inter-process communication, but better isolation and stability
+
+:::tip
+In most cases, you can rely on OOMOL's automatic optimization. Only enable Spawn if you have specific requirements for isolation or resource management.
+:::
 
-Considering users may have special situations, we also allow users to choose whether to run Blocks in independent processes.
+For more details on how executors manage processes and data transfer, see [Executor Concepts - Process Management](/docs/concepts/executor#process-management).
 
 ### Handle Configuration
 

docs/concepts/executor.mdx

@@ -0,0 +1,166 @@
+---
+sidebar_position: 4
+---
+
+import Image from "@theme/ThemedImage";
+import useBaseUrl from "@docusaurus/useBaseUrl";
+
+# Executor
+
+Executor is the runtime engine that executes Block code within OOMOL.
+
+## What is an Executor
+
+An Executor is a runtime component responsible for loading and executing Block code. It acts as the bridge between OOMOL's workflow orchestration system (OOCANA) and the actual code execution environment.
+
+Each code language environment has a corresponding Executor implementation. When a [Node](/docs/concepts/node) in a [Flow](/docs/concepts/flow) is triggered, the Executor loads the specified entry file and invokes the defined function to execute the Block's logic.
+
+## Position in OOMOL Architecture
+
+In the OOMOL system architecture, Executor plays a crucial role in connecting multiple components:
+
+```
+OOMOL Studio (UI Layer)
+    ↓
+OOCANA (Workflow Engine)
+    ↓
+Executor (Runtime Layer)
+    ↓
+OVM (Container Environment)
+```
+
+- **OOMOL Studio** provides the visual interface for users to design workflows
+- **OOCANA** orchestrates the execution sequence and manages data flow between Blocks
+- **Executor** loads and executes the actual code for each Block
+- **OVM** provides the isolated containerized environment where code runs
+
+## Executor Types
+
+OOMOL currently supports two types of Executors, each designed for a specific programming language:
+
+### Python Executor
+
+- Executes Python code
+- Default entry function: `main`
+- Supports standard Python libraries and packages installed via Poetry
+- Can pass complex Python objects (like DataFrame, pandas instances) between Blocks using [Variable type Handles](/docs/advanced-guide/universal-block-settings#variable)
+
+### Node.js Executor
+
+- Executes JavaScript/TypeScript code
+- Default entry function: `default export function`
+- Supports npm packages and TypeScript with full type checking
+- Can pass complex JavaScript objects between Blocks using [Variable type Handles](/docs/advanced-guide/universal-block-settings#variable)
+
+## Relationship with Other Concepts
+
+### Executor and Block
+
+Each [Block](/docs/concepts/block) is configured with an Executor that specifies:
+- Which language runtime to use (Python or Node.js)
+- The entry file containing the code
+- The function name to invoke
+- Whether to run in an independent process
+
+The Executor configuration is part of the Block's metadata and can be modified in the [Block Configuration](/docs/advanced-guide/universal-block-settings#executor) panel.
+
+### Executor and OOCANA
+
+OOCANA (the workflow engine) coordinates with Executors to manage workflow execution:
+
+1. OOCANA analyzes the Flow to determine execution order based on data dependencies
+2. When a Block is ready to execute, OOCANA prepares the input data
+3. OOCANA invokes the appropriate Executor with the Block's code and input data
+4. The Executor runs the code and returns output data to OOCANA
+5. OOCANA passes the output to downstream Blocks or caches it for future use
+
+## Process Management
+
+One of the Executor's key features is intelligent process management, which optimizes resource usage and execution performance.
+
+### Same-Process Execution
+
+When OOMOL Studio runs workflows, it automatically detects opportunities for optimization. If consecutive Blocks meet the following conditions, they will be executed in the same process:
+
+- Implemented in the same programming language
+- For shared Blocks, they must belong to the same package
+
+**Benefits of same-process execution:**
+
+1. **Resource efficiency**: Reduces memory overhead and startup time
+2. **Direct variable passing**: Upstream and downstream Blocks can pass code variables directly without serialization/deserialization
+3. **Performance improvement**: Eliminates the overhead of inter-process communication
+
+### Independent Process Execution
+
+Users can manually configure a Block to run in an independent process via the [Spawn configuration](/docs/advanced-guide/universal-block-settings#spawn). This is useful in scenarios such as:
+
+- Isolating potentially unstable code
+- Managing memory-intensive operations
+- Enforcing strict resource limits
+- Debugging specific Blocks in isolation
+
+## Data Transfer Between Executors
+
+Data transfer between Executors depends on whether they share the same process and language environment:
+
+### JSON Serialization (Cross-Language or Cross-Process)
+
+When Blocks run in different language environments or independent processes, data is transferred via JSON serialization:
+
+```
+Block A (Python) → JSON → Block B (Node.js)
+Block A (same language, independent process) → JSON → Block B
+```
+
+**Characteristics:**
+- Universal compatibility across all languages
+- All Handle types except Variable can be serialized
+- Slight performance overhead for serialization/deserialization
+- Data can be cached for subsequent runs
+
+### Direct Variable Passing (Same Language, Same Process)
+
+When Blocks share the same language and process, they can use [Variable type Handles](/docs/advanced-guide/universal-block-settings#variable) to pass data directly:
+
+```
+Block A (Python) → Variable Reference → Block B (Python)
+```
+
+**Characteristics:**
+- Maximum performance (no serialization overhead)
+- Can pass complex objects that cannot be serialized (e.g., file handles, database connections)
+- Variables follow pass-by-reference semantics (modifications affect all Blocks)
+- Cannot be cached (upstream Block will always re-execute)
+- Reduces Block portability (limited to same-language workflows)
+
+:::info
+Variable type Handles cannot be cached because they reference objects in the code execution environment that only exist during runtime. This means if a downstream Block depends on a Variable Handle, it will always trigger upstream Block execution, regardless of cache settings.
+:::
+
+## Executor Lifecycle
+
+Understanding the Executor lifecycle helps in debugging and optimizing workflow performance:
+
+1. **Initialization**: When a Block is first triggered, the Executor initializes the runtime environment
+2. **Code Loading**: The Executor loads the entry file specified in the Block configuration
+3. **Function Invocation**: The Executor calls the specified function with input parameters and the Context object
+4. **Execution**: The Block code runs, potentially accessing the file system, network, or other resources
+5. **Output Collection**: The Executor collects output values from the Block function
+6. **Cleanup**: After execution completes (or fails), the Executor performs cleanup as needed
+7. **Process Reuse or Termination**: Depending on configuration, the process may be reused for subsequent Blocks or terminated
+
+## Configuration and Best Practices
+
+For detailed information on configuring Executors, see:
+- [Universal Block Settings - Executor](/docs/advanced-guide/universal-block-settings#executor)
+- [Architecture Principles](/docs/workflow-engine/principle)
+
+**Best Practices:**
+
+1. **Use same-language Blocks together** when possible to benefit from same-process optimization
+2. **Use Variable type Handles sparingly** - they improve performance but reduce Block reusability
+3. **Enable independent process execution** for resource-intensive or potentially unstable code
+4. **Follow the code templates** provided by OOMOL to ensure proper Executor integration:
+   - [Node.js Template](/docs/workflow-engine/nodejs-sdk-api#scriptlet-template)
+   - [Python Template](/docs/workflow-engine/python-sdk-api#scriptlet-template)

docs/faq.mdx

@@ -145,4 +145,4 @@ Currently, OOMOL Studio's logs are stored in the following locations:
 
 ## Online Help
 
-If you encounter issues while using OOMOL Studio, or have any suggestions or feedback, please feel free to contact us through the [community](/community).
+If you encounter issues while using OOMOL Studio, or have any suggestions or feedback, please feel free to contact us through the [contact page](/contact-us).

docs/workflow-engine/principle.mdx

@@ -25,7 +25,38 @@ The `flow` file defines the triggering sequence and data transfer relationships
 
 The execution sequence of `blocks` is determined by connections defined in the `flow`, following a data-flow driven model — when required data is ready, the corresponding `block` is automatically triggered for execution. This differs from event-driven step triggering in GitHub Actions (where the next step is triggered after the previous one completes), which is primarily used in CI/CD scenarios like compilation and packaging.
 
-Currently, `blocks` support `Nodejs` and `Python` runtime environments. Blocks of the same language run in the same environment. Data between different language environments is transferred via JSON, while blocks in the same language environment can transfer data through JSON or directly via variables. Note that variables follow pass-by-reference principles, so modifying a variable value in one `block` affects the same variable in other `blocks`.
+### Runtime Environments and Executors
+
+Currently, `blocks` support `Nodejs` and `Python` runtime environments. Each runtime environment has a corresponding [Executor](/docs/concepts/executor) that loads and executes the block code.
+
+**Key execution characteristics:**
+
+- **Same-language blocks** run in the same runtime environment by default
+- **Same-process optimization**: When consecutive blocks use the same language and belong to the same package, OOCANA places them in the same process to reduce overhead
+- **Independent processes**: Blocks can be configured to run in independent processes for isolation or debugging purposes
+
+For detailed information about executors and process management, see [Executor Concepts](/docs/concepts/executor).
+
+### Data Transfer Between Blocks
+
+Data transfer between different language environments is transferred via JSON, while blocks in the same language environment can transfer data through JSON or directly via variables.
+
+**JSON Serialization (Cross-Language or Cross-Process):**
+- Universal compatibility across all supported languages
+- Used when blocks run in different languages or independent processes
+- Slight performance overhead for serialization/deserialization
+- All Handle types except Variable can be cached
+
+**Direct Variable Passing (Same Language, Same Process):**
+- Maximum performance with zero serialization overhead
+- Used via [Variable type Handles](/docs/advanced-guide/universal-block-settings#variable)
+- Can pass complex objects that cannot be serialized
+- Variables follow pass-by-reference semantics - modifying a variable value in one `block` affects the same variable in other `blocks`
+- Cannot be cached (upstream blocks will always re-execute)
+
+:::info
+When using Variable type Handles for maximum performance, be aware that the blocks become tightly coupled and can only work with blocks in the same language environment. This reduces block portability but provides significant performance benefits for complex object passing.
+:::
 
 ## Block Data Transfer Specifications