Dream 主题基于 Halo 博客系统开发,本文将介绍本主题一些功能的使用,文档将持续更新。

一、安装 & 更新

1.1 安装包安装 & 更新

  1. 进入主题 Release 界面:https://github.com/nineya/halo-theme-dream/releases 下载主题压缩包 halo-theme-dream.zip 压缩包文件;
  2. 进入博客后台管理 外观->主题->安装->本地上传,选择下载的 halo-theme-dream.zip 安装包进行上传;
  3. 等待安装完成;
  4. 更新主题时同样前往主题 Release 界面下载主题安装包,然后通过 ``外观->主题->Dream->更多->从主题包更新` 方法上传安装包进行更新。

1.2 在线安装 & 更新

  1. 复制主题仓库地址 https://github.com/nineya/halo-theme-dream.git
  2. 进入博客后台管理 外观->主题->安装->远程下载,黏贴仓库地址进行安装;
  3. 等待安装完成;
  4. 在线更新主题时,通过 ``外观->主题->Dream->更多->在线更新` 方法进行更新。

在线安装 & 更新的方式不推荐:

  1. 因为由于 GitHub 的网络问题,很大几率会安装& 更新失败;
  2. 主题是经过源码编译的,直接从仓库下载包含了主题的源码以及开发所需的相关文件,这些文件并不是安装主题所需要的。

二、导航栏

  1. Dream 主题导航栏支持添加图标,可在菜单项中填写 FontAwesome 的相关图标 class

    主题基于 FontAwesome 4.7.0 版本,图标可参考网站:http://www.fontawesome.com.cn/faicons/

  2. 主题支持多级菜单,但最多支持三级;

  3. 有时候可能想临时关闭菜单项,不想对菜单项进行重复的删除和添加,主题支持通过在菜单栏名称前添加 #hide 临时隐藏菜单项。

    通过#hide临时隐藏菜单项

三、侧边栏

  1. 主题默认采用经典的三列布局,也支持在配置中隐藏左右其中一侧的侧边栏;

  2. 侧边栏的 Widget 模块支持通过配置优先级的方式进行排序,可填写一个数字,值越大优先级越高;

    可能这是 FreeMarker 关于排序的 bug?虽然指定的是一个数字,但是底层应该是按字符串的方式来进行排序处理的,且字符串的长度不做为排序的条件。

    因此将出现这样的情况,优先级为 9 的 Widget 优先级高于 80,800,甚至于 80000;

    所以,配置优先级时切记数值要处于相同的分位,简单说就是数值的字符串长度要相同,避免引起歧义。

四、代码块

主题支持指定代码块的标题,标题和代码块语言之间通过 |< 号进行分隔。

  • “<” 表示默认代码块为折叠;
  • “|” 表示默认代码块为展开。

示例:

// 默认展开
{% codeblock lang|可选代码块标题 %}

// 默认折叠
{% codeblock lang<可选代码块标题 %}

// 默认折叠,且不指定代码块标题
{% codeblock lang< %}

// 默认折叠,且不指定代码类型和代码块标题
{% codeblock < %}

需要注意,halo 本身 markdown 具有一些限制,如代码块名称不能包含空格。

五、元数据的使用

enable_copyright
名称 显示版权模块
范围 文章/自定义页面
可选值 true/false
默认值
说明 指定是否显示版权模块,未指定该值时以主题配置界面中的配置为准。
thumbnail_mode
名称 缩略图显示模式
范围 文章
可选值 back/small/dafault
默认值 dafault
说明 指定文章列表中文章的缩略图显示方法。
back: 缩略图将以背景图的方式显示;
small: 缩略图以小图的方式在文章摘要的左侧显示;
default: 缩略图在标题的上方显示。
tips
名称 文章提示信息内容
范围 文章/自定义页面
可选值 提示信息内容,支持 html 标签
默认值
说明 文章正文顶部显示提示信息内容。
enable_katex
名称 启用数学公式支持
范围 文章/自定义页面
可选值 true/false
默认值
说明 指定是否启用数学公式支持,未指定该值时以主题配置界面中的配置为准。

六、接入FreeCDN

FreeCDN 支持自动切换异常的 CDN 站点,对脚本等文件进行缓存,提升网站的访问速度和稳定性。

有效解决该死的 jsdelivr 出现异常这种问题…

Dream 主题支持使用 FreeCDN 提升网站访问速度,内部已经提供了 FreeCDN 相关的实现,但是由于 halo 博客系统的限制,脚本文件不能放在网站的根目录,导致 FreeCDN 无法生效,所以需要使用 Nginx 进行 url 重写,将 freecdn-manifest.txt freecdn-loader.min.js 两个文件映射到网站根目录。

脚本必须与网站同域,且在网站根目录,且网站不能存在证书问题,否则将无法正常将 FreeCDN 注册为 ServiceWorker

打开 Nginx 的配置文件,添加如下转发配置:

    location ~ ^/(freecdn-manifest.txt|freecdn-loader.min.js) {
      rewrite ^/(.*) /themes/dream/source/$1 break;
      proxy_pass http://localhost:8090;
      proxy_set_header HOST $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

使配置生效:

# 检查配置正确性
nginx -t

# 重新加载配置
nginx -s reload

若你修改了主题的 css/js 文件,需确保关闭 FreeCDN 功能,否则将从远程 CDN 下载资源,修改的内容不会生效。