+
+## Project Introduction
+
+MinerU is a tool that converts PDFs into machine-readable formats (e.g., markdown, JSON), allowing for easy extraction into any format.
+MinerU was born during the pre-training process of [InternLM](https://github.com/InternLM/InternLM). We focus on solving symbol conversion issues in scientific literature and hope to contribute to technological development in the era of large models.
+Compared to well-known commercial products domestically and internationally, MinerU is still young. If you encounter any issues or if the results are not as expected, please submit an issue on [GitHub Issues](https://github.com/opendatalab/MinerU/issues) and **attach the relevant PDF**.
+
+
+
+
+## Key Features
+
+- Remove headers, footers, footnotes, page numbers and other elements to ensure semantic coherence
+- Output text in human reading order, suitable for single-column, multi-column and complex layouts
+- Retain the original document structure, including titles, paragraphs, lists, etc.
+- Extract images, image descriptions, tables, table titles and footnotes
+- Automatically identify and convert formulas in documents to LaTeX format
+- Automatically identify and convert tables in documents to HTML format
+- Automatically detect scanned PDFs and garbled PDFs, and enable OCR functionality
+- OCR supports detection and recognition of 109 languages
+- Support multiple output formats, such as multimodal and NLP Markdown, reading-order-sorted JSON, and information-rich intermediate formats
+- Support multiple visualization results, including layout visualization, span visualization, etc., for efficient confirmation of output effects and quality inspection
+- Support pure CPU environment operation, and support GPU(CUDA)/NPU(CANN)/MPS acceleration
+- Compatible with Windows, Linux and Mac platforms
+
+
+## User Guide
+
+- [Quick Start Guide](./quick_start/index.md)
+- [Detailed Usage Instructions](./usage/index.md)
diff --git a/docs/en/quick_start/docker_deployment.md b/docs/en/quick_start/docker_deployment.md
new file mode 100644
index 0000000..2f5217c
--- /dev/null
+++ b/docs/en/quick_start/docker_deployment.md
@@ -0,0 +1,86 @@
+# Deploying MinerU with Docker
+
+MinerU provides a convenient Docker deployment method, which helps quickly set up the environment and solve some tricky environment compatibility issues.
+
+## Build Docker Image using Dockerfile
+
+```bash
+wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/global/Dockerfile
+docker build -t mineru:latest -f Dockerfile .
+```
+
+> [!TIP]
+> The [Dockerfile](https://github.com/opendatalab/MinerU/blob/master/docker/global/Dockerfile) uses `vllm/vllm-openai:v0.10.1.1` as the base image by default. This version of vLLM v1 engine has limited support for GPU models.
+> This version supports a limited range of GPU models and may only function on Ampere, Ada Lovelace, and Hopper architectures. If you cannot use vLLM for accelerated inference on Volta, Turing, or Blackwell GPUs, you can resolve this issue by changing the base image to `vllm/vllm-openai:v0.11.0`.
+
+## Docker Description
+
+MinerU's Docker uses `vllm/vllm-openai` as the base image, so it includes the `vllm` inference acceleration framework and necessary dependencies by default. Therefore, on compatible devices, you can directly use `vllm` to accelerate VLM model inference.
+
+> [!NOTE]
+> Requirements for using `vllm` to accelerate VLM model inference:
+>
+> - Device must have Volta architecture or later graphics cards with 8GB+ available VRAM.
+> - The host machine's graphics driver should support CUDA 12.8 or higher; You can check the driver version using the `nvidia-smi` command.
+> - Docker container must have access to the host machine's graphics devices.
+
+## Start Docker Container
+
+```bash
+docker run --gpus all \
+ --shm-size 32g \
+ -p 30000:30000 -p 7860:7860 -p 8000:8000 \
+ --ipc=host \
+ -it mineru:latest \
+ /bin/bash
+```
+
+After executing this command, you will enter the Docker container's interactive terminal with some ports mapped for potential services. You can directly run MinerU-related commands within the container to use MinerU's features.
+You can also directly start MinerU services by replacing `/bin/bash` with service startup commands. For detailed instructions, please refer to the [Start the service via command](https://opendatalab.github.io/MinerU/usage/quick_usage/#advanced-usage-via-api-webui-http-clientserver).
+
+## Start Services Directly with Docker Compose
+
+We provide a [compose.yaml](https://github.com/opendatalab/MinerU/blob/master/docker/compose.yaml) file that you can use to quickly start MinerU services.
+
+```bash
+# Download compose.yaml file
+wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml
+```
+
+>[!NOTE]
+>
+>- The `compose.yaml` file contains configurations for multiple services of MinerU, you can choose to start specific services as needed.
+>- Different services might have additional parameter configurations, which you can view and edit in the `compose.yaml` file.
+>- Due to the pre-allocation of GPU memory by the `vllm` inference acceleration framework, you may not be able to run multiple `vllm` services simultaneously on the same machine. Therefore, ensure that other services that might use GPU memory have been stopped before starting the `vlm-openai-server` service or using the `vlm-vllm-engine` backend.
+
+---
+
+### Start OpenAI-compatible server service
+connect to `openai-server` via `vlm-http-client` backend
+ ```bash
+ docker compose -f compose.yaml --profile openai-server up -d
+ ```
+ >[!TIP]
+ >In another terminal, connect to openai server via http client (only requires CPU and network, no vllm environment needed)
+ > ```bash
+ > mineru -p -o -b vlm-http-client -u http://:30000
+ > ```
+
+---
+
+### Start Web API service
+ ```bash
+ docker compose -f compose.yaml --profile api up -d
+ ```
+ >[!TIP]
+ >Access `http://:8000/docs` in your browser to view the API documentation.
+
+---
+
+### Start Gradio WebUI service
+ ```bash
+ docker compose -f compose.yaml --profile gradio up -d
+ ```
+ >[!TIP]
+ >
+ >- Access `http://:7860` in your browser to use the Gradio WebUI.
diff --git a/docs/en/quick_start/extension_modules.md b/docs/en/quick_start/extension_modules.md
new file mode 100644
index 0000000..f6bf34a
--- /dev/null
+++ b/docs/en/quick_start/extension_modules.md
@@ -0,0 +1,56 @@
+# MinerU Extension Modules Installation Guide
+MinerU supports installing extension modules on demand based on different needs to enhance functionality or support specific model backends.
+
+## Common Scenarios
+
+### Core Functionality Installation
+The `core` module is the core dependency of MinerU, containing all functional modules except `vllm`/`lmdeploy`. Installing this module ensures the basic functionality of MinerU works properly.
+```bash
+uv pip install "mineru[core]"
+```
+
+---
+
+### Using `vllm` to Accelerate VLM Model Inference
+> [!NOTE]
+> `vllm` and `lmdeploy` have nearly identical VLM inference acceleration effects and usage methods. You can choose one of them to install and use based on your actual needs, but it is not recommended to install both modules simultaneously to avoid potential dependency conflicts.
+
+The `vllm` module provides acceleration support for VLM model inference, suitable for graphics cards with Volta architecture and later (8GB+ VRAM). Installing this module can significantly improve model inference speed.
+
+```bash
+uv pip install "mineru[core,vllm]"
+```
+> [!TIP]
+> If exceptions occur during installation of the extra package including vllm, please refer to the [vllm official documentation](https://docs.vllm.ai/en/latest/getting_started/installation/index.html) to try to resolve the issue, or directly use the [Docker](./docker_deployment.md) deployment method.
+
+---
+
+### Using `lmdeploy` to Accelerate VLM Model Inference
+> [!NOTE]
+> `vllm` and `lmdeploy` have nearly identical VLM inference acceleration effects and usage methods. You can choose one of them to install and use based on your actual needs, but it is not recommended to install both modules simultaneously to avoid potential dependency conflicts.
+
+The `lmdeploy` module provides acceleration support for VLM model inference, suitable for graphics cards with Volta architecture and later (8GB+ VRAM). Installing this module can significantly improve model inference speed.
+
+```bash
+uv pip install "mineru[core,lmdeploy]"
+```
+> [!TIP]
+> If exceptions occur during installation of the extra package including lmdeploy, please refer to the [lmdeploy official documentation](https://lmdeploy.readthedocs.io/en/latest/get_started/installation.html) to try to resolve the issue.
+
+---
+
+### Installing Lightweight Client to Connect to OpenAI-compatible servers (for vlm-http-client mode)
+If you need to install a lightweight client on edge devices to connect to an OpenAI-compatible server for using VLM mode, you can install the basic mineru package, which is very lightweight and suitable for devices with only CPU and network connectivity.
+```bash
+uv pip install mineru
+mineru -p -o -b vlm-http-client -u http://127.0.0.1:30000
+```
+
+---
+
+### Installing Lightweight Client to Connect to OpenAI-compatible servers (for hybrid-http-client mode)
+If you need to install a lightweight client on edge devices to connect to an OpenAI-compatible server for using hybrid mode, you can install the mineru pipeline extension package, which is relatively lightweight and can be used on devices with only CPU and network connectivity, while running faster on devices that support GPU acceleration.
+```bash
+uv pip install "mineru[pipeline]"
+mineru -p -o -b hybrid-http-client -u http://127.0.0.1:30000
+```
\ No newline at end of file
diff --git a/docs/en/quick_start/index.md b/docs/en/quick_start/index.md
new file mode 100644
index 0000000..05c245d
--- /dev/null
+++ b/docs/en/quick_start/index.md
@@ -0,0 +1,141 @@
+# Quick Start
+
+If you encounter any installation issues, please check the [FAQ](../faq/index.md) first.
+
+## Online Experience
+
+### Official online web application
+The official online version has the same functionality as the client, with a beautiful interface and rich features, requires login to use
+
+- [](https://mineru.net/OpenSourceTools/Extractor?source=github)
+
+### Gradio-based online demo
+A WebUI developed based on Gradio, with a simple interface and only core parsing functionality, no login required
+
+- [](https://www.modelscope.cn/studios/OpenDataLab/MinerU)
+- [](https://huggingface.co/spaces/opendatalab/MinerU)
+
+## Local Deployment
+
+> [!WARNING]
+> **Prerequisites - Hardware and Software Environment Support**
+>
+> To ensure the stability and reliability of the project, we have optimized and tested only specific hardware and software environments during development. This ensures that users can achieve optimal performance and encounter the fewest compatibility issues when deploying and running the project on recommended system configurations.
+>
+> By concentrating our resources and efforts on mainstream environments, our team can more efficiently resolve potential bugs and timely develop new features.
+>
+> In non-mainstream environments, due to the diversity of hardware and software configurations, as well as compatibility issues with third-party dependencies, we cannot guarantee 100% usability of the project. Therefore, for users who wish to use this project in non-recommended environments, we suggest carefully reading the documentation and FAQ first, as most issues have corresponding solutions in the FAQ. Additionally, we encourage community feedback on issues so that we can gradually expand our support range.
+
+
+
+
+
Parsing Backend
+
pipeline
+
*-auto-engine
+
*-http-client
+
+
+
hybrid
+
vlm
+
hybrid
+
vlm
+
+
+
+
+
Backend Features
+
Good Compatibility
+
High Hardware Requirements
+
For OpenAI Compatible Servers2
+
+
+
Accuracy1
+
82+
+
90+
+
+
+
Operating System
+
Linux3 / Windows4 / macOS5
+
+
+
Pure CPU Support
+
✅
+
❌
+
✅
+
+
+
GPU Acceleration
+
Volta and later architecture GPUs or Apple Silicon
+
Not Required
+
+
+
Min VRAM
+
6GB
+
10GB
+
8GB
+
3GB
+
+
+
RAM
+
Min 16GB+, Recommended 32GB+
+
8GB
+
+
+
Disk Space
+
20GB+, SSD Recommended
+
2GB
+
+
+
Python Version
+
3.10-3.13
+
+
+
+
+1 Accuracy metrics are the End-to-End Evaluation Overall scores from OmniDocBench (v1.5), based on the latest version of `MinerU`.
+2 Servers compatible with OpenAI API, such as local model servers or remote model services deployed via inference frameworks like `vLLM`/`SGLang`/`LMDeploy`.
+3 Linux only supports distributions from 2019 and later.
+4 Since the key dependency `ray` does not support Python 3.13 on Windows, only versions 3.10~3.12 are supported.
+5 macOS requires version 14.0 or later.
+
+
+### Install MinerU
+
+#### Install MinerU using pip or uv
+```bash
+pip install --upgrade pip
+pip install uv
+uv pip install -U "mineru[all]"
+```
+
+#### Install MinerU from source code
+```bash
+git clone https://github.com/opendatalab/MinerU.git
+cd MinerU
+uv pip install -e .[all]
+```
+
+> [!TIP]
+> `mineru[all]` includes all core features, compatible with Windows / Linux / macOS systems, suitable for most users.
+> If you need to specify the inference framework for the VLM model, or only intend to install a lightweight client on an edge device, please refer to the documentation [Extension Modules Installation Guide](https://opendatalab.github.io/MinerU/quick_start/extension_modules/).
+
+---
+
+#### Deploy MinerU using Docker
+MinerU provides a convenient Docker deployment method, which helps quickly set up the environment and solve some tricky environment compatibility issues.
+You can get the [Docker Deployment Instructions](./docker_deployment.md) in the documentation.
+
+---
+
+### Using MinerU
+
+If your device meets the GPU acceleration requirements in the table above, you can use a simple command line for document parsing:
+```bash
+mineru -p -o
+```
+If your device does not meet the GPU acceleration requirements, you can specify the backend as `pipeline` to run in a pure CPU environment:
+```bash
+mineru -p -o -b pipeline
+```
+
+You can use MinerU for PDF parsing through various methods such as command line, API, and WebUI. For detailed instructions, please refer to the [Usage Guide](../usage/index.md).
\ No newline at end of file
diff --git a/docs/en/reference/changelog.md b/docs/en/reference/changelog.md
new file mode 100644
index 0000000..9a54d25
--- /dev/null
+++ b/docs/en/reference/changelog.md
@@ -0,0 +1,461 @@
+# Changelog
+
+This document records the update history of MinerU project for version 2.6.7 and earlier. For the latest version updates, please check the project [README](https://github.com/opendatalab/MinerU/blob/master/README.md).
+
+---
+
+## 2.6 Series Versions
+
+### 2.6.7 (2025/12/12)
+
+- Bug fix: #4168
+
+### 2.6.6 (2025/12/02)
+
+**`mineru-api` tool optimizations**
+
+- Added descriptive text to `mineru-api` interface parameters to improve API documentation readability.
+- You can use the environment variable `MINERU_API_ENABLE_FASTAPI_DOCS` to control whether the auto-generated interface documentation page is enabled (enabled by default).
+- Added concurrency configuration options for the `vlm-vllm-async-engine`, `vlm-lmdeploy-engine`, and `vlm-http-client` backends. Users can use the environment variable `MINERU_API_MAX_CONCURRENT_REQUESTS` to set the maximum number of concurrent API requests (unlimited by default).
+
+### 2.6.5 (2025/11/26)
+
+- Added support for a new backend vlm-lmdeploy-engine. Its usage is similar to vlm-vllm-(async)engine, but it uses lmdeploy as the inference engine and additionally supports native inference acceleration on Windows platforms compared to vllm.
+
+### 2.6.4 (2025/11/04)
+
+- Added timeout configuration for PDF image rendering, default is 300 seconds, can be configured via environment variable `MINERU_PDF_RENDER_TIMEOUT` to prevent long blocking of the rendering process caused by some abnormal PDF files.
+- Added CPU thread count configuration options for ONNX models, default is the system CPU core count, can be configured via environment variables `MINERU_INTRA_OP_NUM_THREADS` and `MINERU_INTER_OP_NUM_THREADS` to reduce CPU resource contention conflicts in high concurrency scenarios.
+
+### 2.6.3 (2025/10/31)
+
+- Added support for a new backend `vlm-mlx-engine`, enabling MLX-accelerated inference for the MinerU2.5 model on Apple Silicon devices. Compared to the `vlm-transformers` backend, `vlm-mlx-engine` delivers a 100%–200% speed improvement.
+- Bug fixes: #3849, #3859
+
+### 2.6.2 (2025/10/24)
+
+**`pipeline` backend optimizations**
+
+- Added experimental support for Chinese formulas, which can be enabled by setting the environment variable `export MINERU_FORMULA_CH_SUPPORT=1`. This feature may cause a slight decrease in MFR speed and failures in recognizing some long formulas. It is recommended to enable it only when parsing Chinese formulas is needed. To disable this feature, set the environment variable to `0`.
+- `OCR` speed significantly improved by 200%~300%, thanks to the optimization solution provided by [@cjsdurj](https://github.com/cjsdurj)
+- `OCR` models optimized for improved accuracy and coverage of Latin script recognition, and updated Cyrillic, Arabic, Devanagari, Telugu (te), and Tamil (ta) language systems to `ppocr-v5` version, with accuracy improved by over 40% compared to previous models
+
+**`vlm` backend optimizations**
+
+- `table_caption` and `table_footnote` matching logic optimized to improve the accuracy of table caption and footnote matching and reading order rationality in scenarios with multiple consecutive tables on a page
+- Optimized CPU resource usage during high concurrency when using `vllm` backend, reducing server pressure
+- Adapted to `vllm` version 0.11.0
+
+**General optimizations**
+
+- Cross-page table merging effect optimized, added support for cross-page continuation table merging, improving table merging effectiveness in multi-column merge scenarios
+- Added environment variable configuration option `MINERU_TABLE_MERGE_ENABLE` for table merging feature. Table merging is enabled by default and can be disabled by setting this variable to `0`
+
+---
+
+## 2.5 Series Versions
+
+### 2.5.4 (2025/09/26)
+
+- 🎉🎉 The MinerU2.5 [Technical Report](https://arxiv.org/abs/2509.22186) is now available! We welcome you to read it for a comprehensive overview of its model architecture, training strategy, data engineering and evaluation results.
+- Fixed an issue where some `PDF` files were mistakenly identified as `AI` files, causing parsing failures
+
+### 2.5.3 (2025/09/20)
+
+- Dependency version range adjustment to enable Turing and earlier architecture GPUs to use vLLM acceleration for MinerU2.5 model inference.
+- `pipeline` backend compatibility fixes for torch 2.8.0.
+- Reduced default concurrency for vLLM async backend to lower server pressure and avoid connection closure issues caused by high load.
+- More compatibility-related details can be found in the [announcement](https://github.com/opendatalab/MinerU/discussions/3548)
+
+### 2.5.2 (2025/09/19)
+
+We are officially releasing MinerU2.5, currently the most powerful multimodal large model for document parsing.
+
+With only 1.2B parameters, MinerU2.5's accuracy on the OmniDocBench benchmark comprehensively surpasses top-tier multimodal models like Gemini 2.5 Pro, GPT-4o, and Qwen2.5-VL-72B. It also significantly outperforms leading specialized models such as dots.ocr, MonkeyOCR, and PP-StructureV3.
+
+The model has been released on [HuggingFace](https://huggingface.co/opendatalab/MinerU2.5-2509-1.2B) and [ModelScope](https://modelscope.cn/models/opendatalab/MinerU2.5-2509-1.2B) platforms. Welcome to download and use!
+
+**Core Highlights**
+
+- SOTA Performance with Extreme Efficiency: As a 1.2B model, it achieves State-of-the-Art (SOTA) results that exceed models in the 10B and 100B+ classes, redefining the performance-per-parameter standard in document AI.
+- Advanced Architecture for Across-the-Board Leadership: By combining a two-stage inference pipeline (decoupling layout analysis from content recognition) with a native high-resolution architecture, it achieves SOTA performance across five key areas: layout analysis, text recognition, formula recognition, table recognition, and reading order.
+
+**Key Capability Enhancements**
+
+- Layout Detection: Delivers more complete results by accurately covering non-body content like headers, footers, and page numbers. It also provides more precise element localization and natural format reconstruction for lists and references.
+- Table Parsing: Drastically improves parsing for challenging cases, including rotated tables, borderless/semi-structured tables, and long/complex tables.
+- Formula Recognition: Significantly boosts accuracy for complex, long-form, and hybrid Chinese-English formulas, greatly enhancing the parsing capability for mathematical documents.
+
+**Repository Adjustments**
+
+Additionally, with the release of vlm 2.5, we have made some adjustments to the repository:
+
+- The vlm backend has been upgraded to version 2.5, supporting the MinerU2.5 model and no longer compatible with the MinerU2.0-2505-0.9B model. The last version supporting the 2.0 model is mineru-2.2.2.
+- VLM inference-related code has been moved to [mineru_vl_utils](https://github.com/opendatalab/mineru-vl-utils), reducing coupling with the main mineru repository and facilitating independent iteration in the future.
+- The vlm accelerated inference framework has been switched from `sglang` to `vllm`, achieving full compatibility with the vllm ecosystem, allowing users to use the MinerU2.5 model and accelerated inference on any platform that supports the vllm framework.
+- Due to major upgrades in the vlm model supporting more layout types, we have made some adjustments to the structure of the parsing intermediate file `middle.json` and result file `content_list.json`. Please refer to the [documentation](https://opendatalab.github.io/MinerU/reference/output_files/) for details.
+
+**Other Repository Optimizations**
+
+- Removed file extension whitelist validation for input files. When input files are PDF documents or images, there are no longer requirements for file extensions, improving usability.
+
+---
+
+## 2.2 - 2.4 Series Versions
+
+### 2.2.2 (2025/09/10)
+
+- Fixed the issue where the new table recognition model would affect the overall parsing task when some table parsing failed
+
+### 2.2.1 (2025/09/08)
+
+- Fixed the issue where some newly added models were not downloaded when using the model download command.
+
+### 2.2.0 (2025/09/05)
+
+**Major Updates**
+
+- In this version, we focused on improving table parsing accuracy by introducing a new [wired table recognition model](https://github.com/RapidAI/TableStructureRec) and a brand-new hybrid table structure parsing algorithm, significantly enhancing the table recognition capabilities of the `pipeline` backend.
+- We also added support for cross-page table merging, which is supported by both `pipeline` and `vlm` backends, further improving the completeness and accuracy of table parsing.
+
+**Other Updates**
+
+- The `pipeline` backend now supports 270-degree rotated table parsing, bringing support for table parsing in 0/90/270-degree orientations
+- `pipeline` added OCR capability support for Thai and Greek, and updated the English OCR model to the latest version. English recognition accuracy improved by 11%, Thai recognition model accuracy is 82.68%, and Greek recognition model accuracy is 89.28% (by PPOCRv5)
+- Added `bbox` field (mapped to 0-1000 range) in the output `content_list.json`, making it convenient for users to directly obtain position information for each content block
+- Removed the `pipeline_old_linux` installation option, no longer supporting legacy Linux systems such as `CentOS 7`, to provide better support for `uv`'s `sync`/`run` commands
+
+---
+
+## 2.1 Series Versions
+
+### 2.1.10 (2025/08/01)
+
+- Fixed an issue in the `pipeline` backend where block overlap caused the parsing results to deviate from expectations #3232
+
+### 2.1.9 (2025/07/30)
+
+- `transformers` 4.54.1 version adaptation
+
+### 2.1.8 (2025/07/28)
+
+- `sglang` 0.4.9.post5 version adaptation
+
+### 2.1.7 (2025/07/27)
+
+- `transformers` 4.54.0 version adaptation
+
+### 2.1.6 (2025/07/26)
+
+- Fixed table parsing issues in handwritten documents when using `vlm` backend
+- Fixed visualization box position drift issue when document is rotated #3175
+
+### 2.1.5 (2025/07/24)
+
+- `sglang` 0.4.9 version adaptation, synchronously upgrading the dockerfile base image to sglang 0.4.9.post3
+
+### 2.1.4 (2025/07/23)
+
+**Bug Fixes**
+
+- Fixed the issue of excessive memory consumption during the `MFR` step in the `pipeline` backend under certain scenarios #2771
+- Fixed the inaccurate matching between `image`/`table` and `caption`/`footnote` under certain conditions #3129
+
+### 2.1.1 (2025/07/16)
+
+**Bug fixes**
+
+- Fixed text block content loss issue that could occur in certain `pipeline` scenarios #3005
+- Fixed issue where `sglang-client` required unnecessary packages like `torch` #2968
+- Updated `dockerfile` to fix incomplete text content parsing due to missing fonts in Linux #2915
+
+**Usability improvements**
+
+- Updated `compose.yaml` to facilitate direct startup of `sglang-server`, `mineru-api`, and `mineru-gradio` services
+- Launched brand new [online documentation site](https://opendatalab.github.io/MinerU/), simplified readme, providing better documentation experience
+
+### 2.1.0 (2025/07/05)
+
+This is the first major update of MinerU 2, which includes a large number of new features and improvements, covering significant performance optimizations, user experience enhancements, and bug fixes. The detailed update contents are as follows:
+
+**Performance Optimizations**
+
+- Significantly improved preprocessing speed for documents with specific resolutions (around 2000 pixels on the long side).
+- Greatly enhanced post-processing speed when the `pipeline` backend handles batch processing of documents with fewer pages (<10 pages).
+- Layout analysis speed of the `pipeline` backend has been increased by approximately 20%.
+
+**Experience Enhancements**
+
+- Built-in ready-to-use `fastapi service` and `gradio webui`. For detailed usage instructions, please refer to [Documentation](https://opendatalab.github.io/MinerU/usage/quick_usage/#advanced-usage-via-api-webui-sglang-clientserver).
+- Adapted to `sglang` version `0.4.8`, significantly reducing the GPU memory requirements for the `vlm-sglang` backend. It can now run on graphics cards with as little as `8GB GPU memory` (Turing architecture or newer).
+- Added transparent parameter passing for all commands related to `sglang`, allowing the `sglang-engine` backend to receive all `sglang` parameters consistently with the `sglang-server`.
+- Supports feature extensions based on configuration files, including `custom formula delimiters`, `enabling heading classification`, and `customizing local model directories`. For detailed usage instructions, please refer to [Documentation](https://opendatalab.github.io/MinerU/usage/quick_usage/#extending-mineru-functionality-with-configuration-files).
+
+**New Features**
+
+- Updated the `pipeline` backend with the PP-OCRv5 multilingual text recognition model, supporting text recognition in 37 languages such as French, Spanish, Portuguese, Russian, and Korean, with an average accuracy improvement of over 30%. [Details](https://paddlepaddle.github.io/PaddleOCR/latest/en/version3.x/algorithm/PP-OCRv5/PP-OCRv5_multi_languages.html)
+- Introduced limited support for vertical text layout in the `pipeline` backend.
+
+---
+
+## 2.0 Series Versions
+
+### 2.0.6 (2025/06/20)
+
+- Fixed occasional parsing interruptions caused by invalid block content in `vlm` mode
+- Fixed parsing interruptions caused by incomplete table structures in `vlm` mode
+
+### 2.0.5 (2025/06/17)
+
+- Fixed the issue where models were still required to be downloaded in the `sglang-client` mode
+- Fixed the issue where the `sglang-client` mode unnecessarily depended on packages like `torch` during runtime.
+- Fixed the issue where only the first instance would take effect when attempting to launch multiple `sglang-client` instances via multiple URLs within the same process
+
+### 2.0.3 (2025/06/15)
+
+- Fixed a configuration file key-value update error that occurred when downloading model type was set to `all`
+- Fixed the issue where the formula and table feature toggle switches were not working in `command line mode`, causing the features to remain enabled.
+- Fixed compatibility issues with sglang version 0.4.7 in the `sglang-engine` mode.
+- Updated Dockerfile and installation documentation for deploying the full version of MinerU in sglang environment
+
+### 2.0.0 (2025/06/13)
+
+**New Architecture**
+
+MinerU 2.0 has been deeply restructured in code organization and interaction methods, significantly improving system usability, maintainability, and extensibility.
+
+- **Removal of Third-party Dependency Limitations**: Completely eliminated the dependency on `pymupdf`, moving the project toward a more open and compliant open-source direction.
+- **Ready-to-use, Easy Configuration**: No need to manually edit JSON configuration files; most parameters can now be set directly via command line or API.
+- **Automatic Model Management**: Added automatic model download and update mechanisms, allowing users to complete model deployment without manual intervention.
+- **Offline Deployment Friendly**: Provides built-in model download commands, supporting deployment requirements in completely offline environments.
+- **Streamlined Code Structure**: Removed thousands of lines of redundant code, simplified class inheritance logic, significantly improving code readability and development efficiency.
+- **Unified Intermediate Format Output**: Adopted standardized `middle_json` format, compatible with most secondary development scenarios based on this format, ensuring seamless ecosystem business migration.
+
+**New Model**
+
+MinerU 2.0 integrates our latest small-parameter, high-performance multimodal document parsing model, achieving end-to-end high-speed, high-precision document understanding.
+
+- **Small Model, Big Capabilities**: With parameters under 1B, yet surpassing traditional 72B-level vision-language models (VLMs) in parsing accuracy.
+- **Multiple Functions in One**: A single model covers multilingual recognition, handwriting recognition, layout analysis, table parsing, formula recognition, reading order sorting, and other core tasks.
+- **Ultimate Inference Speed**: Achieves peak throughput exceeding 10,000 tokens/s through `sglang` acceleration on a single NVIDIA 4090 card, easily handling large-scale document processing requirements.
+- **Online Experience**: You can experience our brand-new VLM model on [MinerU.net](https://mineru.net/OpenSourceTools/Extractor), [Hugging Face](https://huggingface.co/spaces/opendatalab/MinerU), and [ModelScope](https://www.modelscope.cn/studios/OpenDataLab/MinerU).
+
+**Incompatible Changes Notice**
+
+To improve overall architectural rationality and long-term maintainability, this version contains some incompatible changes:
+
+- Python package name changed from `magic-pdf` to `mineru`, and the command-line tool changed from `magic-pdf` to `mineru`. Please update your scripts and command calls accordingly.
+- For modular system design and ecosystem consistency considerations, MinerU 2.0 no longer includes the LibreOffice document conversion module. If you need to process Office documents, we recommend converting them to PDF format through an independently deployed LibreOffice service before proceeding with subsequent parsing operations.
+
+---
+
+## 1.x Series Historical Versions
+
+### 1.3.12 (2025/05/24)
+
+Added support for PPOCRv5 models, updated `ch_server` model to `PP-OCRv5_rec_server`, and `ch_lite` model to `PP-OCRv5_rec_mobile` (model update required)
+
+- In testing, we found that PPOCRv5(server) has some improvement for handwritten documents, but has slightly lower accuracy than v4_server_doc for other document types, so the default ch model remains unchanged as `PP-OCRv4_server_rec_doc`.
+- Since PPOCRv5 has enhanced recognition capabilities for handwriting and special characters, you can manually choose the PPOCRv5 model for Japanese-Traditional Chinese mixed scenarios and handwritten documents
+- You can select the appropriate model through the lang parameter `lang='ch_server'` (Python API) or `--lang ch_server` (command line):
+ - `ch`: `PP-OCRv4_server_rec_doc` (default) (Chinese/English/Japanese/Traditional Chinese mixed/15K dictionary)
+ - `ch_server`: `PP-OCRv5_rec_server` (Chinese/English/Japanese/Traditional Chinese mixed + handwriting/18K dictionary)
+ - `ch_lite`: `PP-OCRv5_rec_mobile` (Chinese/English/Japanese/Traditional Chinese mixed + handwriting/18K dictionary)
+ - `ch_server_v4`: `PP-OCRv4_rec_server` (Chinese/English mixed/6K dictionary)
+ - `ch_lite_v4`: `PP-OCRv4_rec_mobile` (Chinese/English mixed/6K dictionary)
+
+Added support for handwritten documents through optimized layout recognition of handwritten text areas
+
+- This feature is supported by default, no additional configuration required
+- You can refer to the instructions above to manually select the PPOCRv5 model for better handwritten document parsing results
+
+The `huggingface` and `modelscope` demos have been updated to versions that support handwriting recognition and PPOCRv5 models, which you can experience online
+
+### 1.3.10 (2025/04/29)
+
+- Added support for custom formula delimiters, which can be configured by modifying the `latex-delimiter-config` section in the `magic-pdf.json` file in your user directory.
+
+### 1.3.9 (2025/04/27)
+
+- Optimized formula parsing functionality, improved formula rendering success rate
+
+### 1.3.8 (2025/04/23)
+
+The default `ocr` model (`ch`) has been updated to `PP-OCRv4_server_rec_doc` (model update required)
+
+- `PP-OCRv4_server_rec_doc` is trained on a mixture of more Chinese document data and PP-OCR training data based on `PP-OCRv4_server_rec`, adding recognition capabilities for some traditional Chinese characters, Japanese, and special characters. It can recognize over 15,000 characters and improves both document-specific and general text recognition abilities.
+- [Performance comparison of PP-OCRv4_server_rec_doc/PP-OCRv4_server_rec/PP-OCRv4_mobile_rec](https://paddlepaddle.github.io/PaddleX/latest/module_usage/tutorials/ocr_modules/text_recognition.html#_3)
+- After verification, the `PP-OCRv4_server_rec_doc` model shows significant accuracy improvements in Chinese/English/Japanese/Traditional Chinese in both single language and mixed language scenarios, with comparable speed to `PP-OCRv4_server_rec`, making it suitable for most use cases.
+- In some pure English scenarios, `PP-OCRv4_server_rec_doc` may have word adhesion issues, while `PP-OCRv4_server_rec` performs better in these cases. Therefore, we've kept the `PP-OCRv4_server_rec` model, which users can access by adding the parameter `lang='ch_server'` (Python API) or `--lang ch_server` (command line).
+
+### 1.3.7 (2025/04/22)
+
+- Fixed the issue where the lang parameter was ineffective during table parsing model initialization
+- Fixed the significant speed reduction of OCR and table parsing in `cpu` mode
+
+### 1.3.4 (2025/04/16)
+
+- Slightly improved OCR-det speed by removing some unnecessary blocks
+- Fixed page-internal sorting errors caused by footnotes in certain cases
+
+### 1.3.2 (2025/04/12)
+
+- Fixed dependency version incompatibility issues when installing on Windows with Python 3.13
+- Optimized memory usage during batch inference
+- Improved parsing of tables rotated 90 degrees
+- Enhanced parsing of oversized tables in financial report samples
+- Fixed the occasional word adhesion issue in English text areas when OCR language is not specified (model update required)
+
+### 1.3.1 (2025/04/08)
+
+Fixed several compatibility issues
+
+- Added support for Python 3.13
+- Made final adaptations for outdated Linux systems (such as CentOS 7) with no guarantee of continued support in future versions, [installation instructions](https://github.com/opendatalab/MinerU/issues/1004)
+
+### 1.3.0 (2025/04/03)
+
+**Installation and compatibility optimizations**
+
+- Resolved compatibility issues caused by `detectron2` by removing `layoutlmv3` usage in layout
+- Extended torch version compatibility to 2.2~2.6 (excluding 2.5)
+- Added CUDA compatibility for versions 11.8/12.4/12.6/12.8 (CUDA version determined by torch), solving compatibility issues for users with 50-series and H-series GPUs
+- Extended Python compatibility to versions 3.10~3.12, fixing the issue of automatic downgrade to version 0.6.1 when installing in non-3.10 environments
+- Optimized offline deployment process, eliminating the need to download any model files after successful deployment
+
+**Performance optimizations**
+
+- Enhanced parsing speed for batches of small files by supporting batch processing of multiple PDF files ([script example](demo/batch_demo.py)), with formula parsing speed improved by up to 1400% and overall parsing speed improved by up to 500% compared to version 1.0.1
+- Reduced memory usage and improved parsing speed by optimizing MFR model loading and usage (requires re-running the [model download process](docs/how_to_download_models_zh_cn.md) to get incremental updates to model files)
+- Optimized GPU memory usage, requiring only 6GB minimum to run this project
+- Improved running speed on MPS devices
+
+**Parsing effect optimizations**
+
+- Updated MFR model to `unimernet(2503)`, fixing line break loss issues in multi-line formulas
+
+**Usability optimizations**
+
+- Completely replaced the `paddle` framework and `paddleocr` in the project by using `paddleocr2torch`, resolving conflicts between `paddle` and `torch`, as well as thread safety issues caused by the `paddle` framework
+- Added real-time progress bar display during parsing, allowing precise tracking of parsing progress and making the waiting process more bearable
+
+### 1.2.1 (2025/03/03)
+
+Fixed some issues
+
+- Fixed the impact on punctuation marks during full-width to half-width conversion of letters and numbers
+- Fixed caption matching inaccuracies in certain scenarios
+- Fixed formula span loss issues in certain scenarios
+
+### 1.2.0 (2025/02/24)
+
+This version includes several fixes and improvements to enhance parsing efficiency and accuracy:
+
+**Performance Optimization**
+
+- Increased classification speed for PDF documents in auto mode.
+
+**Parsing Optimization**
+
+- Improved parsing logic for documents containing watermarks, significantly enhancing the parsing results for such documents.
+- Enhanced the matching logic for multiple images/tables and captions within a single page, improving the accuracy of image-text matching in complex layouts.
+
+**Bug Fixes**
+
+- Fixed an issue where image/table spans were incorrectly filled into text blocks under certain conditions.
+- Resolved an issue where title blocks were empty in some cases.
+
+### 1.1.0 (2025/01/22)
+
+In this version we have focused on improving parsing accuracy and efficiency:
+
+**Model capability upgrade** (requires re-executing the [model download process](https://github.com/opendatalab/MinerU/blob/master/docs/how_to_download_models_en.md) to obtain incremental updates of model files)
+
+- The layout recognition model has been upgraded to the latest `doclayout_yolo(2501)` model, improving layout recognition accuracy.
+- The formula parsing model has been upgraded to the latest `unimernet(2501)` model, improving formula recognition accuracy.
+
+**Performance optimization**
+
+- On devices that meet certain configuration requirements (16GB+ VRAM), by optimizing resource usage and restructuring the processing pipeline, overall parsing speed has been increased by more than 50%.
+
+**Parsing effect optimization**
+
+- Added a new heading classification feature (testing version, enabled by default) to the online demo ([mineru.net](https://mineru.net/OpenSourceTools/Extractor)/[huggingface](https://huggingface.co/spaces/opendatalab/MinerU)/[modelscope](https://www.modelscope.cn/studios/OpenDataLab/MinerU)), which supports hierarchical classification of headings, thereby enhancing document structuring.
+
+### 1.0.1 (2025/01/10)
+
+This is our first official release, where we have introduced a completely new API interface and enhanced compatibility through extensive refactoring, as well as a brand new automatic language identification feature:
+
+**New API Interface**
+
+- For the data-side API, we have introduced the Dataset class, designed to provide a robust and flexible data processing framework. This framework currently supports a variety of document formats, including images (.jpg and .png), PDFs, Word documents (.doc and .docx), and PowerPoint presentations (.ppt and .pptx). It ensures effective support for data processing tasks ranging from simple to complex.
+- For the user-side API, we have meticulously designed the MinerU processing workflow as a series of composable Stages. Each Stage represents a specific processing step, allowing users to define new Stages according to their needs and creatively combine these stages to customize their data processing workflows.
+
+**Enhanced Compatibility**
+
+- By optimizing the dependency environment and configuration items, we ensure stable and efficient operation on ARM architecture Linux systems.
+- We have deeply integrated with Huawei Ascend NPU acceleration, providing autonomous and controllable high-performance computing capabilities. This supports the localization and development of AI application platforms in China. [Ascend NPU Acceleration](https://github.com/opendatalab/MinerU/blob/master/docs/README_Ascend_NPU_Acceleration_zh_CN.md)
+
+**Automatic Language Identification**
+
+- By introducing a new language recognition model, setting the `lang` configuration to `auto` during document parsing will automatically select the appropriate OCR language model, improving the accuracy of scanned document parsing.
+
+---
+
+## 0.x Series Historical Versions
+
+### 0.10.0 (2024/11/22)
+
+Introducing hybrid OCR text extraction capabilities:
+
+- Significantly improved parsing performance in complex text distribution scenarios such as dense formulas, irregular span regions, and text represented by images.
+- Combines the dual advantages of accurate content extraction and faster speed in text mode, and more precise span/line region recognition in OCR mode.
+
+### 0.9.3 (2024/11/15)
+
+Integrated [RapidTable](https://github.com/RapidAI/RapidTable) for table recognition, improving single-table parsing speed by more than 10 times, with higher accuracy and lower GPU memory usage.
+
+### 0.9.2 (2024/11/06)
+
+Integrated the [StructTable-InternVL2-1B](https://huggingface.co/U4R/StructTable-InternVL2-1B) model for table recognition functionality.
+
+### 0.9.0 (2024/10/31)
+
+This is a major new version with extensive code refactoring, addressing numerous issues, improving performance, reducing hardware requirements, and enhancing usability:
+
+- Refactored the sorting module code to use [layoutreader](https://github.com/ppaanngggg/layoutreader) for reading order sorting, ensuring high accuracy in various layouts.
+- Refactored the paragraph concatenation module to achieve good results in cross-column, cross-page, cross-figure, and cross-table scenarios.
+- Refactored the list and table of contents recognition functions, significantly improving the accuracy of list blocks and table of contents blocks, as well as the parsing of corresponding text paragraphs.
+- Refactored the matching logic for figures, tables, and descriptive text, greatly enhancing the accuracy of matching captions and footnotes to figures and tables, and reducing the loss rate of descriptive text to near zero.
+- Added multi-language support for OCR, supporting detection and recognition of 84 languages. For the list of supported languages, see [OCR Language Support List](https://paddlepaddle.github.io/PaddleOCR/latest/en/ppocr/blog/multi_languages.html#5).
+- Added memory recycling logic and other memory optimization measures, significantly reducing memory usage. The memory requirement for enabling all acceleration features except table acceleration (layout/formula/OCR) has been reduced from 16GB to 8GB, and the memory requirement for enabling all acceleration features has been reduced from 24GB to 10GB.
+- Optimized configuration file feature switches, adding an independent formula detection switch to significantly improve speed and parsing results when formula detection is not needed.
+- Integrated [PDF-Extract-Kit 1.0](https://github.com/opendatalab/PDF-Extract-Kit):
+ - Added the self-developed `doclayout_yolo` model, which speeds up processing by more than 10 times compared to the original solution while maintaining similar parsing effects, and can be freely switched with `layoutlmv3` via the configuration file.
+ - Upgraded formula parsing to `unimernet 0.2.1`, improving formula parsing accuracy while significantly reducing memory usage.
+ - Due to the repository change for `PDF-Extract-Kit 1.0`, you need to re-download the model. Please refer to [How to Download Models](https://github.com/opendatalab/MinerU/blob/master/docs/how_to_download_models_en.md) for detailed steps.
+
+### 0.8.1 (2024/09/27)
+
+Fixed some bugs, and providing a [localized deployment version](https://github.com/opendatalab/MinerU/blob/master/projects/web_demo/README.md) of the [online demo](https://opendatalab.com/OpenSourceTools/Extractor/PDF/) and the [front-end interface](https://github.com/opendatalab/MinerU/blob/master/projects/web/README.md).
+
+### 0.8.0 (2024/09/09)
+
+Supporting fast deployment with Dockerfile, and launching demos on Huggingface and Modelscope.
+
+### 0.7.1 (2024/08/30)
+
+Add paddle tablemaster table recognition option
+
+### 0.7.0b1 (2024/08/09)
+
+Simplified installation process, added table recognition functionality
+
+### 0.6.2b1 (2024/08/01)
+
+Optimized dependency conflict issues and installation documentation
+
+### Initial Open-Source Release (2024/07/05)
+
+MinerU project's first open-source release
+
diff --git a/docs/en/reference/index.md b/docs/en/reference/index.md
new file mode 100644
index 0000000..638dbe3
--- /dev/null
+++ b/docs/en/reference/index.md
@@ -0,0 +1,27 @@
+# Reference Documentation
+
+This section provides detailed reference materials for MinerU project. Here you can find technical specifications, API documentation, output file formats, and version history.
+
+## Table of Contents
+
+- [Output Files Documentation](./output_files.md) - Detailed explanation of all output files and their formats
+- [Changelog](./changelog.md) - Version update history and release notes
+
+## Documentation Overview
+
+### Output Files Documentation
+
+Understanding the output files generated by MinerU is crucial for effective use of the tool. The output files documentation provides:
+
+- **Visual debugging files**: Help you understand the document parsing process
+- **Structured data files**: Contain detailed parsing results for further processing
+- **File format specifications**: Detailed descriptions of each output file type
+
+### Changelog
+
+The changelog documents the evolution of MinerU, including:
+
+- **Version updates**: New features and improvements for each release
+- **Bug fixes**: Issues resolved in each version
+- **Breaking changes**: Important changes that may affect your usage
+- **Deprecations**: Features that are being phased out
diff --git a/docs/en/reference/output_files.md b/docs/en/reference/output_files.md
new file mode 100644
index 0000000..ceda518
--- /dev/null
+++ b/docs/en/reference/output_files.md
@@ -0,0 +1,712 @@
+# MinerU Output Files Documentation
+
+## Overview
+
+After executing the `mineru` command, in addition to the main markdown file output, multiple auxiliary files are generated for debugging, quality inspection, and further processing. These files include:
+
+- **Visual debugging files**: Help users intuitively understand the document parsing process and results
+- **Structured data files**: Contain detailed parsing data for secondary development
+
+The following sections provide detailed descriptions of each file's purpose and format.
+
+## Visual Debugging Files
+
+### Layout Analysis File (layout.pdf)
+
+**File naming format**: `{original_filename}_layout.pdf`
+
+**Functionality**:
+
+- Visualizes layout analysis results for each page
+- Numbers in the top-right corner of each detection box indicate reading order
+- Different background colors distinguish different types of content blocks
+
+**Use cases**:
+
+- Check if layout analysis is correct
+- Verify if reading order is reasonable
+- Debug layout-related issues
+
+
+
+### Text Spans File (spans.pdf)
+
+> [!NOTE]
+> Only applicable to pipeline backend
+
+**File naming format**: `{original_filename}_spans.pdf`
+
+**Functionality**:
+
+- Uses different colored line boxes to annotate page content based on span type
+- Used for quality inspection and issue troubleshooting
+
+**Use cases**:
+
+- Quickly troubleshoot text loss issues
+- Check inline formula recognition
+- Verify text segmentation accuracy
+
+
+
+## Structured Data Files
+
+> [!IMPORTANT]
+> The VLM backend output has significant changes in version 2.5 and is not backward-compatible with the pipeline backend. If you plan to build secondary development on structured outputs, please read this document carefully.
+
+### Pipeline Backend Output Results
+
+#### Model Inference Results (model.json)
+
+**File naming format**: `{original_filename}_model.json`
+
+##### Data Structure Definition
+
+```python
+from pydantic import BaseModel, Field
+from enum import IntEnum
+
+class CategoryType(IntEnum):
+ """Content category enumeration"""
+ title = 0 # Title
+ plain_text = 1 # Text
+ abandon = 2 # Including headers, footers, page numbers, and page annotations
+ figure = 3 # Image
+ figure_caption = 4 # Image caption
+ table = 5 # Table
+ table_caption = 6 # Table caption
+ table_footnote = 7 # Table footnote
+ isolate_formula = 8 # Interline formula
+ formula_caption = 9 # Interline formula number
+ embedding = 13 # Inline formula
+ isolated = 14 # Interline formula
+ text = 15 # OCR recognition result
+
+class PageInfo(BaseModel):
+ """Page information"""
+ page_no: int = Field(description="Page number, first page is 0", ge=0)
+ height: int = Field(description="Page height", gt=0)
+ width: int = Field(description="Page width", ge=0)
+
+class ObjectInferenceResult(BaseModel):
+ """Object recognition result"""
+ category_id: CategoryType = Field(description="Category", ge=0)
+ poly: list[float] = Field(description="Quadrilateral coordinates, format: [x0,y0,x1,y1,x2,y2,x3,y3]")
+ score: float = Field(description="Confidence score of inference result")
+ latex: str | None = Field(description="LaTeX parsing result", default=None)
+ html: str | None = Field(description="HTML parsing result", default=None)
+
+class PageInferenceResults(BaseModel):
+ """Page inference results"""
+ layout_dets: list[ObjectInferenceResult] = Field(description="Page recognition results")
+ page_info: PageInfo = Field(description="Page metadata")
+
+# Complete inference results
+inference_result: list[PageInferenceResults] = []
+```
+
+##### Coordinate System Description
+
+`poly` coordinate format: `[x0, y0, x1, y1, x2, y2, x3, y3]`
+
+- Represents coordinates of top-left, top-right, bottom-right, bottom-left points respectively
+- Coordinate origin is at the top-left corner of the page
+
+
+
+##### Sample Data
+
+```json
+[
+ {
+ "layout_dets": [
+ {
+ "category_id": 2,
+ "poly": [
+ 99.1906967163086,
+ 100.3119125366211,
+ 730.3707885742188,
+ 100.3119125366211,
+ 730.3707885742188,
+ 245.81326293945312,
+ 99.1906967163086,
+ 245.81326293945312
+ ],
+ "score": 0.9999997615814209
+ }
+ ],
+ "page_info": {
+ "page_no": 0,
+ "height": 2339,
+ "width": 1654
+ }
+ },
+ {
+ "layout_dets": [
+ {
+ "category_id": 5,
+ "poly": [
+ 99.13092803955078,
+ 2210.680419921875,
+ 497.3183898925781,
+ 2210.680419921875,
+ 497.3183898925781,
+ 2264.78076171875,
+ 99.13092803955078,
+ 2264.78076171875
+ ],
+ "score": 0.9999997019767761
+ }
+ ],
+ "page_info": {
+ "page_no": 1,
+ "height": 2339,
+ "width": 1654
+ }
+ }
+]
+```
+
+#### Intermediate Processing Results (middle.json)
+
+**File naming format**: `{original_filename}_middle.json`
+
+##### Top-level Structure
+
+| Field Name | Type | Description |
+|------------|------|-------------|
+| `pdf_info` | `list[dict]` | Array of parsing results for each page |
+| `_backend` | `string` | Parsing mode: `pipeline` or `vlm` |
+| `_version_name` | `string` | MinerU version number |
+
+##### Page Information Structure (pdf_info)
+
+| Field Name | Description |
+|------------|-------------|
+| `preproc_blocks` | Unsegmented intermediate results after PDF preprocessing |
+| `page_idx` | Page number, starting from 0 |
+| `page_size` | Page width and height `[width, height]` |
+| `images` | Image block information list |
+| `tables` | Table block information list |
+| `interline_equations` | Interline formula block information list |
+| `discarded_blocks` | Block information to be discarded |
+| `para_blocks` | Content block results after segmentation |
+
+##### Block Structure Hierarchy
+
+```
+Level 1 blocks (table | image)
+└── Level 2 blocks
+ └── Lines
+ └── Spans
+```
+
+##### Level 1 Block Fields
+
+| Field Name | Description |
+|------------|-------------|
+| `type` | Block type: `table` or `image` |
+| `bbox` | Rectangular box coordinates of the block `[x0, y0, x1, y1]` |
+| `blocks` | List of contained level 2 blocks |
+
+##### Level 2 Block Fields
+
+| Field Name | Description |
+|------------|-------------|
+| `type` | Block type (see table below) |
+| `bbox` | Rectangular box coordinates of the block |
+| `lines` | List of contained line information |
+
+##### Level 2 Block Types
+
+| Type | Description |
+|------|-------------|
+| `image_body` | Image body |
+| `image_caption` | Image caption text |
+| `image_footnote` | Image footnote |
+| `table_body` | Table body |
+| `table_caption` | Table caption text |
+| `table_footnote` | Table footnote |
+| `text` | Text block |
+| `title` | Title block |
+| `index` | Index block |
+| `list` | List block |
+| `interline_equation` | Interline formula block |
+
+##### Line and Span Structure
+
+**Line fields**:
+- `bbox`: Rectangular box coordinates of the line
+- `spans`: List of contained spans
+
+**Span fields**:
+- `bbox`: Rectangular box coordinates of the span
+- `type`: Span type (`image`, `table`, `text`, `inline_equation`, `interline_equation`)
+- `content` | `img_path`: Text content or image path
+
+##### Sample Data
+
+```json
+{
+ "pdf_info": [
+ {
+ "preproc_blocks": [
+ {
+ "type": "text",
+ "bbox": [
+ 52,
+ 61.956024169921875,
+ 294,
+ 82.99800872802734
+ ],
+ "lines": [
+ {
+ "bbox": [
+ 52,
+ 61.956024169921875,
+ 294,
+ 72.0000228881836
+ ],
+ "spans": [
+ {
+ "bbox": [
+ 54.0,
+ 61.956024169921875,
+ 296.2261657714844,
+ 72.0000228881836
+ ],
+ "content": "dependent on the service headway and the reliability of the departure ",
+ "type": "text",
+ "score": 1.0
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "layout_bboxes": [
+ {
+ "layout_bbox": [
+ 52,
+ 61,
+ 294,
+ 731
+ ],
+ "layout_label": "V",
+ "sub_layout": []
+ }
+ ],
+ "page_idx": 0,
+ "page_size": [
+ 612.0,
+ 792.0
+ ],
+ "_layout_tree": [],
+ "images": [],
+ "tables": [],
+ "interline_equations": [],
+ "discarded_blocks": [],
+ "para_blocks": [
+ {
+ "type": "text",
+ "bbox": [
+ 52,
+ 61.956024169921875,
+ 294,
+ 82.99800872802734
+ ],
+ "lines": [
+ {
+ "bbox": [
+ 52,
+ 61.956024169921875,
+ 294,
+ 72.0000228881836
+ ],
+ "spans": [
+ {
+ "bbox": [
+ 54.0,
+ 61.956024169921875,
+ 296.2261657714844,
+ 72.0000228881836
+ ],
+ "content": "dependent on the service headway and the reliability of the departure ",
+ "type": "text",
+ "score": 1.0
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "_backend": "pipeline",
+ "_version_name": "0.6.1"
+}
+```
+
+#### Content List (content_list.json)
+
+**File naming format**: `{original_filename}_content_list.json`
+
+##### Functionality
+
+This is a simplified version of `middle.json` that stores all readable content blocks in reading order as a flat structure, removing complex layout information for easier subsequent processing.
+
+##### Content Types
+
+| Type | Description |
+|------|-------------|
+| `image` | Image |
+| `table` | Table |
+| `text` | Text/Title |
+| `equation` | Interline formula |
+
+##### Text Level Identification
+
+Text levels are distinguished through the `text_level` field:
+
+- No `text_level` or `text_level: 0`: Body text
+- `text_level: 1`: Level 1 heading
+- `text_level: 2`: Level 2 heading
+- And so on...
+
+##### Common Fields
+
+- All content blocks include a `page_idx` field indicating the page number (starting from 0).
+- All content blocks include a `bbox` field representing the bounding box coordinates of the content block `[x0, y0, x1, y1]`, mapped to a range of 0-1000.
+
+##### Sample Data
+
+```json
+[
+ {
+ "type": "text",
+ "text": "The response of flow duration curves to afforestation ",
+ "text_level": 1,
+ "bbox": [
+ 62,
+ 480,
+ 946,
+ 904
+ ],
+ "page_idx": 0
+ },
+ {
+ "type": "image",
+ "img_path": "images/a8ecda1c69b27e4f79fce1589175a9d721cbdc1cf78b4cc06a015f3746f6b9d8.jpg",
+ "image_caption": [
+ "Fig. 1. Annual flow duration curves of daily flows from Pine Creek, Australia, 1989–2000. "
+ ],
+ "image_footnote": [],
+ "bbox": [
+ 62,
+ 480,
+ 946,
+ 904
+ ],
+ "page_idx": 1
+ },
+ {
+ "type": "equation",
+ "img_path": "images/181ea56ef185060d04bf4e274685f3e072e922e7b839f093d482c29bf89b71e8.jpg",
+ "text": "$$\nQ _ { \\% } = f ( P ) + g ( T )\n$$",
+ "text_format": "latex",
+ "bbox": [
+ 62,
+ 480,
+ 946,
+ 904
+ ],
+ "page_idx": 2
+ },
+ {
+ "type": "table",
+ "img_path": "images/e3cb413394a475e555807ffdad913435940ec637873d673ee1b039e3bc3496d0.jpg",
+ "table_caption": [
+ "Table 2 Significance of the rainfall and time terms "
+ ],
+ "table_footnote": [
+ "indicates that the rainfall term was significant at the $5 \\%$ level, $T$ indicates that the time term was significant at the $5 \\%$ level, \\* represents significance at the $10 \\%$ level, and na denotes too few data points for meaningful analysis. "
+ ],
+ "table_body": "
Site
Percentile
10
20
30
40
50
60
70
80
90
100
Traralgon Ck
P
P,*
P
P
P,
P,
P,
P,
P
P
Redhill
P,T
P,T
，*
**
P.T
P,*
P*
P*
*
，*
Pine Ck
P,T
P,T
P,T
P,T
T
T
T
na
na
Stewarts Ck 5
P,T
P,T
P,T
P,T
P.T
P.T
P,T
na
na
na
Glendhu 2
P
P,T
P,*
P,T
P.T
P,ns
P,T
P,T
P,T
P,T
Cathedral Peak 2
P,T
P,T
P,T
P,T
P,T
*,T
P,T
P,T
P,T
T
Cathedral Peak 3
P.T
P.T
P,T
P,T
P,T
T
P,T
P,T
P,T
T
Lambrechtsbos A
P,T
P
P
P,T
*,T
*,T
*,T
*,T
*,T
T
Lambrechtsbos B
P,T
P,T
P,T
P,T
P,T
P,T
P,T
P,T
T
T
Biesievlei
P,T
P.T
P,T
P,T
*,T
*,T
T
T
P,T
P,T
",
+ "bbox": [
+ 62,
+ 480,
+ 946,
+ 904
+ ],
+ "page_idx": 5
+ }
+]
+```
+
+### VLM Backend Output Results
+
+#### Model Inference Results (model.json)
+
+**File naming format**: `{original_filename}_model.json`
+
+##### File format description
+- Two-level nested list: outer list = pages; inner list = content blocks of that page
+- Each block is a dict with at least: `type`, `bbox`, `angle`, `content` (some types add extra fields like `score`, `block_tags`, `content_tags`, `format`)
+- Designed for direct, raw model inspection
+
+##### Supported content types (type field values)
+```json
+{
+ "text": "Plain text",
+ "title": "Title",
+ "equation": "Display (interline) formula",
+ "image": "Image",
+ "image_caption": "Image caption",
+ "image_footnote": "Image footnote",
+ "table": "Table",
+ "table_caption": "Table caption",
+ "table_footnote": "Table footnote",
+ "phonetic": "Phonetic annotation",
+ "code": "Code block",
+ "code_caption": "Code caption",
+ "ref_text": "Reference / citation entry",
+ "algorithm": "Algorithm block (treated as code subtype)",
+ "list": "List container",
+ "header": "Page header",
+ "footer": "Page footer",
+ "page_number": "Page number",
+ "aside_text": "Side / margin note",
+ "page_footnote": "Page footnote"
+}
+```
+
+##### Coordinate system
+- `bbox` = `[x0, y0, x1, y1]` (top-left, bottom-right)
+- Origin at top-left of the page
+- All coordinates are normalized percentages in `[0,1]`
+
+##### Sample data
+```json
+[
+ [
+ {
+ "type": "header",
+ "bbox": [0.077, 0.095, 0.18, 0.181],
+ "angle": 0,
+ "score": null,
+ "block_tags": null,
+ "content": "ELSEVIER",
+ "format": null,
+ "content_tags": null
+ },
+ {
+ "type": "title",
+ "bbox": [0.157, 0.228, 0.833, 0.253],
+ "angle": 0,
+ "score": null,
+ "block_tags": null,
+ "content": "The response of flow duration curves to afforestation",
+ "format": null,
+ "content_tags": null
+ }
+ ]
+]
+```
+
+#### Intermediate Processing Results (middle.json)
+
+**File naming format**: `{original_filename}_middle.json`
+
+Structure is broadly similar to the pipeline backend, but with these differences:
+
+- `list` becomes a second‑level block, a new field `sub_type` distinguishes list categories:
+ * `text`: ordinary list
+ * `ref_text`: reference / bibliography style list
+- New `code` block type with `sub_type`(a code block always has at least a `code_body`, it may optionally have a `code_caption`):
+ * `code`
+ * `algorithm`
+- `discarded_blocks` may contain additional types:
+ * `header`
+ * `footer`
+ * `page_number`
+ * `aside_text`
+ * `page_footnote`
+- All blocks include an `angle` field indicating rotation (one of `0, 90, 180, 270`).
+
+##### Examples
+- Example: list block
+ ```json
+ {
+ "bbox": [174,155,818,333],
+ "type": "list",
+ "angle": 0,
+ "index": 11,
+ "blocks": [
+ {
+ "bbox": [174,157,311,175],
+ "type": "text",
+ "angle": 0,
+ "lines": [
+ {
+ "bbox": [174,157,311,175],
+ "spans": [
+ {
+ "bbox": [174,157,311,175],
+ "type": "text",
+ "content": "H.1 Introduction"
+ }
+ ]
+ }
+ ],
+ "index": 3
+ },
+ {
+ "bbox": [175,182,464,229],
+ "type": "text",
+ "angle": 0,
+ "lines": [
+ {
+ "bbox": [175,182,464,229],
+ "spans": [
+ {
+ "bbox": [175,182,464,229],
+ "type": "text",
+ "content": "H.2 Example: Divide by Zero without Exception Handling"
+ }
+ ]
+ }
+ ],
+ "index": 4
+ }
+ ],
+ "sub_type": "text"
+ }
+ ```
+
+- Example: code block with optional caption:
+ ```json
+ {
+ "type": "code",
+ "bbox": [114,780,885,1231],
+ "blocks": [
+ {
+ "bbox": [114,780,885,1231],
+ "lines": [
+ {
+ "bbox": [114,780,885,1231],
+ "spans": [
+ {
+ "bbox": [114,780,885,1231],
+ "type": "text",
+ "content": "1 // Fig. H.1: DivideByZeroNoExceptionHandling.java \n2 // Integer division without exception handling. \n3 import java.util.Scanner; \n4 \n5 public class DivideByZeroNoExceptionHandling \n6 { \n7 // demonstrates throwing an exception when a divide-by-zero occurs \n8 public static int quotient( int numerator, int denominator ) \n9 { \n10 return numerator / denominator; // possible division by zero \n11 } // end method quotient \n12 \n13 public static void main(String[] args) \n14 { \n15 Scanner scanner = new Scanner(System.in); // scanner for input \n16 \n17 System.out.print(\"Please enter an integer numerator: \"); \n18 int numerator = scanner.nextInt(); \n19 System.out.print(\"Please enter an integer denominator: \"); \n20 int denominator = scanner.nextInt(); \n21"
+ }
+ ]
+ }
+ ],
+ "index": 17,
+ "angle": 0,
+ "type": "code_body"
+ },
+ {
+ "bbox": [867,160,1280,189],
+ "lines": [
+ {
+ "bbox": [867,160,1280,189],
+ "spans": [
+ {
+ "bbox": [867,160,1280,189],
+ "type": "text",
+ "content": "Algorithm 1 Modules for MCTSteg"
+ }
+ ]
+ }
+ ],
+ "index": 19,
+ "angle": 0,
+ "type": "code_caption"
+ }
+ ],
+ "index": 17,
+ "sub_type": "code"
+ }
+ ```
+
+#### Content List (content_list.json)
+
+**File naming format**: `{original_filename}_content_list.json`
+
+Based on the pipeline format, with these VLM-specific extensions:
+
+- New `code` type with `sub_type` (`code` | `algorithm`):
+ * Fields: `code_body` (string), optional `code_caption` (list of strings)
+- New `list` type with `sub_type` (`text` | `ref_text`):
+ * Field: `list_items` (array of strings)
+- All `discarded_blocks` entries are also output (e.g., headers, footers, page numbers, margin notes, page footnotes).
+- Existing types (`image`, `table`, `text`, `equation`) remain unchanged.
+- `bbox` still uses the 0–1000 normalized coordinate mapping.
+
+
+##### Examples
+Example: code (algorithm) entry
+```json
+{
+ "type": "code",
+ "sub_type": "algorithm",
+ "code_caption": ["Algorithm 1 Modules for MCTSteg"],
+ "code_body": "1: function GETCOORDINATE(d) \n2: $x \\gets d / l$ , $y \\gets d$ mod $l$ \n3: return $(x, y)$ \n4: end function \n5: function BESTCHILD(v) \n6: $C \\gets$ child set of $v$ \n7: $v' \\gets \\arg \\max_{c \\in C} \\mathrm{UCTScore}(c)$ \n8: $v'.n \\gets v'.n + 1$ \n9: return $v'$ \n10: end function \n11: function BACK PROPAGATE(v) \n12: Calculate $R$ using Equation 11 \n13: while $v$ is not a root node do \n14: $v.r \\gets v.r + R$ , $v \\gets v.p$ \n15: end while \n16: end function \n17: function RANDOMSEARCH(v) \n18: while $v$ is not a leaf node do \n19: Randomly select an untried action $a \\in A(v)$ \n20: Create a new node $v'$ \n21: $(x, y) \\gets \\mathrm{GETCOORDINATE}(v'.d)$ \n22: $v'.p \\gets v$ , $v'.d \\gets v.d + 1$ , $v'.\\Gamma \\gets v.\\Gamma$ \n23: $v'.\\gamma_{x,y} \\gets a$ \n24: if $a = -1$ then \n25: $v.lc \\gets v'$ \n26: else if $a = 0$ then \n27: $v.mc \\gets v'$ \n28: else \n29: $v.rc \\gets v'$ \n30: end if \n31: $v \\gets v'$ \n32: end while \n33: return $v$ \n34: end function \n35: function SEARCH(v) \n36: while $v$ is fully expanded do \n37: $v \\gets$ BESTCHILD(v) \n38: end while \n39: if $v$ is not a leaf node then \n40: $v \\gets$ RANDOMSEARCH(v) \n41: end if \n42: return $v$ \n43: end function",
+ "bbox": [510,87,881,740],
+ "page_idx": 0
+}
+```
+
+Example: list (text) entry
+```json
+{
+ "type": "list",
+ "sub_type": "text",
+ "list_items": [
+ "H.1 Introduction",
+ "H.2 Example: Divide by Zero without Exception Handling",
+ "H.3 Example: Divide by Zero with Exception Handling",
+ "H.4 Summary"
+ ],
+ "bbox": [174,155,818,333],
+ "page_idx": 0
+}
+```
+
+Example: discarded blocks output
+```json
+[
+ {
+ "type": "header",
+ "text": "Journal of Hydrology 310 (2005) 253-265",
+ "bbox": [363,164,623,177],
+ "page_idx": 0
+ },
+ {
+ "type": "page_footnote",
+ "text": "* Corresponding author. Address: Forest Science Centre, Department of Sustainability and Environment, P.O. Box 137, Heidelberg, Vic. 3084, Australia. Tel.: +61 3 9450 8719; fax: +61 3 9450 8644.",
+ "bbox": [71,815,915,841],
+ "page_idx": 0
+ }
+]
+```
+
+## Summary
+
+The above files constitute MinerU's complete output results. Users can choose appropriate files for subsequent processing based on their needs:
+
+- **Model outputs** (Use raw outputs):
+ * model.json
+
+- **Debugging and verification** (Use visualization files):
+ * layout.pdf
+ * spans.pdf
+
+- **Content extraction**: (Use simplified files):
+ * *.md
+ * content_list.json
+
+- **Secondary development**: (Use structured files):
+ * middle.json
diff --git a/docs/en/usage/advanced_cli_parameters.md b/docs/en/usage/advanced_cli_parameters.md
new file mode 100644
index 0000000..9b57144
--- /dev/null
+++ b/docs/en/usage/advanced_cli_parameters.md
@@ -0,0 +1,53 @@
+# Advanced Command Line Parameters
+
+## Pass-through of inference engine parameters
+
+### vllm Acceleration Parameter Optimization
+> [!TIP]
+> If you can already use vllm normally for accelerated VLM model inference but still want to further improve inference speed, you can try the following parameters:
+>
+> - If you have multiple graphics cards, you can use vllm's multi-card parallel mode to increase throughput: `--data-parallel-size 2`
+
+### Parameter Passing Instructions
+> [!TIP]
+> - All officially supported vllm/lmdeploy parameters can be passed to MinerU through command line arguments, including the following commands: `mineru`, `mineru-openai-server`, `mineru-gradio`, `mineru-api`
+> - If you want to learn more about `vllm` parameter usage, please refer to the [vllm official documentation](https://docs.vllm.ai/en/latest/cli/serve.html)
+> - If you want to learn more about `lmdeploy` parameter usage, please refer to the [lmdeploy official documentation](https://lmdeploy.readthedocs.io/en/latest/llm/api_server.html)
+
+## GPU Device Selection and Configuration
+
+### CUDA_VISIBLE_DEVICES Basic Usage
+> [!TIP]
+> - In any situation, you can specify visible GPU devices by adding the `CUDA_VISIBLE_DEVICES` environment variable at the beginning of the command line. For example:
+> ```bash
+> CUDA_VISIBLE_DEVICES=1 mineru -p -o
+> ```
+> - This specification method is effective for all command line calls, including `mineru`, `mineru-openai-server`, `mineru-gradio`, and `mineru-api`, and applies to both `pipeline` and `vlm` backends.
+
+### Common Device Configuration Examples
+> [!TIP]
+> Here are some common `CUDA_VISIBLE_DEVICES` setting examples:
+> ```bash
+> CUDA_VISIBLE_DEVICES=1 # Only device 1 will be seen
+> CUDA_VISIBLE_DEVICES=0,1 # Devices 0 and 1 will be visible
+> CUDA_VISIBLE_DEVICES="0,1" # Same as above, quotation marks are optional
+> CUDA_VISIBLE_DEVICES=0,2,3 # Devices 0, 2, 3 will be visible; device 1 is masked
+> CUDA_VISIBLE_DEVICES="" # No GPU will be visible
+> ```
+
+## Practical Application Scenarios
+> [!TIP]
+> Here are some possible usage scenarios:
+>
+> - If you have multiple graphics cards and need to specify cards 0 and 1, using multi-card parallelism to start `openai-server`, you can use the following command:
+> ```bash
+> CUDA_VISIBLE_DEVICES=0,1 mineru-openai-server --engine vllm --port 30000 --data-parallel-size 2
+> ```
+>
+> - If you have multiple graphics cards and need to start two `fastapi` services on cards 0 and 1, listening on different ports respectively, you can use the following commands:
+> ```bash
+> # In terminal 1
+> CUDA_VISIBLE_DEVICES=0 mineru-api --host 127.0.0.1 --port 8000
+> # In terminal 2
+> CUDA_VISIBLE_DEVICES=1 mineru-api --host 127.0.0.1 --port 8001
+> ```
diff --git a/docs/en/usage/cli_tools.md b/docs/en/usage/cli_tools.md
new file mode 100644
index 0000000..946d63d
--- /dev/null
+++ b/docs/en/usage/cli_tools.md
@@ -0,0 +1,127 @@
+# Command Line Tools Usage Instructions
+
+## View Help Information
+To view help information for MinerU command line tools, you can use the `--help` parameter. Here are help information examples for various command line tools:
+```bash
+mineru --help
+Usage: mineru [OPTIONS]
+
+Options:
+ -v, --version Show version and exit
+ -p, --path PATH Input file path or directory (required)
+ -o, --output PATH Output directory (required)
+ -m, --method [auto|txt|ocr] Parsing method: auto (default), txt, ocr (pipeline and hybrid* backend only)
+ -b, --backend [pipeline|hybrid-auto-engine|hybrid-http-client|vlm-auto-engine|vlm-http-client]
+ Parsing backend (default: hybrid-auto-engine)
+ -l, --lang [ch|ch_server|ch_lite|en|korean|japan|chinese_cht|ta|te|ka|th|el|latin|arabic|east_slavic|cyrillic|devanagari]
+ Specify document language (improves OCR accuracy, pipeline and hybrid* backend only)
+ -u, --url TEXT Service address when using http-client
+ -s, --start INTEGER Starting page number for parsing (0-based)
+ -e, --end INTEGER Ending page number for parsing (0-based)
+ -f, --formula BOOLEAN Enable formula parsing (default: enabled)
+ -t, --table BOOLEAN Enable table parsing (default: enabled)
+ -d, --device TEXT Inference device (e.g., cpu/cuda/cuda:0/npu/mps, pipeline and vlm-transformers backend only)
+ --vram INTEGER Maximum GPU VRAM usage per process (GB) (pipeline backend only)
+ --source [huggingface|modelscope|local]
+ Model source, default: huggingface
+ --help Show help information
+```
+```bash
+mineru-api --help
+Usage: mineru-api [OPTIONS]
+
+Options:
+ --host TEXT Server host (default: 127.0.0.1)
+ --port INTEGER Server port (default: 8000)
+ --reload Enable auto-reload (development mode)
+ --help Show this message and exit.
+```
+```bash
+mineru-gradio --help
+Usage: mineru-gradio [OPTIONS]
+
+Options:
+ --enable-example BOOLEAN Enable example files for input. The example
+ files to be input need to be placed in the
+ `example` folder within the directory where
+ the command is currently executed.
+ --enable-http-client BOOLEAN Enable http-client backend to link openai-
+ compatible servers.
+ --enable-api BOOLEAN Enable gradio API for serving the
+ application.
+ --max-convert-pages INTEGER Set the maximum number of pages to convert
+ from PDF to Markdown.
+ --server-name TEXT Set the server name for the Gradio app.
+ --server-port INTEGER Set the server port for the Gradio app.
+ --latex-delimiters-type [a|b|all]
+ Set the type of LaTeX delimiters to use in
+ Markdown rendering: 'a' for type '$', 'b' for
+ type '()[]', 'all' for both types.
+ --help Show this message and exit.
+```
+
+## Environment Variables Description
+
+Some parameters of MinerU command line tools have equivalent environment variable configurations. Generally, environment variable configurations have higher priority than command line parameters and take effect across all command line tools.
+Here are the environment variables and their descriptions:
+
+- `MINERU_DEVICE_MODE`:
+ * Used to specify inference device
+ * supports device types like `cpu/cuda/cuda:0/npu/mps`
+ * only effective for `pipeline` and `vlm-transformers` backends.
+
+- `MINERU_VIRTUAL_VRAM_SIZE`:
+ * Used to specify maximum GPU VRAM usage per process (GB)
+ * only effective for `pipeline` backend.
+
+- `MINERU_MODEL_SOURCE`:
+ * Used to specify model source
+ * supports `huggingface/modelscope/local`
+ * defaults to `huggingface`, can be switched to `modelscope` or local models through environment variables.
+
+- `MINERU_TOOLS_CONFIG_JSON`:
+ * Used to specify configuration file path
+ * defaults to `mineru.json` in user directory, can specify other configuration file paths through environment variables.
+
+- `MINERU_FORMULA_ENABLE`:
+ * Used to enable formula parsing
+ * defaults to `true`, can be set to `false` through environment variables to disable formula parsing.
+
+- `MINERU_FORMULA_CH_SUPPORT`:
+ * Used to enable Chinese formula parsing optimization (experimental feature)
+ * Default is `false`, can be set to `true` via environment variable to enable Chinese formula parsing optimization.
+ * Only effective for `pipeline` backend.
+
+- `MINERU_TABLE_ENABLE`:
+ * Used to enable table parsing
+ * Default is `true`, can be set to `false` via environment variable to disable table parsing.
+
+- `MINERU_TABLE_MERGE_ENABLE`:
+ * Used to enable table merging functionality
+ * Default is `true`, can be set to `false` via environment variable to disable table merging functionality.
+
+- `MINERU_PDF_RENDER_TIMEOUT`:
+ * Used to set the timeout period (in seconds) for rendering PDF to images
+ * Default is `300` seconds, can be set to other values via environment variable to adjust the image rendering timeout.
+
+- `MINERU_INTRA_OP_NUM_THREADS`:
+ * Used to set the intra_op thread count for ONNX models, affects the computation speed of individual operators
+ * Default is `-1` (auto-select), can be set to other values via environment variable to adjust the thread count.
+
+- `MINERU_INTER_OP_NUM_THREADS`:
+ * Used to set the inter_op thread count for ONNX models, affects the parallel execution of multiple operators
+ * Default is `-1` (auto-select), can be set to other values via environment variable to adjust the thread count.
+
+- `MINERU_HYBRID_BATCH_RATIO`:
+ * Used to set the batch ratio for small model processing in `hybrid-*` backends.
+ * Commonly used in `hybrid-http-client`, it allows adjusting the VRAM usage of a single client by controlling the batch ratio of small models.
+ * Single Client VRAM Size | MINERU_HYBRID_BATCH_RATIO
+ ------------------------|--------------------------
+ <= 6 GB | 8
+ <= 4.5 GB | 4
+ <= 3 GB | 2
+ <= 2.5 GB | 1
+
+- `MINERU_HYBRID_FORCE_PIPELINE_ENABLE`:
+ * Used to force the text extraction part in `hybrid-*` backends to be processed using small models.
+ * Defaults to `false`. Can be set to `true` via environment variable to enable this feature, thereby reducing hallucinations in certain extreme cases.
diff --git a/docs/en/usage/index.md b/docs/en/usage/index.md
new file mode 100644
index 0000000..bee4978
--- /dev/null
+++ b/docs/en/usage/index.md
@@ -0,0 +1,16 @@
+# Usage Guide
+
+This section provides comprehensive usage instructions for the project. We will help you progressively master the project's usage from basic to advanced through the following sections:
+
+## Table of Contents
+
+- [Quick Usage](./quick_usage.md) - Quick setup and basic usage
+- [Model Source Configuration](./model_source.md) - Detailed configuration instructions for model sources
+- [Command Line Tools](./cli_tools.md) - Detailed parameter descriptions for command line tools
+- [Advanced Optimization Parameters](./advanced_cli_parameters.md) - Advanced parameter descriptions for command line tool adaptation
+
+## Getting Started
+
+We recommend reading the documentation in the order listed above, which will help you better understand and use the project features.
+
+If you encounter issues during usage, please check the [FAQ](../faq/index.md)
\ No newline at end of file
diff --git a/docs/en/usage/model_source.md b/docs/en/usage/model_source.md
new file mode 100644
index 0000000..a6a840c
--- /dev/null
+++ b/docs/en/usage/model_source.md
@@ -0,0 +1,55 @@
+# Model Source Documentation
+
+MinerU uses `HuggingFace` and `ModelScope` as model repositories. Users can switch model sources or use local models as needed.
+
+- `HuggingFace` is the default model source, providing excellent loading speed and high stability globally.
+- `ModelScope` is the best choice for users in mainland China, providing seamlessly compatible `hf` SDK modules, suitable for users who cannot access HuggingFace.
+
+## Methods to Switch Model Sources
+
+### Switch via Command Line Parameters
+Currently, only the `mineru` command line tool supports switching model sources through command line parameters. Other command line tools such as `mineru-api`, `mineru-gradio`, etc., do not support this yet.
+```bash
+mineru -p -o --source modelscope
+```
+
+### Switch via Environment Variables
+You can switch model sources by setting environment variables in any situation. This applies to all command line tools and API calls.
+```bash
+export MINERU_MODEL_SOURCE=modelscope
+```
+or
+```python
+import os
+os.environ["MINERU_MODEL_SOURCE"] = "modelscope"
+```
+>[!TIP]
+> Model sources set through environment variables will take effect in the current terminal session until the terminal is closed or the environment variable is modified. They have higher priority than command line parameters - if both command line parameters and environment variables are set, the command line parameters will be ignored.
+
+## Using Local Models
+
+### 1. Download Models to Local Storage
+```bash
+mineru-models-download --help
+```
+or use the interactive command line tool to select model downloads:
+```bash
+mineru-models-download
+```
+> [!NOTE]
+>- After download completion, the model path will be output in the current terminal window and automatically written to `mineru.json` in the user directory.
+>- You can also create it by copying the [configuration template file](https://github.com/opendatalab/MinerU/blob/master/mineru.template.json) to your user directory and renaming it to `mineru.json`.
+>- After downloading models locally, you can freely move the model folder to other locations while updating the model path in `mineru.json`.
+>- If you deploy the model folder to another server, please ensure you move the `mineru.json` file to the user directory of the new device and configure the model path correctly.
+>- If you need to update model files, you can run the `mineru-models-download` command again. Model updates do not support custom paths currently - if you haven't moved the local model folder, model files will be incrementally updated; if you have moved the model folder, model files will be re-downloaded to the default location and `mineru.json` will be updated.
+
+### 2. Use Local Models for Parsing
+
+```bash
+mineru -p -o --source local
+```
+or enable through environment variables:
+```bash
+export MINERU_MODEL_SOURCE=local
+mineru -p -o
+```
diff --git a/docs/en/usage/quick_usage.md b/docs/en/usage/quick_usage.md
new file mode 100644
index 0000000..fe35020
--- /dev/null
+++ b/docs/en/usage/quick_usage.md
@@ -0,0 +1,100 @@
+# Using MinerU
+
+## Quick Model Source Configuration
+MinerU uses `huggingface` as the default model source. If users cannot access `huggingface` due to network restrictions, they can conveniently switch the model source to `modelscope` through environment variables:
+```bash
+export MINERU_MODEL_SOURCE=modelscope
+```
+For more information about model source configuration and custom local model paths, please refer to the [Model Source Documentation](./model_source.md) in the documentation.
+
+## Quick Usage via Command Line
+MinerU has built-in command line tools that allow users to quickly use MinerU for PDF parsing through the command line:
+```bash
+mineru -p -o
+```
+> [!TIP]
+>- ``: Local PDF/image file or directory
+>- ``: Output directory
+>
+> For more information about output files, please refer to [Output File Documentation](../reference/output_files.md).
+
+> [!NOTE]
+> The command line tool will automatically attempt cuda/mps acceleration on Linux and macOS systems.
+> Windows users who need cuda acceleration should visit the [PyTorch official website](https://pytorch.org/get-started/locally/) to select the appropriate command for their cuda version to install acceleration-enabled `torch` and `torchvision`.
+
+If you need to adjust parsing options through custom parameters, you can also check the more detailed [Command Line Tools Usage Instructions](./cli_tools.md) in the documentation.
+
+## Advanced Usage via API, WebUI, http-client/server
+
+- Direct Python API calls: [Python Usage Example](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py)
+- FastAPI calls:
+ ```bash
+ mineru-api --host 0.0.0.0 --port 8000
+ ```
+ >[!TIP]
+ >Access `http://127.0.0.1:8000/docs` in your browser to view the API documentation.
+- Start Gradio WebUI visual frontend:
+ ```bash
+ mineru-gradio --server-name 0.0.0.0 --server-port 7860
+ ```
+ >[!TIP]
+ >
+ >- Access `http://127.0.0.1:7860` in your browser to use the Gradio WebUI.
+
+- Using `http-client/server` method:
+ ```bash
+ # Start openai compatible server (requires vllm or lmdeploy environment)
+ mineru-openai-server --port 30000
+ ```
+ >[!TIP]
+ >In another terminal, connect to openai server via http client
+ > ```bash
+ > mineru -p -o -b hybrid-http-client -u http://127.0.0.1:30000
+ > ```
+
+> [!NOTE]
+> All officially supported `vllm/lmdeploy` parameters can be passed to MinerU through command line arguments, including the following commands: `mineru`, `mineru-openai-server`, `mineru-gradio`, `mineru-api`.
+> We have compiled some commonly used parameters and usage methods for `vllm/lmdeploy`, which can be found in the documentation [Advanced Command Line Parameters](./advanced_cli_parameters.md).
+
+## Extending MinerU Functionality with Configuration Files
+
+MinerU is now ready to use out of the box, but also supports extending functionality through configuration files. You can edit `mineru.json` file in your user directory to add custom configurations.
+
+>[!IMPORTANT]
+>The `mineru.json` file will be automatically generated when you use the built-in model download command `mineru-models-download`, or you can create it by copying the [configuration template file](https://github.com/opendatalab/MinerU/blob/master/mineru.template.json) to your user directory and renaming it to `mineru.json`.
+
+Here are some available configuration options:
+
+- `latex-delimiter-config`:
+ * Used to configure LaTeX formula delimiters
+ * Defaults to `$` symbol, can be modified to other symbols or strings as needed.
+
+- `llm-aided-config`:
+ * Used to configure parameters for LLM-assisted title hierarchy
+ * Compatible with all LLM models supporting `openai protocol`, defaults to using Alibaba Cloud Bailian's `qwen3-next-80b-a3b-instruct` model.
+ * You need to configure your own API key and set `enable` to `true` to enable this feature.
+ * If your API provider does not support the `enable_thinking` parameter, please manually remove it.
+ * For example, in your configuration file, the `llm-aided-config` section may look like:
+ ```json
+ "llm-aided-config": {
+ "api_key": "your_api_key",
+ "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+ "model": "qwen3-next-80b-a3b-instruct",
+ "enable_thinking": false,
+ "enable": false
+ }
+ ```
+ * To remove the `enable_thinking` parameter, simply delete the line containing `"enable_thinking": false`, resulting in:
+ ```json
+ "llm-aided-config": {
+ "api_key": "your_api_key",
+ "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+ "model": "qwen3-next-80b-a3b-instruct",
+ "enable": false
+ }
+ ```
+
+- `models-dir`:
+ * Used to specify local model storage directory
+ * Please specify model directories for `pipeline` and `vlm` backends separately.
+ * After specifying the directory, you can use local models by configuring the environment variable `export MINERU_MODEL_SOURCE=local`.
diff --git a/docs/images/MinerU-logo.png b/docs/images/MinerU-logo.png
new file mode 100644
index 0000000..09ab46b
Binary files /dev/null and b/docs/images/MinerU-logo.png differ
diff --git a/docs/images/datalab_logo.png b/docs/images/datalab_logo.png
new file mode 100644
index 0000000..5019ae7
Binary files /dev/null and b/docs/images/datalab_logo.png differ
diff --git a/docs/images/flowchart_en.png b/docs/images/flowchart_en.png
new file mode 100644
index 0000000..b490011
Binary files /dev/null and b/docs/images/flowchart_en.png differ
diff --git a/docs/images/flowchart_zh_cn.png b/docs/images/flowchart_zh_cn.png
new file mode 100644
index 0000000..32e0a14
Binary files /dev/null and b/docs/images/flowchart_zh_cn.png differ
diff --git a/docs/images/layout_example.png b/docs/images/layout_example.png
new file mode 100644
index 0000000..4a57dff
Binary files /dev/null and b/docs/images/layout_example.png differ
diff --git a/docs/images/logo.png b/docs/images/logo.png
new file mode 100644
index 0000000..0181808
Binary files /dev/null and b/docs/images/logo.png differ
diff --git a/docs/images/logo.svg b/docs/images/logo.svg
new file mode 100644
index 0000000..6553978
--- /dev/null
+++ b/docs/images/logo.svg
@@ -0,0 +1,22 @@
+
diff --git a/docs/images/poly.png b/docs/images/poly.png
new file mode 100644
index 0000000..14af772
Binary files /dev/null and b/docs/images/poly.png differ
diff --git a/docs/images/project_panorama_en.png b/docs/images/project_panorama_en.png
new file mode 100644
index 0000000..19616da
Binary files /dev/null and b/docs/images/project_panorama_en.png differ
diff --git a/docs/images/project_panorama_zh_cn.png b/docs/images/project_panorama_zh_cn.png
new file mode 100644
index 0000000..3cd6843
Binary files /dev/null and b/docs/images/project_panorama_zh_cn.png differ
diff --git a/docs/images/spans_example.png b/docs/images/spans_example.png
new file mode 100644
index 0000000..14de87e
Binary files /dev/null and b/docs/images/spans_example.png differ
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..6669ada
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,4 @@
+mkdocs
+mkdocs-static-i18n
+markdown-gfm-admonition
+mkdocs-video
\ No newline at end of file
diff --git a/docs/zh/demo/index.md b/docs/zh/demo/index.md
new file mode 100644
index 0000000..103ffc5
--- /dev/null
+++ b/docs/zh/demo/index.md
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/zh/faq/index.md b/docs/zh/faq/index.md
new file mode 100644
index 0000000..e4a198d
--- /dev/null
+++ b/docs/zh/faq/index.md
@@ -0,0 +1,29 @@
+# 常见问题解答
+
+如果未能列出您的问题，您也可以使用[DeepWiki](https://deepwiki.com/opendatalab/MinerU)与AI助手交流，这可以解决大部分常见问题。
+
+如果您仍然无法解决问题，您可通过[Discord](https://discord.gg/Tdedn9GTXq)或[WeChat](https://mineru.net/community-portal/?aliasId=3c430f94)加入社区，与其他用户和开发者交流。
+
+??? question "在WSL2的Ubuntu22.04中遇到报错`ImportError: libGL.so.1: cannot open shared object file: No such file or directory`"
+
+ WSL2的Ubuntu22.04中缺少`libgl`库，可通过以下命令安装`libgl`库解决：
+
+ ```bash
+ sudo apt-get install libgl1-mesa-glx
+ ```
+
+ 参考：[#388](https://github.com/opendatalab/MinerU/issues/388)
+
+??? question "在 Linux 系统安装并使用时，解析结果缺失部份文字信息。"
+
+ MinerU在>=2.0的版本中使用`pypdfium2`代替`pymupdf`作为PDF页面的渲染引擎，以解决AGPLv3的许可证问题，在某些Linux发行版，由于缺少CJK字体，可能会在将PDF渲染成图片的过程中丢失部份文字。
+ 为了解决这个问题，您可以通过以下命令安装noto字体包，这在Ubuntu/debian系统中有效：
+ ```bash
+ sudo apt update
+ sudo apt install fonts-noto-core
+ sudo apt install fonts-noto-cjk
+ fc-cache -fv
+ ```
+ 也可以直接使用我们的[Docker部署](../quick_start/docker_deployment.md)方式构建镜像，镜像中默认包含以上字体包。
+
+ 参考：[#2915](https://github.com/opendatalab/MinerU/issues/2915)
\ No newline at end of file
diff --git a/docs/zh/index.md b/docs/zh/index.md
new file mode 100644
index 0000000..48af523
--- /dev/null
+++ b/docs/zh/index.md
@@ -0,0 +1,69 @@
+
+