mirror of
https://github.com/halo-dev/docs.git
synced 2026-01-22 03:00:10 +08:00
refactor: document versioning structure (#99)
重构文档版本结构。 - 移除 1.5/1.4 相关所有 patch 版本的文档，使用 1.5/1.4 版本号代替。 - 创建 1.6 的文档版本。 - 后续针对 1.5 或者 1.6 的更新，可以直接对具体版本进行更改。 本打算使用 [@docusaurus/plugin-client-redirects](https://docusaurus.io/zh-CN/docs/api/plugins/@docusaurus/plugin-client-redirects) 做已删除的 patch 版本的重定向，旦可能不是很好满足匹配重定向的需求。~~所以在此 PR 合并之前我将通过 Nginx 对具体版本进行重定向转发~~。 比如：`/1.4.17/{path}` 重定向到 `/1.4/{path}`，`/1.5.4/{path}` `/1.5.3/{path}` 都从定向到 `/1.5/{path}` /kind documentation /cc @halo-dev/sig-docs > PS: 此 PR 未对新发布的 [1.6.0](https://github.com/halo-dev/halo/releases/tag/v1.6.0) [1.5.5](https://github.com/halo-dev/halo/releases/tag/v1.5.5) [2.0.0-alpha.2](https://github.com/halo-dev/halo/releases/tag/v2.0.0-alpha.2) 做修改，将在后续 PR 更改。 ```release-note None ```
This commit is contained in:
Ryan Wang
261
versioned_docs/version-1.5/developer-guide/theme/config-files.md
Normal file
261
versioned_docs/version-1.5/developer-guide/theme/config-files.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
title: 配置文件
|
||||
description: 主题配置文件的说明
|
||||
---
|
||||
|
||||
> Halo 的主题模块使用 yaml 来对主题进行配置，`theme.yaml` 里面主要描述主题的名称，开发者的信息，开源地址等等。`settings.yaml` 包含了主题所有的配置选项，需要注意的是，这些选项仅仅是用于构建配置表单，并不起到对主题的配置作用。
|
||||
|
||||
## theme.yaml
|
||||
|
||||
```yaml
|
||||
id: 主题id，唯一，不能与其他主题一样。我们建议设置为 `作者名_主题名称`
|
||||
name: 主题名称
|
||||
author:
|
||||
name: 作者名称
|
||||
website: 作者网址
|
||||
description: 主题描述
|
||||
logo: 主题 Logo 地址
|
||||
website: 主题地址，可填写为 git 仓库地址
|
||||
repo: 主题 git 仓库地址，如有填写，后台可在线更新
|
||||
version: 版本号
|
||||
require: 最低支持的 Halo 版本，如：1.3.0，那么如果用户的版本为 1.3.0 以下，则无法安装
|
||||
|
||||
postMetaField: 文章自定义 meta 变量
|
||||
- meta_key
|
||||
|
||||
sheetMetaField:
|
||||
- meta_key 页面自定义 meta 变量
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```yaml
|
||||
id: caicai_anatole
|
||||
name: Anatole
|
||||
author:
|
||||
name: Caicai
|
||||
website: https://www.caicai.me
|
||||
description: A other Halo theme
|
||||
logo: https://avatars1.githubusercontent.com/u/1811819?s=460&v=4
|
||||
website: https://github.com/halo-dev/halo-theme-anatole
|
||||
repo: https://github.com/halo-dev/halo-theme-anatole
|
||||
version: 1.0.0
|
||||
require: 1.3.0
|
||||
postMetaField:
|
||||
- music_url # 假设在文章页面需要播放背景音乐，用户可以自己填写音乐地址。
|
||||
- download_url # 假设在文章页有一个下载按钮，那么用户也可以自己填写加载地址。
|
||||
|
||||
sheetMetaField:
|
||||
- music_url
|
||||
- download_url
|
||||
```
|
||||
|
||||
### 自定义 meta
|
||||
|
||||
这个为 1.2.0 引入的功能，用户可以在文章设置中设置自定义 meta，我们在 `theme.yaml` 中填写的 `postMetaField` 和 `sheetMetaField` 为预设项，当用户激活当前主题之后，在文章设置中即可看到预先设置好的项，然后填写对应的值即可。
|
||||
|
||||
关于这个 meta 变量如何调用的问题，会在后面的模板变量中阐述。
|
||||
|
||||
## settings.yaml
|
||||
|
||||
```yaml
|
||||
# Tab 节点
|
||||
group1:
|
||||
label: 第一个 Tab 名称
|
||||
# 表单项
|
||||
items:
|
||||
# 省略
|
||||
group2:
|
||||
label: 第二个 Tab 名称
|
||||
# 表单项
|
||||
items:
|
||||
# 省略
|
||||
```
|
||||
|
||||
## settings.yaml#items
|
||||
|
||||
> settings.yaml 的 items 下即为所有表单元素，所支持的表单元素如下
|
||||
|
||||
```yaml
|
||||
items:
|
||||
|
||||
# 普通文本框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: text // 表单项类型：普通文本框
|
||||
placeholder: '' // 表单项的 placeholder，一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 颜色选择框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: color // 表单项类型：颜色选择框
|
||||
placeholder: '' // 表单项的 placeholder，一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 附件选择框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: attachment // 表单项类型：颜色选择框
|
||||
placeholder: '' // 表单项的 placeholder，一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 多行文本框
|
||||
item2: // 设置项的 name 值，在页面可通过 ${settings.item2!} 获取值。
|
||||
name: item2
|
||||
label: item2 // 同上
|
||||
type: textarea // 表单项类型：多行文本框
|
||||
placeholder: '' // 同上
|
||||
default: '' // 同上
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 单选框
|
||||
item3:
|
||||
name: item3 // 同上
|
||||
label: item3_label // 同上
|
||||
type: radio // 表单项类型：单选框
|
||||
data-type: bool // 数据类型：bool，string，long，double
|
||||
default: value1 // 同上
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
options: // 选项
|
||||
- value: value1 // 值
|
||||
label: label1 // 说明
|
||||
- value: value2
|
||||
label: label2
|
||||
|
||||
# 下拉框
|
||||
item4:
|
||||
name: item4 // 同上
|
||||
label: item4 // 同上
|
||||
type: select // 表单项类型：下拉框
|
||||
data-type: bool // 数据类型：bool，string，long，double
|
||||
default: value1 // 同上
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
options: // 选项
|
||||
- value: value1 // 值
|
||||
label: label1 // 说明
|
||||
- value: value2
|
||||
label: label2
|
||||
```
|
||||
|
||||
### 一个例子
|
||||
|
||||
假设我们的配置文件如下：
|
||||
|
||||
```yaml
|
||||
general:
|
||||
label: 基础设置
|
||||
items:
|
||||
index_title:
|
||||
name: index_title
|
||||
label: 首页标题
|
||||
type: text
|
||||
description: '注意：将覆盖博客标题'
|
||||
background_cover:
|
||||
name: background_cover
|
||||
label: 首页背景图
|
||||
type: attachment
|
||||
default: '/casper/assets/images/blog-cover.jpg'
|
||||
description: '设置首页的背景图，你可以点击右边的选择按钮选择图片。'
|
||||
background_color:
|
||||
name: background_color
|
||||
label: 首页背景颜色
|
||||
type: color
|
||||
default: '#fff'
|
||||
music_enabled:
|
||||
name: music_enabled
|
||||
label: 背景音乐
|
||||
type: radio
|
||||
data-type: bool
|
||||
default: false
|
||||
description: '是否开启背景音乐，默认为 false'
|
||||
options:
|
||||
- value: true
|
||||
label: 开启
|
||||
- value: false
|
||||
label: 关闭
|
||||
code_pretty:
|
||||
name: code_pretty
|
||||
label: 文章代码高亮主题
|
||||
type: select
|
||||
default: Default
|
||||
options:
|
||||
- value: Default
|
||||
label: Default
|
||||
- value: Coy
|
||||
label: Coy
|
||||
- value: Dark
|
||||
label: Dark
|
||||
- value: Okaidia
|
||||
label: Okaidia
|
||||
- value: Solarized Light
|
||||
label: Solarized Light
|
||||
- value: Tomorrow Night
|
||||
label: Tomorrow Night
|
||||
- value: Twilight
|
||||
label: Twilight
|
||||
```
|
||||
|
||||
页面取值：
|
||||
|
||||
```html
|
||||
// 获取首页标题
|
||||
|
||||
<#if settings.index_title?? && settings.index_title != ''>
|
||||
<h1>${settings.index_title!}</h1>
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取背景图片
|
||||
|
||||
<#if settings.background_cover?? && settings.background_cover != ''>
|
||||
<img src="${settings.background_cover!}">
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取背景颜色
|
||||
|
||||
<style>
|
||||
body{
|
||||
<#if settings.background_color?? && settings.background_color != ''>
|
||||
background-color: ${settings.background_color!}
|
||||
<#else>
|
||||
background-color: #fff
|
||||
</#if>
|
||||
}
|
||||
</style>
|
||||
|
||||
或者
|
||||
|
||||
<style>
|
||||
body{
|
||||
background-color: ${settings.background_color!'#fff'}
|
||||
}
|
||||
</style>
|
||||
|
||||
```
|
||||
|
||||
```html
|
||||
// 判断是否开启背景音乐
|
||||
|
||||
<#if settings.music_enabled!false>
|
||||
do something...
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取代码高亮主题
|
||||
|
||||
<link rel="stylesheet" type="text/css" href="${theme_base!}/assets/prism/css/prism-${settings.code_pretty!'Default'}.css" />
|
||||
<script type="text/javascript" src="${theme_base!}/assets/prism/js/prism.js"></script>
|
||||
```
|
||||
|
||||
更多实例可参考：<https://github.com/halo-dev/halo-theme-material/blob/master/settings.yaml>。
|
||||
@@ -0,0 +1,261 @@
|
||||
---
|
||||
title: 全局变量
|
||||
description: 系统提供的一些全局变量
|
||||
---
|
||||
|
||||
## 博客地址
|
||||
|
||||
```html
|
||||
${blog_url!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `博客地址` 相对应。
|
||||
|
||||
## 网站根路径
|
||||
|
||||
```html
|
||||
${context!}
|
||||
```
|
||||
|
||||
需要注意的是，此变量和 `blog_url` 不同的是，这个变量有两种值，一种为相对路径形式，一种为绝对路径形式。
|
||||
|
||||
那么，当在后台博客设置中将 `全局绝对路径` 的选项打开时，`context` 变量值为 `${blog_url}/`，关闭时，`context` 的变量值为 `/`。
|
||||
|
||||
假设，我设置的 `博客地址` 为 `https://halo.run`，那么：
|
||||
|
||||
- 全局绝对路径为开启的状态下：<https://halo.run/>
|
||||
- 全局绝对路径为关闭的状态下：/
|
||||
|
||||
## 主题资源根路径
|
||||
|
||||
```html
|
||||
${theme_base!}
|
||||
```
|
||||
|
||||
假设你的主题在 `~/halo-dev/templates/themes/anatole` 这个目录，那么 `theme_base` 为 `https://yourdomain/themes/anatole`
|
||||
|
||||
举个例子，你当前开发的主题为 `anatole`，当你要获取主题下 `css/style.css` 这个文件的路径，那么：
|
||||
|
||||
```html
|
||||
${theme_base!}/css/style.css
|
||||
```
|
||||
|
||||
## 主题信息
|
||||
|
||||
主题名称：
|
||||
|
||||
```html
|
||||
${theme.name!}
|
||||
```
|
||||
|
||||
主题 git 仓库地址：
|
||||
|
||||
```html
|
||||
${theme.repo!}
|
||||
```
|
||||
|
||||
主题版本号：
|
||||
|
||||
```html
|
||||
${theme.version!}
|
||||
```
|
||||
|
||||
## 博客标题
|
||||
|
||||
```html
|
||||
${blog_title!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `博客标题` 相对应。
|
||||
|
||||
## 博客 Logo
|
||||
|
||||
```html
|
||||
${blog_logo!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `Logo` 相对应。
|
||||
|
||||
## Halo 版本
|
||||
|
||||
```html
|
||||
${version!}
|
||||
```
|
||||
|
||||
当前 Halo 的版本，如：1.3.0
|
||||
|
||||
## 博主信息
|
||||
|
||||
昵称：
|
||||
|
||||
```html
|
||||
${user.nickname!}
|
||||
```
|
||||
|
||||
邮箱地址：
|
||||
|
||||
```html
|
||||
${user.email!}
|
||||
```
|
||||
|
||||
描述：
|
||||
|
||||
```html
|
||||
${user.description!}
|
||||
```
|
||||
|
||||
头像地址：
|
||||
|
||||
```html
|
||||
${user.avatar!}
|
||||
```
|
||||
|
||||
上次登录时间：
|
||||
|
||||
```html
|
||||
${user.expireTime!}
|
||||
```
|
||||
|
||||
## SEO 关键词
|
||||
|
||||
```html
|
||||
${meta_keywords!}
|
||||
```
|
||||
|
||||
需要注意的是，虽然这个变量在任何页面都可以使用，但是其值可能在不同的页面是不一样的。会根据用户的设置，生成对应的值。
|
||||
|
||||
假设在文章页面：
|
||||
|
||||
- 如果用户为文章设置了标签，而没有设置 `自定义关键词`，系统会自动将标签设置为页面关键词。
|
||||
- 如果用户设置了 `自定义关键词`，那么则会取用户设置的值。
|
||||
|
||||
## SEO 描述
|
||||
|
||||
```html
|
||||
${meta_description!}
|
||||
```
|
||||
|
||||
需要注意的是，虽然这个变量在任何页面都可以使用，但是其值可能在不同的页面是不一样的。会根据用户的设置，生成对应的值。
|
||||
|
||||
## RSS 2.0 订阅地址
|
||||
|
||||
```html
|
||||
${rss_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/rss.xml`
|
||||
|
||||
## Atom 格式的订阅地址
|
||||
|
||||
```html
|
||||
${atom_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/atom.xml`
|
||||
|
||||
## XML 格式的网站地图地址
|
||||
|
||||
```html
|
||||
${sitemap_xml_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/sitemap.xml`
|
||||
|
||||
## HTML 格式的网站地图地址
|
||||
|
||||
```html
|
||||
${sitemap_html_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/sitemap.html`
|
||||
|
||||
## 友情链接页面地址
|
||||
|
||||
```html
|
||||
${links_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{links_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{links_prefix}`
|
||||
|
||||
`{links_prefix}` 是用户可设定的值，用户可以在后台修改 `友情链接` 的前缀，默认为 `links`。
|
||||
|
||||
## 图库页面地址
|
||||
|
||||
```html
|
||||
${photos_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{photos_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{photos_prefix}`
|
||||
|
||||
`{photos_prefix}` 是用户可设定的值，用户可以在后台修改 `图库页面` 的前缀，默认为 `photos`。
|
||||
|
||||
## 日志页面地址
|
||||
|
||||
```html
|
||||
${journals_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{journals_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{journals_prefix}`
|
||||
|
||||
`{journals_prefix}` 是用户可设定的值，用户可以在后台修改 `日志页面` 的前缀，默认为 `journals`。
|
||||
|
||||
## 文章归档页面地址
|
||||
|
||||
```html
|
||||
${archives_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{archives_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{archives_prefix}`
|
||||
|
||||
`{archives_prefix}` 是用户可设定的值，用户可以在后台修改 `归档` 的前缀，默认为 `archives`。
|
||||
|
||||
## 分类列表页面地址
|
||||
|
||||
```html
|
||||
${categories_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{categories_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{categories_prefix}`
|
||||
|
||||
`{categories_prefix}` 是用户可设定的值，用户可以在后台修改 `分类` 的前缀，默认为 `categories`。
|
||||
|
||||
## 标签列表页面地址
|
||||
|
||||
```html
|
||||
${tags_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{tags_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{tags_prefix}`
|
||||
|
||||
`{tags_prefix}` 是用户可设定的值，用户可以在后台修改 `标签` 的前缀，默认为 `tags`。
|
||||
|
||||
## 页面判断
|
||||
|
||||
判断当前页面是否是特定的页面。
|
||||
|
||||
- **is_index**：首页
|
||||
- **is_post**：文章页
|
||||
- **is_sheet**：自定义页面
|
||||
- **is_archives**：归档页面
|
||||
- **is_categories**：分类列表页面
|
||||
- **is_category**：单个分类页面
|
||||
- **is_tags**：标签列表页面
|
||||
- **is_tag**：单个标签页面
|
||||
- **is_search**：搜索结果页面
|
||||
- **is_journals**：日志页面
|
||||
- **is_photos**：图库页面
|
||||
- **is_links**：友情链接页面
|
||||
|
||||
用法：
|
||||
|
||||
```html
|
||||
<#if is_index??>
|
||||
当前页面是首页
|
||||
</#if>
|
||||
```
|
||||
1354
versioned_docs/version-1.5/developer-guide/theme/page-variable.md
Normal file
1354
versioned_docs/version-1.5/developer-guide/theme/page-variable.md
Normal file
File diff suppressed because it is too large
Load Diff
76
versioned_docs/version-1.5/developer-guide/theme/prepare.md
Normal file
76
versioned_docs/version-1.5/developer-guide/theme/prepare.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: 准备工作
|
||||
description: 主题开发的环境搭建
|
||||
---
|
||||
|
||||
:::info
|
||||
Halo 的模板引擎为 FreeMarker，建议在开发 Halo 的主题之前，先阅读一遍 FreeMarker 的相关文档：<https://freemarker.apache.org>。
|
||||
:::
|
||||
|
||||
## 搭建开发环境
|
||||
|
||||
> 假设你已经在本地电脑配置好了 Java 开发环境。
|
||||
|
||||
Halo 的运行可参考上述 [系统开发](/developer-guide/core/prepare)，或者直接下载打包好的程序启动，如下步骤：
|
||||
|
||||
1. 从 [GitHub release](https://github.com/halo-dev/halo/releases) 或者 [https://dl.halo.run](https://dl.halo.run) 下载最新的运行包。
|
||||
2. 在终端中执行 `java -jar halo.jar --spring.profiles.active=dev`
|
||||
|
||||
启动完成之后，在电脑的用户目录即可看到 `halo-dev` 文件夹。
|
||||
|
||||
## 新建主题
|
||||
|
||||
1. 在 `~/halo-dev/templates/themes` 下新建一个文件夹，该文件夹就是你所新建的主题目录。
|
||||
2. 使用你熟悉的编辑器打开你所新建的主题目录，这里我们推荐使用 [Visual Studio Code](https://code.visualstudio.com)，并安装 [FreeMarker](https://marketplace.visualstudio.com/items?itemName=dcortes92.FreeMarker) 扩展。
|
||||
|
||||
:::info
|
||||
我们同样为 Halo 主题开发了一个 `Visual Studio Code` Snippets 扩展，以简化一些操作，但目前处于 beta 状态，有需要的可以试试 [Halo theme develop Snippets](https://marketplace.visualstudio.com/items?itemName=halo-dev.halo-theme-dev-snippets-for-vs-code)。
|
||||
:::
|
||||
|
||||
## 开发约定
|
||||
|
||||
- 主题目录下必须存在 `theme.yaml（主题描述文件）`，`settings.yaml（主题配置文件）`，相关格式在后面会详细讲解。
|
||||
- 如果要开源到 GitHub 我们建议将仓库名设置为 `halo-theme-主题名`，并设置仓库的 `topic` 为 `halo` 和 `halo-theme`，这样可以方便使用者搜索。
|
||||
- 所有模板文件的后缀为 `.ftl`。
|
||||
- 主题目录需要以 `screenshot.png` 命名的预览图片，以供后台展示。
|
||||
|
||||
## 开发样板
|
||||
|
||||
> 为了让开发者更快速的上手主题的开发，我们提供了一个简单的开发样板以供参考。
|
||||
|
||||
仓库地址：<https://github.com/halo-dev/halo-theme-quick-starter>
|
||||
|
||||
## 目录结构
|
||||
|
||||
> 为了让开发更加规范，我们推荐使用以下的目录结构。
|
||||
|
||||
```txt
|
||||
├── module // 公共模板目录
|
||||
│ ├── comment.ftl // 比如：评论模板
|
||||
│ ├── layout.ftl // 比如：布局模板
|
||||
├── source // 静态资源目录
|
||||
│ ├── css // 样式目录
|
||||
│ ├── images // 图片目录
|
||||
│ ├── js // JS 脚本目录
|
||||
│ └── plugins // 前端库目录
|
||||
├── index.ftl // 首页
|
||||
├── post.ftl // 文章页
|
||||
├── post_xxx.ftl // 自定义文章模板，如：post_diary.ftl。可在后台发布文章时选择。
|
||||
├── sheet.ftl // 自定义页面
|
||||
├── sheet_xxx.ftl // 自定义模板，如：sheet_search.ftl、sheet_author.ftl。可在后台发布页面时选择。
|
||||
├── archives.ftl // 归档页
|
||||
├── categories.ftl // 分类目录页
|
||||
├── category.ftl // 单个分类的所属文章页
|
||||
├── tags.ftl // 标签页面
|
||||
├── tag.ftl // 单个标签的所属文章页
|
||||
├── search.ftl // 搜索结果页
|
||||
├── links.ftl // 内置页面：友情链接
|
||||
├── photos.ftl // 内置页面：图库
|
||||
├── journals.ftl // 内置页面：日志
|
||||
├── 404.ftl // 404 页
|
||||
├── 500.ftl // 500 页
|
||||
├── README.md // README，一般用于主题介绍或说明
|
||||
├── screenshot.png // 主题预览图
|
||||
├── settings.yaml // 主题选项配置文件
|
||||
└── theme.yaml // 主题描述文件
|
||||
```
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: 公共宏模板
|
||||
description: 系统提供的一些宏模板
|
||||
---
|
||||
|
||||
> 为了减少重复代码，我们将某些常见的全局变量封装成了一个公共模板，我们只需要引入该模板，然后调用其中的宏模板即可。
|
||||
|
||||
## 公共 head 模板
|
||||
|
||||
> 需要注意的是，为了保证系统功能的完整性，我们强制要求在每个页面的 `<head>` 标签下必须包含此模板。
|
||||
|
||||
```html
|
||||
<@global.head />
|
||||
```
|
||||
|
||||
等同于：
|
||||
|
||||
```html
|
||||
<#if options.seo_spider_disabled!false>
|
||||
<meta name="robots" content="none">
|
||||
</#if>
|
||||
<meta name="generator" content="Halo ${version!}"/>
|
||||
<@global.favicon />
|
||||
<@global.custom_head />
|
||||
<@global.custom_content_head />
|
||||
```
|
||||
|
||||
## 公共底部
|
||||
|
||||
> 需要注意的是，为了保证系统功能的完整性，我们强制要求在每个页面的尾部必须包含此模板。
|
||||
|
||||
```html
|
||||
<@global.footer />
|
||||
```
|
||||
|
||||
等同于：
|
||||
|
||||
```html
|
||||
<@global.statistics />
|
||||
<@global.footer_info />
|
||||
````
|
||||
|
||||
## 相对时间
|
||||
|
||||
```html
|
||||
<@global.timeline datetime="时间" />
|
||||
|
||||
// 输出
|
||||
x 年前/x 个月前/x 天前/昨天/x 小时前/x 分钟前/x 秒前/刚刚
|
||||
```
|
||||
|
||||
## 评论模块
|
||||
|
||||
```html
|
||||
<@global.comment target= type="" />
|
||||
```
|
||||
|
||||
等同于：
|
||||
|
||||
```html
|
||||
<#if !post.disallowComment!false>
|
||||
<script src="//cdn.jsdelivr.net/npm/vue@2.6.10/dist/vue.min.js"></script>
|
||||
<script src="${options.comment_internal_plugin_js!'//cdn.jsdelivr.net/npm/halo-comment@latest/dist/halo-comment.min.js'"></script>
|
||||
<halo-comment id="${post.id}" type="${type}"/>
|
||||
</#if>
|
||||
```
|
||||
|
||||
参数说明：
|
||||
|
||||
- target：post / sheet / journal 对象
|
||||
- type：评论类型，可为：post / sheet / journal
|
||||
|
||||
例子：
|
||||
|
||||
在文章页面（post.ftl or post_xxx.ftl）：
|
||||
|
||||
```html
|
||||
<@global.comment target=post type="post" />
|
||||
```
|
||||
|
||||
在自定义页面（sheet.ftl or post_sheet.ftl）：
|
||||
|
||||
```html
|
||||
<@global.comment target=sheet type="sheet" />
|
||||
```
|
||||
|
||||
在日志页面（journals.ftl）：
|
||||
|
||||
```html
|
||||
<@global.comment target=journal type="journal" />
|
||||
```
|
||||
2746
versioned_docs/version-1.5/developer-guide/theme/template-tag.md
Normal file
2746
versioned_docs/version-1.5/developer-guide/theme/template-tag.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user