配置文件

Halo-Plus 的主题模块使用 yaml 来对主题进行配置，theme.yaml 里面主要描述主题的名称，开发者的信息，开源地址等等。settings.yaml 包含了主题所有的配置选项，需要注意的是，这些选项仅仅是用于构建配置表单，并不起到对主题的配置作用。

theme.yaml

id: 主题id，唯一，不能与其他主题一样。我们建议设置为 `作者名_主题名称`
name: 主题名称
author:
  name: 作者名称
  website: 作者网址
description: 主题描述
logo: 主题 Logo 地址
website: 主题地址，可填写为 git 仓库地址
repo: 主题 git 仓库地址，如有填写，后台可在线更新
version: 版本号
require: 最低支持的 Halo-Plus 版本，如：1.3.0，那么如果用户的版本为 1.3.0 以下，则无法安装

postMetaField:              文章自定义 meta 变量
  - meta_key  

sheetMetaField:
  - meta_key                页面自定义 meta 变量

示例：

id: dream
name: Dream
author:
  name: nineya
  website: https://www.nineya.com
description: '梦之城，童话梦境'
logo: https://q1.qlogo.cn/g?b=qq&nk=361654768&s=640
website: https://blog.nineya.com
repo: https://github.com/nineya/halo-theme-dream
version: 2.2.1
require: 1.0.0
postMetaField:
  - enable_copyright               # 假设在文章页面需要播放背景音乐，用户可以自己填写音乐地址。
  - thumbnail_mode            # 假设在文章页有一个下载按钮，那么用户也可以自己填写加载地址。

sheetMetaField:
  - enable_copyright 
  - tips

自定义 meta

这个为 1.2.0 引入的功能，用户可以在文章设置中设置自定义 meta，我们在 theme.yaml 中填写的 postMetaField 和 sheetMetaField 为预设项，当用户激活当前主题之后，在文章设置中即可看到预先设置好的项，然后填写对应的值即可。

关于这个 meta 变量如何调用的问题，会在后面的模板变量中阐述。

settings.yaml

# Tab 节点
group1:
  label: 第一个 Tab 名称
  # 表单项
  items:
    # 省略
group2:
  label: 第二个 Tab 名称
  # 表单项
  items:
    # 省略

settings.yaml#items

settings.yaml 的 items 下即为所有表单元素，所支持的表单元素如下

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

    # 复选框
    item3:
      name: item3               // 同上
      label: item3_label        // 同上
      type: checkbox            // 表单项类型：复选框
      data-type: bool           // 数据类型：bool，string，long，double
      default:
        - value1
        - value2
      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

    # 集合中继器
    item5:
      name: item5
      label: item5
      type: repeater
      description: 'item5'
      default:
        - children1: children1
          children2: children2
      children:
        - name: children1
          label: children1
          type: text
          placeholder: 'children1'
        - name: children2
          label: children2
          type: text
          placeholder: 'children2'

    # 代码文本框
    item6:
      name: item6               // 设置项的 name 值，在页面可通过 ${settings.item6!} 获取值。
      label: item6              // 表单项的 label
      type: code                // 表单项类型：代码文本框
      default: ''               // 表单项的默认值
      description: ''           // 描述，一般用于说明该设置的具体用途

一个例子

假设我们的配置文件如下：

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

页面取值：

// 获取首页标题

<#if settings.index_title?? && settings.index_title != ''>
    <h1>${settings.index_title!}</h1>
</#if>

// 获取背景图片

<#if settings.background_cover?? && settings.background_cover != ''>
    <img src="${settings.background_cover!}">
</#if>

// 获取背景颜色

<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>

// 判断是否开启背景音乐

<#if settings.music_enabled!false>
    do something...
</#if>

// 获取代码高亮主题

<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/nineya/halo-theme-dream/blob/master/settings.yaml。