halo-dev · f2c-ci-robot · Oct 28, 2024 · Oct 28, 2024 · Oct 28, 2024
diff --git a/docs/developer-guide/theme/config.md b/docs/developer-guide/theme/config.md
@@ -62,9 +62,9 @@ spec:
 | `spec.issues`                   | 主题问题反馈地址，如果你的主题是开源在 GitHub 上，可以直接配置为 GitHub Issues 地址。            | 否       |
 | `spec.settingName`              | 设置表单定义的名称，需要同时创建对应的 `settings.yaml` 文件                                    | 否       |
 | `spec.configMapName`            | 设置持久化配置的 ConfigMap 名称                                                               | 否       |
-| `spec.customTemplates.post`     | 文章的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates)     | 否       |
-| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates)     | 否       |
-| `spec.customTemplates.page`     | 独立页面的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否       |
+| `spec.customTemplates.post`     | 文章的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md)     | 否       |
+| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md)     | 否       |
+| `spec.customTemplates.page`     | 独立页面的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否       |
 | `spec.version`                  | 主题版本                                                                                      | 是       |
 | `spec.requires`                 | 所需 Halo 的运行版本                                                                          | 是       |
 | `spec.license`                  | 协议                                                                                          | 否       |

diff --git a/docs/developer-guide/theme/structure.md b/docs/developer-guide/theme/structure.md
@@ -27,7 +27,7 @@ my-theme
 
 详细说明：
 
-1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板路由](./template-route-mapping)。
+1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板编写](./template-variables.md)。
 2. `/templates/assets/` - 主题静态资源目录，存放主题的静态资源文件，目前静态资源文件只能放在这个目录，引用方式请查阅 [静态资源](./static-resources)。
 3. `/theme.yaml` - 主题配置文件，配置主题的基本信息，如主题名称、版本、作者等。详细文档请查阅 [配置文件](./config)。
 4. `/settings.yaml` - 主题设置定义文件，配置主题的设置项表单。详细文档请查阅 [设置选项](./settings)。
diff --git a/docs/developer-guide/theme/template-variables.md b/docs/developer-guide/theme/template-variables.md
@@ -1,7 +1,11 @@
 ---
-title: 模板变量
+title: 模板编写
 ---
 
+此章节我们将详细介绍如何在主题中编写页面的模板，以下是 Halo 核心中支持的所有模板：
+
+```mdx-code-block
 import DocCardList from '@theme/DocCardList';
 
 <DocCardList />
+```
diff --git a/docs/developer-guide/theme/template-variables/archives.md b/docs/developer-guide/theme/template-variables/archives.md
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md";
 import ContributorVo from "../vo/_ContributorVo.md";
 import ListedPostVo from "../vo/_ListedPostVo.md";
 
+文章归档页面，用于列出网站的所有文章，如果你编写的主题首页不显示文章列表，那么可以利用这个模板为网站单独提供一个查看文章列表的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/archives.html`

diff --git a/docs/developer-guide/theme/template-variables/author.md b/docs/developer-guide/theme/template-variables/author.md
@@ -9,6 +9,8 @@ import TagVo from "../vo/_TagVo.md"
 import ContributorVo from "../vo/_ContributorVo.md"
 import ListedPostVo from "../vo/_ListedPostVo.md"
 
+根据作者列出所有文章的页面，如果你的主题偏向于社区类型，那么可以添加一个这样的模板，用于提供作者的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/author.html`

diff --git a/docs/developer-guide/theme/template-variables/categories.md b/docs/developer-guide/theme/template-variables/categories.md
@@ -5,6 +5,8 @@ description: categories.html - /categories
 
 import CategoryTreeVo from "../vo/_CategoryTreeVo.md"
 
+用于列出所有文章分类的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/categories.html`

diff --git a/docs/developer-guide/theme/template-variables/category.md b/docs/developer-guide/theme/template-variables/category.md
@@ -8,11 +8,52 @@ import TagVo from "../vo/_TagVo.md"
 import ContributorVo from "../vo/_ContributorVo.md";
 import ListedPostVo from "../vo/_ListedPostVo.md"
 
+用于根据分类列出所有文章的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/category.html`
 - 访问路径：`/categories/:slug`
 
+### 自定义模板
+
+除了上面提到的 `category.html`，主题作者还可以添加多种形式的额外渲染模板，提供给用户选择，可以通过这个功能实现将网站上的文章内容进行领域划分，比如网站上同时存在新闻、文档、博客等分区，那么就可以利用这个功能提供多个模板，同时 Halo 还支持为分类设置文章渲染模板，详情可见[新建文章分类](../../../user-guide/posts.md#新建文章分类)。
+
+定义方式为：
+
+```yaml title="theme.yaml"
+customTemplates:
+  category:
+    - name: {name}
+      description: {description}
+      screenshot: {screenshot}
+      file: {file}.html
+```
+
+- `name`：模板名称
+- `description`：模板描述
+- `screenshot`：模板预览图
+- `file`：模板文件名，需要在 `/templates/` 目录下创建
+
+示例：
+
+```yaml title="theme.yaml"
+customTemplates:
+  category:
+    - name: 新闻
+      description: 用于展示新闻分类下的文章
+      screenshot: 
+      file: category_news.html
+    - name: 博客
+      description: 用于展示博客分类下的文章
+      screenshot: 
+      file: category_blog.html
+```
+
+:::info
+需要注意，修改 theme.yaml 需要[重载主题配置](../../../user-guide/themes.md#重载主题配置)。
+:::
+
 ## 变量
 
 ### category

diff --git a/docs/developer-guide/theme/template-variables/index_.md b/docs/developer-guide/theme/template-variables/index_.md
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md"
 import ContributorVo from "../vo/_ContributorVo.md";
 import ListedPostVo from "../vo/_ListedPostVo.md"
 
+网站的首页模板，在这个模板中默认设置了最新文章列表的变量，也可以通过调用 [Finder API](../finder-apis.md) 和 [主题设置](../settings.md) 来展示其他数据。
+
 ## 路由信息
 
 - 模板路径：`/templates/index.html`

diff --git a/docs/developer-guide/theme/template-variables/page.md b/docs/developer-guide/theme/template-variables/page.md
@@ -1,17 +1,54 @@
 ---
-title: 独立页面
+title: 单页面
 description: page.html - /:slug
 ---
 
 import SinglePageVo from "../vo/_SinglePageVo.md"
 import ContributorVo from "../vo/_ContributorVo.md"
 import ContentVo from "../vo/_ContentVo.md"
 
+页面与文章类似，同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息，一般用于站点中单一展示功能的页面，例如常见的站点关于页面、联系我们页面等。
+
 ## 路由信息
 
 - 模板路径：`/templates/page.html`
 - 访问路径：`/:slug`
 
+### 自定义模板
+
+除了上面提到的 `page.html`，主题作者还可以添加多种形式的额外渲染模板，提供给用户选择，此举可以丰富网站的使用类型。
+
+定义方式为：
+
+```yaml title="theme.yaml"
+customTemplates:
+  page:
+    - name: {name}
+      description: {description}
+      screenshot: {screenshot}
+      file: {file}.html
+```
+
+- `name`：模板名称
+- `description`：模板描述
+- `screenshot`：模板预览图
+- `file`：模板文件名，需要在 `/templates/` 目录下创建
+
+示例：
+
+```yaml title="theme.yaml"
+customTemplates:
+  page:
+    - name: 关于公司
+      description: 用于展示公司的一些信息
+      screenshot: 
+      file: page_about.html
+```
+
+:::info
+需要注意，修改 theme.yaml 需要[重载主题配置](../../../user-guide/themes.md#重载主题配置)。
+:::
+
 ## 变量
 
 ### singlePage

diff --git a/docs/developer-guide/theme/template-variables/post.md b/docs/developer-guide/theme/template-variables/post.md
@@ -9,10 +9,47 @@ import ContentVo from "../vo/_ContentVo.md"
 import ContributorVo from "../vo/_ContributorVo.md"
 import PostVo from "../vo/_PostVo.md"
 
+文章详情页面的模板。
+
 ## 路由信息
 
 - 模板路径：`/templates/post.html`
-- 访问路径：`/archives/:slug`
+- 访问路径：默认为 `/archives/:slug`，用户可手动更改为其他路由形式，可参考：[主题路由设置](../../../user-guide/settings.md#主题路由设置)
+
+### 自定义模板
+
+除了上面提到的 `post.html`，主题作者还可以添加多种形式的额外渲染模板，提供给用户选择，此举可以丰富网站的使用类型，用户设置方式可参考 [文章设置](../../../user-guide/posts.md#文章设置)。
+
+定义方式为：
+
+```yaml title="theme.yaml"
+customTemplates:
+  post:
+    - name: {name}
+      description: {description}
+      screenshot: {screenshot}
+      file: {file}.html
+```
+
+- `name`：模板名称
+- `description`：模板描述
+- `screenshot`：模板预览图
+- `file`：模板文件名，需要在 `/templates/` 目录下创建
+
+示例：
+
+```yaml title="theme.yaml"
+customTemplates:
+  post:
+    - name: 文档
+      description: 文档类型的文章
+      screenshot: 
+      file: post_documentation.html
+```
+
+:::info
+需要注意，修改 theme.yaml 需要[重载主题配置](../../../user-guide/themes.md#重载主题配置)。
+:::
 
 ## 变量
 
@@ -59,7 +96,17 @@ import PostVo from "../vo/_PostVo.md"
 
 <PostVo />
 
-- [#CategoryVo](#categoryvo)
-- [#TagVo](#tagvo)
-- [#ContributorVo](#contributorvo)
-- [#ContentVo](#contentvo)
+- [路由信息](#路由信息)
+  - [自定义模板](#自定义模板)
+- [变量](#变量)
+  - [post](#post)
+    - [变量类型](#变量类型)
+    - [示例](#示例)
+  - [\_templateId](#_templateid)
+    - [变量值](#变量值)
+- [类型定义](#类型定义)
+  - [CategoryVo](#categoryvo)
+  - [TagVo](#tagvo)
+  - [ContributorVo](#contributorvo)
+  - [ContentVo](#contentvo)
+  - [PostVo](#postvo)
diff --git a/docs/developer-guide/theme/template-variables/tag.md b/docs/developer-guide/theme/template-variables/tag.md
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md"
 import ContributorVo from "../vo/_ContributorVo.md";
 import ListedPostVo from "../vo/_ListedPostVo.md"
 
+用于根据标签列出所有文章的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/tag.html`

diff --git a/docs/developer-guide/theme/template-variables/tags.md b/docs/developer-guide/theme/template-variables/tags.md
@@ -5,6 +5,8 @@ description: tags.html - /tags
 
 import TagVo from '../vo/_TagVo.md'
 
+用于列出所有文章标签的页面，可以用于实现标签墙等功能。
+
 ## 路由信息
 
 - 模板路径：`/templates/tags.html`

diff --git a/docs/developer-guide/theme/vo/_ThemeVo.md b/docs/developer-guide/theme/vo/_ThemeVo.md
@@ -32,5 +32,5 @@
 
 其中：
 
-1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板路由#自定义模板](../template-route-mapping.md#custom-templates)
+1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板编写](../template-variables.md))
 2. `config`：主题配置，使用文档请参考：[设置选项](../settings.md)
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -189,7 +189,7 @@ const config = {
       prism: {
         theme: darkCodeTheme,
         darkTheme: darkCodeTheme,
-        additionalLanguages: ["java","sql"],
+        additionalLanguages: ["java", "json", "sql"],
       },
       zoom: {
         selector: ".markdown :not(a) > img",

diff --git a/sidebars.js b/sidebars.js
@@ -320,13 +320,12 @@ module.exports = {
         "developer-guide/theme/prepare",
         "developer-guide/theme/config",
         "developer-guide/theme/structure",
-        "developer-guide/theme/template-route-mapping",
         "developer-guide/theme/static-resources",
         "developer-guide/theme/settings",
         "developer-guide/theme/annotations",
         {
           type: "category",
-          label: "模板变量",
+          label: "模板编写",
           link: {
             type: "doc",
             id: "developer-guide/theme/template-variables",

diff --git a/versioned_docs/version-2.20/developer-guide/theme/config.md b/versioned_docs/version-2.20/developer-guide/theme/config.md
@@ -62,9 +62,9 @@ spec:
 | `spec.issues`                   | 主题问题反馈地址，如果你的主题是开源在 GitHub 上，可以直接配置为 GitHub Issues 地址。            | 否       |
 | `spec.settingName`              | 设置表单定义的名称，需要同时创建对应的 `settings.yaml` 文件                                    | 否       |
 | `spec.configMapName`            | 设置持久化配置的 ConfigMap 名称                                                               | 否       |
-| `spec.customTemplates.post`     | 文章的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates)     | 否       |
-| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates)     | 否       |
-| `spec.customTemplates.page`     | 独立页面的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否       |
+| `spec.customTemplates.post`     | 文章的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md)     | 否       |
+| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md)     | 否       |
+| `spec.customTemplates.page`     | 独立页面的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否       |
 | `spec.version`                  | 主题版本                                                                                      | 是       |
 | `spec.requires`                 | 所需 Halo 的运行版本                                                                          | 是       |
 | `spec.license`                  | 协议                                                                                          | 否       |

diff --git a/versioned_docs/version-2.20/developer-guide/theme/structure.md b/versioned_docs/version-2.20/developer-guide/theme/structure.md
@@ -27,7 +27,7 @@ my-theme
 
 详细说明：
 
-1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板路由](./template-route-mapping)。
+1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板编写](./template-variables.md)。
 2. `/templates/assets/` - 主题静态资源目录，存放主题的静态资源文件，目前静态资源文件只能放在这个目录，引用方式请查阅 [静态资源](./static-resources)。
 3. `/theme.yaml` - 主题配置文件，配置主题的基本信息，如主题名称、版本、作者等。详细文档请查阅 [配置文件](./config)。
 4. `/settings.yaml` - 主题设置定义文件，配置主题的设置项表单。详细文档请查阅 [设置选项](./settings)。
diff --git a/versioned_docs/version-2.20/developer-guide/theme/template-variables.md b/versioned_docs/version-2.20/developer-guide/theme/template-variables.md
@@ -1,7 +1,11 @@
 ---
-title: 模板变量
+title: 模板编写
 ---
 
+此章节我们将详细介绍如何在主题中编写页面的模板，以下是 Halo 核心中支持的所有模板：
+
+```mdx-code-block
 import DocCardList from '@theme/DocCardList';
 
 <DocCardList />
+```
diff --git a/versioned_docs/version-2.20/developer-guide/theme/template-variables/archives.md b/versioned_docs/version-2.20/developer-guide/theme/template-variables/archives.md
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md";
 import ContributorVo from "../vo/_ContributorVo.md";
 import ListedPostVo from "../vo/_ListedPostVo.md";
 
+文章归档页面，用于列出网站的所有文章，如果你编写的主题首页不显示文章列表，那么可以利用这个模板为网站单独提供一个查看文章列表的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/archives.html`

diff --git a/versioned_docs/version-2.20/developer-guide/theme/template-variables/author.md b/versioned_docs/version-2.20/developer-guide/theme/template-variables/author.md
@@ -9,6 +9,8 @@ import TagVo from "../vo/_TagVo.md"
 import ContributorVo from "../vo/_ContributorVo.md"
 import ListedPostVo from "../vo/_ListedPostVo.md"
 
+根据作者列出所有文章的页面，如果你的主题偏向于社区类型，那么可以添加一个这样的模板，用于提供作者的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/author.html`

diff --git a/versioned_docs/version-2.20/developer-guide/theme/template-variables/categories.md b/versioned_docs/version-2.20/developer-guide/theme/template-variables/categories.md
@@ -5,6 +5,8 @@ description: categories.html - /categories
 
 import CategoryTreeVo from "../vo/_CategoryTreeVo.md"
 
+用于列出所有文章分类的页面。
+
 ## 路由信息
 
 - 模板路径：`/templates/categories.html`