You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
docs/versioned_docs/version-1.5.1/developer-guide/theme/config-files.md

262 lines
7.9 KiB

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

---
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 // 数据类型boolstringlongdouble
default: value1 // 同上
description: '' // 描述,一般用于说明该设置的具体用途
options: // 选项
- value: value1 // 值
label: label1 // 说明
- value: value2
label: label2
# 下拉框
item4:
name: item4 // 同上
label: item4 // 同上
type: select // 表单项类型:下拉框
data-type: bool // 数据类型boolstringlongdouble
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>