docs: add documentation for template engine global variables (#180)

添加 Halo 为模板引擎提供的全局变量的文档。

/kind documentation

Fixes #161 

```release-note
None
```

docs/developer-guide/theme/global-variables.md

@@ -0,0 +1,58 @@
+---
+title: 全局变量
+description: 本文档介绍 Halo 为模板引擎提供的专有全局变量。
+---
+
+import SiteSettingVo from "./vo/SiteSettingVo.md"
+import ThemeVo from "./vo/ThemeVo.md"
+
+Halo 目前为模板引擎在全局提供了一些变量，本文档将列出已提供的变量以及介绍这些变量的使用方法。
+
+## site
+
+### 描述
+
+提供了部分可公开的系统相关的设置项，其中所有参数均来自于 Console 的系统设置。
+
+### 类型
+
+<SiteSettingVo />
+
+### 示例
+
+显示站点标题：
+
+```html
+<h1 th:text="${site.title}"></h1>
+```
+
+显示站点 Logo：
+
+```html
+<img th:src="${site.logo}" alt="Logo" />
+```
+
+## theme
+
+### 描述
+
+关于当前激活主题的信息。
+
+### 类型
+
+<ThemeVo />
+
+### 示例
+
+显示主题名称：
+
+```html
+<h1 th:text="${theme.spec.displayName}"></h1>
+```
+
+在静态资源加入版本号参数，以防止升级之后的缓存问题：
+
+```html
+<link rel="stylesheet" th:href="@{/assets/dist/style.css?v={version}(version=${theme.spec.version})}" />
+<script th:src="@{/assets/dist/main.iife.js?v={version}(version=${theme.spec.version})}"></script>
+```

docs/developer-guide/theme/vo/SiteSettingVo.md

@@ -0,0 +1,26 @@
+```json title="SiteSettingVo"
+{
+  "title": "string",                      // 站点标题
+  "subtitle": "string",                   // 站点副标题
+  "url": "string",                        // 站点的外部访问链接
+  "logo": "string",                       // Logo 地址
+  "favicon": "string",                    // Favicon 地址
+  "allowRegistration": false,             // 是否允许注册
+  "post": {                               // 文章相关设置
+    "postPageSize": 10,                   // 首页默认分页大小
+    "archivePageSize": 10,                // 归档页默认分页大小
+    "categoryPageSize": 10,               // 分类归档页默认分页大小
+    "tagPageSize": 10                     // 标签归档页默认分页大小
+  },
+  "seo": {                                // SEO 相关设置
+    "blockSpiders": false,                // 禁止搜索引擎抓取
+    "keywords": "string",                 // 站点全局关键词，一般不需要主动使用，Halo 会自动插入到 head 标签中
+    "description": "string"               // 站点全局描述，一般不需要主动使用，Halo 会自动插入到 head 标签中
+  },
+  "comment": {                            // 评论相关设置
+    "enable": true,                       // 是否开启评论
+    "systemUserOnly": false,              // 是否只允许登录用户评论
+    "requireReviewForNew": false          // 是否需要审核新评论
+  }
+}
+```

docs/developer-guide/theme/vo/ThemeVo.md

@@ -0,0 +1,36 @@
+```json title="ThemeVo"
+{
+  "metadata": {
+    "name": "string",                                   // 唯一标识
+    "labels": {
+      "additionalProp1": "string"
+    },
+    "annotations": {
+      "additionalProp1": "string"
+    },
+    "creationTimestamp": "2022-11-20T14:44:58.984Z"    // 创建时间
+  },
+  "spec": {
+    "displayName": "string",                           // 显示名称
+    "author": {                                        // 作者相关信息
+      "name": "string",                                // 作者名称
+      "website": "string"                              // 作者网站
+    },
+    "description": "string",                           // 主题描述
+    "logo": "string",                                  // 主题 Logo
+    "website": "string",                               // 主题网站
+    "repo": "string",                                  // 主题仓库地址
+    "version": "string",                               // 主题版本
+    "requires": "string",                              // 主题依赖 Halo 版本的设置
+    "settingName": "string",                           // 主题设置表单名称
+    "configMapName": "string",                         // 主题配置名称
+    "customTemplates": {}                              // 主题自定义模板设置
+  },
+  "config": {}                                         // 主题配置
+}
+```
+
+其中：
+
+1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板路由#自定义模板](../template-route-mapping.md#custom-templates)
+2. `config`：主题配置，使用文档请参考：[设置选项](../settings.md)

sidebars.js

@@ -151,6 +151,7 @@ module.exports = {
                 "developer-guide/theme/finder-apis/plugin",
               ],
             },
+            "developer-guide/theme/global-variables",
             "developer-guide/theme/code-snippets",
           ],
         },

versioned_docs/version-2.0/developer-guide/theme/global-variables.md

@@ -0,0 +1,58 @@
+---
+title: 全局变量
+description: 本文档介绍 Halo 为模板引擎提供的专有全局变量。
+---
+
+import SiteSettingVo from "./vo/SiteSettingVo.md"
+import ThemeVo from "./vo/ThemeVo.md"
+
+Halo 目前为模板引擎在全局提供了一些变量，本文档将列出已提供的变量以及介绍这些变量的使用方法。
+
+## site
+
+### 描述
+
+提供了部分可公开的系统相关的设置项，其中所有参数均来自于 Console 的系统设置。
+
+### 类型
+
+<SiteSettingVo />
+
+### 示例
+
+显示站点标题：
+
+```html
+<h1 th:text="${site.title}"></h1>
+```
+
+显示站点 Logo：
+
+```html
+<img th:src="${site.logo}" alt="Logo" />
+```
+
+## theme
+
+### 描述
+
+关于当前激活主题的信息。
+
+### 类型
+
+<ThemeVo />
+
+### 示例
+
+显示主题名称：
+
+```html
+<h1 th:text="${theme.spec.displayName}"></h1>
+```
+
+在静态资源加入版本号参数，以防止升级之后的缓存问题：
+
+```html
+<link rel="stylesheet" th:href="@{/assets/dist/style.css?v={version}(version=${theme.spec.version})}" />
+<script th:src="@{/assets/dist/main.iife.js?v={version}(version=${theme.spec.version})}"></script>
+```

versioned_docs/version-2.0/developer-guide/theme/vo/SiteSettingVo.md

@@ -0,0 +1,26 @@
+```json title="SiteSettingVo"
+{
+  "title": "string",                      // 站点标题
+  "subtitle": "string",                   // 站点副标题
+  "url": "string",                        // 站点的外部访问链接
+  "logo": "string",                       // Logo 地址
+  "favicon": "string",                    // Favicon 地址
+  "allowRegistration": false,             // 是否允许注册
+  "post": {                               // 文章相关设置
+    "postPageSize": 10,                   // 首页默认分页大小
+    "archivePageSize": 10,                // 归档页默认分页大小
+    "categoryPageSize": 10,               // 分类归档页默认分页大小
+    "tagPageSize": 10                     // 标签归档页默认分页大小
+  },
+  "seo": {                                // SEO 相关设置
+    "blockSpiders": false,                // 禁止搜索引擎抓取
+    "keywords": "string",                 // 站点全局关键词，一般不需要主动使用，Halo 会自动插入到 head 标签中
+    "description": "string"               // 站点全局描述，一般不需要主动使用，Halo 会自动插入到 head 标签中
+  },
+  "comment": {                            // 评论相关设置
+    "enable": true,                       // 是否开启评论
+    "systemUserOnly": false,              // 是否只允许登录用户评论
+    "requireReviewForNew": false          // 是否需要审核新评论
+  }
+}
+```

versioned_docs/version-2.0/developer-guide/theme/vo/ThemeVo.md

@@ -0,0 +1,36 @@
+```json title="ThemeVo"
+{
+  "metadata": {
+    "name": "string",                                   // 唯一标识
+    "labels": {
+      "additionalProp1": "string"
+    },
+    "annotations": {
+      "additionalProp1": "string"
+    },
+    "creationTimestamp": "2022-11-20T14:44:58.984Z"    // 创建时间
+  },
+  "spec": {
+    "displayName": "string",                           // 显示名称
+    "author": {                                        // 作者相关信息
+      "name": "string",                                // 作者名称
+      "website": "string"                              // 作者网站
+    },
+    "description": "string",                           // 主题描述
+    "logo": "string",                                  // 主题 Logo
+    "website": "string",                               // 主题网站
+    "repo": "string",                                  // 主题仓库地址
+    "version": "string",                               // 主题版本
+    "requires": "string",                              // 主题依赖 Halo 版本的设置
+    "settingName": "string",                           // 主题设置表单名称
+    "configMapName": "string",                         // 主题配置名称
+    "customTemplates": {}                              // 主题自定义模板设置
+  },
+  "config": {}                                         // 主题配置
+}
+```
+
+其中：
+
+1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板路由#自定义模板](../template-route-mapping.md#custom-templates)
+2. `config`：主题配置，使用文档请参考：[设置选项](../settings.md)

versioned_docs/version-2.1/developer-guide/theme/global-variables.md

@@ -0,0 +1,58 @@
+---
+title: 全局变量
+description: 本文档介绍 Halo 为模板引擎提供的专有全局变量。
+---
+
+import SiteSettingVo from "./vo/SiteSettingVo.md"
+import ThemeVo from "./vo/ThemeVo.md"
+
+Halo 目前为模板引擎在全局提供了一些变量，本文档将列出已提供的变量以及介绍这些变量的使用方法。
+
+## site
+
+### 描述
+
+提供了部分可公开的系统相关的设置项，其中所有参数均来自于 Console 的系统设置。
+
+### 类型
+
+<SiteSettingVo />
+
+### 示例
+
+显示站点标题：
+
+```html
+<h1 th:text="${site.title}"></h1>
+```
+
+显示站点 Logo：
+
+```html
+<img th:src="${site.logo}" alt="Logo" />
+```
+
+## theme
+
+### 描述
+
+关于当前激活主题的信息。
+
+### 类型
+
+<ThemeVo />
+
+### 示例
+
+显示主题名称：
+
+```html
+<h1 th:text="${theme.spec.displayName}"></h1>
+```
+
+在静态资源加入版本号参数，以防止升级之后的缓存问题：
+
+```html
+<link rel="stylesheet" th:href="@{/assets/dist/style.css?v={version}(version=${theme.spec.version})}" />
+<script th:src="@{/assets/dist/main.iife.js?v={version}(version=${theme.spec.version})}"></script>
+```

versioned_docs/version-2.1/developer-guide/theme/vo/SiteSettingVo.md

@@ -0,0 +1,26 @@
+```json title="SiteSettingVo"
+{
+  "title": "string",                      // 站点标题
+  "subtitle": "string",                   // 站点副标题
+  "url": "string",                        // 站点的外部访问链接
+  "logo": "string",                       // Logo 地址
+  "favicon": "string",                    // Favicon 地址
+  "allowRegistration": false,             // 是否允许注册
+  "post": {                               // 文章相关设置
+    "postPageSize": 10,                   // 首页默认分页大小
+    "archivePageSize": 10,                // 归档页默认分页大小
+    "categoryPageSize": 10,               // 分类归档页默认分页大小
+    "tagPageSize": 10                     // 标签归档页默认分页大小
+  },
+  "seo": {                                // SEO 相关设置
+    "blockSpiders": false,                // 禁止搜索引擎抓取
+    "keywords": "string",                 // 站点全局关键词，一般不需要主动使用，Halo 会自动插入到 head 标签中
+    "description": "string"               // 站点全局描述，一般不需要主动使用，Halo 会自动插入到 head 标签中
+  },
+  "comment": {                            // 评论相关设置
+    "enable": true,                       // 是否开启评论
+    "systemUserOnly": false,              // 是否只允许登录用户评论
+    "requireReviewForNew": false          // 是否需要审核新评论
+  }
+}
+```

versioned_docs/version-2.1/developer-guide/theme/vo/ThemeVo.md

@@ -0,0 +1,36 @@
+```json title="ThemeVo"
+{
+  "metadata": {
+    "name": "string",                                   // 唯一标识
+    "labels": {
+      "additionalProp1": "string"
+    },
+    "annotations": {
+      "additionalProp1": "string"
+    },
+    "creationTimestamp": "2022-11-20T14:44:58.984Z"    // 创建时间
+  },
+  "spec": {
+    "displayName": "string",                           // 显示名称
+    "author": {                                        // 作者相关信息
+      "name": "string",                                // 作者名称
+      "website": "string"                              // 作者网站
+    },
+    "description": "string",                           // 主题描述
+    "logo": "string",                                  // 主题 Logo
+    "website": "string",                               // 主题网站
+    "repo": "string",                                  // 主题仓库地址
+    "version": "string",                               // 主题版本
+    "requires": "string",                              // 主题依赖 Halo 版本的设置
+    "settingName": "string",                           // 主题设置表单名称
+    "configMapName": "string",                         // 主题配置名称
+    "customTemplates": {}                              // 主题自定义模板设置
+  },
+  "config": {}                                         // 主题配置
+}
+```
+
+其中：
+
+1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板路由#自定义模板](../template-route-mapping.md#custom-templates)
+2. `config`：主题配置，使用文档请参考：[设置选项](../settings.md)

versioned_docs/version-2.2/developer-guide/theme/global-variables.md

@@ -0,0 +1,58 @@
+---
+title: 全局变量
+description: 本文档介绍 Halo 为模板引擎提供的专有全局变量。
+---
+
+import SiteSettingVo from "./vo/SiteSettingVo.md"
+import ThemeVo from "./vo/ThemeVo.md"
+
+Halo 目前为模板引擎在全局提供了一些变量，本文档将列出已提供的变量以及介绍这些变量的使用方法。
+
+## site
+
+### 描述
+
+提供了部分可公开的系统相关的设置项，其中所有参数均来自于 Console 的系统设置。
+
+### 类型
+
+<SiteSettingVo />
+
+### 示例
+
+显示站点标题：
+
+```html
+<h1 th:text="${site.title}"></h1>
+```
+
+显示站点 Logo：
+
+```html
+<img th:src="${site.logo}" alt="Logo" />
+```
+
+## theme
+
+### 描述
+
+关于当前激活主题的信息。
+
+### 类型
+
+<ThemeVo />
+
+### 示例
+
+显示主题名称：
+
+```html
+<h1 th:text="${theme.spec.displayName}"></h1>
+```
+
+在静态资源加入版本号参数，以防止升级之后的缓存问题：
+
+```html
+<link rel="stylesheet" th:href="@{/assets/dist/style.css?v={version}(version=${theme.spec.version})}" />
+<script th:src="@{/assets/dist/main.iife.js?v={version}(version=${theme.spec.version})}"></script>
+```

versioned_docs/version-2.2/developer-guide/theme/vo/SiteSettingVo.md

@@ -0,0 +1,26 @@
+```json title="SiteSettingVo"
+{
+  "title": "string",                      // 站点标题
+  "subtitle": "string",                   // 站点副标题
+  "url": "string",                        // 站点的外部访问链接
+  "logo": "string",                       // Logo 地址
+  "favicon": "string",                    // Favicon 地址
+  "allowRegistration": false,             // 是否允许注册
+  "post": {                               // 文章相关设置
+    "postPageSize": 10,                   // 首页默认分页大小
+    "archivePageSize": 10,                // 归档页默认分页大小
+    "categoryPageSize": 10,               // 分类归档页默认分页大小
+    "tagPageSize": 10                     // 标签归档页默认分页大小
+  },
+  "seo": {                                // SEO 相关设置
+    "blockSpiders": false,                // 禁止搜索引擎抓取
+    "keywords": "string",                 // 站点全局关键词，一般不需要主动使用，Halo 会自动插入到 head 标签中
+    "description": "string"               // 站点全局描述，一般不需要主动使用，Halo 会自动插入到 head 标签中
+  },
+  "comment": {                            // 评论相关设置
+    "enable": true,                       // 是否开启评论
+    "systemUserOnly": false,              // 是否只允许登录用户评论
+    "requireReviewForNew": false          // 是否需要审核新评论
+  }
+}
+```

versioned_docs/version-2.2/developer-guide/theme/vo/ThemeVo.md

@@ -0,0 +1,36 @@
+```json title="ThemeVo"
+{
+  "metadata": {
+    "name": "string",                                   // 唯一标识
+    "labels": {
+      "additionalProp1": "string"
+    },
+    "annotations": {
+      "additionalProp1": "string"
+    },
+    "creationTimestamp": "2022-11-20T14:44:58.984Z"    // 创建时间
+  },
+  "spec": {
+    "displayName": "string",                           // 显示名称
+    "author": {                                        // 作者相关信息
+      "name": "string",                                // 作者名称
+      "website": "string"                              // 作者网站
+    },
+    "description": "string",                           // 主题描述
+    "logo": "string",                                  // 主题 Logo
+    "website": "string",                               // 主题网站
+    "repo": "string",                                  // 主题仓库地址
+    "version": "string",                               // 主题版本
+    "requires": "string",                              // 主题依赖 Halo 版本的设置
+    "settingName": "string",                           // 主题设置表单名称
+    "configMapName": "string",                         // 主题配置名称
+    "customTemplates": {}                              // 主题自定义模板设置
+  },
+  "config": {}                                         // 主题配置
+}
+```
+
+其中：
+
+1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板路由#自定义模板](../template-route-mapping.md#custom-templates)
+2. `config`：主题配置，使用文档请参考：[设置选项](../settings.md)

versioned_sidebars/version-2.0-sidebars.json

@@ -129,6 +129,7 @@
                 "developer-guide/theme/finder-apis/plugin"
               ]
             },
+            "developer-guide/theme/global-variables",
             "developer-guide/theme/code-snippets"
           ]
         },

versioned_sidebars/version-2.1-sidebars.json

@@ -133,6 +133,7 @@
                 "developer-guide/theme/finder-apis/plugin"
               ]
             },
+            "developer-guide/theme/global-variables",
             "developer-guide/theme/code-snippets"
           ]
         },

versioned_sidebars/version-2.2-sidebars.json

@@ -133,6 +133,7 @@
                 "developer-guide/theme/finder-apis/plugin"
               ]
             },
+            "developer-guide/theme/global-variables",
             "developer-guide/theme/code-snippets"
           ]
         },