docs: update documentation for Halo 2.20 (#429)

为 [Halo 2.20](https://github.com/halo-dev/halo/releases/tag/v2.20.0) 更新文档。

/kind documentation

```release-note
None
```
This commit is contained in:
Ryan Wang
2024-10-14 11:33:15 +08:00
committed by GitHub
parent f752dd74d7
commit 9876911e3a
185 changed files with 15652 additions and 58 deletions

View File

@@ -0,0 +1,108 @@
---
title: 文章归档
description: archives.html - /archives
---
import CategoryVo from "../vo/_CategoryVo.md";
import TagVo from "../vo/_TagVo.md";
import ContributorVo from "../vo/_ContributorVo.md";
import ListedPostVo from "../vo/_ListedPostVo.md";
## 路由信息
- 模板路径:`/templates/archives.html`
- 访问路径
- `/archives`
- `/archives/:year`
- `/archives/:year/:month`
## 变量
### archives
#### 变量类型
[#UrlContextListResult\<PostArchiveVo\>](#urlcontextlistresultpostarchivevo)
#### 示例
```html title="/templates/archives.html"
<th:block th:each="archive : ${archives.items}">
<h1 th:text="${archive.year}"></h1>
<ul>
<th:block th:each="month : ${archive.months}">
<li th:each="post : ${month.posts}">
<a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}">
</a>
</li>
</th:block>
</ul>
</th:block>
<div th:if="${archives.hasPrevious() || archives.hasNext()}">
<a th:href="@{${archives.prevUrl}}">
<span>上一页</span>
</a>
<span th:text="${archives.page} +' / '+ ${archives.totalPages}"></span>
<a th:href="@{${archives.nextUrl}}">
<span>下一页</span>
</a>
</div>
```
## 类型定义
### CategoryVo
<CategoryVo />
### TagVo
<TagVo />
### ContributorVo
<ContributorVo />
### ListedPostVo
\<ListedPostVo \/\>
- [#CategoryVo](#categoryvo)
- [#TagVo](#tagvo)
- [#ContributorVo](#contributorvo)
### PostArchiveVo
```json title="PostArchiveVo"
{
"year": "string", // 年份
"months": [ // 按月的文章集合
{
"month": "string", // 月份
"posts": "List<#ListedPostVo>" // 文章列表数据
}
]
}
```
- [#ListedPostVo](#listedpostvo)
### UrlContextListResult\<PostArchiveVo\>
```json title="UrlContextListResult<PostArchiveVo>"
{
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#PostArchiveVo>", // 文章归档数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"nextUrl": "string", // 下一页链接
"prevUrl": "string" // 上一页链接
}
```
- [#PostArchiveVo](#postarchivevo)

View File

@@ -0,0 +1,104 @@
---
title: 作者归档
description: author.html - /authors/:name
---
import UserVo from "../vo/_UserVo.md"
import CategoryVo from "../vo/_CategoryVo.md"
import TagVo from "../vo/_TagVo.md"
import ContributorVo from "../vo/_ContributorVo.md"
import ListedPostVo from "../vo/_ListedPostVo.md"
## 路由信息
- 模板路径:`/templates/author.html`
- 访问路径:`/authors/:name`
## 变量
### author
#### 变量类型
[#UserVo](#uservo)
### posts
#### 变量类型
[#UrlContextListResult\<ListedPostVo\>](#urlcontextlistresultlistedpostvo)
#### 示例
```html title="/templates/author.html"
<div>
<h1 th:text="${author.spec.displayName}"></h1>
<ul>
<li th:each="post : ${posts.items}">
<a
th:text="${post.spec.title}"
th:href="${post.status.permalink}"
></a>
</li>
</ul>
<div th:if="${posts.hasPrevious() || posts.hasNext()}">
<a
th:href="@{${posts.prevUrl}}"
>
<span>上一页</span>
</a>
<span th:text="${posts.page} +' / '+ ${posts.total}"></span>
<a
th:href="@{${posts.nextUrl}}"
>
<span>下一页</span>
</a>
</div>
</div>
```
## 类型定义
### UserVo
<UserVo />
### CategoryVo
<CategoryVo />
### TagVo
<TagVo />
### ContributorVo
<ContributorVo />
### ListedPostVo
\<ListedPostVo \/\>
- [#CategoryVo](#categoryvo)
- [#TagVo](#tagvo)
- [#ContributorVo](#contributorvo)
### UrlContextListResult\<ListedPostVo\>
```json title="UrlContextListResult<ListedPostVo>"
{
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#ListedPostVo>", // 文章列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"nextUrl": "string", // 下一页链接
"prevUrl": "string" // 上一页链接
}
```
- [#ListedPostVo](#listedpostvo)

View File

@@ -0,0 +1,54 @@
---
title: 文章分类集合
description: categories.html - /categories
---
import CategoryTreeVo from "../vo/_CategoryTreeVo.md"
## 路由信息
- 模板路径:`/templates/categories.html`
- 访问路径:`/categories`
## 变量
### categories
#### 变量类型
List\<[#CategoryTreeVo](#categorytreevo)\>
#### 示例
```html title="/templates/categories.html"
<ul>
<li th:replace="~{modules/category-tree :: single(categories=${categories})}" />
</ul>
```
```html title="/templates/category-tree.html"
<ul th:fragment="next (categories)">
<li th:fragment="single (categories)" th:each="category : ${categories}">
<a th:href="@{${category.status.permalink}}">
<span th:text="${category.spec.displayName}"> </span>
</a>
<th:block th:if="${not #lists.isEmpty(category.children)}">
<th:block th:replace="~{modules/category-tree :: next (categories=${category.children})}"></th:block>
</th:block>
</li>
</ul>
```
### _templateId
#### 变量值
`categories`
## 类型定义
### CategoryTreeVo
<CategoryTreeVo />
- [#CategoryTreeVo](#categorytreevo)

View File

@@ -0,0 +1,105 @@
---
title: 分类归档
description: category.html - /categories/:slug
---
import CategoryVo from "../vo/_CategoryVo.md"
import TagVo from "../vo/_TagVo.md"
import ContributorVo from "../vo/_ContributorVo.md";
import ListedPostVo from "../vo/_ListedPostVo.md"
## 路由信息
- 模板路径:`/templates/category.html`
- 访问路径:`/categories/:slug`
## 变量
### category
#### 变量类型
[#CategoryVo](#categoryvo)
### posts
#### 变量类型
[#UrlContextListResult\<ListedPostVo\>](#urlcontextlistresultlistedpostvo)
#### 示例
```html title="/templates/category.html"
<div>
<h1 th:text="${category.spec.displayName}"></h1>
<ul>
<li th:each="post : ${posts.items}">
<a
th:text="${post.spec.title}"
th:href="${post.status.permalink}"
></a>
</li>
</ul>
<div th:if="${posts.hasPrevious() || posts.hasNext()}">
<a
th:href="@{${posts.prevUrl}}"
>
<span>上一页</span>
</a>
<span th:text="${posts.page} +' / '+ ${posts.total}"></span>
<a
th:href="@{${posts.nextUrl}}"
>
<span>下一页</span>
</a>
</div>
</div>
```
### _templateId
#### 变量值
`category`
## 类型定义
### CategoryVo
<CategoryVo />
### TagVo
<TagVo />
### ContributorVo
<ContributorVo />
### ListedPostVo
\<ListedPostVo \/\>
- [#CategoryVo](#categoryvo)
- [#TagVo](#tagvo)
- [#ContributorVo](#contributorvo)
### UrlContextListResult\<ListedPostVo\>
```json title="UrlContextListResult<ListedPostVo>"
{
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#ListedPostVo>", // 文章列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"nextUrl": "string", // 下一页链接
"prevUrl": "string" // 上一页链接
}
```
- [#ListedPostVo](#listedpostvo)

View File

@@ -0,0 +1,45 @@
---
title: 错误页面
description: 关于错误页面的模板变量
---
## 路由信息
- 模板路径:`/templates/error/{404,4xx,500,5xx,error}.html`
- 访问路径:无固定访问路径,由异常决定
:::info 提示
错误页面的可使用模板由状态码决定,例如 404 状态码对应的模板为 `/templates/error/404.html` 或者 `/templates/error/4xx.html`。也可以使用 `/templates/error/error.html` 作为默认模板。
识别顺序如下:
1. `/templates/error/404.html`
2. `/templates/error/4xx.html`
3. `/templates/error/error.html`
:::
## 变量
### error
#### 变量类型
```json
{
"detail": "string", // 异常详细信息
"instance": "string", // 异常实例
"status": "number", // 异常状态码
"title": "string", // 异常标题
"type": "string" // 异常类型
}
```
#### 示例
```html title="/templates/error/error.html"
<div>
<h2 th:text="${error.status}"></h2>
<p th:text="${#strings.defaultString(error.title, 'Internal server error')}"></p>
<p th:if="${not #strings.isEmpty(error.detail)}" th:text="${error.detail}"></p>
</div>
```

View File

@@ -0,0 +1,98 @@
---
title: 首页
description: index.html - /
---
import CategoryVo from "../vo/_CategoryVo.md"
import TagVo from "../vo/_TagVo.md"
import ContributorVo from "../vo/_ContributorVo.md";
import ListedPostVo from "../vo/_ListedPostVo.md"
## 路由信息
- 模板路径:`/templates/index.html`
- 访问路径:`/`
## 变量
### posts
#### 变量类型
[#UrlContextListResult\<ListedPostVo\>](#urlcontextlistresultlistedpostvo)
#### 示例
```html title="/templates/index.html"
<div>
<ul>
<li th:each="post : ${posts.items}">
<a
th:text="${post.spec.title}"
th:href="${post.status.permalink}"
></a>
</li>
</ul>
<div th:if="${posts.hasPrevious() || posts.hasNext()}">
<a
th:href="@{${posts.prevUrl}}"
>
<span>上一页</span>
</a>
<span th:text="${posts.page} +' / '+ ${posts.total}"></span>
<a
th:href="@{${posts.nextUrl}}"
>
<span>下一页</span>
</a>
</div>
</div>
```
### _templateId
#### 变量值
`index`
## 类型定义
### CategoryVo
<CategoryVo />
### TagVo
<TagVo />
### ContributorVo
<ContributorVo />
### ListedPostVo
\<ListedPostVo \/\>
- [#CategoryVo](#categoryvo)
- [#TagVo](#tagvo)
- [#ContributorVo](#contributorvo)
### UrlContextListResult\<ListedPostVo\>
```json title="UrlContextListResult<ListedPostVo>"
{
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#ListedPostVo>", // 文章列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"nextUrl": "string", // 下一页链接
"prevUrl": "string" // 上一页链接
}
```
- [#ListedPostVo](#listedpostvo)

View File

@@ -0,0 +1,53 @@
---
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`
## 变量
### singlePage
#### 变量类型
[#SinglePageVo](#singlepagevo)
#### 示例
```html title="/templates/page.html"
<article>
<h1 th:text="${singlePage.spec.title}"></h1>
<div th:utext="${singlePage.content.content}"> </div>
</article>
```
### _templateId
#### 变量值
`page`
## 类型定义
### SinglePageVo
<SinglePageVo />
- [#ContentVo](#contentvo)
- [#ContributorVo](#contributorvo)
### ContentVo
<ContentVo />
### ContributorVo
<ContributorVo />

View File

@@ -0,0 +1,65 @@
---
title: 文章
description: post.html - /archives/:slug
---
import CategoryVo from "../vo/_CategoryVo.md"
import TagVo from "../vo/_TagVo.md"
import ContentVo from "../vo/_ContentVo.md"
import ContributorVo from "../vo/_ContributorVo.md"
import PostVo from "../vo/_PostVo.md"
## 路由信息
- 模板路径:`/templates/post.html`
- 访问路径:`/archives/:slug`
## 变量
### post
#### 变量类型
[#PostVo](#postvo)
#### 示例
```html title="/templates/post.html"
<article>
<h1 th:text="${post.spec.title}"></h1>
<div th:utext="${post.content.content}"> </div>
</article>
```
### _templateId
#### 变量值
`post`
## 类型定义
### CategoryVo
<CategoryVo />
### TagVo
<TagVo />
### ContributorVo
<ContributorVo />
### ContentVo
<ContentVo />
### PostVo
<PostVo />
- [#CategoryVo](#categoryvo)
- [#TagVo](#tagvo)
- [#ContributorVo](#contributorvo)
- [#ContentVo](#contentvo)

View File

@@ -0,0 +1,105 @@
---
title: 标签归档
description: tag.html - /tags/:slug
---
import CategoryVo from "../vo/_CategoryVo.md"
import TagVo from "../vo/_TagVo.md"
import ContributorVo from "../vo/_ContributorVo.md";
import ListedPostVo from "../vo/_ListedPostVo.md"
## 路由信息
- 模板路径:`/templates/tag.html`
- 访问路径:`/tags/:slug`
## 变量
### tag
#### 变量类型
[#TagVo](#tagvo)
### posts
#### 变量类型
[#UrlContextListResult\<ListedPostVo\>](#urlcontextlistresultlistedpostvo)
#### 示例
```html title="/templates/tag.html"
<div>
<h1 th:text="${tag.spec.displayName}"></h1>
<ul>
<li th:each="post : ${posts.items}">
<a
th:text="${post.spec.title}"
th:href="${post.status.permalink}"
></a>
</li>
</ul>
<div th:if="${posts.hasPrevious() || posts.hasNext()}">
<a
th:href="@{${posts.prevUrl}}"
>
<span>上一页</span>
</a>
<span th:text="${posts.page} +' / '+ ${posts.total}"></span>
<a
th:href="@{${posts.nextUrl}}"
>
<span>下一页</span>
</a>
</div>
</div>
```
### _templateId
#### 变量值
`tag`
## 类型定义
### CategoryVo
<CategoryVo />
### TagVo
<TagVo />
### ContributorVo
<ContributorVo />
### ListedPostVo
\<ListedPostVo \/\>
- [#CategoryVo](#categoryvo)
- [#TagVo](#tagvo)
- [#ContributorVo](#contributorvo)
### UrlContextListResult\<ListedPostVo\>
```json title="UrlContextListResult<ListedPostVo>"
{
"page": 0, // 当前页码
"size": 0, // 每页条数
"total": 0, // 总条数
"items": "List<#ListedPostVo>", // 文章列表数据
"first": true, // 是否为第一页
"last": true, // 是否为最后一页
"hasNext": true, // 是否有下一页
"hasPrevious": true, // 是否有上一页
"totalPages": 0, // 总页数
"nextUrl": "string", // 下一页链接
"prevUrl": "string" // 上一页链接
}
```
- [#ListedPostVo](#listedpostvo)

View File

@@ -0,0 +1,39 @@
---
title: 文章标签集合
description: tags.html - /tags
---
import TagVo from '../vo/_TagVo.md'
## 路由信息
- 模板路径:`/templates/tags.html`
- 访问路径:`/tags`
## 变量
### tags
#### 变量类型
List\<[#TagVo](#tagvo)\>
#### 示例
```html title="/templates/tags.html"
<ul>
<li th:each="tag : ${tags}" th:text="${tag.spec.displayName}" th:href="${tag.status.permalink}" />
</ul>
```
### _templateId
#### 变量值
`tags`
## 类型定义
### TagVo
<TagVo />