Merge pull request #3068 from myhloli/dev

fix: update usage instructions and add quick usage guide in documentation

docs/en/faq/index.md

 # Frequently Asked Questions
 
-If your question is not listed, you can also use [DeepWiki](https://deepwiki.com/opendatalab/MinerU) to communicate with the AI assistant, which can solve most common problems.
+If your question is not listed, try using [DeepWiki](https://deepwiki.com/opendatalab/MinerU)'s AI assistant for common issues.
 
-If you still cannot resolve the issue, you can join the community through [Discord](https://discord.gg/Tdedn9GTXq) or [WeChat](http://mineru.space/s/V85Yl) to communicate with other users and developers.
+For unresolved problems, join our [Discord](https://discord.gg/Tdedn9GTXq) or [WeChat](http://mineru.space/s/V85Yl) community for support.
 
 ??? question "Encountered the error `ImportError: libGL.so.1: cannot open shared object file: No such file or directory` in Ubuntu 22.04 on WSL2"
 

docs/en/quick_start/index.md

@@ -93,4 +93,9 @@ You can get the [Docker Deployment Instructions](./docker_deployment.md) in the
 
 ### Using MinerU
 
+The simplest command line invocation is:
+```bash
+mineru -p <input_path> -o <output_path>
+```
+
 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

docs/en/usage/index.md

-# Using MinerU
+# Usage Guide
 
-## 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.
+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 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
-# Default parsing using pipeline backend
-mineru -p <input_path> -o <output_path>
-```
-> [!TIP]
->- `<input_path>`: Local PDF/image file or directory
->- `<output_path>`: Output directory
->
-> For more information about output files, please refer to [Output File Documentation](../output_files.md).
+- [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
 
-> [!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`.
+## Getting Started
 
+We recommend reading the documentation in the order listed above, which will help you better understand and use the project features.
 
-```bash
-# Or specify vlm backend for parsing
+If you encounter issues during usage, please check the [FAQ](../faq/index.md)
\ No newline at end of file
-mineru -p <input_path> -o <output_path> -b vlm-transformers
-```
-> [!TIP]
-> The vlm backend additionally supports `sglang` acceleration. Compared to the `transformers` backend, `sglang` can achieve 20-30x speedup. You can check the installation method for the complete package supporting `sglang` acceleration in the [Extension Modules Installation Guide](../quick_start/extension_modules.md).
-
-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, sglang-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 127.0.0.1 --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
-  # Using pipeline/vlm-transformers/vlm-sglang-client backends
-  mineru-gradio --server-name 127.0.0.1 --server-port 7860
-  # Or using vlm-sglang-engine/pipeline backends (requires sglang environment)
-  mineru-gradio --server-name 127.0.0.1 --server-port 7860 --enable-sglang-engine true
-  ```
-  >[!TIP]
-  >
-  >- Access `http://127.0.0.1:7860` in your browser to use the Gradio WebUI.
-  >- Access `http://127.0.0.1:7860/?view=api` to use the Gradio API.
-- Using `sglang-client/server` method:
-  ```bash
-  # Start sglang server (requires sglang environment)
-  mineru-sglang-server --port 30000
-  ``` 
-  >[!TIP]
-  >In another terminal, connect to sglang server via sglang client (only requires CPU and network, no sglang environment needed)
-  > ```bash
-  > mineru -p <input_path> -o <output_path> -b vlm-sglang-client -u http://127.0.0.1:30000
-  > ```
-
-> [!TIP]
-> All officially supported sglang parameters can be passed to MinerU through command line arguments, including the following commands: `mineru`, `mineru-sglang-server`, `mineru-gradio`, `mineru-api`.
-> We have compiled some commonly used parameters and usage methods for `sglang`, 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.  
-
->[!TIP]
->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 `qwen2.5-32b-instruct` model. You need to configure your own API key and set `enable` to `true` to enable this feature.
-- `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`.
-

docs/en/usage/model_source.md

@@ -36,7 +36,7 @@ or use the interactive command line tool to select model downloads:
 ```bash
 mineru-models-download
 ```
->[!TIP]
+> [!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`.

docs/en/usage/quick_usage.md

+# 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
+# Default parsing using pipeline backend
+mineru -p <input_path> -o <output_path>
+```
+> [!TIP]
+>- `<input_path>`: Local PDF/image file or directory
+>- `<output_path>`: 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`.
+
+
+```bash
+# Or specify vlm backend for parsing
+mineru -p <input_path> -o <output_path> -b vlm-transformers
+```
+> [!TIP]
+> The vlm backend additionally supports `sglang` acceleration. Compared to the `transformers` backend, `sglang` can achieve 20-30x speedup. You can check the installation method for the complete package supporting `sglang` acceleration in the [Extension Modules Installation Guide](../quick_start/extension_modules.md).
+
+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, sglang-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 127.0.0.1 --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
+  # Using pipeline/vlm-transformers/vlm-sglang-client backends
+  mineru-gradio --server-name 127.0.0.1 --server-port 7860
+  # Or using vlm-sglang-engine/pipeline backends (requires sglang environment)
+  mineru-gradio --server-name 127.0.0.1 --server-port 7860 --enable-sglang-engine true
+  ```
+  >[!TIP]
+  >
+  >- Access `http://127.0.0.1:7860` in your browser to use the Gradio WebUI.
+  >- Access `http://127.0.0.1:7860/?view=api` to use the Gradio API.
+- Using `sglang-client/server` method:
+  ```bash
+  # Start sglang server (requires sglang environment)
+  mineru-sglang-server --port 30000
+  ``` 
+  >[!TIP]
+  >In another terminal, connect to sglang server via sglang client (only requires CPU and network, no sglang environment needed)
+  > ```bash
+  > mineru -p <input_path> -o <output_path> -b vlm-sglang-client -u http://127.0.0.1:30000
+  > ```
+
+> [!NOTE]
+> All officially supported sglang parameters can be passed to MinerU through command line arguments, including the following commands: `mineru`, `mineru-sglang-server`, `mineru-gradio`, `mineru-api`.
+> We have compiled some commonly used parameters and usage methods for `sglang`, 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 `qwen2.5-32b-instruct` model. You need to configure your own API key and set `enable` to `true` to enable this feature.
+- `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`.
+

docs/zh/quick_start/index.md

@@ -93,4 +93,9 @@ MinerU提供了便捷的docker部署方式，这有助于快速搭建环境并
 
 ### 使用 MinerU
 
+最简单的命令行调用方式:
+```bash
+mineru -p <input_path> -o <output_path>
+```
+
 您可以通过命令行、API、WebUI等多种方式使用MinerU进行PDF解析，具体使用方法请参考[使用指南](../usage/index.md)。
\ No newline at end of file

docs/zh/usage/advanced_cli_parameters.md

-# 命令行参数进阶技巧
+# 命令行参数进阶
 
 ---
 

docs/zh/usage/index.md

-# 使用 MinerU
+# 使用指南
 
-## 快速配置模型源
-MinerU默认使用`huggingface`作为模型源，若用户网络无法访问`huggingface`，可以通过环境变量便捷地切换模型源为`modelscope`：
-```bash
-export MINERU_MODEL_SOURCE=modelscope
-```
-有关模型源配置和自定义本地模型路径的更多信息，请参考文档中的[模型源说明](./model_source.md)。
+本章节提供了项目的完整使用说明。我们将通过以下几个部分，帮助您从基础到进阶逐步掌握项目的使用方法：
 
----
+## 目录
 
-## 通过命令行快速使用
-MinerU内置了命令行工具，用户可以通过命令行快速使用MinerU进行PDF解析：
-```bash
-# 默认使用pipeline后端解析
-mineru -p <input_path> -o <output_path>
-```
-> [!TIP]
-> - `<input_path>`：本地 PDF/图片 文件或目录
-> - `<output_path>`：输出目录
-> 
-> 更多关于输出文件的信息，请参考[输出文件说明](../output_files.md)。
+- [快速使用](./quick_usage.md) - 快速上手和基本使用
+- [模型源配置](./model_source.md) - 模型源的详细配置说明  
+- [命令行工具](./cli_tools.md) - 命令行工具的详细参数说明
+- [进阶优化参数](./advanced_cli_parameters.md) - 一些适配命令行工具的进阶参数说明
 
-> [!NOTE]
-> 命令行工具会在Linux和macOS系统自动尝试cuda/mps加速。Windows用户如需使用cuda加速，
-> 请前往 [Pytorch官网](https://pytorch.org/get-started/locally/) 选择适合自己cuda版本的命令安装支持加速的`torch`和`torchvision`。
+## 开始使用
 
+建议按照上述顺序阅读文档，这样可以帮助您更好地理解和使用项目功能。
 
-```bash
-# 或指定vlm后端解析
+如果您在使用过程中遇到问题，请查看 [FAQ](../faq/index.md)
\ No newline at end of file
-mineru -p <input_path> -o <output_path> -b vlm-transformers
-```
-> [!TIP]
-> vlm后端另外支持`sglang`加速，与`transformers`后端相比，`sglang`的加速比可达20～30倍，可以在[扩展模块安装指南](../quick_start/extension_modules.md)中查看支持`sglang`加速的完整包安装方法。
-
-如果需要通过自定义参数调整解析选项，您也可以在文档中查看更详细的[命令行工具使用说明](./cli_tools.md)。
-
----
-
-## 通过api、webui、sglang-client/server进阶使用
-
-- 通过python api直接调用：[Python 调用示例](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py)
-- 通过fast api方式调用：
-  ```bash
-  mineru-api --host 127.0.0.1 --port 8000
-  ```
-  >[!TIP]
-  >在浏览器中访问 `http://127.0.0.1:8000/docs` 查看API文档。
-- 启动gradio webui 可视化前端：
-  ```bash
-  # 使用 pipeline/vlm-transformers/vlm-sglang-client 后端
-  mineru-gradio --server-name 127.0.0.1 --server-port 7860
-  # 或使用 vlm-sglang-engine/pipeline 后端（需安装sglang环境）
-  mineru-gradio --server-name 127.0.0.1 --server-port 7860 --enable-sglang-engine true
-  ```
-  >[!TIP]
-  > 
-  >- 在浏览器中访问 `http://127.0.0.1:7860` 使用 Gradio WebUI。
-  >- 访问 `http://127.0.0.1:7860/?view=api` 使用 Gradio API。
-- 使用`sglang-client/server`方式调用：
-  ```bash
-  # 启动sglang server(需要安装sglang环境)
-  mineru-sglang-server --port 30000
-  ``` 
-  >[!TIP]
-  >在另一个终端中通过sglang client连接sglang server（只需cpu与网络，不需要sglang环境）
-  > ```bash
-  > mineru -p <input_path> -o <output_path> -b vlm-sglang-client -u http://127.0.0.1:30000
-  > ```
-
-> [!TIP]
-> 所有sglang官方支持的参数都可用通过命令行参数传递给 MinerU，包括以下命令:`mineru`、`mineru-sglang-server`、`mineru-gradio`、`mineru-api`，
-> 我们整理了一些`sglang`使用中的常用参数和使用方法，可以在文档[命令行进阶参数](./advanced_cli_parameters.md)中获取。
-
----
-
-## 基于配置文件扩展 MinerU 功能
-
-MinerU 现已实现开箱即用，但也支持通过配置文件扩展功能。您可通过编辑用户目录下的 `mineru.json` 文件，添加自定义配置。
-
->[!TIP]
->`mineru.json` 文件会在您使用内置模型下载命令 `mineru-models-download` 时自动生成，也可以通过将[配置模板文件](https://github.com/opendatalab/MinerU/blob/master/mineru.template.json)复制到用户目录下并重命名为 `mineru.json` 来创建。  
-
-以下是一些可用的配置选项： 
-
-- `latex-delimiter-config`：用于配置 LaTeX 公式的分隔符，默认为`$`符号，可根据需要修改为其他符号或字符串。
-- `llm-aided-config`：用于配置 LLM 辅助标题分级的相关参数，兼容所有支持`openai协议`的 LLM 模型，默认使用`阿里云百炼`的`qwen2.5-32b-instruct`模型，您需要自行配置 API 密钥并将`enable`设置为`true`来启用此功能。
-- `models-dir`：用于指定本地模型存储目录，请为`pipeline`和`vlm`后端分别指定模型目录，指定目录后您可通过配置环境变量`export MINERU_MODEL_SOURCE=local`来使用本地模型。

docs/zh/usage/model_source.md

@@ -37,7 +37,7 @@ mineru-models-download --help
 ```bash
 mineru-models-download
 ```
->[!TIP]
+> [!NOTE]
 >- 下载完成后，模型路径会在当前终端窗口输出，并自动写入用户目录下的 `mineru.json`。
 >- 您也可以通过将[配置模板文件](https://github.com/opendatalab/MinerU/blob/master/mineru.template.json)复制到用户目录下并重命名为 `mineru.json` 来创建配置文件。
 >- 模型下载到本地后，您可以自由移动模型文件夹到其他位置，同时需要在 `mineru.json` 中更新模型路径。

docs/zh/usage/quick_usage.md

+# 使用 MinerU
+
+## 快速配置模型源
+MinerU默认使用`huggingface`作为模型源，若用户网络无法访问`huggingface`，可以通过环境变量便捷地切换模型源为`modelscope`：
+```bash
+export MINERU_MODEL_SOURCE=modelscope
+```
+有关模型源配置和自定义本地模型路径的更多信息，请参考文档中的[模型源说明](./model_source.md)。
+
+---
+
+## 通过命令行快速使用
+MinerU内置了命令行工具，用户可以通过命令行快速使用MinerU进行PDF解析：
+```bash
+# 默认使用pipeline后端解析
+mineru -p <input_path> -o <output_path>
+```
+> [!TIP]
+> - `<input_path>`：本地 PDF/图片 文件或目录
+> - `<output_path>`：输出目录
+> 
+> 更多关于输出文件的信息，请参考[输出文件说明](../reference/output_files.md)。
+
+> [!NOTE]
+> 命令行工具会在Linux和macOS系统自动尝试cuda/mps加速。Windows用户如需使用cuda加速，
+> 请前往 [Pytorch官网](https://pytorch.org/get-started/locally/) 选择适合自己cuda版本的命令安装支持加速的`torch`和`torchvision`。
+
+
+```bash
+# 或指定vlm后端解析
+mineru -p <input_path> -o <output_path> -b vlm-transformers
+```
+> [!TIP]
+> vlm后端另外支持`sglang`加速，与`transformers`后端相比，`sglang`的加速比可达20～30倍，可以在[扩展模块安装指南](../quick_start/extension_modules.md)中查看支持`sglang`加速的完整包安装方法。
+
+如果需要通过自定义参数调整解析选项，您也可以在文档中查看更详细的[命令行工具使用说明](./cli_tools.md)。
+
+---
+
+## 通过api、webui、sglang-client/server进阶使用
+
+- 通过python api直接调用：[Python 调用示例](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py)
+- 通过fast api方式调用：
+  ```bash
+  mineru-api --host 127.0.0.1 --port 8000
+  ```
+  >[!TIP]
+  >在浏览器中访问 `http://127.0.0.1:8000/docs` 查看API文档。
+- 启动gradio webui 可视化前端：
+  ```bash
+  # 使用 pipeline/vlm-transformers/vlm-sglang-client 后端
+  mineru-gradio --server-name 127.0.0.1 --server-port 7860
+  # 或使用 vlm-sglang-engine/pipeline 后端（需安装sglang环境）
+  mineru-gradio --server-name 127.0.0.1 --server-port 7860 --enable-sglang-engine true
+  ```
+  >[!TIP]
+  > 
+  >- 在浏览器中访问 `http://127.0.0.1:7860` 使用 Gradio WebUI。
+  >- 访问 `http://127.0.0.1:7860/?view=api` 使用 Gradio API。
+- 使用`sglang-client/server`方式调用：
+  ```bash
+  # 启动sglang server(需要安装sglang环境)
+  mineru-sglang-server --port 30000
+  ``` 
+  >[!TIP]
+  >在另一个终端中通过sglang client连接sglang server（只需cpu与网络，不需要sglang环境）
+  > ```bash
+  > mineru -p <input_path> -o <output_path> -b vlm-sglang-client -u http://127.0.0.1:30000
+  > ```
+
+> [!NOTE]
+> 所有sglang官方支持的参数都可用通过命令行参数传递给 MinerU，包括以下命令:`mineru`、`mineru-sglang-server`、`mineru-gradio`、`mineru-api`，
+> 我们整理了一些`sglang`使用中的常用参数和使用方法，可以在文档[命令行进阶参数](./advanced_cli_parameters.md)中获取。
+
+---
+
+## 基于配置文件扩展 MinerU 功能
+
+MinerU 现已实现开箱即用，但也支持通过配置文件扩展功能。您可通过编辑用户目录下的 `mineru.json` 文件，添加自定义配置。
+
+>[!IMPORTANT]
+>`mineru.json` 文件会在您使用内置模型下载命令 `mineru-models-download` 时自动生成，也可以通过将[配置模板文件](https://github.com/opendatalab/MinerU/blob/master/mineru.template.json)复制到用户目录下并重命名为 `mineru.json` 来创建。  
+
+以下是一些可用的配置选项： 
+
+- `latex-delimiter-config`：用于配置 LaTeX 公式的分隔符，默认为`$`符号，可根据需要修改为其他符号或字符串。
+- `llm-aided-config`：用于配置 LLM 辅助标题分级的相关参数，兼容所有支持`openai协议`的 LLM 模型，默认使用`阿里云百炼`的`qwen2.5-32b-instruct`模型，您需要自行配置 API 密钥并将`enable`设置为`true`来启用此功能。
+- `models-dir`：用于指定本地模型存储目录，请为`pipeline`和`vlm`后端分别指定模型目录，指定目录后您可通过配置环境变量`export MINERU_MODEL_SOURCE=local`来使用本地模型。

mkdocs.yml

@@ -56,12 +56,12 @@ extra:
       name: GitHub
     - icon: fontawesome/brands/x-twitter
       link: https://x.com/OpenDataLab_AI
-      name: Twitter
+      name: X-Twitter
     - icon: fontawesome/brands/discord
       link: https://discord.gg/Tdedn9GTXq
       name: Discord
     - icon: fontawesome/brands/weixin
-      link: https://mineru.space/common/qun/?qid=362634
+      link: http://mineru.space/s/V85Yl
       name: WeChat
     - icon: material/email
       link: mailto:OpenDataLab@pjlab.org.cn