chore: update docs with comments in bug bash

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.1.98 (October 28, 2022)
+
+- chore: update "how-to/deploy" docs
+- chore: update "reference/blocklet-actions" docs
+- fix: correct links "Blocklet UI"
+- fix: `./blocklet/bundle` -> `.blocklet/bundle`
+
 ## 0.1.97 (October 28, 2022)
 
 - docs: update blocklet.yml: requirements

developer/docs/blocklet.yml

@@ -14,7 +14,7 @@ repository:
   type: git
   url: git+https://github.com/blocklet/blocklet-site.git
 specVersion: 1.2.7
-version: 0.1.97
+version: 0.1.98
 logo: logo.png
 files:
   - hooks/post-start.js

developer/docs/pages/how-to/auth/index.md

@@ -71,7 +71,7 @@ export default function App() {
 }
 ```
 
-More: [Blocklet UI](/development/blocklet-ui-usage)
+More: [Blocklet UI](/reference/blocklet-ui)
 
 ### Use default login page
 

developer/docs/pages/how-to/auth/index.zh.md

@@ -71,7 +71,7 @@ export default function App() {
 }
 ```
 
-更多：[Blocklet UI](/development/blocklet-ui-usage)
+更多：[Blocklet UI](/reference/blocklet-ui)
 
 ### 使用默认的登录页
 

developer/docs/pages/how-to/deploy/index.md

@@ -4,40 +4,42 @@ description: Deploy blocklet directly to the server
 layout: documentation
 ---
 
-如果你是 blocklet 的开发者，或者你有 blocklet 的 release bundle, 你可以将 blocklet 直接部署到你的 Blocklet Server 中
+Before you can deploy, you need to make sure you have a release bundle file that can be used for deployment. Generally, release bundle files can be obtained by bundle from the project's source code, see here: [Bundle](/how-to/bundle), or someone else can share the release bundle with you.
 
-## 将 Blocklet 部署到 Blocklet Server
+With the release bundle file in place, you can deploy the blocklet directly to your Blocklet Server
+
+## Deploy your blocklet to Blocklet Server
 
 ### STEP 1
 
-在你的 Blocklet Server 创建 Access Key
+Create Access Key in your Blocklet Server
 
 ![](./access-key.png)
 
 ### STEP 2
 
-执行 `blocklet deploy` 命令，将 blocklet 部署到 Blocklet Server
+Execute the `blocklet deploy` command to deploy the blocklet to the Blocklet Server
 
 ```bash
 blocklet deploy <blocklet-bundle-folder> --endpoint xxxxxx --access-key xxxxxx --access-secret xxxxxx
 ```
 
-- blocklet-bundle-folder: 使用 [blocklet bundle](/how-to/bundle) 构建后的目录，如果当前你在项目根目录，则是 `./blocklet/bundle`.
-- `--endpoint`: server 的地址，以 /admin 结尾。比如，你本地的 Blocklet Server 的地址是 `http://127.0.0.1/admin`
-- `--access-key`: 第一步创建的 Access Key
-- `--access-secret`: 第一步创建的 Access Secret
+- blocklet-bundle-folder: The directory after building with [blocklet bundle](/how-to/bundle), or if you are currently in the root of the project, the value is `.blocklet/bundle`.
+- `--endpoint`: The address of the server, ending with /admin. For example, the address of your local Blocklet Server is `http://127.0.0.1/admin`
+- `--access-key`: The Access Key created in the first step
+- `--access-secret`: Access Secret created in the first step
 
-## 将 Blocklet 部署到本机的 Blocklet Server
+## Deploy your blocklet to local Blocklet Server
 
-如果你想将 Blocklet 部署到本机的 Blocklet Server, 则可以直接执行 `blocklet deploy <blocklet-bundle-folder>`
+If you want to deploy the Blocklet to the local Blocklet Server, you can directly execute `blocklet deploy <blocklet-bundle-folder>`
 
-## 将 Component 部署到 Blocklet Server
+## Deploy component blocklet to Blocklet Server
 
-部署 Component 到 Blocklet Server 与部署 Blocklet 的命令相同，你需要添加额外的参数
+Deploying a component blocklet to Blocklet Server is the same command as deploying a Blocklet, but you need to add additional parameters
 
 ```
 blocklet deploy <blocklet-bundle-folder> --endpoint xxxxxx --access-key xxxxxx --access-secret xxxxxx --app-id <blocklet-app-id> --mount-point /xxx`
 ```
 
-- `--app-id`: 应用的 AppID, 可在 blocklet 详情页中查看
-- `--mount-point`: 组件的挂载点
+- `--app-id`: AppID of the application, available in the blocklet details page
+- `--mount-point`: Mount points for components

developer/docs/pages/how-to/deploy/index.zh.md

@@ -4,7 +4,9 @@ description: 部署应用到节点
 layout: documentation
 ---
 
-如果你是 blocklet 的开发者，或者你有 blocklet 的 release bundle, 你可以将 blocklet 直接部署到你的 Blocklet Server 中
+在进行部署操作前，你需要确保你拥有可用于部署的 release bundle 文件。通常来说 release bundle 文件可以通过从项目的源码中打包获得，打包步骤可以参考这里：[Bundle](/how-to/bundle)，也可以是其他人将已经打包好的 release bundle 分享给你。
+
+在拥有了 release bundle 文件后，你可以将 blocklet 直接部署到你的 Blocklet Server 中
 
 ## 将 Blocklet 部署到 Blocklet Server
 
@@ -22,7 +24,7 @@ layout: documentation
 blocklet deploy <blocklet-bundle-folder> --endpoint xxxxxx --access-key xxxxxx --access-secret xxxxxx
 ```
 
-- blocklet-bundle-folder: 使用 [blocklet bundle](/how-to/bundle) 构建后的目录，如果当前你在项目根目录，则是 `./blocklet/bundle`.
+- blocklet-bundle-folder: 使用 [blocklet bundle](/how-to/bundle) 构建后的目录，如果当前你在项目根目录，则是 `.blocklet/bundle`.
 - `--endpoint`: server 的地址，以 /admin 结尾。比如，你本地的 Blocklet Server 的地址是 `http://127.0.0.1/admin`
 - `--access-key`: 第一步创建的 Access Key
 - `--access-secret`: 第一步创建的 Access Secret

developer/docs/pages/reference/blocklet-actions/index.md

@@ -16,7 +16,7 @@ With action-workflow, we can quickly configure the flow in CI for each Blocklet
 
 First your project needs to create a `.github` folder to enable the [GitHub Actions](https://docs.github.com/en/actions) feature
 
-Then create a `workflows/main.yml` file in `.github` and configure some necessary initialization processes. Such as `git checkout`, `dependencies install`, etc.
+Then create a `workflows/main.yml` file in `.github` and configure some necessary initialization processes. Such as `git checkout`, `dependencies install`, etc. A full example can be found here: [Blocklet Site](https://github.com/blocklet/publish-kit/blob/master/.github/workflows/main.yml)
 
 Once everything is in place, add the following to access the Blocklet action-workflow functionality.
 
@@ -44,21 +44,125 @@ Once everything is in place, add the following to access the Blocklet action-wor
     github-token: xxxxx
 ```
 
+### Function Introduction
+
+Blocklet action-workflow consists of five major functions: environment preparation, project packaging, uploading to Blocklet Store, deploying to Blocklet Server, and releasing to Github Release.
+
+The following is a detailed description of action-workflow by function:
+
+#### Base configuration
+- `working-directory`: The directory where the Blocklet action-workflow is executed, often used in monorepo, where multiple Blocklet applications need to be packaged, uploaded and released at the same time, default is `. /`
+
+#### Environment Preparation
+
 - `skip-deps`: Whether to skip the blocklet-server environment preparation step, default is ``false`''
+
+#### Bundle
+
 - `skip-bundle`: Whether to skip the bundle step, default is ``false`''
-- `skip-upload`: Whether to skip uploading Blocklet applications to Blocklet Store, default is `true`.
-- `skip-deploy`: Whether to skip the step of deploying the Blocklet application to the specified Blocklet Server, default is `true`.
-- `skip-release`: Whether to skip the release Github Release step, default is `false`
-- `skip-readme`: Whether to skip the step of updating the `README.md` file, default is `false`
-- `working-directory`: The directory where the Blocklet action-workflow is executed, often used in monorepo, where multiple Blocklet applications need to be packaged, uploaded and released at the same time, default is `. /`
 - `bundle-command`: The command to package Blocklet applications, usually `npm run bundle`, if `skip-bundle` is not `true`, then this item is required
+
+#### Upload to Blocklet Store
+- `skip-upload`: Whether to skip uploading Blocklet applications to Blocklet Store, default is `true`.
 - `store-endpoint`: The URL of the Blocklet Store, you can freely configure which Blocklet Store you need to upload the application to, if `skip-upload` is not `true`, then this item is required
 - `store-access-token`: The key applied in Blocklet Store, you need to register as the developer of the corresponding Blocklet Store first, then apply for an upload key, if `skip-upload` is not `true`, then this item is required. For more details, please refer to: [Blocklet Store](https://store.blocklet.dev/docs)
 - `store-developer-did`: The developer ID of the developer in the corresponding Blocklet Store, this item is required when you need to upload a paid Blocklet. For more details, please refer to: [Blocklet Store](https://store.blocklet.dev/docs)
+
+#### Deploy to Blocklet Server
+- `skip-deploy`: Whether to skip the step of deploying the Blocklet application to the specified Blocklet Server, default is `true`.
 - `server-endpoint`: The address of the Blocklet Server to be deployed, if `skip-deploy` is not empty. For more details, please refer to: [Blocklet Deploy](/reference/blocklet-cli#deploy)
 - `server-access-key`: Access Key created in Blocklet Server, if `skip-deploy` is not empty. For more details, please refer to: [Blocklet Deploy](/reference/blocklet-cli#deploy)
 - `server-access-secret`: The Access Secret `skip-deploy` created in Blocklet Server is not empty. For more details, please refer to: [Blocklet Deploy](/reference/blocklet-cli#deploy)
 - `deploy-app-did`: Under which Blocklet application the current application will be deployed (become its sub-component), if you need to deploy the application as a sub-component, you need to fill in this item. For more details, please refer to: [Blocklet Deploy](/reference/blocklet-cli#deploy)
 - `deploy-mount-point`: The path where the application is mounted when it is deployed as a subcomponent, if you need to deploy the application as a subcomponent, you need to fill in this item. For more details, please refer to: [Blocklet Deploy](/reference/blocklet-cli#deploy)
 - `slack-webhook`: Configure a slack webhook to send a slack notification when the Blocklet application is successfully deployed.
+
+#### Release to Github Release
+- `skip-release`: Whether to skip the release Github Release step, default is `false`
+- `skip-readme`: Whether to skip the step of updating the `README.md` file, default is `false`
 - `github-token`: Configure a `token` with `write` permissions that will be used to update the project's `README.md` file in CI
+
+
+### Usage Scenarios
+The following is a description of how action-workflow can be combined in each scenario
+#### Upload blocklet to Blocklet Store
+After completing the development of the application, you want to be able to publish the latest code to the Blocklet Store every time, this time you need to use the `Environment Preparation`, `Bundle`, `Upload to Blocklet Store` steps, refer to the following code:
+```yaml
+- name: Upload to Blocklet Store
+  uses: blocklet/action-workflow@v1
+  with:
+    skip-deps: false
+    skip-bundle: false
+    skip-upload: false
+    skip-deploy: true
+    skip-release: true
+    skip-readme: true
+    bundle-command: npm run bundle
+    store-endpoint: ${{ secrets.STORE_ENDPOINT }}
+    store-access-token: ${{ secrets.STORE_ACCESS_TOKEN }}
+    store-developer-did: ${{ secrets.STORE_DEVELOPER_DID }}
+```
+
+#### Deploy blocklet to Blocklet Server
+In some cases, you do not want to publish the application to the Blocklet Store, but deploy it directly to a specified Blocklet Server, you need to use the `Environment Preparation`, `Bundle`, `Deploy to Blocklet Server` steps, refer to the following code:
+```yaml
+- name: Deploy to Blocklet Server
+  uses: blocklet/action-workflow@v1
+  with:
+    skip-deps: false
+    skip-bundle: false
+    skip-upload: true
+    skip-deploy: false
+    skip-release: true
+    skip-readme: true
+    bundle-command: npm run bundle
+    server-endpoint: ${{ secrets.XMARK_NODE_ENDPOINT }}
+    server-access-key: ${{ secrets.XMARK_NODE_ACCESS_KEY }}
+    server-access-secret: ${{ secrets.XMARK_NODE_ACCESS_SECRET }}
+    slack-webhook: xxxxxx
+```
+
+If the application needs to be deployed as a component blocklet of another blocklet, it can be configured by adding the following parameters:
+```yaml
+deploy-app-did: xxxxxx
+deploy-mount-point: xxxxxx
+```
+
+#### Release to Github Release
+In some cases, you want to package the current application for an archive, and then install and run it in the future through Blocklet Server, you need to use the `Environment Preparation`, `Bundle`, `Release to Github Release` steps, refer to the following code.
+```yaml
+- name: Release to Github Release
+  uses: blocklet/action-workflow@v1
+  with:
+    skip-deps: false
+    skip-bundle: false
+    skip-upload: true
+    skip-deploy: true
+    skip-release: false
+    skip-readme: true
+    bundle-command: npm run bundle
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+#### Other situations
+The above three cases describe three common scenarios, sometimes you need to combine the above three scenarios to meet the use of more cases. For example, if you need to publish to Blocklet Store and deploy to Blocklet Server at the same time, you can combine the above described configuration by referring to the following code:
+
+```yaml
+- name: Upload to Blocklet Store & Deploy to Blocklet Store
+  uses: blocklet/action-workflow@v1
+  with:
+    skip-deps: false
+    skip-bundle: false
+    skip-upload: false
+    skip-deploy: false
+    skip-release: true
+    skip-readme: true
+    bundle-command: npm run bundle
+    store-endpoint: ${{ secrets.STORE_ENDPOINT }}
+    store-access-token: ${{ secrets.STORE_ACCESS_TOKEN }}
+    store-developer-did: ${{ secrets.STORE_DEVELOPER_DID }}
+    server-endpoint: ${{ secrets.XMARK_NODE_ENDPOINT }}
+    server-access-key: ${{ secrets.XMARK_NODE_ACCESS_KEY }}
+    server-access-secret: ${{ secrets.XMARK_NODE_ACCESS_SECRET }}
+    slack-webhook: xxxxxx
+```