配置文件

主题配置文件的说明

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

theme.yaml

  1. id: 主题id，唯一，不能与其他主题一样。我们建议设置为 `作者名_主题名称`
  2. name: 主题名称
  3. author:
  4.   name: 作者名称
  5.   website: 作者网址
  6. description: 主题描述
  7. logo: 主题 Logo 地址
  8. website: 主题地址，可填写为 git 仓库地址
  9. repo: 主题 git 仓库地址，如有填写，后台可在线更新
  10. version: 版本号
  11. require: 最低支持的 Halo 版本，如：1.3.0，那么如果用户的版本为 1.3.0 以下，则无法安装
  13. postMetaField:              文章自定义 meta 变量
  14.   - meta_key  
  16. sheetMetaField:
  17.   - meta_key                页面自定义 meta 变量

示例：

  1. id: caicai_anatole
  2. name: Anatole
  3. author:
  4.   name: Caicai
  5.   website: https://www.caicai.me
  6. description: A other Halo theme
  7. logo: https://avatars1.githubusercontent.com/u/1811819?s=460&v=4
  8. website: https://github.com/halo-dev/halo-theme-anatole
  9. repo: https://github.com/halo-dev/halo-theme-anatole
  10. version: 1.0.0
  11. require: 1.3.0
  12. postMetaField:
  13.   - music_url               # 假设在文章页面需要播放背景音乐，用户可以自己填写音乐地址。
  14.   - download_url            # 假设在文章页有一个下载按钮，那么用户也可以自己填写加载地址。
  16. sheetMetaField:
  17.   - music_url 
  18.   - download_url

自定义 meta

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

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

settings.yaml

  1. # Tab 节点
  2. group1:
  3.   label: 第一个 Tab 名称
  4.   # 表单项
  5.   items:
  6.     # 省略
  7. group2:
  8.   label: 第二个 Tab 名称
  9.   # 表单项
  10.   items:
  11.     # 省略

settings.yaml#items

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

  1. items:
  3.     # 普通文本框
  4.     item1:
  5.       name: item1               // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
  6.       label: item1              // 表单项的 label
  7.       type: text                // 表单项类型：普通文本框
  8.       placeholder: ''           // 表单项的 placeholder，一般给用户提示
  9.       default: ''               // 表单项的默认值
  10.       description: ''           // 描述，一般用于说明该设置的具体用途
  12.     # 颜色选择框
  13.     item1:
  14.       name: item1               // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
  15.       label: item1              // 表单项的 label
  16.       type: color               // 表单项类型：颜色选择框
  17.       placeholder: ''           // 表单项的 placeholder，一般给用户提示
  18.       default: ''               // 表单项的默认值
  19.       description: ''           // 描述，一般用于说明该设置的具体用途
  21.     # 附件选择框
  22.     item1:
  23.       name: item1               // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
  24.       label: item1              // 表单项的 label
  25.       type: attachment               // 表单项类型：颜色选择框
  26.       placeholder: ''           // 表单项的 placeholder，一般给用户提示
  27.       default: ''               // 表单项的默认值
  28.       description: ''           // 描述，一般用于说明该设置的具体用途
  30.     # 多行文本框
  31.     item2:                      // 设置项的 name 值，在页面可通过 ${settings.item2!} 获取值。
  32.       name: item2
  33.       label: item2              // 同上
  34.       type: textarea            // 表单项类型：多行文本框
  35.       placeholder: ''           // 同上
  36.       default: ''               // 同上
  37.       description: ''           // 描述，一般用于说明该设置的具体用途
  39.     # 单选框
  40.     item3:
  41.       name: item3               // 同上
  42.       label: item3_label        // 同上
  43.       type: radio               // 表单项类型：单选框
  44.       data-type: bool           // 数据类型：bool，string，long，double
  45.       default: value1           // 同上
  46.       description: ''           // 描述，一般用于说明该设置的具体用途
  47.       options:                  // 选项
  48.         - value: value1         // 值
  49.           label: label1         // 说明
  50.         - value: value2
  51.           label: label2
  53.     # 下拉框
  54.     item4:
  55.       name: item4               // 同上
  56.       label: item4              // 同上
  57.       type: select              // 表单项类型：下拉框
  58.       data-type: bool           // 数据类型：bool，string，long，double
  59.       default: value1           // 同上
  60.       description: ''           // 描述，一般用于说明该设置的具体用途
  61.       options:                  // 选项
  62.         - value: value1         // 值
  63.           label: label1         // 说明
  64.         - value: value2
  65.           label: label2

一个例子

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

  1. general:
  2.   label: 基础设置
  3.   items:
  4.     index_title:
  5.       name: index_title           
  6.       label: 首页标题
  7.       type: text 
  8.       description: '注意：将覆盖博客标题'
  9.     background_cover:
  10.       name: background_cover
  11.       label: 首页背景图
  12.       type: attachment
  13.       default: '/casper/assets/images/blog-cover.jpg'
  14.       description: '设置首页的背景图，你可以点击右边的选择按钮选择图片。'
  15.     background_color:
  16.       name: background_color
  17.       label: 首页背景颜色
  18.       type: color
  19.       default: '#fff'
  20.     music_enabled:
  21.       name: music_enabled
  22.       label: 背景音乐
  23.       type: radio
  24.       data-type: bool
  25.       default: false
  26.       description: '是否开启背景音乐，默认为 false'
  27.       options:
  28.         - value: true
  29.           label: 开启
  30.         - value: false
  31.           label: 关闭
  32.     code_pretty:
  33.       name: code_pretty
  34.       label: 文章代码高亮主题
  35.       type: select
  36.       default: Default
  37.       options:
  38.         - value: Default
  39.           label: Default
  40.         - value: Coy
  41.           label: Coy
  42.         - value: Dark
  43.           label: Dark
  44.         - value: Okaidia
  45.           label: Okaidia
  46.         - value: Solarized Light
  47.           label: Solarized Light
  48.         - value: Tomorrow Night
  49.           label: Tomorrow Night
  50.         - value: Twilight
  51.           label: Twilight

页面取值：

  1. // 获取首页标题
  3. <#if settings.index_title?? && settings.index_title != ''>
  4.     <h1>${settings.index_title!}</h1>
  5. </#if>
  1. // 获取背景图片
  3. <#if settings.background_cover?? && settings.background_cover != ''>
  4.     <img src="${settings.background_cover!}">
  5. </#if>
  1. // 获取背景颜色
  3. <style>
  4.     body{
  5.         <#if settings.background_color?? && settings.background_color != ''>
  6.             background-color: ${settings.background_color!}
  7.         <#else>
  8.             background-color: #fff
  9.         </#if>
  10.     }
  11. </style>
  13. 或者
  15. <style>
  16.     body{
  17.         background-color: ${settings.background_color!'#fff'}
  18.     }
  19. </style>
  1. // 判断是否开启背景音乐
  3. <#if settings.music_enabled!false>
  4.     do something...
  5. </#if>
  1. // 获取代码高亮主题
  3. <link rel="stylesheet" type="text/css" href="${theme_base!}/assets/prism/css/prism-${settings.code_pretty!'Default'}.css" />
  4. <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。