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

    通过#hide临时隐藏菜单项

    通过#hide临时隐藏菜单项

三、侧边栏

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

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

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

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

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

四、代码块

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

  • “<” 表示默认代码块为折叠；

  • “|” 表示默认代码块为展开。

示例：

0102030405060708091011// 默认展开
{% 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

默认值

无

说明

在首页时，文章通过大图轮播方式展示（仅对置顶文章有效）。

enable_donate

名称

开启文章打赏

范围

文章/自定义页面

可选值

true/false

默认值

无

说明

开启文章打赏二维码。

七、样式更改

Dream 面向所有 Halo 博客用户，不同用户之间对样式不可避免的会有不同的喜好偏差。如果要满足所有人的喜好，则主题不可避免将要有 n+ 个配置项。

为了避免主题包含一堆次要的配置，也为了满足前端样式定制化的需求，主题开放了配置 CSS 和 JavaScript 的方式进行主题定制。

或许有人会考虑直接修改主题代码，但目前该方法目前是不建议的，因为：

  1. 主题的 css / js 代码经过压缩处理；

  2. 升级主题版本后你的修改将会丢失；

  3. 直接修改文件代码将导致 FreeCDN 的功能失效（虽然我一直想换掉这个工具，但是目前还在使用着）。

ftl 文件可直接修改，没有压缩，也不会造成 FreeCDN 使用上的问题，但还是不建议，非必要不修改。

本文的定制化需求都来源于各个博主实际使用的需求摘要记录，感谢各位博主提出的宝贵建议，可前往 GitHub issue 上查看相关的记录 。

1. 移动端侧边抽屉去除博主信息

移动端侧边栏包含了博主信息，Widget 信息模块中也包含了博主信息，造成了信息重复，可能你想去掉侧边栏上的博主信息，那么可在 内嵌 CSS 框中添加如下代码实现。

建议来源：Issue #76 · nineya/halo-theme-dream

css

010203ul.navbar-slideout-menu:not(.is-toc,.not-toc) {
    display: none;
}

2. 背景图淡化

背景图太鲜艳了，造成了喧宾夺主的感觉，可对背景图进行淡化处理，在 内嵌 CSS 框中添加如下代码实现。

css

010203body:before {
    opacity: 0.5 !important;
}

3. 文章列表摘要行数

默认的文章列表项样式中，摘要是 4 行，想增大或者减少摘要行数？在 内嵌 CSS 框中添加如下代码实现。

css

010203.widget.card .main .main-content {
    -webkit-line-clamp: 3;
}

4. 文章内图片隐藏图片名称

文章内嵌图片默认显示图片名称，但是作者可能不想维护图片名称，希望能够隐藏图片名称，在 内嵌 CSS 框中添加如下代码实现。

css

010203.main-content .gallery-item p {
    display: none;
}

5. 调整背景透明度

文章、侧边栏等模块的背景颜色和透明度调整，在 内嵌 CSS 框中添加如下代码实现。

css

010203040506070809html {
  --background2: rgba(255, 255, 255, 0.1);
}
html.night {
  --background2: rgba(40, 44, 52, .1);
}
.section .card {
  background: var(--background2);
}