封面来源：碧蓝航线 永夜幻光 活动CG

0. 前言

0.1 本文须知

本博客采用 Hexo 框架进行搭建，使用 hexo-theme-butterfly 主题进行美化，并对一些细节进行了魔改，部署在 Gitee GitHub 上（垃圾码云，又要手动部署，又要实名认证，实名就算了，还要本人手持身份证，垃圾玩意儿），未来会将其部署在服务器上（先暂时白嫖一会） （白嫖一时爽，一直白嫖一直爽 😆）。

0.2 如何搭建博客

编写目的

最近没事时经常在交流群里宣传我的博客并互换友链，让博客的流量增加了不少（虽然也就几百😂），很多小伙伴看到我的博客后，都觉得还行，也想自己搭建一个博客。新手在第一次搭建博客的时候总会出一些问题，要么是不知道怎么搭建，要么看不懂主题的文档，抑或是不知道插件的使用。

原本以为根据网上的众多教程可以解决这些问题，可依旧有小伙伴来问我，因此决定写一下怎么搭建一个博客。

—— 本节编辑于 2020/08/13

搭建须知

搭建博客的前提是需要你的电脑上有 Node.js 和 Git。

不会 Git 及其配置？没关系！在本博客搜索关键词 Git，我写过一篇关于 Git 的 简易 （不断补充中，内容越来越多）使用教程。

如果想要对搭建好的博客进行魔改美化，还需要有一定的前端基础知识（HTML、CSS、JavaScript 等）。

不会以上提及的技术也没关系，我会给出参考教程来告诉你如何搭建，一些魔改美化也可以去网上搜索。

编写博客文章使用的是 Typora，这是一款高自定义化的、简洁的 Markdown 编辑工具。

什么？你没用过？没关系，在本博客搜索关键词 Typora，会得到一篇关于 Typora 和 Markdown 相关的文章。

不使用 Typora 也行，任何一个 Markdown 编辑器甚至是记事本都可以，但必须掌握 Markdown 的书写语法。

那么！我们就开始了！👊

初步搭建

首先需要先搭建出一个简单的博客，然后才可以在这个基础上进行美化，参考教程看这里：

手把手教你从0开始搭建自己的个人博客

这是一个视频教程，讲的十分详细（感谢羊哥！），我当初也是跟着这个视频进行搭建的。

在视频最后，还给出了主题配置的步骤，如果不喜欢视频中的主题，可以去 GitHub 上搜索 hexo theme ，就能找到许多好看的主题，配置方式与视频中类似。

使用 npm 全局安装 hexo 后，在 Git Bash 中使用 hexo 命令显示“-bash: hexo: command not found”时，需要将 npm 的全局模块存放路径添加到环境变量 Path 中。如果添加后依旧存在错误，那么在 hexo 命令前加上 npx，即 npx hexo，然后再追加相关选项。

配置图床

完成以上步骤后，博客基本就初步搭建好了，之后就可以编写 Markdown 文件并放进博客文章目录 blog/source/_posts 中，这下又出现了一个问题，博客中的图片应该怎么办呢？

Markdown 文件中的图片都是引用的，图片是放在本地的，那怎么在博客中引用图片呢？

这里需要使用到图床，图床有很多，可以使用 Gitee 或 GitHub 解决 （不再推荐使用这种方式，前者不在支持，后者访问速度过慢） ，也有使用其他方式解决，而我选择的是国内的阿里OSS。

既然如此，得先注册一个阿里云账号，具体步骤就省略了，这个很简单。

然后可以参考这篇教程： 阿里云OSS PicGo 配置图床教程 超详细

这篇文章配置了阿里云 OSS，然后将其与 PicGo 结合，这不重要，重点是配置阿里云 OSS 的方法。

对了，还有一点，配置阿里云 OSS 时不用购买什么流量包、储存包（我记得是不用购买的，具体我也忘记了，相信你肯定懂得随机应变 😘），直接用就完事了，别忘了往里面充值几块钱，阿里云 OSS 默认是按量收费的，我们博客的访问量较低，使用默认的就行。

当然，如果想白嫖，可以使用 GitHub 或 Gitee 来搭建一个免费的图床，具体做法可以参考羊哥的这篇文章：使用GitHub作为个人博客免费图床

使用 emoji 表情

你会发现我在博客中使用了一些 emoji 表情，它们很有意思，这些表情可以直接在 Typora 中使用，但是部署到博客上就成了类似 :kissing_heart: 这样的字符串，解决办法很简单，安装一些插件即可。

在博客根目录下执行：

1
2
3
4
5
6
# 卸载默认渲染引擎
npm un hexo-renderer-marked --save
# 安装新的渲染引擎
npm i hexo-renderer-markdown-it --save
# 解析 emoji 简短代码
npm install markdown-it-emoji --save

这里卸载了 Hexo 默认的 Markdown 渲染引擎，而是采用 hexo-renderer-markdown-it 作为新的渲染引擎，该引擎十分强大，也支持很多插件，可以按需安装一下插件：

1
2
3
4
5
6
7
8
npm i markdown-it-mark --save
npm i markdown-it-footnote --save
npm i markdown-it-sup --save
npm i markdown-it-sub --save
npm i markdown-it-abbr --save
npm i markdown-it-emoji --save
npm i markdown-it-checkbox --save
npm i katex @renbaoshuo/markdown-it-katex

然后在博客的 主配置文件 中增加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
## 修改 markdown 渲染引擎为 hexo-renderer-marked-it，这个插件渲染速度更快，且有新特性
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: false
    typographer: true
    quotes: '“”‘’'
  plugins:
    - markdown-it-mark
    - markdown-it-footnote
    - markdown-it-sup
    - markdown-it-sub
    - markdown-it-abbr
    - markdown-it-emoji
    - markdown-it-checkbox # tasklist
    - plugin: # 数学公式 Katex
      name: '@renbaoshuo/markdown-it-katex'
      options:
        strict: false
  anchors:
    level: 1
    collisionSuffix: 'v'
    permalink: true
    permalinkClass: header-anchor
    permalinkSymbol: ''

什么是 主配置文件 ？就是博客根目录下的 _config.yml 文件，后文也会介绍到。

主题配置

接下来到了美化博客，选取一个自己喜欢的主题，然后用它就完事了！

本站使用的是 hexo-theme-butterfly 主题进行美化，如果你不喜欢这个主题，可以去 GitHub 上以 hexo theme 为关键词进行搜索，可以找到许多好看的主题。

主题都有对应的使用文档，主题的配置不在此多说，可以参看下面这些链接：

butterfly 文档：Butterfly 安裝文檔(一) 快速開始 | Butterfly

butterfly 主题魔改： Hexo博客之butterfly主题优雅魔改系列

下载主题使用后，你会发现菜单栏的选项很少，只有归档，分类、标签都没有，那么你需要自己添加这些选项，做法在主题文档中也给出了，再给你一个参考链接： 短短1天我学会了如何修改Butterfly的配置文件

主题的配置文档一定要认真读 ，内容很多，不同的人有不同的表述方式，认真读就知道文档的具体含义了。

主题配置补充

虽然主题文档写的很详细，但我还是有些地方需要说明，以免部分小伙伴看不懂主题文档，在此以 butterfly 主题的文档为参考，其他主题的文档应该也差不多。

在主题文档中，会涉及到这几个页面：

front-matter

这里出现了两种页面 Page 页和 Post 页，那它们指的是什么意思呢？（Front-matter 指的是啥可以看主题文档的说明）

Page 页指的就是我们的博客文章详情页 ，比如下图是博客文章在首页的样子，类似一张卡片，点一下可以查看文章的详细内容，跳转到的页面就是 Page 页（文章详情页）。

文章首页卡片：

文章首页卡片

Page页（文章详情页）：

Page页

那 Post 页又是什么呢？

Post 页就是我们点击菜单栏选项后跳转的页面。 Post 页都是使用命令 hexo new page xxxx 创建的页面，首页是主题本来就有的，因此不属于 Post 页。

菜单栏选项（首页不属于 Post 页）：

菜单栏选项

选中其中其中一个点击进去，就可以进入 Post 页，比如点击 “ 标签 ” ：

标签页

进入的标签页就是一个 Post 页。

还要说明一下 配置文件的区别 ：

下载 Hexo 后，进入博客文件夹，有一个名为 _config.yml 的文件，目录结构如下：

主配置文件

这里的 _config.yml 文件是主配置文件，某些插件的使用需要在这里面添加一些配置。

在主题文件中，可能也有一个名为 _config.yml 的文件，目录：themes/主题名/_config.yml。

主题配置文件

我们管这个 _config.yml 文件叫 主题配置文件，每一个主题都有一个主题配置文件，不同的主题中主题配置文件的内容不一样。 当需要对主题进行一些设置时，一般都是在主题配置文件中进行修改。

还有很重要的一点： 这些配置文件都是 YML 文件，需要注意 YML 文件的正确书写方式，比如每个英文冒号后都要加一个空格，同级配置前的缩进保持一致等等。

如果你阅读完上述内容，并成功实现了，那么一个博客基本就搭建完成了！ 🎉

下文是我在搭建博客时遇到的一些问题和一些魔改，感兴趣可以阅读一下！😎

1. 问题

由来

Hexo 框架中文章链接默认的生成规则是：:year/:month/:day/:title，即：按照年、月、日、标题来生成的。如果标题中没有中文还好，如果有中文，文章链接也会是中文，但是复制后的链接会变成 URL 编码形式表示的 ASCII 字符（十六进制格式）。很长一串，十分不好看，这时候可以选用安装 hexo-abbrlink 插件来解决。

具体的安装方式参考：Hexo+Github 博客butterfly 和 matery 主题 搭建完全教程

再补充一点，随着编写的博客数量的增加，存放 .md 文件的 _post 目录下的文件越来越多，给后续的检索和修改带来了诸多不便，其实 Hexo 是支持在 _post 目录下新建子目录的。在没有使用 hexo-abbrlink 插件的情况下，文章的详细链接与其在 _post 目录下的位置是有关系的，而在使用之后，无论其在哪个子目录下，最终的链接都是 hexo-abbrlink 所指定的，因此 强烈推荐使用该插件！

问题描述

安装好插件后，给文章的 font 部分添加自定义 abbrlink 即可实现自定义文章链接。

我在第一次自定义 abbrlink 时，没有将自定义的地址书写规范。有一天发现后，便前往文章修改，修改之后使用 hexo -g 命令可以看到修改后的文件，但部署后依旧没有修改，这导致在博客点击修改完的文章时直接显示 404。

问题示例

修改前： abbrlink:Basic-CSS3-knowledge

修改为：abbrlink:Basic-CSS3-Knowledge（Knowledge 的首字母修改为大写）

然后一波操作：hexo clean、hexo g、hexo d，但在远程仓库中可以看到，文件的名字依旧没有改变，仍然是： abbrlink:Basic-CSS3-knowledge（这是因为 Git 不会检测文件夹名称是否修改）。

之后前往博客网址，点击修改后地址的文章，不出意外地出现 404，地址栏为 https://xxxxxxx/Basic-CSS3-knowledge。😠

同时在执行 hexo d 时，出现错误：😡

1
The file will have its original line endings in your working directory.

解决方法

暴力强制推送（不推荐，这会让你仓库的提交次数清零）：

  • 前往博客的文件夹，删除文件夹 .deploy_git
  • 运行命令：git config --global core.autocrlf false
  • 然后继续一波操作：hexo clean、hexo g、hexo d
  • 前往远程仓库查看，名字更改成功

推荐的方式：

  • 先在 _posts 文件夹中移除更改的文章
  • 部署一次博客
  • 再将移除的文章重新添加至 _posts 文件夹中
  • 最后再部署一次博客

这种方式利用 Git 先移除旧文件，再重新生成新文件的方式完成名称的更改，并且使用这种方式不会对仓库的版本控制产生较大的影响。

1.2 无法显示社交图标

问题描述

根据 Butterfly 的文档，可以在侧边栏添加社交图标，但是我的浏览器总是无法显示这些图标。同时，在文章页末尾可以设置分享按钮以分享文章，我的浏览器也无法显示。最奇怪的是，使用手机是可以看到这些内容的。

我曾一度认为是主题的 Bug，一直等待修复，直到一次升级主题，使用其他浏览器访问了博客，奇怪的事情发生了：社交图标和分享按钮可以正常显示。

那么很显然就是浏览器的问题了。

问题原因

我最开始使用的是 Chrome（谷歌浏览器），无法正常显示，然后使用 QQ 浏览器可以正常访问。难道是 Chrome 的问题？

可以说是，可以说不是。

经过短暂的排查，我在 Chrome 上安装了广告拦截插件 AdGuard，就是因为这个插件对上面的内容进行了拦截才无法正常显示。

解决方法

  • 不使用插件 AdGuard
  • 更换广告拦截插件为 AdBlock
  • 自定义插件 AdGuard 拦截规则

错误关联

因为插件 AdGuard 的拦截效果，也导致文章搜索功能迟迟无法成功添加。

本地搜索插件一直被拦截，我也曾一度以为是搜索插件或主题的问题。

1.3 本地运行错误

当我们下载好 Hexo，执行 hexo init 并换上喜欢的主题后，可以执行以下命令在本地查看主题的效果：

1
2
3
hexo clean
hexo g
hexo s

在浏览器地址栏输入 localhost:4000 进行本地访问时，浏览器页面上出现以下字样，并且也没有跳转至博客界面：

1
extends includes/layout.pug block content include ./includes/mixins/post -ui.pug #recent posts.recent posts +postUI include includes/pagination.pug

这是因为缺少某些插件，只需在博客目录下执行以下命令安装需要的插件：

1
npm install --save hexo-renderer-jade hexo-generator-feed hexo-generator-sitemap hexo-browsersync hexo-generator-archive

安装完成后执行：

1
2
3
hexo clean
hexo g
hexo s

最后再次访问 localhost:4000 即可。

1.4 Node.js 版本过高？

运行 hexo v 命令，查看一下 Hexo 版本时可能会出现以下问题：

1
2
Warning: Accessing non-existent property 'column' of module exports inside circular dependency
Warning: Accessing non-existent property 'filename' of module exports inside circular dependency

或者当执行 hexo g 时，出现以下问题：

1
2
Warning: Accessing non-existent property 'column' of module exports inside circular dependency
Warning: Accessing non-existent property 'filename' of module exports inside circular dependency

出现以上两种问题很有可能是因为 Node.js 版本过高，建议换成低版本的 Node.js。

比如：出现上述错误时，我的 Node.js 的版本是 14.15，最后我将其卸载重新安装了 12.18 版本的 Node.js 就解决了问题。

总的来说，不建议使用版本过于高的软件，指不定会出现什么错误，而且很有可能还找不到资料。

1.5 重建博客时运行错误

情况一：未按要求创建文件夹

在选定目录下执行完 hexo init 命令后，会生成博客的基本骨架，source 目录下有且仅有一个名为 _posts 的目录。如果曾经搭建过 Hexo 博客，很有可能会直接将旧博客目录下的 source 文件夹直接复制到新的博客目录下，但这也很有可能带来问题。

建议 在博客目录下执行 hexo new page tags 类似的命令生成对应的文件夹。比如前面的命令就是生成名为 tags 的文件夹，用于存放博客文章的分类，如果想要生成其他文件夹，将 tags 更改为想要生成的文件夹名称即可。

情况二：插件缺失

重建博客后运行 hexo g 时很有可能因为 缺失某些插件 而导致出现某些错误。

如果出现错误，建议检查插件是否缺失。

在此列举一下本站所使用的插件：

  • butterfly 主题必备渲染插件： pug 以及 stylus 的渲染器：
1
npm install hexo-renderer-pug hexo-renderer-stylus --save
  • 文章字数统计插件：
1
npm install hexo-wordcount --save
  • 本地搜索插件：
1
npm install hexo-generator-search --save
  • Markdown 渲染器与 emoji 表情显示插件：
1
2
3
4
5
6
7
8
9
10
11
12
# 卸载默认渲染引擎
npm un hexo-renderer-marked --save
# 安装新的渲染引擎
npm i hexo-renderer-markdown-it --save
npm i markdown-it-mark --save
npm i markdown-it-footnote --save
npm i markdown-it-sup --save
npm i markdown-it-sub --save
npm i markdown-it-abbr --save
npm i markdown-it-emoji --save
npm i markdown-it-checkbox --save
npm i katex @renbaoshuo/markdown-it-katex
  • 地址栏美化，文章永久链接插件：
1
npm install hexo-abbrlink --save
  • RSS 订阅插件：
1
npm install hexo-generator-feed --save
  • Git 部署插件：
1
npm install --save hexo-deployer-git
  • 解析 Mermaid：
1
npm i mofan212/hexo-filter-mermaid-diagrams --save
  • 其他必要的插件：
1
npm install --save hexo-renderer-jade hexo-generator-feed hexo-generator-sitemap hexo-browsersync hexo-generator-archive

1.6 YAML 语法报错

最近在网上看到一款不错的字体：霞鹜文楷，于是想把它作为网站的全局字体。

以 Butterfly 主题为例，在 主题配置文件 中引入字体所需的 CSS 文件：

1
2
3
inject:
  head:
    - <link rel="stylesheet" href="https://npm.elemecdn.com/lxgw-wenkai-screen-webfont@1.1.0/style.css" />

然后修改博客的全局字体：

1
2
3
4
5
font:
  global-font-size: 15px
  code-font-size: 16px 
  font-family: "LXGW WenKai Screen", "Microsoft YaHei", sans-serif
  code-font-family:

你觉得上面这些配置有问题吗？

其实是有问题的，在执行 hexo g 命令时会显示 YAML 语法解析错误。这是为什么呢？

YAML 是 JSON 的超集，上述 font-family 后的内容需要被解析为字符串，在没有转义字符和显式声明其为一个字符串的情况下是无法解析成功的，因此需要 使用单引号将其显式声明其内容为一个字符串：

1
2
3
4
5
font:
  global-font-size: 15px
  code-font-size: 16px 
  font-family: '"LXGW WenKai Screen", "Microsoft YaHei", sans-serif'
  code-font-family:

1.7 LaTex 公式重复显示

先说结论：LaTex 渲染插件冲突，比如 Katex 和 Mathjax 冲突，移除其中一个即可。

可以从这些地方尝试修改：

  • 安装了多种渲染插件，尝试 只保留一个，这些渲染插件有：
hexo-renderer-marked
hexo-renderer-kramed
@renbaoshuo/markdown-it-katex
@upupming/hexo-renderer-markdown-it-plus

@renbaoshuo/markdown-it-katex 插件依赖 hexo-renderer-markdown-it 插件，而在使用 hexo-renderer-markdown-it 插件时，需要移除 Hexo 默认的 Markdown 渲染插件 hexo-renderer-marked， 这也需要注意一下！

  • 在使用了某些主题后，需要在主题配置文件中打开 MathJax 或 KaTeX 的配置，也可能出现重复显示的情况。我在使用 butterfly 主题时就是因为没有进行配置出现了重复显示的情况。

1.8 Win11 PowerShell 无法执行 hexo 命令

全局安装 Hexo 后，在 Git Bash 能够运行 hexo 的相关命令，但在 Win11 的 PowerShell 中无法运行，提示“无法加载文件”。

以管理员身份运行 PowerShell，执行以下命令即可解决：

1
Set-ExecutionPolicy -ExecutionPolicy UNRESTRICTED

1.9 归档页面 404

某次在点击归档后跳转到了自定义的 404 页面，为什么归档页面会 404 呢？这不是 Hexo 自动生成的吗？

在本地执行 hexo s 命令本地启动后，再点击归档页面，显示 Cannot GET /archives/，出现类似信息表示在博客根目录下的 public 目录下不存在指定目录，这里表示不存在 archives 目录，为什么会不存在呢？这不是 Hexo 自动生成的吗？

Hexo 是通过 hexo-generator-archive 插件来实现归档页面的，首次执行 hexo init 命令后，会自动安装该插件。执行 hexo g 命令时会在 public 目录下生成 archives 目录，此处没有该目录可能是因为某些误操作移除了该插件，而在 node_modules 目录下查看是否缺少 hexo-generator-archive 插件时，确实也没有此插件。

执行以下命令安装插件：

1
npm install hexo-generator-archive --save

安装完成后重新部署博客。

1.10 消失的历史评论

本站选用的评论系统是 Twikoo，近日从 Zeabur 部署更换为 Netlify 部署，但在更换之后，历史评论和先前设置的管理员密码都丢失了。

最初采用 Zeabur 部署时，使用 MongoDB 官方的数据库对 Twikoo 的评论和设置进行了存储，切换成 Netlify 后，也依旧使用了相同的 MongoDB 连接，按理说信息不应该会丢失。

尝试配置新的管理员密码，能够成功配置，这说明 MongoDB 的连接没有问题，那到底是哪里出了问题？

查看 MongoDB 中的数据：

新增的test数据库

发现新增了 test 数据库，而历史评论和配置则是在 twikoo 库中。也就是说，历史评论和配置会消失是因为连错了数据库。那为什么会连错数据库呢？这或许要从源码入手。

查看 fork 的 twikoojs/twikoo-netlify 库中 twikoo.js 的源码：

1
exports.handler = require('twikoo-netlify').handler

导入了 twikoo-netlify 模块，上 NPM 查看该模块的源码：

1
const twikoo = require('twikoo-vercel')

源码第一行导入了 twikoo-vercel 模块，并且在注释中说明：

Netlify 函数兼容 Vercel 函数实现，复用 Twikoo Vercel 函数代码

那再看看 twikoo-vercel 的源码，这个模块的源码就比较多了，在开头有这么一句：

1
const MongoClient = require('mongodb').MongoClient

不难猜出在源码中存在连接 MongoDB 的逻辑，使用 MongoClient 进行搜索，能够看到这样一个函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// 全局变量 / variables
let db = null

// --snip--

// A function for connecting to MongoDB,
// taking a single parameter of the connection string
async function connectToDatabase (uri) {
  // If the database connection is cached,
  // use it instead of creating a new connection
  if (db) return db
  if (!uri) throw new Error('未设置环境变量 MONGODB_URI')
  // If no connection is cached, create a new one
  logger.info('Connecting to database...')
  const client = await MongoClient.connect(uri, {
    useNewUrlParser: true,
    useUnifiedTopology: true
  })
  // Select the database through the connection,
  // using the database path of the connection string
  db = await client.db((new URL(uri)).pathname.substr(1))
  // Cache the database connection and return the connection
  logger.info('Connected to database')
  return db
}

这个函数用于连接到指定 uri 的 MongoDB，其中的 db 显然是要连接的库，它的值是通过截取 pathname 得到的，那 uri 是什么呢？看看哪里调用了它：

1
await connectToDatabase(process.env.MONGODB_URI)

大胆推测 process.env.MONGODB_URI 就是在 Netlify 中配置的 MONGODB_URI 环境变量。也就是说，在 MongoDB 的连接中一定存在指定连接哪个数据库的配置，MongoDB 连接 一文中指出 MongoDB 标准 URI 连接语法是：

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

并且说明 /database 是要连接的数据库，在不指定的情况下，默认打开 test 数据库。

对味了，感觉正在一步步地接近真相。

先前在 Netlify 中配置的 MONGODB_URI 环境变量类似：

mongodb+srv://<username>:<password>@cluster0.sxuss9s.mongodb.net/?retryWrites=true&w=majority

确实没有显式指定连接的数据库，那就修改环境变量并指定连接的数据库是 twikoo：

mongodb+srv://<username>:<password>@cluster0.sxuss9s.mongodb.net/twikoo?retryWrites=true&w=majority

之后在 Netlify 左侧的菜单中点击 Deploys 进入到部署界面，点击 Trigger deploy 手动重新部署。

回到博客，发现历史评论和配置的管理员密码都回来了！ 🎉

一些感受

解决方式虽然简单，但它离不开一系列分析，因此花了大量的篇幅讲述分析过程，从源码入手，逐步定位，再到解决问题。

现实世界中，谁都有可能欺骗你，但在计算机的世界中，源码不会欺骗你。

2. 一些魔改

2.1 移除文章页侧边栏滚动条

本次修改基于 Butterfly 主题。

前往 blog – themes – Butterfly – layout – includes – sidebar.pug 进行修改，在下图所示的位置添加 (style="overflow: hidden;") 即可。

移除文章侧边栏滚动条

2.2 查看网页 RSS

本次修改基于 Butterfly 3.0.0。

操作步骤

  • 下载插件 hexo-generator-feed
1
npm install hexo-generator-feed --save
  • 在 hexo 的主配置文件 _config.yml 中任意位置添加以下代码：
1
2
3
4
5
6
7
8
9
10
11
12
feed:
  type: atom
  path: atom.xml
  limit: 20
  hub:
  content:
  content_limit: 140
  content_limit_delim: ' '
  order_by: -date
  icon: icon.png
  autodiscovery: true
  template:
  • 修改 butterfly 主题配置文件 _config.yml ，添加 RSS 的图标：
1
2
social:
  fa fa-rss: /atom.xml || RSS链接

参考链接：hexo-generator-feed

2.3 分割线图标更换

本次修改基于 Butterfly 3.0.0。

将图标更换为“太空飞船”。

操作步骤

修改 butterfly 主题配置文件 _config.yml ：

1
2
3
4
hr_icon:
  enable: true
  icon: '\f197' # the unicode value of Font Awesome icon
  icon-top: -10px

icon-top 常用数值：

-20px：图标位于分割线上方

-10px：图标位于分割线中间

0px：图标位于分割线下方

效果图：

分割线图标

2.4 实现 CheckBox

前言

Hexo 默认的 Markdown 渲染引擎名为：hexo-renderer-marked，但这个引擎无法实现 emoji 表情，因此我将它更换为 hexo-renderer-markdown-it，据说它比默认的引擎渲染速度更快，它也支持很多插件，可以实现 emoji 表情的使用。

某日，我想利用 Markdown 实现 CheckBox，列出自己的计划，但是 markdown-it 引擎默认是不支持 CheckBox，需要使用第三方插件。

实现

在 GitHub 上选了三种插件，分别是 markdown-it-task-lists、markdown-it-task-checkbox 和 markdown-it-checkbox，最终选择了 markdown-it-checkbox 插件，其他两个插件的使用效果都不太好。

markdown-it-checkbox 插件也有一些问题，需要小改一下。

先在博客 根目录 下安装插件：

1
npm install markdown-it-checkbox --save

然后在博客 主题文件夹 下 \source\css 创建一个 CSS 文件，将下面的代码复制到文件中，并 在主题配置文件内引用这个 CSS 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
input[type="checkbox"] {
  display: none !important;
}
input[type="checkbox"] + label::before {
  content: '\a0';
  display: inline-block;
  margin-right: 0.2em;
  border: 1px solid;
  border-radius: 0.2em;
  width: 0.8em;
  height: 0.8em;
  vertical-align: 0.1em;
  text-indent: 0.1em;
  line-height: 0.7;
  cursor: not-allowed;
}
input[type="checkbox"]:checked + label::before {
  content: '\2714';
}

到此，美化就完毕了。这时的 CheckBox 并不是只读的，如果想要设置成只读，可以在博客 主题文件夹 下 \source\js 创建一个 JS 文件，将下面的代码复制到文件中，并 在主题配置文件内引用这个 JS 文件：

1
2
3
4
5
6
/*设置 checkbox 为只读*/
$(function() {
    $("input[type='checkbox']").click(function() {
        this.checked = !this.checked;
    });
});

最终效果可以在本站的【计划】一栏中看到效果。

从 Butterfly 3.4.0 开始，移除了 JQuery，因此需要采用原生 JS 的方式实现上述 JQuery 代码：

1
2
3
4
5
6
7
8
9
10
window.onload = function(){
    var inputs =  document.getElementsByTagName("input");
    for(var i = 0;i < inputs.length; i++){
        if(inputs[i].type == "checkbox"){
            inputs[i].onclick = function() {
                this.checked = !this.checked;
            }
        }
    }
}

语法

这种插件的 CheckBox 语法和 Typora 语法不一样。

Typora 语法是：-空格[空格]

该插件语法是：[空格] ，简单来说就是没有前面的 -。

如果要实现选择已勾选的话，在中括号里添加 x，即 [x]。

2.5 添加图片边框

本节内容基于 Butterfly 5.2.1。

在博客 主题文件夹 下 \source\css 创建一个 CSS 文件，将下面的代码复制到文件中，并在主题配置文件内引用这个 CSS 文件：

1
2
3
4
5
6
7
/* 文章图片增加边框*/
#post img[class^=entered][class$=loaded]{
    display: block;
    border: 5px solid #ddd;
    padding: 5px;
    background: #fff;
}

2.6 使用 Mermaid

Mermaid 是一个用于画流程图、状态图、时序图、甘特图的库，使用 JS 进行本地渲染，广泛集成于许多 Markdown 编辑器中。

Typora 也支持使用 Mermaid 绘制流程图、状态图、时序图和甘特图。在 Typora 中的基本语法是：

1
<pre class="mermaid">内容</pre>

但在 Butterfly 主题中并不支持使用这种语法，而是采用了标签外挂（Tag Plugins）进行实现，基本语法是：

1
2
3
{% mermaid %}
内容
{% endmermaid %}

为了能够不进行任何修改就能直接将使用 Typora 编写的 Markdown 文件迁移到 Hexo 中，使用 Mermaid 时采用的语法最好与 Typora 中一致。

解决方法

在博客目录下安装插件：

1
npm install hexo-filter-mermaid-diagrams --save

在 Hexo 的配置文件 _config.yml 中添加以下配置：

1
2
3
4
5
6
7
# Mermaid tag
mermaid:
  enable: true
  # Available themes: default | dark | forest | neutral
  theme:
    light: default
    dark: dark

在 Butterfly 主题的配置文件 _config.yml 中引入 mermaid.min.js：

1
2
3
4
5
6
inject:
  head:
    # - <link rel="stylesheet" href="/xxx.css">
  bottom:
    # - <script src="xxxx"></script>
    - <script src="https://unpkg.com/mermaid/dist/mermaid.min.js"></script>

参考链接：

【hexo指南】hexo配置ER图流程图时序图插件

webappdevelp/hexo-filter-mermaid-diagrams: mermaid diagrams for hexo

3. 最佳实践

3.1 Markdown 编写建议

接受以下建议能够使得 Markdown 在不同的场景更正确地进行渲染：

  • 对文字进行加粗、高亮、删除、斜体等操作时，Markdown 语法前后前后使用空格隔开，比如：

    1
    2
    3
    4
    空格**加粗**空格
    空格==高亮==空格
    空格~~删除~~空格
    空格_斜体_空格

  • Emoji 表情前后使用空格隔开，比如：

    1
    空格👻空格