This is an automated email from the ASF dual-hosted git repository.
shuai pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-answer-website.git
The following commit(s) were added to refs/heads/main by this push:
new 74db3588 fix: rename filename
74db3588 is described below
commit 74db358802f20af8ef7c615a8a70bc2fdf9605d4
Author: shuai <[email protected]>
AuthorDate: Tue Jul 9 10:57:14 2024 +0800
fix: rename filename
---
.../docusaurus-plugin-content-docs/current.json | 4 +
.../current/development/plugins/plugin.md | 335 +++++++++++++++++++++
.../current/development/plugins/plugins.md | 225 --------------
3 files changed, 339 insertions(+), 225 deletions(-)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
b/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
index 1071380a..b9e3c939 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
@@ -66,5 +66,9 @@
"sidebar.docs.category.Developer Guides": {
"message": "开发者指南",
"description": "The label for category Developer Guides in sidebar docs"
+ },
+ "sidebar.docs.category.Plugins": {
+ "message": "插件",
+ "description": "The label for category Plugins in sidebar docs"
}
}
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
new file mode 100644
index 00000000..52eecf8c
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugin.md
@@ -0,0 +1,335 @@
+---
+# sidebar_label: Plugins
+slug: /development/plugins
+---
+
+# 插件开发指南
+
+Plugins are a way to extend the functionality of the Answer project. You can
create your own plugins to meet your own needs.
+
+:::tip
+
+Viewing the [**official plugin
code**](https://github.com/apache/incubator-answer-plugins) will make you to
quickly understand and learn plugin development.
+
+:::
+
+## Introduction
+
+### Plugin template types
+Currently we have three types of plugins:
+
+- Backend plugin
+- Standard UI plugin
+- Builtin plugin
+
+### Plugin type
+
+We classify plugins into different types. Different types of plugins have
different functions. Plugins of the same type have the same effect, but are
implemented differently.
+
+Plugin Name | Template Type | Description
+--- | --- | ---
+Connector | Backend Plugin | The Connector plugin helps us to implement
third-party login functionality
+Storage | Backend Plugin | The Storage plugin helps us to upload files to
third-party storage.
+Cache | Backend Plugin | Support for using different caching middleware.
+Search | Backend Plugin | Support for using search engines to speed up the
search for question answers.
+User Center | Backend Plugin | Using the third-party user system to manage
users.
+Notification | Backend Plugin | The Notification plugin helps us to send
messages to third-party notification systems.
+Route | Standard UI Plugin | Provides support for custom routing.
+Editor | Standard UI Plugin | Supports extending the markdown editor's toolbar.
+Captcha | Standard UI Plugin | Provides support for captcha.
+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:
+
+"editor-chart" ✅
+"editor_chart" ❌
+
+:::
+
+1. Go to the `ui > src > plugin` directory of the project.
+
+2. Execute the following commands in that directory:
+
+```shell
+npx create-answer-plugin <pluginName>
+```
+
+3. Select the type of plugin you want to create.
+
+
+
+## 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/incubator-answer/cmd"
+
+ // Import the plugins
+ _ "github.com/apache/incubator-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/incubator-answer/ui/src/plugins/my-plugin=../ui/src/plugins/my-plugin
+ ```
+4. Update the dependencies.
+
+ ```shell
+ go mod tidy
+ ```
+
+5. 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.
+
+ ```shell
+ pnpm pre-install
+ ```
+
+3. Start the project.
+
+ ```shell
+ pnpm start
+ ```
+
+4. Refer to the [Run the Backend
Plugin](/docs/development/plugins#debugging-plugins) and add the plugin to the
project.
+
+## Backend Plugin Development
+
+### Implement the Base interface
+
+The `Base` interface contains basic information about the plugin and is used
to display.
+
+```go
+// Info presents the plugin information
+type Info struct {
+ Name Translator
+ SlugName string
+ Description Translator
+ Author string
+ Version string
+ Link string
+}
+
+// Base is the base plugin
+type Base interface {
+ // Info returns the plugin information
+ Info() Info
+}
+```
+
+:::caution
+
+The `SlugName` of the plugin must be unique. Two plugins with the same
`SlugName` will panic when registering.
+
+:::
+
+### Implement the function interface
+
+:::note
+
+Different plugin types require different interfaces of implementation.
+
+For example, following is the `Connector` plugin interface.
+
+:::
+
+```go
+type Connector interface {
+ Base
+
+ // ConnectorLogoSVG presents the logo in svg format
+ ConnectorLogoSVG() string
+
+ // ConnectorName presents the name of the connector
+ // e.g. Facebook, Twitter, Instagram
+ ConnectorName() Translator
+
+ // ConnectorSlugName presents the slug name of the connector
+ // Please use lowercase and hyphen as the separator
+ // e.g. facebook, twitter, instagram
+ ConnectorSlugName() string
+
+ // ConnectorSender presents the sender of the connector
+ // It handles the start endpoint of the connector
+ // receiverURL is the whole URL of the receiver
+ ConnectorSender(ctx *GinContext, receiverURL string) (redirectURL string)
+
+ // ConnectorReceiver presents the receiver of the connector
+ // It handles the callback endpoint of the connector, and returns the
+ ConnectorReceiver(ctx *GinContext, receiverURL string) (userInfo
ExternalLoginUserInfo, err error)
+}
+```
+
+:::tip
+
+`Translator` is a struct for translation. Please refer to [the
documentation](/docs/development/plugins/plugin-translation) for details.
+
+:::
+
+### Implement the configuration interface
+
+For details on the description of each configuration item, please refer to
[the documentation](/docs/development/plugins/plugin-config).
+
+```go
+type Config interface {
+ Base
+
+ // ConfigFields returns the list of config fields
+ ConfigFields() []ConfigField
+
+ // ConfigReceiver receives the config data, it calls when the config is
saved or initialized.
+ // We recommend to unmarshal the data to a struct, and then use the struct
to do something.
+ // The config is encoded in JSON format.
+ // It depends on the definition of ConfigFields.
+ ConfigReceiver(config []byte) error
+}
+```
+
+### Register initialization function
+
+```go
+import "github.com/apache/incubator-answer/plugin"
+
+func init() {
+ plugin.Register(&GitHubConnector{
+ Config: &GitHubConnectorConfig{},
+ })
+}
+```
+
+## Standard UI plugin Development
+
+The default configuration is as follows:
+
+```yaml
+slug_name: <slug_name>
+type: <type>
+version: 0.0.1
+author:
+
+```
+```tsx
+import i18nConfig from './i18n';
+import Component from './Component';
+import info from './info.yaml';
+
+export default {
+ info: {
+ slug_name: info.slug_name,
+ type: info.type,
+ },
+ i18nConfig,
+ component: Component,
+};
+```
+
+Among them, `type`、`slug_name` and `component` are required fields.
`i18nConfig` and `hooks` are optional fields.
+
+Currently the front end supports the following types of plugins:
+* editor
+* route
+* captcha
+
+### Editor plugin
+
+Refer to
[editor-chart](https://github.com/apache/incubator-answer-plugins/tree/main/editor-chart)
for details.
+
+### Route plugin
+
+The plugin configuration of the routing type adds the `route` field to the
configuration file.
+
+```yaml
+slug_name: <slug_name>
+route: /<route>
+type: route
+version: 0.0.1
+author:
+
+```
+```tsx
+import i18nConfig from './i18n';
+import Component from './Component';
+import info from './info.yaml';
+
+export default {
+ info: {
+ slug_name: info.slug_name,
+ type: info.type,
+ route: info.route,
+ },
+ i18nConfig,
+ component: Component,
+};
+```
+
+### Captcha plugin
+
+Refer to
[captcha-basic](https://github.com/apache/incubator-answer-plugins/tree/main/captcha-basic)
for details.
+
+## Builtin plugin Development
+
+It is not so different from React component, this plugin is more suitable for
the following scenarios:
+
+1. There are complex business logics that cannot be separated from the code
(such as Oauth).
+2. Some back-end plugins require UI support for business purposes (such as
Search).
+3. This plugin has extremely low requirements for developers and requires no
additional configuration work.
+
+### How to develop builtin plugin
+
+1. **Get familiar with the directory structure**. Go to the
`ui/src/plugins/builtin` directory and create a directory, such as Demo. Then
refer to the existing plugins to create the necessary files to start
development.
+
+ ```txt
+ // ui/src/plugins/builtin
+ .
+ ├── ...
+ ├── Demo
+ ├── i18n (language file)
+ ├── en_US.yaml (default language required)
+ ├── index.ts (required)
+ ├── zh_CN.ts (any language you want to provide)
+ ├── index.tsx (component required)
+ ├── info.yaml (plugin information required)
+ ├── services.ts (api)
+ ```
+
+2. Export the plugins you have just defined in the plugins list file
`plugins/builtin/index.ts`
+
+ ```ts
+ import Demo from './Demo'
+
+ export default {
+ ...(exists plugins),
+ Demo,
+ };
+ ```
+
+3. Now you can use the PluginRender component to render the just-defined
plugin where you want it!
+
+ ```ts
+ <PluginRender
+ type="connector"
+ slug_name="third_party_connector"
+ />
+ ```
+
+4. **Publish plugin**: initiate the PR process normally and describe the
plugin function and scope of influence in detail.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugins.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugins.md
deleted file mode 100644
index f902a586..00000000
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins/plugins.md
+++ /dev/null
@@ -1,225 +0,0 @@
----
-slug: /plugins
----
-
-# 插件
-
-:::tip
-
-当我们需要对 Apache Answer 的功能进行扩展，例如 OAuth 登录，我们设计了一种使用插件实现这些功能的方式。
-
-:::
-
-## 介绍
-
-### 官方插件
-
-你可以在 [这里](https://github.com/apache/incubator-answer-plugins) 找到 Apache Answer
官方支持的插件列表。
-
-### 插件类型
-> 我们将插件分为不同的类型。
-> 不同类型的插件有不同的功能。
-> 同一类型的插件具有相同的效果，但实现方式不同。
-
-- Connector: 支持实现第三方登录功能。例如 GitHub OAuth 登录。
-- Storage: 支持将文件上传到第三方服务。例如 `AliyunOSS` `S3`。（预览）
-- Cache: 支持使用不同的缓存中间件。例如 `Redis`。（预览）
-- Filter: 支持过滤非法问题或回答。（即将推出）
-- Render: 支持通过不同的解析器渲染不同格式的内容。（即将推出）
-- Finder: 支持使用搜索引擎加速搜索问题和回答。（即将推出）
-
-## 构建
-> Apache Answer 二进制文件支持将不同的必需插件打包到二进制文件中。
-
-### 先决条件
-
-- 原始的 Apache Answer 二进制文件
-- [Golang](https://go.dev/) `>=1.18`
-
-### 命令
-
-:::tip
-我们使用 Apache Answer 二进制文件提供的 build 命令来重新构建带插件的 Apache Answer 版本。
-:::
-
-> 例如，让我们看看如何构建一个包含 github 第三方登录插件的 Apache Answer 二进制文件
-
-```shell
-# answer build --with [plugin@plugin_version=[replacement]] --output [file]
-$ ./answer build --with
github.com/apache/incubator-answer-plugins/connector-github
-
-# 构建一个带有 github 登录插件的新 Apache Answer，然后输出到 ./new_answer。
-$ ./answer build --with
github.com/apache/incubator-answer-plugins/[email protected] --output
./new_answer
-
-# 带有多个插件
-$ ./answer build \
---with github.com/apache/incubator-answer-plugins/connector-github \
---with github.com/apache/incubator-answer-plugins/connector-google
-
-# 带有本地插件
-$ ./answer build --with
github.com/apache/incubator-answer-plugins/[email protected]=/my-local-space
-
-# 交叉编译。在 macos 中构建一个 linux-amd64 二进制文件
-$ CGO_ENABLED=0 GOOS=linux GOARCH=amd64 ./answer build --with
github.com/apache/incubator-answer-plugins/connector-github
-```
-
-:::tip
-你可以使用 `plugin` 命令列出当前包含插件的二进制文件。
-:::
-
-```shell
-$ ./new_answer plugin
-
-# 输出
-# github connector[0.0.1] made by answerdev
-# google connector[0.0.1] made by answerdev
-```
-
-## 第三方插件
-
-:::tip
-我们建议使用[官方插件](https://github.com/apache/incubator-answer-plugins)，如果你想使用第三方插件，请参考以下内容。
-:::
-
-- 如果第三方插件是公开可用的，则可以像官方插件一样构建它。
-- 如果第三方插件是私有的，则需要下载然后构建。
-
-## 使用
->
-> 具有插件版本的 answer 与之前的使用方式相同。
-> 你可以在管理员页面中找到插件的配置。
-
-
-
-## 升级
-
-你只需要重新编译并使用插件的最新版本即可。
-
-## 开发
-
-:::tip
-查看官方[插件代码](https://github.com/apache/incubator-answer-plugins)，可以帮助你快速了解和学习插件开发。
-:::
-
-### 后端开发
-
-#### 实现 Base
->
-> `Base` 接口包含有关插件的基本信息，并用于显示。
-
-```go
-// Info 显示插件信息
-type Info struct {
- Name Translator
- SlugName string
- Description Translator
- Author string
- Version string
- Link string
-}
-
-// Base 是基础插件
-type Base interface {
- // Info 返回插件信息
- Info() Info
-}
-```
-
-:::caution
-插件的 `SlugName` 必须是唯一的。如果有两个 `SlugName` 相同的插件将在注册时引发混乱。
-:::
-
-#### 实现函数接口
-
-:::note
-不同类型的插件需要不同的接口实现。
-
-例如，以下是 `Connector` 插件接口。
-:::
-
-```go
-type Connector interface {
- Base
-
- // ConnectorLogoSVG 显示 svg 格式的标志
- ConnectorLogoSVG() string
-
- // ConnectorName 显示连接器的名称
- // 例如 Facebook、Twitter、Instagram
- ConnectorName() Translator
-
- // ConnectorSlugName 显示连接器的 slug 名称
- // 请使用小写和连字符作为分隔符
- // 例如 facebook、twitter、instagram
- ConnectorSlugName() string
-
- // ConnectorSender 显示连接器的发送器
- // 它处理连接器的起始端点
- // receiverURL 是接收方的完整 URL
- ConnectorSender(ctx *GinContext, receiverURL string) (redirectURL string)
-
- // ConnectorReceiver 显示连接器的接收器
- // 它处理连接器的回调端点，并返回
- ConnectorReceiver(ctx *GinContext, receiverURL string) (userInfo
ExternalLoginUserInfo, err error)
-}
-```
-
-:::tip
-`Translator` 是用于翻译的结构体。请参阅[文档](/docs/plugins/plugin-translation)了解详情。
-:::
-
-#### 实现配置接口
-
-有关每个配置项的描述详见[文档](/docs/plugins/plugin-config)。
-
-```go
-type Config interface {
- Base
-
- // ConfigFields 返回配置字段列表
- ConfigFields() []ConfigField
-
- // ConfigReceiver 接收配置数据，在保存或初始化配置时调用。
- // 我们建议将数据反序列化为结构体，然后使用结构体来进行操作。
- // 配置以 JSON 格式编码。
- // 它依赖于 ConfigFields 的定义。
- ConfigReceiver(config []byte) error
-}
-```
-
-#### 注册初始化函数
-
-```go
-import "github.com/apache/incubator-answer/plugin"
-
-func init() {
- plugin.Register(&GitHubConnector{
- Config: &GitHubConnectorConfig{},
- })
-}
-```
-
-#### 调试提示
-
-:::tip
-在开发和调试阶段，你可以使用以下提示，避免重复打包。
-:::
-
-1. U 使用 Apache Answer 的源代码进行开发。
-2. 直接在插件目录中编写插件。
-3. 在主函数中导入插件。
-
-之后，你只需要正常启动 Apache Answer 项目，它将包含你开发的插件。
-
-## 贡献
-
-对于尚未实现的插件类型，请等待官方实现完成后再进行贡献。
-对于已有的插件类型，你可以按照以下步骤向我们贡献插件实现。
-
-1. 提交问题请求，以确保官方没有开发与你相同的插件。
-2. 得到确认后，开发你的插件，进行测试并提交 PR。
-3. 等待 PR 合并，官方包含你的插件。
-
-## 设计和原则
-
-由于 Golang 是一种静态语言，因此没有友好的插件机制。因此，我们使用重新编译进行部署，而不是动态方法。
