This is an automated email from the ASF dual-hosted git repository. fenbox pushed a commit to branch build-community in repository https://gitbox.apache.org/repos/asf/incubator-answer-website.git
commit d0531aa0412ef1ddad64d91cf2b881d0e70caee6 Author: fen <[email protected]> AuthorDate: Mon Nov 27 17:33:15 2023 +0800 docs: convert tab to space, update markdown format --- community/contributing/plugins.md | 70 +++++++++++++--------- community/contributing/plugins/plugin-config.md | 28 +++++---- .../contributing/plugins/plugin-translation.md | 38 ++++++------ docs/development/{extending => }/plugins.md | 55 ++++++++++------- sidebars.js | 2 +- 5 files changed, 113 insertions(+), 80 deletions(-) diff --git a/community/contributing/plugins.md b/community/contributing/plugins.md index 6cbc2547..768ccd84 100644 --- a/community/contributing/plugins.md +++ b/community/contributing/plugins.md @@ -6,50 +6,57 @@ slug: /plugins # Contribute for Plugins :::tip -Viewing the official plugin code will make you to quickly understand and learn plugin development. -https://github.com/apache/incubator-answer-plugins +Viewing the [**official plugin code**](https://github.com/apache/incubator-answer-plugins) will make you to quickly understand and learn plugin development. + ::: ## Plugin types Currently we have three types of plugins: -- Only Backend plugin +- Only Backend plugin - Frontend Builtin plugin - Standard UI plugin ## Backend plugin + ### Implement the Base interface -> The `Base` interface contains basic information about the plugin and is used to display. + +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 + 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 + // 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 @@ -80,42 +87,48 @@ type Connector interface { ``` :::tip + `Translator` is a struct for translation. Please refer to [the documentation](/docs/plugins/plugin-translation) for details. -::: +::: ### Implement the configuration interface -For details on the description of each configuration item, please refer to [the documentation](/docs/plugins/plugin-config). + +For details on the description of each configuration item, please refer to [the documentation](/community/plugins/plugin-config). ```go type Config interface { - Base + Base - // ConfigFields returns the list of config fields - ConfigFields() []ConfigField + // 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 + // 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{}, - }) + plugin.Register(&GitHubConnector{ + Config: &GitHubConnectorConfig{}, + }) } ``` ### Debugging tips + :::tip + During the development and debugging phase, you can use the following tips to avoid repetitive packaging. + ::: 1. Use answer source code for development. @@ -183,7 +196,7 @@ This plugin is suitable for the following scenarios 1. A plug-in that can independently complete some UI functions and does not require back-end support; 2. The code needs to be isolated to prevent confusion with the main site; -Existing examples:[editor-chart](https://github.com/apache/incubator-answer-plugins/blob/main/editor-chart), [editor-formula](https://github.com/apache/incubator-answer-plugins/tree/main/editor-formula). +Existing examples:[editor-chart](https://github.com/apache/incubator-answer-plugins/tree/main/editor-chart), [editor-formula](https://github.com/apache/incubator-answer-plugins/tree/main/editor-formula). In order to simplify the development and compilation process, we use [workspace](https://pnpm.io/next/workspaces) to manage this independent front-end warehouse. @@ -193,10 +206,9 @@ In order to simplify the development and compilation process, we use [workspace] :::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" ✅ + 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" ❌ ::: diff --git a/community/contributing/plugins/plugin-config.md b/community/contributing/plugins/plugin-config.md index 333c7e04..058b3643 100644 --- a/community/contributing/plugins/plugin-config.md +++ b/community/contributing/plugins/plugin-config.md @@ -6,15 +6,13 @@ slug: /plugins/plugin-config # Plugin Configuration Schema ## Feature -> For plugins, we often need some configuration items to record the information necessary for the plugin. -> -> For example, OAuth plugins require secret key configuration. -> -> These configurations need to be described by the developer and used by the user. -> -> So, the following is about how to describe the configuration required for a plugin. - -### Backend & Plugin developer + +For plugins, we often need some configuration items to record the information necessary for the plugin. + +For example, OAuth plugins require secret key configuration. These configurations need to be described by the developer and used by the user. So, the following is about how to describe the configuration required for a plugin. + +### Backend & plugin developer + :::note For backend or plugin developers, we use the following structure to describe the plugin configuration. @@ -48,6 +46,7 @@ type ConfigFieldOption struct { ``` ### Frontend + :::note On the frontend we use JSON to describe and render the plugin's configuration items. @@ -99,10 +98,12 @@ On the frontend we use JSON to describe and render the plugin's configuration it ``` The following is what looks like on the Admin Page. +  -### Supported Config Types -> Different types will be rendered as different UI. +### Supported config types + +Different types will be rendered as different UI. - input - textarea @@ -113,8 +114,9 @@ The following is what looks like on the Admin Page. - timezone - switch -### Supported Config Input Types -> Different formats are supported for the input type +### Supported config input types + +Different formats are supported for the input type. - text - color diff --git a/community/contributing/plugins/plugin-translation.md b/community/contributing/plugins/plugin-translation.md index 37f7eb4c..0f21d28d 100644 --- a/community/contributing/plugins/plugin-translation.md +++ b/community/contributing/plugins/plugin-translation.md @@ -4,12 +4,12 @@ slug: /plugins/plugin-translation # Plugin Translation -## How to make your plugin support multi-language? -> Since answer supports multiple languages, the plugin also needs to support multiple languages. -> The following is an example of how to make your plugin support multiple languages. +Since answer supports multiple languages, the plugin also needs to support multiple languages. +The following is an example of how to make your plugin support multiple languages. -## Translator Structure -> In some plugins interface, you can see the `Translator` structure, which is used to support multiple languages. +## Translator structure + +In some plugins interface, you can see the `Translator` structure, which is used to support multiple languages. For example, the `ConfigField` structure has a `Title` field of type `Translator`. @@ -30,7 +30,7 @@ It's easy to build a `Translator` structure, just like this: ```go import ( - "github.com/apache/incubator-answer/plugin" + "github.com/apache/incubator-answer/plugin" ) plugin.MakeTranslator("plugin.github_connector.backend.name") @@ -40,7 +40,8 @@ The `plugin.github_connector.backend.name` is the key of the translation file, w So, the first step is build a `Translator` structure for each field that needs to be translated. -## Translation File +## Translation file + Make directory `i18n` in the root directory of your plugin, and then create a file named `en_US.yaml` in it. The `en_US.yaml` file is used to store the English translation of the plugin. @@ -88,13 +89,13 @@ Create a `i18n.go` file in the root directory of your plugin, and then add the f package i18n const ( - ConnectorName = "plugin.github_connector.backend.name" - InfoName = "plugin.github_connector.backend.info.name" - InfoDescription = "plugin.github_connector.backend.info.description" - ConfigClientIDTitle = "plugin.github_connector.backend.config.client_id.title" - ConfigClientIDDescription = "plugin.github_connector.backend.config.client_id.description" - ConfigClientSecretTitle = "plugin.github_connector.backend.config.client_secret.title" - ConfigClientSecretDescription = "plugin.github_connector.backend.config.client_secret.description" + ConnectorName = "plugin.github_connector.backend.name" + InfoName = "plugin.github_connector.backend.info.name" + InfoDescription = "plugin.github_connector.backend.info.description" + ConfigClientIDTitle = "plugin.github_connector.backend.config.client_id.title" + ConfigClientIDDescription = "plugin.github_connector.backend.config.client_id.description" + ConfigClientSecretTitle = "plugin.github_connector.backend.config.client_secret.title" + ConfigClientSecretDescription = "plugin.github_connector.backend.config.client_secret.description" ) ``` @@ -114,11 +115,14 @@ Finally, the directory structure of the plugin is as follows: └── zh_CN.yaml ``` -## Backend Translation -You just need to return `Translator` structure with the key of the translation file. +## Backend translation + +You just need to return `Translator` structure with the key of the translation file. + ```go func (g *GitHubConnector) ConnectorName() plugin.Translator { - return plugin.MakeTranslator(i18n.ConnectorName) + return plugin.MakeTranslator(i18n.ConnectorName) } ``` + The `Answer` will automatically translate the key of the translation file into the corresponding language. diff --git a/docs/development/extending/plugins.md b/docs/development/plugins.md similarity index 65% rename from docs/development/extending/plugins.md rename to docs/development/plugins.md index 5c729cad..d3c5241d 100644 --- a/docs/development/extending/plugins.md +++ b/docs/development/plugins.md @@ -3,6 +3,7 @@ slug: /plugins --- # Plugins + :::tip When we need to do some extensions to Answer's functionality, for example, OAuth login, we design a way to use plugins to implement these functions. @@ -10,36 +11,42 @@ When we need to do some extensions to Answer's functionality, for example, OAuth ::: ## Introduction -### Official Plugins + +### Official plugins + You can find a list of officially supported plugins for Answer [here](https://github.com/apache/incubator-answer-plugins). -### 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 type -- Connector: The Connector plugin helps us to implement third-party login functionality. e.g. `GitHub OAuth Login` -- Storage: The Storage plugin helps us to upload files to third-party storage. (preview) -- Cache: Support for using different caching middleware. e.g. `Redis` (preview) -- Filter: Filter out illegal questions or answers. (coming soon) -- Render: Parsers for different content formats. (coming soon) -- Finder: Support for using search engines to speed up the search for question answers. (coming soon) +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. + +- **Connector**: The Connector plugin helps us to implement third-party login functionality. e.g. `GitHub OAuth Login` +- **Storage**: The Storage plugin helps us to upload files to third-party storage. (preview) +- **Cache**: Support for using different caching middleware. e.g. `Redis` (preview) +- **Filter**: Filter out illegal questions or answers. (coming soon) +- **Render**: Parsers for different content formats. (coming soon) +- **Finder**: Support for using search engines to speed up the search for question answers. (coming soon) ## Build -> Answer binary supports packaging different required plugins into the binary. + +Answer binary supports packaging different required plugins into the binary. ### Prerequisites + - Original Answer binary - [Golang](https://go.dev/) `>=1.18` - [Node.js](https://nodejs.org/) `>=16.17` - [pnpm](https://pnpm.io/) `>=7` ### Command + :::tip + We use the `build` command provided with the Answer binary to rebuild a version of Answer with the plugin. + ::: -> For example, let's see how to build an Answer binary that includes the github third-party login plugin +For example, let's see how to build an Answer binary that includes the github third-party login plugin. ```shell # answer build --with [plugin@plugin_version=[replacement]] --output [file] @@ -61,7 +68,9 @@ $ CGO_ENABLED=0 GOOS=linux GOARCH=amd64 ./answer build --with github.com/apache/ ``` :::tip + You can use the `plugin` command to list the current binary containing plugins. + ::: ```shell @@ -73,25 +82,31 @@ $ ./new_answer plugin ``` ## Third-party plugin + :::tip + We recommend the use of [official plugins](https://github.com/apache/incubator-answer-plugins), if you want to use third-party plugins, refer to the following. + ::: - If the third-party plugin is publicly available, you can build with it like official plugins. - If the third-party plugin is private, you need to download it then build with. -## Use -> The answer with the plug-in version is used in the same way as before. -> You can find the plugin's configuration in the admin page. +## Usage + +The answer with the plug-in version is used in the same way as before. +You can find the plugin's configuration in the admin page.  ## Upgrade + You just need to recompile and use the latest version of the plugin. -## Develop and Contributing +## Develop and contributing + Please refer to [the documentation](/community/plugins) for details. -## Design & Principle -Since Golang is a static language, there is no friendly plugin mechanism. So instead of a dynamic approach, we use recompilation for deployment. -Please refer to [the blog](/blog/2023/07/22/why-the-answer-plugin-system-was-designed-this-way) for details. +## Design & principle + +Since Golang is a static language, there is no friendly plugin mechanism. So instead of a dynamic approach, we use recompilation for deployment. Please refer to [the blog](/blog/2023/07/22/why-the-answer-plugin-system-was-designed-this-way) for details. diff --git a/sidebars.js b/sidebars.js index 6c05fe99..30c991c9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -44,7 +44,7 @@ module.exports = { 'guides/settings', ], }, - 'development/extending/plugins', + 'development/plugins', 'notice', 'faq', ],
