Skip to content

Commit cd44c8b

Browse files
ruibabyruibaby
authored
docs: restructure theme development documentation (#450)
重构主题开发的部分文档，合并模板路由和模板变量章节。 /kind documentation ```release-note None ```
1 parent 5ef6bc2 commit cd44c8b

File tree

29 files changed

+309
-29
lines changed

29 files changed

+309
-29
lines changed

‎docs/developer-guide/theme/config.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,9 @@ spec:
6262
| `spec.issues` | 主题问题反馈地址，如果你的主题是开源在 GitHub 上，可以直接配置为 GitHub Issues 地址。 | 否 |
6363
| `spec.settingName` | 设置表单定义的名称，需要同时创建对应的 `settings.yaml` 文件 | 否 |
6464
| `spec.configMapName` | 设置持久化配置的 ConfigMap 名称 | 否 |
65-
| `spec.customTemplates.post` | 文章的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否 |
66-
| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否 |
67-
| `spec.customTemplates.page` | 独立页面的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否 |
65+
| `spec.customTemplates.post` | 文章的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否 |
66+
| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否 |
67+
| `spec.customTemplates.page` | 独立页面的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否 |
6868
| `spec.version` | 主题版本 | 是 |
6969
| `spec.requires` | 所需 Halo 的运行版本 | 是 |
7070
| `spec.license` | 协议 | 否 |

‎docs/developer-guide/theme/structure.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ my-theme
2727

2828
详细说明：
2929

30-
1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板路由](./template-route-mapping)。
30+
1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板编写](./template-variables.md)。
3131
2. `/templates/assets/` - 主题静态资源目录，存放主题的静态资源文件，目前静态资源文件只能放在这个目录，引用方式请查阅 [静态资源](./static-resources)。
3232
3. `/theme.yaml` - 主题配置文件，配置主题的基本信息，如主题名称、版本、作者等。详细文档请查阅 [配置文件](./config)。
3333
4. `/settings.yaml` - 主题设置定义文件，配置主题的设置项表单。详细文档请查阅 [设置选项](./settings)。

‎docs/developer-guide/theme/template-variables.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
---
2-
title: 模板变量
2+
title: 模板编写
33
---
44

5+
此章节我们将详细介绍如何在主题中编写页面的模板，以下是 Halo 核心中支持的所有模板：
6+
7+
```mdx-code-block
58
import DocCardList from '@theme/DocCardList';
69
710
<DocCardList />
11+
```

‎docs/developer-guide/theme/template-variables/archives.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md";
88
import ContributorVo from "../vo/_ContributorVo.md";
99
import ListedPostVo from "../vo/_ListedPostVo.md";
1010

11+
文章归档页面，用于列出网站的所有文章，如果你编写的主题首页不显示文章列表，那么可以利用这个模板为网站单独提供一个查看文章列表的页面。
12+
1113
## 路由信息
1214

1315
- 模板路径：`/templates/archives.html`

‎docs/developer-guide/theme/template-variables/author.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ import TagVo from "../vo/_TagVo.md"
99
import ContributorVo from "../vo/_ContributorVo.md"
1010
import ListedPostVo from "../vo/_ListedPostVo.md"
1111

12+
根据作者列出所有文章的页面，如果你的主题偏向于社区类型，那么可以添加一个这样的模板，用于提供作者的页面。
13+
1214
## 路由信息
1315

1416
- 模板路径：`/templates/author.html`

‎docs/developer-guide/theme/template-variables/categories.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: categories.html - /categories
55

66
import CategoryTreeVo from "../vo/_CategoryTreeVo.md"
77

8+
用于列出所有文章分类的页面。
9+
810
## 路由信息
911

1012
- 模板路径：`/templates/categories.html`

‎docs/developer-guide/theme/template-variables/category.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,52 @@ import TagVo from "../vo/_TagVo.md"
88
import ContributorVo from "../vo/_ContributorVo.md";
99
import ListedPostVo from "../vo/_ListedPostVo.md"
1010

11+
用于根据分类列出所有文章的页面。
12+
1113
## 路由信息
1214

1315
- 模板路径：`/templates/category.html`
1416
- 访问路径：`/categories/:slug`
1517

18+
### 自定义模板
19+
20+
除了上面提到的 `category.html`，主题作者还可以添加多种形式的额外渲染模板，提供给用户选择，可以通过这个功能实现将网站上的文章内容进行领域划分，比如网站上同时存在新闻、文档、博客等分区，那么就可以利用这个功能提供多个模板，同时 Halo 还支持为分类设置文章渲染模板，详情可见[新建文章分类](../../../user-guide/posts.md#新建文章分类)。
21+
22+
定义方式为：
23+
24+
```yaml title="theme.yaml"
25+
customTemplates:
26+
category:
27+
- name: {name}
28+
description: {description}
29+
screenshot: {screenshot}
30+
file: {file}.html
31+
```
32+
33+
- `name`：模板名称
34+
- `description`：模板描述
35+
- `screenshot`：模板预览图
36+
- `file`：模板文件名，需要在 `/templates/` 目录下创建
37+
38+
示例：
39+
40+
```yaml title="theme.yaml"
41+
customTemplates:
42+
category:
43+
- name: 新闻
44+
description: 用于展示新闻分类下的文章
45+
screenshot:
46+
file: category_news.html
47+
- name: 博客
48+
description: 用于展示博客分类下的文章
49+
screenshot:
50+
file: category_blog.html
51+
```
52+
53+
:::info
54+
需要注意，修改 theme.yaml 需要[重载主题配置](../../../user-guide/themes.md#重载主题配置)。
55+
:::
56+
1657
## 变量
1758

1859
### category

‎docs/developer-guide/theme/template-variables/index_.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md"
88
import ContributorVo from "../vo/_ContributorVo.md";
99
import ListedPostVo from "../vo/_ListedPostVo.md"
1010

11+
网站的首页模板，在这个模板中默认设置了最新文章列表的变量，也可以通过调用 [Finder API](../finder-apis.md) 和 [主题设置](../settings.md) 来展示其他数据。
12+
1113
## 路由信息
1214

1315
- 模板路径：`/templates/index.html`

‎docs/developer-guide/theme/template-variables/page.md

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,54 @@
11
---
2-
title: 独立页面
2+
title: 单页面
33
description: page.html - /:slug
44
---
55

66
import SinglePageVo from "../vo/_SinglePageVo.md"
77
import ContributorVo from "../vo/_ContributorVo.md"
88
import ContentVo from "../vo/_ContentVo.md"
99

10+
页面与文章类似，同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息，一般用于站点中单一展示功能的页面，例如常见的站点关于页面、联系我们页面等。
11+
1012
## 路由信息
1113

1214
- 模板路径：`/templates/page.html`
1315
- 访问路径：`/:slug`
1416

17+
### 自定义模板
18+
19+
除了上面提到的 `page.html`，主题作者还可以添加多种形式的额外渲染模板，提供给用户选择，此举可以丰富网站的使用类型。
20+
21+
定义方式为：
22+
23+
```yaml title="theme.yaml"
24+
customTemplates:
25+
page:
26+
- name: {name}
27+
description: {description}
28+
screenshot: {screenshot}
29+
file: {file}.html
30+
```
31+
32+
- `name`：模板名称
33+
- `description`：模板描述
34+
- `screenshot`：模板预览图
35+
- `file`：模板文件名，需要在 `/templates/` 目录下创建
36+
37+
示例：
38+
39+
```yaml title="theme.yaml"
40+
customTemplates:
41+
page:
42+
- name: 关于公司
43+
description: 用于展示公司的一些信息
44+
screenshot:
45+
file: page_about.html
46+
```
47+
48+
:::info
49+
需要注意，修改 theme.yaml 需要[重载主题配置](../../../user-guide/themes.md#重载主题配置)。
50+
:::
51+
1552
## 变量
1653

1754
### singlePage

‎docs/developer-guide/theme/template-variables/post.md

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,47 @@ import ContentVo from "../vo/_ContentVo.md"
99
import ContributorVo from "../vo/_ContributorVo.md"
1010
import PostVo from "../vo/_PostVo.md"
1111

12+
文章详情页面的模板。
13+
1214
## 路由信息
1315

1416
- 模板路径：`/templates/post.html`
15-
- 访问路径：`/archives/:slug`
17+
- 访问路径：默认为 `/archives/:slug`，用户可手动更改为其他路由形式，可参考：[主题路由设置](../../../user-guide/settings.md#主题路由设置)
18+
19+
### 自定义模板
20+
21+
除了上面提到的 `post.html`，主题作者还可以添加多种形式的额外渲染模板，提供给用户选择，此举可以丰富网站的使用类型，用户设置方式可参考 [文章设置](../../../user-guide/posts.md#文章设置)。
22+
23+
定义方式为：
24+
25+
```yaml title="theme.yaml"
26+
customTemplates:
27+
post:
28+
- name: {name}
29+
description: {description}
30+
screenshot: {screenshot}
31+
file: {file}.html
32+
```
33+
34+
- `name`：模板名称
35+
- `description`：模板描述
36+
- `screenshot`：模板预览图
37+
- `file`：模板文件名，需要在 `/templates/` 目录下创建
38+
39+
示例：
40+
41+
```yaml title="theme.yaml"
42+
customTemplates:
43+
post:
44+
- name: 文档
45+
description: 文档类型的文章
46+
screenshot:
47+
file: post_documentation.html
48+
```
49+
50+
:::info
51+
需要注意，修改 theme.yaml 需要[重载主题配置](../../../user-guide/themes.md#重载主题配置)。
52+
:::
1653

1754
## 变量
1855

@@ -59,7 +96,17 @@ import PostVo from "../vo/_PostVo.md"
5996

6097
<PostVo />
6198

62-
- [#CategoryVo](#categoryvo)
63-
- [#TagVo](#tagvo)
64-
- [#ContributorVo](#contributorvo)
65-
- [#ContentVo](#contentvo)
99+
- [路由信息](#路由信息)
100+
- [自定义模板](#自定义模板)
101+
- [变量](#变量)
102+
- [post](#post)
103+
- [变量类型](#变量类型)
104+
- [示例](#示例)
105+
- [\_templateId](#_templateid)
106+
- [变量值](#变量值)
107+
- [类型定义](#类型定义)
108+
- [CategoryVo](#categoryvo)
109+
- [TagVo](#tagvo)
110+
- [ContributorVo](#contributorvo)
111+
- [ContentVo](#contentvo)
112+
- [PostVo](#postvo)

‎docs/developer-guide/theme/template-variables/tag.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md"
88
import ContributorVo from "../vo/_ContributorVo.md";
99
import ListedPostVo from "../vo/_ListedPostVo.md"
1010

11+
用于根据标签列出所有文章的页面。
12+
1113
## 路由信息
1214

1315
- 模板路径：`/templates/tag.html`

‎docs/developer-guide/theme/template-variables/tags.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: tags.html - /tags
55

66
import TagVo from '../vo/_TagVo.md'
77

8+
用于列出所有文章标签的页面，可以用于实现标签墙等功能。
9+
810
## 路由信息
911

1012
- 模板路径：`/templates/tags.html`

‎docs/developer-guide/theme/vo/_ThemeVo.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,5 +32,5 @@
3232

3333
其中：
3434

35-
1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板路由#自定义模板](../template-route-mapping.md#custom-templates)
35+
1. `customTemplates`：一般不会在模板引擎中使用，使用文档请参考：[模板编写](../template-variables.md))
3636
2. `config`：主题配置，使用文档请参考：[设置选项](../settings.md)

‎docusaurus.config.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ const config = {
189189
prism: {
190190
theme: darkCodeTheme,
191191
darkTheme: darkCodeTheme,
192-
additionalLanguages: ["java","sql"],
192+
additionalLanguages: ["java", "json", "sql"],
193193
},
194194
zoom: {
195195
selector: ".markdown :not(a) > img",

‎sidebars.js

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -320,13 +320,12 @@ module.exports = {
320320
"developer-guide/theme/prepare",
321321
"developer-guide/theme/config",
322322
"developer-guide/theme/structure",
323-
"developer-guide/theme/template-route-mapping",
324323
"developer-guide/theme/static-resources",
325324
"developer-guide/theme/settings",
326325
"developer-guide/theme/annotations",
327326
{
328327
type: "category",
329-
label: "模板变量",
328+
label: "模板编写",
330329
link: {
331330
type: "doc",
332331
id: "developer-guide/theme/template-variables",

‎versioned_docs/version-2.20/developer-guide/theme/config.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,9 @@ spec:
6262
| `spec.issues` | 主题问题反馈地址，如果你的主题是开源在 GitHub 上，可以直接配置为 GitHub Issues 地址。 | 否 |
6363
| `spec.settingName` | 设置表单定义的名称，需要同时创建对应的 `settings.yaml` 文件 | 否 |
6464
| `spec.configMapName` | 设置持久化配置的 ConfigMap 名称 | 否 |
65-
| `spec.customTemplates.post` | 文章的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否 |
66-
| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否 |
67-
| `spec.customTemplates.page` | 独立页面的自定义模板配置，详细文档可查阅 [模板路由](./template-route-mapping#custom-templates) | 否 |
65+
| `spec.customTemplates.post` | 文章的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否 |
66+
| `spec.customTemplates.category` | 分类的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否 |
67+
| `spec.customTemplates.page` | 独立页面的自定义模板配置，详细文档可查阅 [模板编写](./template-variables.md) | 否 |
6868
| `spec.version` | 主题版本 | 是 |
6969
| `spec.requires` | 所需 Halo 的运行版本 | 是 |
7070
| `spec.license` | 协议 | 否 |

‎versioned_docs/version-2.20/developer-guide/theme/structure.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ my-theme
2727

2828
详细说明：
2929

30-
1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板路由](./template-route-mapping)。
30+
1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。关于模板的详细说明，请查阅 [模板编写](./template-variables.md)。
3131
2. `/templates/assets/` - 主题静态资源目录，存放主题的静态资源文件，目前静态资源文件只能放在这个目录，引用方式请查阅 [静态资源](./static-resources)。
3232
3. `/theme.yaml` - 主题配置文件，配置主题的基本信息，如主题名称、版本、作者等。详细文档请查阅 [配置文件](./config)。
3333
4. `/settings.yaml` - 主题设置定义文件，配置主题的设置项表单。详细文档请查阅 [设置选项](./settings)。

‎versioned_docs/version-2.20/developer-guide/theme/template-variables.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
---
2-
title: 模板变量
2+
title: 模板编写
33
---
44

5+
此章节我们将详细介绍如何在主题中编写页面的模板，以下是 Halo 核心中支持的所有模板：
6+
7+
```mdx-code-block
58
import DocCardList from '@theme/DocCardList';
69
710
<DocCardList />
11+
```

‎versioned_docs/version-2.20/developer-guide/theme/template-variables/archives.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import TagVo from "../vo/_TagVo.md";
88
import ContributorVo from "../vo/_ContributorVo.md";
99
import ListedPostVo from "../vo/_ListedPostVo.md";
1010

11+
文章归档页面，用于列出网站的所有文章，如果你编写的主题首页不显示文章列表，那么可以利用这个模板为网站单独提供一个查看文章列表的页面。
12+
1113
## 路由信息
1214

1315
- 模板路径：`/templates/archives.html`

‎versioned_docs/version-2.20/developer-guide/theme/template-variables/author.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ import TagVo from "../vo/_TagVo.md"
99
import ContributorVo from "../vo/_ContributorVo.md"
1010
import ListedPostVo from "../vo/_ListedPostVo.md"
1111

12+
根据作者列出所有文章的页面，如果你的主题偏向于社区类型，那么可以添加一个这样的模板，用于提供作者的页面。
13+
1214
## 路由信息
1315

1416
- 模板路径：`/templates/author.html`

‎versioned_docs/version-2.20/developer-guide/theme/template-variables/categories.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: categories.html - /categories
55

66
import CategoryTreeVo from "../vo/_CategoryTreeVo.md"
77

8+
用于列出所有文章分类的页面。
9+
810
## 路由信息
911

1012
- 模板路径：`/templates/categories.html`

0 commit comments

Comments
 (0)