更新 Hexo 主题时，一般都会有这样的经历：先将主题目录下的 _config.yml 文件备份，更新完主题后，再将备份的数据复制粘贴还原回去。

这个过程繁琐又浪费时间，因此我们需要一种友好的更新方式。如果你也经历着这样的痛苦，那么不妨尝试 Hexo 3.0 新增的功能 -- 数据文件 (opens new window)。

Stun 主题利用该功能实现了平滑升级的特性，使用步骤如下：将主题目录下的 _config.yml 文件复制到博客根目录下的 /source/_data/ 中，并重命名为主题名称。例如使用 stun 主题，那么就叫做 stun.yml 。如果 source 目录下没有 _data 文件夹请自行创建。

这两个文件的关系为 stun.yml 覆盖 _config.yml，也就是说，想要修改配置时，只需要修改 stun.yml 里的即可（修改 _config.yml 里的不会生效）。这样就实现了平滑升级，更新时 _config.yml （可能）会更新，而你的配置数据保留在 stun.yml 中。

注意 ！！！

主题更新后，如果主题目录下的 _config.yml 文件里出现了新的选项，那么你必须从该文件中将它们复制到 /source/_data/stun.yml 中，并设置它们的值为你想要的选项。

如果你使用了平滑升级这一特性，那么 /themes/stun/_config.yml 和 /source/_data/stun.yml 这两个文件里的选项没有同步，是更新主题后，启动报错的最主要的原因！

有时候，同步 /themes/stun/_config.yml 和 /source/_data/stun.yml 两个配置文件里的内容也比较麻烦。因此，推荐使用代码对比工具进行查看，这样再进行同步就方便多了。例如，VS Code 自带的代码对比工具：

修改 Hexo 根目录下的 _config.yml 文件：

语言文件在主题文件夹的 languages 目录下。Stun 主题默认有 zh-CN.yml 和 en.yml 两种语言文件，如果需要支持其他语言，请自行编写语言文件。语言文件的命名请参考：https://github.com/theme-next/hexo-theme-next/tree/master/languages (opens new window)

WARNING

该功能从 v1.6.0 版本开始支持，在 v1.7.0 版本中对配置项进行了更改。

主题提供了对布局的一些常用设置。修改主题配置文件：

v1.6.0：

v1.7.0 ~ Latest：

上面的属性所对应的地方，示意图如下：

修改主题配置文件：

Front-Matter 在 Hexo 主题中，占据了极其重要的地位。如果你还不了解 Front-Matter，可以查看这里：https://hexo.io/zh-cn/docs/Front-Matter (opens new window)。

下面是 Hexo 中默认提供的几种 Front-Matter 属性。

例如：

效果如下：

TIP

Hexo 会使用 git commit 中，文件的最新提交时间作为更新日期，所以一般不需要手动指定 updated 属性。并且当你使用 hexo new xxx 指令生成文件时，Hexo 会帮你添加好 title 和 date 属性。因此这三个属性一般不需要手动设置。

在 Stun 主题中，如果你启用了某个评论系统，默认是对所有通过 Markdown 文件生成的页面（除首页，归档页，单个分类页，单个标签页以外的所有页面）生效。因此，你可以使用该属性单独设置某个页面 / 文章是否启用评论。例如：

Hexo 3.9.0 及以前的版本中，只能通过添加 标记来保留文章摘要。在 Hexo 4.0.0 及以后的版本中，可以通过在 Front-Matter 中使用 excerpt 来设置文章摘要。例如：

例如，你有两篇文章：https://xxx/2020/02/03/foo 和 https://xxx/2020/02/03/bar，它们分别由 foo.md 和 bar.md 文件生成。如果你在 bar.md 的 Front-Matter 中设置了 permalink：

这样，foo.md 和 bar.md 文件都会被解析为：https://xxx/2020/02/03/foo。

文章分类有顺序性和层次性。下面是一些例子：

嵌套分类

这样会使分类 Life 成为 Diary 的子分类。

并列分类

这样会使 Life 和 Diary 成为并列分类。

并列嵌套分类

这样会使 PlayStation 和 Games 同为 Diary 的子分类，而 Life 和 Diary 是并列分类。

标签没有顺序性和层次性，只能设置为同级的。也就是说，标签只有一种用法：

这样会被解析为 PlayStation、Games、Diary,Life 三个并列标签。

在 Front-Matter 中设置了 layout: false

可以看到，设置了 layout: false 后，只将 Markdown 解析成 HTML，不做其他处理。

在 Front-Matter 中设置了 layout: true 等价于 默认

下面几种 Front-Matter 属性在 Hexo 文档中并没有出现（也许是 Hexo 的文档没有更新吧），但在 Hexo 提供的主题单元测试库中出现。按照测试文件的要求，一个合格的 Hexo 主题都应该支持它们。这些属性如下：

如果指定该属性，当点击该文章标题时，应该在新窗口或新的标签页中，打开所指定的链接地址。

用于设置一些图片，插入到页面中（Stun 主题将其显示在页面主体部分的最顶部）。使用如下：

默认情况下，这些图片会按照文档流的方式显示，效果如下：

为了优化这些图片的显示效果，Stun 主题提供了瀑布流布局 Stable v1.1.4，如果想启用这一布局，你需要修改主题配置文件：

效果如下：

TIP

下面是 Stun 主题中，特有的几种 Front-Matter 属性。

作用：设置某页面的顶部图。

取值：字符串。

示例：top_image: https://a.example.com/xxx.jpg。

详情：指定顶部图 (opens new window)。

作用：设置某页面是否启用目录。

取值：true | false。

说明：

在主题配置文件中启用该功能后，默认只对所有文章页面生效。如果想要对非文章页面启用，则需要使用 Front-Matter 中的 toc 属性。因此可以总结为以下两种情况：

详情：文章目录 (opens new window)。

作用：设置某文章中，解析标题生成目录的最小深度。

取值：1 ~ 6，默认值：1。

示例：toc_min_depth: 3，只会解析文中的 h3, h4, h5, h6 标签来生成目录。

详情：文章目录 (opens new window)。

作用：设置某文章中，解析标题生成目录的最大深度。

取值：1 ~ 6，默认值：6。

示例：toc_max_depth: 4，只会解析文中的 h1, h2, h3, h4 标签来生成目录。

详情：文章目录 (opens new window)。

作用：是否在浏览器空闲时间内，预取页面可视区中的链接，以加快点击链接后页面的加载时间。

取值：true | false。

详情：启用 Quicklink (opens new window)。

作用：是否解析某页面中的数学公式。

取值：true | false。

详情：数学公式 (opens new window)。

作用：是否显示某页面中的侧边栏。

取值：false。

说明：在主题配置文件中启用该功能后，默认对所有页面生效。如果想要指定某页面不启用侧边栏，则需要在 Front-Matter 中设置 sidebar: false。

详情：侧边栏设置 (opens new window)。

作用：是否启用某页面中的打赏功能。

取值：true | false。

说明：

在主题配置文件中启用该功能后，默认只对所有文章页面生效。如果想要对非文章页面启用，则需要使用 Front-Matter 中的 reward 属性。因此可以总结为以下两种情况：

详情：启用赞赏码 (opens new window)。

作用：是否启用某页面中的版权信息。

取值：true | false。

说明：

在主题配置文件中启用该功能后，默认只对所有文章页面生效。如果想要对非文章页面启用，则需要使用 Front-Matter 中的 copyright 属性。因此可以总结为以下两种情况：

详情：知识共享许可协议（cc） (opens new window)。

下面是安装某些插件后，可以设置的几种 Front-Matter 属性。

作用：是否置顶文章。

取值：true | false。

详情：文章置顶 (opens new window)。

作用：是否解析某页面中的 emoji 代码。

取值：true | false。

详情：添加-emoji-支持 (opens new window)。

启用二级导航菜单，需要修改主题配置文件：

修改 menu 配置项

修改 submenu 配置项

国际化设置

找到 languages 目录下的语言文件，根据你网站使用的语言选择对应的语言文件，例如：

zh-CN.yml：

例如，添加一个友情链接的二级菜单：

修改主题配置文件

国际化设置

zh-CN.yml：

效果如下：

如果你想要在文章页面启用赞赏码，修改主题配置文件：

效果如下：

TIP

用于设置你的文章的版权信息，不启用则表示无版权限制。修改主题配置文件：

效果如下：

TIP

知识共享许可协议启用后，默认对所有文章页面生效。你可以在 Front-Matter 中，设置 copyright: false 来指定某文章不启用该功能。

修改主题配置文件：

注意

开启该功能后，默认只对所有文章页面启用。如果需要单独设置某页面是否启用，详见：Front-Matter - toc (opens new window)

设置邮件订阅和 RSS 订阅，修改主题配置文件：

想要使用邮件订阅，你需要自己构建 或 使用第三方提供的邮件订阅服务。例如我的邮件订阅地址：http://eepurl.com/guAE6j (opens new window)

开启 RSS 订阅之前，你需要安装 Hexo 插件：hexo-generator-feed (opens new window)。然后在 Hexo 根目录下的 _config.yml 文件中添加配置项（关于各个配置项的具体含义，请查看插件的文档 (opens new window)）：

配置完成之后，访问你设置的订阅地址，如：https://yoursite.com/atom.xml，即可看到 RSS 订阅信息。

修改主题配置文件：

侧边栏所有效果如下：

修改主题配置文件：

效果如下：

WARNING

该功能从 v1.0.1 版本开始支持，在 v1.0.3 版本中对配置项进行了更改。

如果你想设置首页或归档页的文章列表是否分页，可以修改主题配置文件：

v1.0.1 ~ v1.0.2：

v1.0.3 ~ Latest：

默认情况下，网站首页的文章列表启用分页，归档页面的文章列表不启用分页。

分页效果如下：

WARNING

该功能从 v1.0.3 版本开始支持，在 v1.1.2 版本中对配置项进行了更改。

如果你为一篇文章单独设置了顶部图，并且想使用这个顶部图作为文章列表的封面图片来显示，可以修改主题配置文件：

v1.0.3 ~ v1.1.1：

v1.1.2 ~ Latest：

封面图片效果如下：

WARNING

该功能从 v1.0.0-beta.1 版本开始支持，在 v1.0.3 版本中对配置项进行了更改。

在文章末尾显示文章的所有标签，修改主题配置文件：

v1.0.0-beta.1 ~ v1.0.2：

v1.0.3 ~ Latest：

效果如下：

WARNING

该功能从 v1.0.0-beta.1 版本开始支持，在 v1.0.3 版本中对配置项进行了更改。

在文章末尾自动添加文章结束的提示信息，修改主题配置文件：

v1.0.0-beta.1 ~ v1.0.2：

v1.0.3 ~ Latest：

效果如下：

想要使用文章置顶功能，首先你需要安装 Hexo 插件 hexo-generator-index-pin-top (opens new window)，然后执行命令：

最后，在文章的 Front-Matter 中，使用 top: true 来实现置顶。

设置文章置顶后，在文章列表中可以看到表示置顶的图标。你可以对图标进行设置，修改主题配置文件：

效果如下：

WARNING

该配置项从 v1.0.0 开始支持，在 v1.6.0 版本中进行了修改。

设置代码高亮样式，修改主题配置文件：

v1.0.0 ~ v1.5.4：

v1.6.0 ~ Latest：

有三种可供选择的代码高亮样式：light、drak、ocean。默认是 light。效果分别如下：

light

dark

ocean

WARNING

如果代码没有高亮样式，请确保 Hexo 根目录下的 _config.yml 文件中 highlight.hljs 设为 false。

设置代码块样式，修改主题配置文件：

有三个可选值：default、simple、carbon。默认为：default。效果分别如下：

default

默认样式。具有显示语言、显示行号和启用复制按钮的功能。

下图中的代码高亮样式（从左至右，从上至下）分别为：light、light（开启夜间模式）、dark、ocean。

simple

极简样式，只显示代码。

carbon

仿 carbon 样式，只显示代码。

WARNING

该配置项从 v1.0.0 开始支持，在 v1.6.0 版本中进行了修改。

修改主题配置文件：

v1.0.0 ~ v1.5.4：

v1.6.0 ~ Latest：

可选值为：true、false。默认是 false。效果分别如下：

true（代码溢出换行）

false（代码溢出不换行）

WARNING

该配置项，即 img_horizonal_align 在 v1.4.0 版本废弃。

WARNING

该配置项，即 text_vertical_align_with_img 在 v1.2.0 版本废弃。

如果你启用了 tags 页面，想要对其进行设置，修改主题配置文件：

效果如下：

设置图片大小

使用 HTML 中的 img 标签，通过 style 属性控制图片大小。

使用 Hexo 提供的语法 {% img https://xxxxx.png width height %}，填入宽、高即可设置大小。

Stun 主题提供了一个便捷的方法，你可以在图片路径后面使用查询参数：?size=宽度x高度 Stable v1.0.0 来控制图片显示大小。例如：

使用行内图片

默认情况下，文章中的图片水平居中显示。如果你想使用行内图片，你可以在图片路径后面使用查询参数：?show=inline Beta v2.0.0-rc.0，使得图片显示为行内图片。例如：

当然，你可以同时控制图片的大小和是否显示为行内图片：

它们的用法和 URL 中的查询参数完全相同！

如果你想修改主题的样式，推荐将样式代码添加到 source/css/_custom 目录下的 index.styl 文件中。这样，当主题更新时，不会覆盖你已经修改了的样式代码。

当然，你也可以进行模块化分类：在该目录下新建样式文件，然后通过 @import xxx 语句在同目录下的 index.styl 文件中引入你新建的样式文件。

从 v1.1.3 版本开始，除了侧边栏，顶部栏以外的区域，Stun 主题会在外链后面加上一个 Icon，用于标识这是一个外部链接。

你可以通过修改主题配置文件，来设置 Icon 以及是否启用这一功能：

如果想要使用 FancyBox 功能，只需要修改主题配置文件即可：

效果如下：

可以去官网在线体验：http://fancyapps.com/fancybox/3/ (opens new window)

从 v1.2.0 版本开始，Stun 主题内置了图片放大的功能（无第三方依赖，默认启用）。想要配置该功能，请修改主题配置文件：

WARNING

FancyBox 功能也具有图片放大的效果，如果你启用了 FancyBox，那么 FancyBox 会优先生效（zoom_image 功能不会生效）。

从 v1.2.0 版本开始，Stun 主题支持图片懒加载的功能，但是该功能只对文章页面起作用。想要配置该功能，请修改主题配置文件：

占位符取不同的值效果如下：

gif

block

注意 ！！！

下面是启用 lazyload 之后，已知的一些问题。

← 新手上路 第三方支持 →