This is an automated email from the ASF dual-hosted git repository.
robin0716 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/answer-website.git
The following commit(s) were added to refs/heads/main by this push:
new fc350bed8 docs: enhance plugin creation and installation instructions
with scaffolding tool details
fc350bed8 is described below
commit fc350bed8eb7becbae105b5c0953ab5fce3dded3
Author: robin <[email protected]>
AuthorDate: Sun Nov 30 11:34:59 2025 +0800
docs: enhance plugin creation and installation instructions with
scaffolding tool details
---
docs/development/plugins/plugin.md | 264 +++++++++++++++++---
.../current/development/plugins/plugin.md | 274 ++++++++++++++++++---
2 files changed, 461 insertions(+), 77 deletions(-)
diff --git a/docs/development/plugins/plugin.md
b/docs/development/plugins/plugin.md
index 81ae4e8e6..c06819f9f 100644
--- a/docs/development/plugins/plugin.md
+++ b/docs/development/plugins/plugin.md
@@ -13,6 +13,12 @@ Viewing the [**official plugin
code**](https://github.com/apache/answer-plugins)
:::
+:::info
+
+**Recommended**: Use the official scaffolding tool
[`create-answer-plugin`](https://www.npmjs.com/package/create-answer-plugin) to
create and manage plugins. It automates most of the setup process, including
file generation, Go module configuration, and plugin installation.
+
+:::
+
## Introduction
### Plugin template types
@@ -52,66 +58,252 @@ The **name** field in package.json is the name of the
package we add dependencie
:::
-1. Go to the `ui > src > plugin` directory of the project.
+### Using the Scaffolding Tool (Recommended)
+
+The easiest way to create a plugin is using the official scaffolding tool:
+
+```shell
+# Install the tool globally (optional)
+npm install -g create-answer-plugin
+# or
+pnpm add -g create-answer-plugin
+
+# Or use npx directly (recommended)
+npx create-answer-plugin create <pluginName>
+# or use the alias
+npx answer-plugin create <pluginName>
+# or use the simplified form
+npx answer-plugin <pluginName>
+```
+
+**Note**: The package name is `create-answer-plugin`, but you can use either
`create-answer-plugin` or `answer-plugin` as the command (both work!).
+
+The tool will:
+1. Guide you through an interactive wizard to select the plugin type
+2. Generate all required files with the correct structure
+3. Create the Go wrapper file (required for Backend plugins)
+4. Set up proper `go.mod` with all dependencies
+5. Generate i18n files with the correct structure
-2. Execute the following commands in that directory:
+**Options:**
+- `pluginName` (optional): Pre-fill the plugin name
+- `--path, -p`: Path to Answer project (root directory). If not specified,
defaults to current directory.
+**Example:**
```shell
-npx create-answer-plugin <pluginName>
+# Navigate to your Answer project root
+cd /path/to/answer
+
+# Create a plugin
+npx create-answer-plugin create my-plugin
+# or with path option
+npx create-answer-plugin create my-plugin --path /path/to/answer
+# Select: Standard UI Plugin → Route
+# Enter route path: /hello
```
-3. Select the type of plugin you want to create.
+The plugin will be created in `ui/src/plugins/my-plugin/` (note: `plugins` is
plural).
+
+### Manual Creation
+
+If you prefer to create plugins manually:
+
+1. Go to the `ui > src > plugins` directory of the project (note: `plugins` is
plural).
+
+2. Create your plugin directory and files following the structure of existing
plugins.
## Run the Plugin
-### Run the Backend Plugin
+### Install Plugin (Automated - Recommended)
+
+The easiest way to install a plugin is using the scaffolding tool's `install`
command:
+
+```shell
+# Navigate to your Answer project root
+cd /path/to/answer
+
+# Install a specific plugin (automatically handles registration)
+npx create-answer-plugin install my-plugin
+# or
+npx answer-plugin install my-plugin
+# or with path option
+npx answer-plugin install my-plugin --path /path/to/answer
+
+# Install all not installed plugins
+npx create-answer-plugin install
+```
+
+**Options:**
+- `plugins` (optional): Plugin names to install (defaults to all not installed
plugins)
+- `--path, -p`: Path to Answer project (defaults to current directory)
+
+The `install` command automatically:
+- ✅ Adds plugin import to `cmd/answer/main.go`
+- ✅ Adds `replace` directive to `go.mod`
+- ✅ Runs `go mod tidy`
+- ✅ Merges i18n resources using `go run ./cmd/answer/main.go i18n`
+
+### List Plugins
+
+List all plugins in the Answer project:
+
+```shell
+# List all plugins
+npx create-answer-plugin list
+# or
+npx answer-plugin list
+# or with path option
+npx answer-plugin list /path/to/answer
+```
-1. First, execute `make ui` to compile the front-end code.
-2. In the `cmd > answer > main.go` file, import your plugin.
+**Options:**
+- `path` (optional): Path to Answer project (defaults to current directory)
- ```go
- import (
- answercmd "github.com/apache/answer/cmd"
+### Uninstall Plugins
- // Import the plugins
- _ "github.com/apache/answer-plugins/my-plugin"
- )
- ```
-3. Use `go mod edit` to add the plugin to the `go.mod` file.
+Uninstall plugins from the Answer project:
- ```shell
- go mod edit
-replace=github.com/apache/answer-plugins/my-plugin=./ui/src/plugins/my-plugin
- ```
-4. Update the dependencies.
+```shell
+# Uninstall all installed plugins
+npx create-answer-plugin uninstall
+# or
+npx answer-plugin uninstall
+
+# Uninstall specific plugins
+npx create-answer-plugin uninstall my-plugin another-plugin
+# or with path option
+npx answer-plugin uninstall my-plugin --path /path/to/answer
+```
- ```shell
- go mod tidy
- ```
+**Options:**
+- `plugins` (optional): Plugin names to uninstall (defaults to all installed
plugins)
+- `--path, -p`: Path to Answer project (defaults to current directory)
-5. Start the project.
+The `uninstall` command automatically:
+- ✅ Removes plugin import from `cmd/answer/main.go`
+- ✅ Removes `replace` directive from `go.mod`
+- ✅ Runs `go mod tidy`
+- ✅ Updates i18n resources
- ```shell
- go run cmd/answer/main.go run -C ./answer-data
- ```
+### Run the Backend Plugin
+
+#### Using the Scaffolding Tool (Recommended)
+
+1. Install the plugin using the scaffolding tool (see above).
+
+2. Build the frontend:
+ ```shell
+ cd ui
+ pnpm pre-install
+ pnpm build
+ cd ..
+ ```
+
+3. Merge i18n resources (if not done automatically):
+ ```shell
+ go run ./cmd/answer/main.go i18n
+ ```
+
+4. Start the project:
+ ```shell
+ go run cmd/answer/main.go run -C ./answer-data
+ ```
+
+#### Manual Installation
+
+If you prefer to install manually:
+
+1. First, build the frontend:
+ ```shell
+ cd ui
+ pnpm pre-install
+ pnpm build
+ cd ..
+ ```
+
+2. In the `cmd > answer > main.go` file, import your plugin:
+ ```go
+ import (
+ answercmd "github.com/apache/answer/cmd"
+
+ // Import the plugins
+ _ "github.com/apache/answer/ui/src/plugins/my-plugin"
+ )
+ ```
+
+3. Use `go mod edit` to add the plugin to the `go.mod` file:
+ ```shell
+ go mod edit
-replace=github.com/apache/answer/ui/src/plugins/my-plugin=./ui/src/plugins/my-plugin
+ ```
+
+4. Update the dependencies:
+ ```shell
+ go mod tidy
+ ```
+
+5. Merge i18n resources:
+ ```shell
+ go run ./cmd/answer/main.go i18n
+ ```
+
+6. Start the project:
+ ```shell
+ go run cmd/answer/main.go run -C ./answer-data
+ ```
### Run the Standard UI Plugin
-1. Go to the `ui` directory.
-2. Install the dependencies.
+#### Using the Scaffolding Tool (Recommended)
- ```shell
- pnpm pre-install
- ```
+1. Install the plugin using the scaffolding tool:
+ ```shell
+ cd /path/to/answer
+ npx create-answer-plugin install my-plugin
+ ```
-3. Start the project.
+2. Go to the `ui` directory and install dependencies:
+ ```shell
+ cd ui
+ pnpm pre-install
+ ```
- ```shell
- pnpm start
- ```
+3. Build the frontend:
+ ```shell
+ pnpm build
+ ```
-4. Refer to the [Run the Backend
Plugin](/docs/development/plugins#debugging-plugins) and add the plugin to the
project.
+4. For development, start the dev server:
+ ```shell
+ pnpm start
+ ```
+
+5. Merge i18n resources (if not done automatically):
+ ```shell
+ cd ..
+ go run ./cmd/answer/main.go i18n
+ ```
+
+#### Manual Installation
+
+1. Go to the `ui` directory.
+2. Install the dependencies:
+ ```shell
+ pnpm pre-install
+ ```
+
+3. Build the frontend:
+ ```shell
+ pnpm build
+ ```
+
+4. For development, start the dev server:
+ ```shell
+ pnpm start
+ ```
+
+5. Refer to the [Run the Backend
Plugin](/docs/development/plugins#run-the-backend-plugin) section and manually
add the plugin to the project (import in `main.go`, add `replace` directive,
etc.).
## Backend Plugin Development
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugin.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugin.md
index 24eb10d41..e3aa77962 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugin.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugin.md
@@ -9,7 +9,13 @@ Plugins are a way to extend the functionality of the Answer
project. You can cre
:::tip
-Viewing the [**official plugin
code**](https://github.com/apache/answer-plugins) will make you to quickly
understand and learn plugin development.
+查看 [**官方插件代码**](https://github.com/apache/answer-plugins) 将帮助你快速理解和学习插件开发。
+
+:::
+
+:::info
+
+**推荐**：使用官方脚手架工具
[`create-answer-plugin`](https://www.npmjs.com/package/create-answer-plugin)
来创建和管理插件。它可以自动化大部分设置过程，包括文件生成、Go 模块配置和插件安装。
:::
@@ -41,77 +47,263 @@ Reviewer | Backend Plugin |Allows customizing the
reviewer functionality.
Filter | Backend Plugin | Filter out illegal questions or answers. (coming
soon)
Render | Standard UI Plugin | Parsers for different content formats. (coming
soon)
-## Create a Plugin
+## 创建插件
:::info
-The **name** field in package.json is the name of the package we add
dependencies to; do not use `_` to connect this field naming, please use `-`;
for example:
+package.json 中的 **name** 字段是我们添加依赖的包名；请不要使用 `_` 连接此字段命名，请使用 `-`；例如：
"editor-chart" ✅
"editor_chart" ❌
:::
-1. Go to the `ui > src > plugin` directory of the project.
+### 使用脚手架工具（推荐）
+
+创建插件最简单的方法是使用官方脚手架工具：
+
+```shell
+# 全局安装工具（可选）
+npm install -g create-answer-plugin
+# 或
+pnpm add -g create-answer-plugin
+
+# 或直接使用 npx（推荐）
+npx create-answer-plugin create <pluginName>
+# 或使用别名
+npx answer-plugin create <pluginName>
+# 或使用简化形式
+npx answer-plugin <pluginName>
+```
+
+**注意**：包名是 `create-answer-plugin`，但你可以使用 `create-answer-plugin` 或
`answer-plugin` 作为命令（两者都可以使用！）。
-2. Execute the following commands in that directory:
+该工具将：
+1. 通过交互式向导引导你选择插件类型
+2. 生成所有必需的文件，并具有正确的结构
+3. 创建 Go 包装文件（后端插件必需）
+4. 设置包含所有依赖项的 `go.mod`
+5. 生成具有正确结构的 i18n 文件
+**选项：**
+- `pluginName`（可选）：预填充插件名称
+- `--path, -p`：Answer 项目路径（根目录）。如果未指定，默认为当前目录。
+
+**示例：**
```shell
-npx create-answer-plugin <pluginName>
+# 导航到你的 Answer 项目根目录
+cd /path/to/answer
+
+# 创建插件
+npx create-answer-plugin create my-plugin
+# 或使用路径选项
+npx create-answer-plugin create my-plugin --path /path/to/answer
+# 选择：Standard UI Plugin → Route
+# 输入路由路径：/hello
```
-3. Select the type of plugin you want to create.
+插件将创建在 `ui/src/plugins/my-plugin/`（注意：`plugins` 是复数形式）。
+
+### 手动创建
+
+如果你更喜欢手动创建插件：
+1. 进入项目的 `ui > src > plugins` 目录（注意：`plugins` 是复数形式）。
+2. 创建你的插件目录和文件，遵循现有插件的结构。
-## Run the Plugin
-### Run the Backend Plugin
-1. First, execute `make ui` to compile the front-end code.
-2. In the `cmd > answer > main.go` file, import your plugin.
+## 运行插件
- ```go
- import (
- answercmd "github.com/apache/answer/cmd"
+### 安装插件（自动化 - 推荐）
- // Import the plugins
- _ "github.com/apache/answer/ui/src/plugins/my-plugin"
- )
- ```
-3. Use `go mod edit` to add the plugin to the `go.mod` file.
+安装插件最简单的方法是使用脚手架工具的 `install` 命令：
+
+```shell
+# 导航到你的 Answer 项目根目录
+cd /path/to/answer
+
+# 安装特定插件（自动处理注册）
+npx create-answer-plugin install my-plugin
+# 或
+npx answer-plugin install my-plugin
+# 或使用路径选项
+npx answer-plugin install my-plugin --path /path/to/answer
+
+# 安装所有未安装的插件
+npx create-answer-plugin install
+```
- ```shell
- go mod edit
-replace=github.com/apache/answer/ui/src/plugins/my-plugin=../ui/src/plugins/my-plugin
- ```
-4. Update the dependencies.
+**选项：**
+- `plugins`（可选）：要安装的插件名称（默认为所有未安装的插件）
+- `--path, -p`：Answer 项目路径（默认为当前目录）
- ```shell
- go mod tidy
- ```
+`install` 命令会自动：
+- ✅ 在 `cmd/answer/main.go` 中添加插件导入
+- ✅ 在 `go.mod` 中添加 `replace` 指令
+- ✅ 运行 `go mod tidy`
+- ✅ 使用 `go run ./cmd/answer/main.go i18n` 合并 i18n 资源
-5. Start the project.
+### 列出插件
- ```shell
- go run cmd/answer/main.go run -C ./answer-data
- ```
+列出 Answer 项目中的所有插件：
-### Run the Standard UI Plugin
+```shell
+# 列出所有插件
+npx create-answer-plugin list
+# 或
+npx answer-plugin list
+# 或使用路径选项
+npx answer-plugin list /path/to/answer
+```
-1. Go to the `ui` directory.
-2. Install the dependencies.
+**选项：**
+- `path`（可选）：Answer 项目路径（默认为当前目录）
- ```shell
- pnpm pre-install
- ```
+### 卸载插件
-3. Start the project.
+从 Answer 项目中卸载插件：
- ```shell
- pnpm start
- ```
+```shell
+# 卸载所有已安装的插件
+npx create-answer-plugin uninstall
+# 或
+npx answer-plugin uninstall
+
+# 卸载特定插件
+npx create-answer-plugin uninstall my-plugin another-plugin
+# 或使用路径选项
+npx answer-plugin uninstall my-plugin --path /path/to/answer
+```
-4. Refer to the [Run the Backend
Plugin](/docs/development/plugins#debugging-plugins) and add the plugin to the
project.
+**选项：**
+- `plugins`（可选）：要卸载的插件名称（默认为所有已安装的插件）
+- `--path, -p`：Answer 项目路径（默认为当前目录）
+
+`uninstall` 命令会自动：
+- ✅ 从 `cmd/answer/main.go` 中移除插件导入
+- ✅ 从 `go.mod` 中移除 `replace` 指令
+- ✅ 运行 `go mod tidy`
+- ✅ 更新 i18n 资源
+
+### 运行后端插件
+
+#### 使用脚手架工具（推荐）
+
+1. 使用脚手架工具安装插件（见上文）。
+
+2. 构建前端：
+ ```shell
+ cd ui
+ pnpm pre-install
+ pnpm build
+ cd ..
+ ```
+
+3. 合并 i18n 资源（如果未自动完成）：
+ ```shell
+ go run ./cmd/answer/main.go i18n
+ ```
+
+4. 启动项目：
+ ```shell
+ go run cmd/answer/main.go run -C ./answer-data
+ ```
+
+#### 手动安装
+
+如果你更喜欢手动安装：
+
+1. 首先，构建前端：
+ ```shell
+ cd ui
+ pnpm pre-install
+ pnpm build
+ cd ..
+ ```
+
+2. 在 `cmd > answer > main.go` 文件中，导入你的插件：
+ ```go
+ import (
+ answercmd "github.com/apache/answer/cmd"
+
+ // Import the plugins
+ _ "github.com/apache/answer/ui/src/plugins/my-plugin"
+ )
+ ```
+
+3. 使用 `go mod edit` 将插件添加到 `go.mod` 文件：
+ ```shell
+ go mod edit
-replace=github.com/apache/answer/ui/src/plugins/my-plugin=./ui/src/plugins/my-plugin
+ ```
+
+4. 更新依赖：
+ ```shell
+ go mod tidy
+ ```
+
+5. 合并 i18n 资源：
+ ```shell
+ go run ./cmd/answer/main.go i18n
+ ```
+
+6. 启动项目：
+ ```shell
+ go run cmd/answer/main.go run -C ./answer-data
+ ```
+
+### 运行标准 UI 插件
+
+#### 使用脚手架工具（推荐）
+
+1. 使用脚手架工具安装插件：
+ ```shell
+ cd /path/to/answer
+ npx create-answer-plugin install my-plugin
+ ```
+
+2. 进入 `ui` 目录并安装依赖：
+ ```shell
+ cd ui
+ pnpm pre-install
+ ```
+
+3. 构建前端：
+ ```shell
+ pnpm build
+ ```
+
+4. 开发时，启动开发服务器：
+ ```shell
+ pnpm start
+ ```
+
+5. 合并 i18n 资源（如果未自动完成）：
+ ```shell
+ cd ..
+ go run ./cmd/answer/main.go i18n
+ ```
+
+#### 手动安装
+
+1. 进入 `ui` 目录。
+2. 安装依赖：
+ ```shell
+ pnpm pre-install
+ ```
+
+3. 构建前端：
+ ```shell
+ pnpm build
+ ```
+
+4. 开发时，启动开发服务器：
+ ```shell
+ pnpm start
+ ```
+
+5. 参考 [运行后端插件](/docs/development/plugins#运行后端插件) 部分，手动将插件添加到项目中（在 `main.go`
中导入，添加 `replace` 指令等）。
## Backend Plugin Development
