docs: rewrite extension development documentation (#455)

halo-dev · Oct 31, 2024 · eac3f93 · eac3f93
1 parent 97f7aba
commit eac3f93
Show file tree

Hide file tree

Showing 10 changed files with 1,070 additions and 300 deletions.
diff --git a/docs/developer-guide/annotations-form.md b/docs/developer-guide/annotations-form.md
@@ -36,7 +36,7 @@ spec:
 
 字段说明：
 
-1. `metadata.name`：唯一标识，命名规范可参考 [metadata name](./plugin/api-reference/server/extension.md#metadata-name)，为了尽可能避免冲突，建议自定义前缀以及追加随机字符串，如：`theme-earth-post-wanfs5`。
+1. `metadata.name`：唯一标识，命名规范可参考 [metadata name](./plugin/api-reference/server/extension.md#naming-spec-for-metadata-name)，为了尽可能避免冲突，建议自定义前缀以及追加随机字符串，如：`theme-earth-post-wanfs5`。
 2. `spec.targetRef`：模型的关联，即为哪个模型添加元数据表单，目前支持的模型可查看下方的列表。
 3. `spec.formSchema`：表单的定义，使用 FormKit Schema 来定义。虽然我们使用的 YAML，但与 FormKit Schema 完全一致。
 

diff --git a/docs/developer-guide/plugin/api-reference/server/extension-client.md b/docs/developer-guide/plugin/api-reference/server/extension-client.md
@@ -100,7 +100,7 @@ public PersonService {
 
 我们建议你更多的使用响应式的 `ReactiveExtensionClient` 去替代 `ExtensionClient`。
 
-### 查询
+### 查询 {#query}
 
 `ReactiveExtensionClient` 提供了两个方法用于查询数据，`listBy` 和 `listAll`。
 

diff --git a/docs/developer-guide/plugin/api-reference/server/extension.md b/docs/developer-guide/plugin/api-reference/server/extension.md
diff --git a/docs/developer-guide/plugin/basics/devtools.md b/docs/developer-guide/plugin/basics/devtools.md
@@ -215,7 +215,7 @@ API client 是一种工具或库，旨在简化前端应用程序与后端服务
 
 - 提高开发效率：通过使用 API 客户端，开发者可以专注于业务逻辑的实现，而不用关心底层的 HTTP 细节。这不仅提高了开发效率，还减少了代码冗余。
 
-#### 如何生成 API client
+#### 如何生成 API client {#how-to-generate-api-client}
 
 本插件提供了一个 `generateApiClient` 任务，用于为插件项目生成 API client，生成规则基于 OpenAPI 规范来自动生成客户端代码。
 

diff --git a/docs/developer-guide/plugin/security/role-template.md b/docs/developer-guide/plugin/security/role-template.md
@@ -131,7 +131,7 @@ rules:
 
 1. 定义了一个用于管理 Person 自定义模型对象的角色模板 `my-plugin-role-manage-persons`，它具有所有权限。
 2. 定义了一个只允许查询 Person 资源的角色模板 `my-plugin-role-view-persons`。
-3. `metadata.name` 的命名规则参考 [metadata name 命名规范](../api-reference/server/extension.md#metadata-name)。
+3. `metadata.name` 的命名规则参考 [metadata name 命名规范](../api-reference/server/extension.md#naming-spec-for-metadata-name)。
 
 下面让我们回顾一下这些配置：
 

diff --git a/versioned_docs/version-2.20/developer-guide/annotations-form.md b/versioned_docs/version-2.20/developer-guide/annotations-form.md
@@ -36,7 +36,7 @@ spec:
 
 字段说明：
 
-1. `metadata.name`：唯一标识，命名规范可参考 [metadata name](./plugin/api-reference/server/extension.md#metadata-name)，为了尽可能避免冲突，建议自定义前缀以及追加随机字符串，如：`theme-earth-post-wanfs5`。
+1. `metadata.name`：唯一标识，命名规范可参考 [metadata name](./plugin/api-reference/server/extension.md#naming-spec-for-metadata-name，为了尽可能避免冲突，建议自定义前缀以及追加随机字符串，如：`theme-earth-post-wanfs5`。
 2. `spec.targetRef`：模型的关联，即为哪个模型添加元数据表单，目前支持的模型可查看下方的列表。
 3. `spec.formSchema`：表单的定义，使用 FormKit Schema 来定义。虽然我们使用的 YAML，但与 FormKit Schema 完全一致。
 

diff --git a/...cs/version-2.20/developer-guide/plugin/api-reference/server/extension-client.md b/...cs/version-2.20/developer-guide/plugin/api-reference/server/extension-client.md
@@ -100,7 +100,7 @@ public PersonService {
 
 我们建议你更多的使用响应式的 `ReactiveExtensionClient` 去替代 `ExtensionClient`。
 
-### 查询
+### 查询 {#query}
 
 `ReactiveExtensionClient` 提供了两个方法用于查询数据，`listBy` 和 `listAll`。
 

diff --git a/...oned_docs/version-2.20/developer-guide/plugin/api-reference/server/extension.md b/...oned_docs/version-2.20/developer-guide/plugin/api-reference/server/extension.md
diff --git a/versioned_docs/version-2.20/developer-guide/plugin/basics/devtools.md b/versioned_docs/version-2.20/developer-guide/plugin/basics/devtools.md
@@ -34,11 +34,11 @@ plugins {
 
 ```shell
 =======================================================================
-> Halo 启动成功！                                                      
-访问地址：http://localhost:8090/console?language=zh-CN                 
-用户名：admin                                                          
-密码：admin                                                            
-API 文档：http://localhost:8090/swagger-ui.html                        
+> Halo 启动成功！
+访问地址：http://localhost:8090/console?language=zh-CN
+用户名：admin
+密码：admin
+API 文档：http://localhost:8090/swagger-ui.html
 插件开发文档：https://docs.halo.run/developer-guide/plugin/introduction
 =======================================================================
 ```
@@ -117,8 +117,8 @@ halo {
 ```yaml
 # workplace/config/application.yaml
 logging:
-    level:
-        run.halo.app: DEBUG
+  level:
+    run.halo.app: DEBUG
 ```
 
 更多配置项请参考 [Halo 配置列表](../../../getting-started/install/config.md#配置列表)。
@@ -215,7 +215,7 @@ API client 是一种工具或库，旨在简化前端应用程序与后端服务
 
 - 提高开发效率：通过使用 API 客户端，开发者可以专注于业务逻辑的实现，而不用关心底层的 HTTP 细节。这不仅提高了开发效率，还减少了代码冗余。
 
-#### 如何生成 API client
+#### 如何生成 API client {#how-to-generate-api-client}
 
 本插件提供了一个 `generateApiClient` 任务，用于为插件项目生成 API client，生成规则基于 OpenAPI 规范来自动生成客户端代码。
 
@@ -421,5 +421,5 @@ halo {
 
 ```shell
 # 如将 Gradle 版本升级至 8.9
-./gradlew wrapper --gradle-version=8.9 
+./gradlew wrapper --gradle-version=8.9
 ```
diff --git a/versioned_docs/version-2.20/developer-guide/plugin/security/role-template.md b/versioned_docs/version-2.20/developer-guide/plugin/security/role-template.md
@@ -131,7 +131,7 @@ rules:
 
 1. 定义了一个用于管理 Person 自定义模型对象的角色模板 `my-plugin-role-manage-persons`，它具有所有权限。
 2. 定义了一个只允许查询 Person 资源的角色模板 `my-plugin-role-view-persons`。
-3. `metadata.name` 的命名规则参考 [metadata name 命名规范](../api-reference/server/extension.md#metadata-name)。
+3. `metadata.name` 的命名规则参考 [metadata name 命名规范](../api-reference/server/extension.md#naming-spec-for-metadata-name)。
 
 下面让我们回顾一下这些配置：