Dream 主题使用手册 - 基础篇

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 临时隐藏菜单项。

   [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-j5EXAyhg-1681178684990)(/upload/2022/05/image-20220501221505345-0ba8641ee686478f9c6f1e7ed8b955f3.png)]

三、侧边栏

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
说明	指定文章列表中文章的缩略图显示方法。 default： （默认）缩略图在标题的上方显示； back： 缩略图将以背景图的方式显示； small： 缩略图以小图的方式在文章摘要的左侧显示； small-right： 缩略图以小图的方式在文章摘要的右侧显示； small-alter： 缩略图以小图的方式在文章摘要的左右侧交替显示； fold： （置顶文章有效）正文内容折叠。

	tips
名称	文章提示信息内容
范围	文章/自定义页面
可选值	提示信息内容，支持 html 标签
默认值	无
说明	文章正文顶部显示提示信息内容。

	enable_katex
名称	启用数学公式支持
范围	文章/自定义页面
可选值	true/false
默认值	无
说明	指定是否启用数学公式支持，未指定该值时以主题配置界面中的配置为准。

	enable_share
名称	开启文章分享
范围	文章/自定义页面
可选值	true/false
默认值	无
说明	开启文章分享插件。

	enable_bullet_screen
名称	开启评论弹幕
范围	文章/自定义页面
可选值	true/false
默认值	无
说明	开启评论弹幕。

	index_carousel
名称	开启首页轮播
范围	置顶文章
可选值	true/false
默认值	无
说明	在首页时，文章通过大图轮播方式展示（仅对置顶文章有效）。

六、启用Service Worker优化

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

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

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

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

打开 Nginx 的配置文件，添加如下转发配置：

    location ~ ^/sw.min.js {
      rewrite ^/(.*) /themes/dream/source/js/$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

通过 https://域名/sw.min.js 能够成功访问到文件即配置成功。

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